Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

feat: add Jenks natural breaks color scale (#3742)

Igor Dykhta3be42f855a19
diff --git a/docs/spatial-analysis-tutorial/basic-mapping.md b/docs/spatial-analysis-tutorial/basic-mapping.md
index b62fdf388..39d712722 100644
--- a/docs/spatial-analysis-tutorial/basic-mapping.md
+++ b/docs/spatial-analysis-tutorial/basic-mapping.md
@@ -73,6 +73,10 @@ Any time there are ties in the ranking of observations that align with the value
A natural (Jenks) breaks map uses a nonlinear algorithm to group observations such that the within-group homogeneity is maximized, following the pathbreaking work of Fisher ([1958](https://www.jstor.org/stable/2281952)) and Jenks ([1977](https://books.google.com/books/about/Optimal_Data_Classification_for_Chorople.html?id=HvAENQAACAAJ)). In essence, this is a clustering algorithm in one dimension to determine the break points that yield groups with the largest internal similarity.
+:::tip
+In Kepler.gl, natural breaks are the **Jenks Natural Breaks** color scale. You can select it from the Color Scale dropdown when coloring a numeric field.
+:::
+
To create such a map with four categories, you can use the following prompt:
```
diff --git a/docs/user-guides/d-layer-attributes.md b/docs/user-guides/d-layer-attributes.md
index 2ca15f5d5..7453c07a4 100644
--- a/docs/user-guides/d-layer-attributes.md
+++ b/docs/user-guides/d-layer-attributes.md
@@ -12,7 +12,7 @@
| Stroke width range | Set a lower and upper threshold for projected stroke width. | Arc, Line, Geojson |
| Grid size | Change the number of square kilometers covered by each grid square. | Grid |
| Color Palette | Choose from multiple, predefined or customized color palettes to apply to your layer. Predefined palettes are either Uber or ColorBrewer colors. | All layers |
-| Color Scale | Choose either a quantile or quantized color scale. A quantile color scale is determined by rank, while a quantized color scale is determined by value. | All layers |
+| Color Scale | Choose a quantile, quantized, Jenks natural breaks, or custom color scale. Quantile is determined by rank, quantized by equal value intervals, and Jenks by clustering similar values. | All layers |
| Height based on | Assign grid square height based on a field from your dataset. | Grid, Hexagon, S2 |
| Filter by count percentile | Increase or decrease the number of grid squares by choosing a range of percentiles to display. | Grid, Hexagon |
| Coverage | Change what portion of each grid cell is covered by a color square. | Grid, Hexagon |
diff --git a/src/constants/src/default-settings.ts b/src/constants/src/default-settings.ts
index f05d3da57..ff4670d41 100644
--- a/src/constants/src/default-settings.ts
+++ b/src/constants/src/default-settings.ts
@@ -451,6 +451,7 @@ export type SCALE_TYPES_DEF = {
ordinal: 'ordinal';
quantile: 'quantile';
quantize: 'quantize';
+ jenks: 'jenks';
linear: 'linear';
sqrt: 'sqrt';
log: 'log';
@@ -464,6 +465,7 @@ export const SCALE_TYPES: SCALE_TYPES_DEF = keyMirror({
ordinal: null,
quantile: null,
quantize: null,
+ jenks: null,
linear: null,
sqrt: null,
log: null,
@@ -477,6 +479,7 @@ export const SCALE_TYPE_NAMES: {[key in keyof SCALE_TYPES_DEF]: string} = {
ordinal: 'Ordinal',
quantile: 'Quantile',
quantize: 'Quantize',
+ jenks: 'Jenks Natural Breaks',
linear: 'Linear',
sqrt: 'Sqrt',
log: 'Log',
@@ -494,6 +497,7 @@ export const SCALE_FUNC = {
[SCALE_TYPES.linear]: scaleLinear,
[SCALE_TYPES.quantize]: scaleQuantize,
[SCALE_TYPES.quantile]: scaleQuantile,
+ [SCALE_TYPES.jenks]: scaleThreshold,
[SCALE_TYPES.ordinal]: scaleOrdinal,
[SCALE_TYPES.sqrt]: scaleSqrt,
[SCALE_TYPES.log]: scaleLog,
@@ -702,7 +706,12 @@ export const AGGREGATION_TYPE_OPTIONS: {id: string; label: string}[] = Object.en
}));
export const linearFieldScaleFunctions = {
- [CHANNEL_SCALES.color]: [SCALE_TYPES.quantize, SCALE_TYPES.quantile, SCALE_TYPES.custom],
+ [CHANNEL_SCALES.color]: [
+ SCALE_TYPES.quantize,
+ SCALE_TYPES.quantile,
+ SCALE_TYPES.jenks,
+ SCALE_TYPES.custom
+ ],
[CHANNEL_SCALES.radius]: [SCALE_TYPES.sqrt],
[CHANNEL_SCALES.size]: [SCALE_TYPES.linear, SCALE_TYPES.sqrt, SCALE_TYPES.log],
[CHANNEL_SCALES.angle]: [SCALE_TYPES.linear]
@@ -711,6 +720,7 @@ export const linearFieldScaleFunctions = {
const DEFAULT_AGGREGATION_COLOR_SCALES = [
SCALE_TYPES.quantize,
SCALE_TYPES.quantile,
+ SCALE_TYPES.jenks,
SCALE_TYPES.custom
];
diff --git a/src/deckgl-layers/src/layer-utils/aggregation-utils.ts b/src/deckgl-layers/src/layer-utils/aggregation-utils.ts
index 2211bb0ef..ce60b1792 100644
--- a/src/deckgl-layers/src/layer-utils/aggregation-utils.ts
+++ b/src/deckgl-layers/src/layer-utils/aggregation-utils.ts
@@ -2,6 +2,38 @@
// Copyright contributors to the kepler.gl project
import type {AggregatedBin, ColorMap} from '@kepler.gl/types';
+import {naturalBreaks} from '@kepler.gl/utils';
+
+type JenksColorMapCache = {
+ source: Float32Array;
+ k: number;
+ breaks: number[];
+ colorMap: ColorMap;
+};
+
+function getJenksColorMap(values: number[], k: number): {breaks: number[]; colorMap: ColorMap} {
+ const breaks = naturalBreaks(values, k);
+ // classifyBinsByCustomBreaks only reads numeric thresholds from colorMap.
+ const colorMap: ColorMap = [
+ ...breaks.map(threshold => [threshold, '#000000'] as [number, string]),
+ [null, '#000000']
+ ];
+ return {breaks, colorMap};
+}
+
+function resolveJenksColorMapCache(
+ source: Float32Array,
+ binCount: number,
+ k: number,
+ cached?: JenksColorMapCache | null
+): JenksColorMapCache {
+ if (cached && cached.source === source && cached.k === k) {
+ return cached;
+ }
+ const values = Array.from(source.subarray(0, binCount)).filter(Number.isFinite) as number[];
+ const {breaks, colorMap} = getJenksColorMap(values, k);
+ return {source, k, breaks, colorMap};
+}
/**
* Build a Record<index, AggregatedBin> from the raw Float32Array of per-bin
@@ -121,10 +153,7 @@ export function enrichedAggregationUpdate(layer: any, ParentClass: any, channel:
const binValues = result?.value as Float32Array | undefined;
if (!binValues || aggregator.binCount <= 0) return;
- layer.setState({
- rawColorBinValues: Float32Array.from(binValues.subarray(0, aggregator.binCount))
- });
-
+ const rawColorBinValues = Float32Array.from(binValues.subarray(0, aggregator.binCount));
const domain = aggregator.getResultDomain(0);
const aggregatedBins = buildAggregatedBinMap(binValues, aggregator.binCount, aggregator);
@@ -133,18 +162,36 @@ export function enrichedAggregationUpdate(layer: any, ParentClass: any, channel:
}
let enrichedDomain = domain;
+ let jenksColorMapCache: JenksColorMapCache | null = null;
if (props.colorScaleType === 'quantile') {
enrichedDomain = Array.from(binValues)
.slice(0, aggregator.binCount)
.filter(Number.isFinite)
.sort((a: number, b: number) => a - b);
+ } else if (props.jenksScale) {
+ const k = Array.isArray(props.colorRange) ? props.colorRange.length : 0;
+ jenksColorMapCache = resolveJenksColorMapCache(rawColorBinValues, aggregator.binCount, k, null);
+ classifyBinsByCustomBreaks(
+ layer.state.colors,
+ aggregator.binCount,
+ jenksColorMapCache.colorMap,
+ binValues
+ );
+ enrichedDomain = jenksColorMapCache.breaks;
}
+
+ layer.setState({
+ rawColorBinValues,
+ jenksColorMapCache
+ });
props.onSetColorDomain?.({domain: enrichedDomain, aggregatedBins});
}
/**
* Shared renderLayers() wrapper that re-classifies bins when custom colorMap
- * changes between renders without triggering a full re-aggregation.
+ * or Jenks class count changes between renders without a full re-aggregation.
+ * Jenks breaks are reused from `jenksColorMapCache` until the bin values or
+ * palette size change.
*
* @param layer The enhanced layer instance (`this`)
* @param ParentClass The deck.gl parent class (HexagonLayer or GridLayer)
@@ -152,9 +199,24 @@ export function enrichedAggregationUpdate(layer: any, ParentClass: any, channel:
*/
export function enrichedRenderLayers(layer: any, ParentClass: any): any {
const props = layer.getCurrentLayer().props;
- const {colors, rawColorBinValues, aggregator} = layer.state;
- if (props.colorMap && colors && rawColorBinValues && aggregator?.binCount > 0) {
- classifyBinsByCustomBreaks(colors, aggregator.binCount, props.colorMap, rawColorBinValues);
+ const {colors, rawColorBinValues, aggregator, jenksColorMapCache} = layer.state;
+ if (colors && rawColorBinValues && aggregator?.binCount > 0) {
+ if (props.colorMap) {
+ classifyBinsByCustomBreaks(colors, aggregator.binCount, props.colorMap, rawColorBinValues);
+ } else if (props.jenksScale) {
+ const k = Array.isArray(props.colorRange) ? props.colorRange.length : 0;
+ const cache = resolveJenksColorMapCache(
+ rawColorBinValues,
+ aggregator.binCount,
+ k,
+ jenksColorMapCache
+ );
+ // Assign on state directly: setState during renderLayers would retrigger rendering.
+ if (cache !== jenksColorMapCache) {
+ layer.state.jenksColorMapCache = cache;
+ }
+ classifyBinsByCustomBreaks(colors, aggregator.binCount, cache.colorMap, rawColorBinValues);
+ }
}
return (ParentClass.prototype as any).renderLayers.call(layer);
}
diff --git a/src/deckgl-layers/src/layer-utils/cpu-aggregator.ts b/src/deckgl-layers/src/layer-utils/cpu-aggregator.ts
index 89770b375..5713fd0a0 100644
--- a/src/deckgl-layers/src/layer-utils/cpu-aggregator.ts
+++ b/src/deckgl-layers/src/layer-utils/cpu-aggregator.ts
@@ -4,8 +4,8 @@
/* eslint-disable guard-for-in */
import {console as Console} from 'global/window';
-import {aggregate} from '@kepler.gl/utils';
-import {AGGREGATION_TYPES, SCALE_FUNC} from '@kepler.gl/constants';
+import {aggregate, naturalBreaks} from '@kepler.gl/utils';
+import {AGGREGATION_TYPES, SCALE_FUNC, SCALE_TYPES} from '@kepler.gl/constants';
import {RGBAColor} from '@kepler.gl/types';
import type ClusterBuilder from './cluster-utils';
@@ -303,6 +303,14 @@ export function getDimensionValueDomain(this: CPUAggregator, step, props, dimens
);
}
+ if (props.colorScaleType === SCALE_TYPES.jenks) {
+ const values = this.state.dimensions[key].sortedBins.aggregatedBins
+ .map(bin => bin.value)
+ .filter(Number.isFinite);
+ const k = Array.isArray(props.colorRange) ? props.colorRange.length : 0;
+ valueDomain = naturalBreaks(values, k);
+ }
+
this._setDimensionState(key, {valueDomain});
}
@@ -411,7 +419,7 @@ function getSubLayerAccessor(
const domain = scaleFunc.domain();
const isValueInDomain =
- scaleFunc.scaleType === 'custom'
+ scaleFunc.scaleType === 'custom' || scaleFunc.scaleType === SCALE_TYPES.jenks
? cv >= sortedBins.minValue && cv <= sortedBins.maxValue
: cv >= domain[0] && cv <= domain[domain.length - 1];
diff --git a/src/layers/src/aggregation-layer.ts b/src/layers/src/aggregation-layer.ts
index ad0db7345..e2b158896 100644
--- a/src/layers/src/aggregation-layer.ts
+++ b/src/layers/src/aggregation-layer.ts
@@ -10,7 +10,7 @@ import Layer, {
VisualChannelDescription,
VisualChannels
} from './base-layer';
-import {hexToRgb, aggregate, DataContainerInterface} from '@kepler.gl/utils';
+import {hexToRgb, aggregate, DataContainerInterface, naturalBreaks} from '@kepler.gl/utils';
import {
HIGHLIGH_COLOR_3D,
CHANNEL_SCALES,
@@ -19,7 +19,8 @@ import {
AGGREGATION_TYPES,
ALL_FIELD_TYPES,
GEOJSON_FIELDS,
- GEOARROW_METADATA_KEY
+ GEOARROW_METADATA_KEY,
+ SCALE_TYPES
} from '@kepler.gl/constants';
import {ColorRange, Field, LayerColumn, Merge} from '@kepler.gl/types';
import {KeplerTable, Datasets} from '@kepler.gl/table';
@@ -336,8 +337,9 @@ export default class AggregationLayer extends Layer {
updateLayerVisualChannel({dataContainer}, channel) {
this.validateVisualChannel(channel);
- // When the color scale type changes, recompute colorDomain from stored aggregatedBins.
- // quantile scale needs the full sorted array of bin values; other scales need [min, max].
+ // When the color scale type or palette size changes, recompute colorDomain from
+ // stored aggregatedBins. Quantile needs the full sorted array; Jenks needs k-1
+ // thresholds from those bins; other scales need [min, max].
// aggregatedBins is only populated from onSetColorDomain, so restrict to the color channel.
const visualChannel = this.visualChannels[channel];
if (channel === 'color' && visualChannel && this.config.aggregatedBins) {
@@ -351,6 +353,13 @@ export default class AggregationLayer extends Layer {
.filter(Number.isFinite)
.sort((a, b) => a - b);
this.updateLayerConfig({[domainKey]: sorted});
+ } else if (scaleType === SCALE_TYPES.jenks) {
+ const values = bins.map(b => b.value).filter(Number.isFinite) as number[];
+ const colorRange = visualChannel.range
+ ? this.config.visConfig[visualChannel.range]
+ : undefined;
+ const k = Array.isArray(colorRange?.colors) ? colorRange.colors.length : 0;
+ this.updateLayerConfig({[domainKey]: naturalBreaks(values, k)});
} else {
let min = Infinity;
let max = -Infinity;
@@ -673,6 +682,7 @@ export default class AggregationLayer extends Layer {
colorAggregation: this.config.visConfig.colorAggregation,
colorRange: visConfig.colorRange,
colorMap: visConfig.colorRange.colorMap,
+ colorScale: this.config.colorScale,
filterRange: gpuFilter.filterRange,
...gpuFilter.filterValueUpdateTriggers
},
@@ -687,18 +697,19 @@ export default class AggregationLayer extends Layer {
// deck.gl's aggregation shader maps bin values to a color texture using a
// simple linear interpolation: (value - domain[0]) / (domain[1] - domain[0]).
// It only understands 'quantize', 'quantile', 'ordinal', and 'linear'.
- // kepler.gl's 'custom' scale (d3.scaleThreshold with user-defined break
- // points) cannot be represented in the shader directly. Instead, our
- // ScaleEnhanced*Layer._onAggregationUpdate reclassifies each bin's raw
- // value into a break index [0 … N-1]. We then tell deck.gl to use
- // 'quantize' over [0, N-1] so each index maps to the correct color pixel.
+ // kepler.gl's 'custom' and 'jenks' scales (d3.scaleThreshold) cannot be
+ // represented in the shader directly. Instead, ScaleEnhanced*Layer
+ // reclassifies each bin's raw value into a break index [0 … N-1]. We then
+ // tell deck.gl to use 'quantize' over [0, N-1] so each index maps to the
+ // correct color pixel.
let colorScaleType = this.config.colorScale as string;
let customColorDomain: [number, number] | undefined;
- const isCustomScale = colorScaleType === 'custom';
+ const isCustomScale = colorScaleType === SCALE_TYPES.custom;
+ const isJenksScale = colorScaleType === SCALE_TYPES.jenks;
const colorMap = isCustomScale ? visConfig.colorRange.colorMap : undefined;
- if (isCustomScale && colorMap) {
- colorScaleType = 'quantize';
- customColorDomain = [0, colorMap.length - 1];
+ if ((isCustomScale && colorMap) || isJenksScale) {
+ colorScaleType = SCALE_TYPES.quantize;
+ customColorDomain = [0, visConfig.colorRange.colors.length - 1];
}
return {
@@ -709,6 +720,7 @@ export default class AggregationLayer extends Layer {
colorRange: this.getColorRange(visConfig.colorRange),
colorMap,
colorScaleType,
+ jenksScale: isJenksScale,
...(customColorDomain ? {colorDomain: customColorDomain} : {}),
upperPercentile: visConfig.percentile[1],
lowerPercentile: visConfig.percentile[0],
diff --git a/src/layers/src/base-layer.ts b/src/layers/src/base-layer.ts
index 5716ab2ee..46339b3ff 100644
--- a/src/layers/src/base-layer.ts
+++ b/src/layers/src/base-layer.ts
@@ -1286,9 +1286,11 @@ class Layer implements KeplerLayer {
return getScale;
}
- return SCALE_FUNC[fixed ? 'linear' : scale]()
+ const scaleFunc = SCALE_FUNC[fixed ? 'linear' : scale]()
.domain(domain)
.range(fixed ? domain : range);
+ (scaleFunc as {scaleType?: string}).scaleType = fixed ? 'linear' : scale;
+ return scaleFunc;
}
/**
@@ -1553,7 +1555,8 @@ class Layer implements KeplerLayer {
return defaultDomain;
}
- return dataset.getColumnLayerDomain(field, scaleType) || defaultDomain;
+ const range = this.config.visConfig[visualChannel.range];
+ return dataset.getColumnLayerDomain(field, scaleType, range) || defaultDomain;
}
hasHoveredObject(objectInfo) {
diff --git a/src/layers/src/vector-tile/vector-tile-layer.ts b/src/layers/src/vector-tile/vector-tile-layer.ts
index 1f560842a..521ef9a70 100644
--- a/src/layers/src/vector-tile/vector-tile-layer.ts
+++ b/src/layers/src/vector-tile/vector-tile-layer.ts
@@ -413,6 +413,9 @@ export default class VectorTileLayer extends AbstractTileLayer<VectorTile, Featu
getScaleOptions(channelKey: string): string[] {
let options = KeplerLayer.prototype.getScaleOptions.call(this, channelKey);
+ // Jenks needs the full value distribution, which tilesets don't provide.
+ options = options.filter(scale => scale !== SCALE_TYPES.jenks);
+
const channel = this.visualChannels.strokeColor;
const field = this.config[channel.field];
if (
diff --git a/src/reducers/src/vis-state-updaters.ts b/src/reducers/src/vis-state-updaters.ts
index 7dedd2e31..6218eb86d 100644
--- a/src/reducers/src/vis-state-updaters.ts
+++ b/src/reducers/src/vis-state-updaters.ts
@@ -1200,6 +1200,25 @@ export function layerVisConfigChangeUpdater(
const newLayer = oldLayer.updateLayerConfig({visConfig: newVisConfig});
+ // Jenks breaks depend on the number of colors. Recalculate the domain when
+ // the color range of a Jenks channel changes.
+ if (oldLayer.config.dataId) {
+ const dataset = state.datasets[oldLayer.config.dataId];
+ if (dataset) {
+ Object.keys(newLayer.visualChannels).forEach(channelKey => {
+ const channel = newLayer.visualChannels[channelKey];
+ if (
+ channel?.scale &&
+ newLayer.config[channel.scale] === SCALE_TYPES.jenks &&
+ channel.range &&
+ Object.prototype.hasOwnProperty.call(action.newVisConfig, channel.range)
+ ) {
+ newLayer.updateLayerVisualChannel(dataset, channelKey);
+ }
+ });
+ }
+ }
+
let nextState = state;
// Exclusive bitmap editing: when editBounds is turned on for one bitmap layer,
diff --git a/src/table/src/kepler-table.ts b/src/table/src/kepler-table.ts
index 7216428b1..351b79aa1 100644
--- a/src/table/src/kepler-table.ts
+++ b/src/table/src/kepler-table.ts
@@ -14,6 +14,7 @@ import {
} from '@kepler.gl/constants';
import {
RGBColor,
+ ColorRange,
Field,
FieldPair,
FieldDomain,
@@ -49,6 +50,7 @@ import {
getLogDomain,
getOrdinalDomain,
getQuantileDomain,
+ getJenksDomain,
DataContainerInterface,
FilterChanged
} from '@kepler.gl/utils';
@@ -795,7 +797,11 @@ class KeplerTable<F extends Field = Field> {
/**
* Get the domain of this column based on scale type
*/
- getColumnLayerDomain(field: F, scaleType: string): number[] | string[] | [number, number] | null {
+ getColumnLayerDomain(
+ field: F,
+ scaleType: string,
+ range?: ColorRange
+ ): number[] | string[] | [number, number] | null {
const {dataContainer, filteredIndexForDomain} = this;
if (!SCALE_TYPES[scaleType]) {
@@ -818,6 +824,15 @@ class KeplerTable<F extends Field = Field> {
case SCALE_TYPES.quantile:
return getQuantileDomain(filteredIndexForDomain, indexValueAccessor, sortFunction);
+ case SCALE_TYPES.jenks:
+ if (!range?.colors) {
+ Console.error(
+ 'the range is either missing or it does not have colors available for Jenks scale domain calculation'
+ );
+ return null;
+ }
+ return getJenksDomain(filteredIndexForDomain, indexValueAccessor, range.colors.length);
+
case SCALE_TYPES.log:
return getLogDomain(filteredIndexForDomain, indexValueAccessor);
diff --git a/src/utils/src/data-scale-utils.ts b/src/utils/src/data-scale-utils.ts
index 603824c5f..18953a106 100644
--- a/src/utils/src/data-scale-utils.ts
+++ b/src/utils/src/data-scale-utils.ts
@@ -27,6 +27,7 @@ import {isRgbColor, rgbToHex, hexToRgb} from './color-utils';
import {DataContainerInterface} from './data-container-interface';
import {formatNumber, isNumber, reverseFormatNumber, unique} from './data-utils';
import {getTimeWidgetHintFormatter} from './filter-utils';
+import naturalBreaks from './jenks';
import {isPlainObject} from './utils';
export type ColorBreak = {
@@ -63,6 +64,23 @@ export function getQuantileDomain(
return values.filter(notNullorUndefined).sort(sortFunc);
}
+/**
+ * Return Jenks natural-break thresholds for an array of data.
+ * `k` is the number of color classes (range length).
+ */
+export function getJenksDomain(
+ data: any[],
+ valueAccessor: dataValueAccessor | undefined,
+ k: number
+): number[] {
+ const values =
+ typeof valueAccessor === 'function'
+ ? data.map(valueAccessor).filter(isNumber)
+ : data.filter(isNumber);
+
+ return naturalBreaks(values, k);
+}
+
/**
* return ordinal domain for a data container
*/
@@ -237,7 +255,7 @@ export function getQuantLegends(scale: D3ScaleFunction, labelFormat: LabelFormat
const thresholdLabelFormat = (n, type) =>
n && labelFormat ? labelFormat(n) : n ? formatNumber(n, type) : 'no value';
const labels =
- scale.scaleType === 'threshold'
+ scale.scaleType === 'threshold' || scale.scaleType === SCALE_TYPES.jenks
? getThresholdLabels(scale, thresholdLabelFormat)
: scale.scaleType === 'custom'
? getThresholdLabels(scale, customScaleLabelFormat)
@@ -307,6 +325,9 @@ export function getLegendOfScale({
}
const formatLabel = labelFormat || getQuantLabelFormat(scale.domain(), fieldType);
+ if (scaleType === SCALE_TYPES.jenks) {
+ scale.scaleType = SCALE_TYPES.jenks;
+ }
return getQuantLegends(scale, formatLabel);
}
diff --git a/src/utils/src/index.ts b/src/utils/src/index.ts
index 4477203be..132bd0822 100644
--- a/src/utils/src/index.ts
+++ b/src/utils/src/index.ts
@@ -170,6 +170,7 @@ export {
colorBreaksToColorMap,
getLayerColorScale,
getLegendOfScale,
+ getJenksDomain,
getLinearDomain,
getLogDomain,
getOrdinalDomain,
@@ -215,6 +216,7 @@ export type {DatabaseAdapter, DatabaseConnection} from './application-config-typ
export {isAppleDevice} from './browser-utils';
export {default as quickInsertionSort} from './quick-insertion-sort';
+export {default as naturalBreaks} from './jenks';
export type {KeplerTableModel} from './types';
diff --git a/src/utils/src/jenks.ts b/src/utils/src/jenks.ts
new file mode 100644
index 000000000..2461e02cd
--- /dev/null
+++ b/src/utils/src/jenks.ts
@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import quickInsertionSort from './quick-insertion-sort';
+
+type JenksLocalResult = {
+ gvf: number;
+ breakValues: number[];
+};
+
+/**
+ * Permutation-based Jenks natural breaks.
+ * Returns k-1 thresholds for a d3 threshold scale (or fewer when unique values < k).
+ */
+export default function naturalBreaks(data: number[], k: number): number[] {
+ const dataSize = data.length;
+ const sortedData = data.slice();
+
+ quickInsertionSort(sortedData);
+
+ // Unique values and the first index of each in the sorted array.
+ const uniqueValPositions: number[] = [];
+ for (let i = 0; i < dataSize; ++i) {
+ if (i === 0 || sortedData[i] !== sortedData[i - 1]) {
+ uniqueValPositions.push(i);
+ }
+ }
+ const uniqueValuesSize = uniqueValPositions.length;
+
+ // Rule of thumb: small data size -- more permutations; large -- fewer.
+ let permutation = Math.floor(44000000 / Math.max(dataSize, 1));
+ if (permutation < 10) permutation = 10;
+ if (permutation > 1000) permutation = 1000;
+
+ return run();
+
+ function run(): number[] {
+ if (k <= 1 || uniqueValuesSize <= 0) {
+ return [];
+ }
+
+ if (k >= uniqueValuesSize) {
+ // Each unique value is its own class. A threshold scale with k colors
+ // needs exactly k-1 edges, so pad duplicate thresholds only up to that.
+ let breaks = uniqueValPositions.map(i => sortedData[i]);
+ if (uniqueValuesSize > 1) {
+ breaks = breaks.slice(1);
+ }
+ const lastBreak = breaks[breaks.length - 1];
+ for (let i = breaks.length; i < k - 1; ++i) {
+ breaks.push(lastBreak);
+ }
+ return breaks;
+ }
+
+ const gssd = computeGSSD();
+ return findBestBreaks(gssd, permutation);
+ }
+
+ function findBestBreaks(gssd: number, perm: number): number[] {
+ let bestGvf = 0;
+ let bestBreaks: number[] = [];
+
+ for (let i = 0; i < perm; ++i) {
+ const localResult = computeLocalSSD(i, gssd);
+ if (localResult.gvf > bestGvf) {
+ bestGvf = localResult.gvf;
+ bestBreaks = localResult.breakValues;
+ }
+ }
+ return bestBreaks;
+ }
+
+ function computeGSSD(): number {
+ let sum = 0;
+ for (let i = 0; i < dataSize; ++i) {
+ sum += sortedData[i];
+ }
+ const mean = dataSize === 0 ? 0 : sum / dataSize;
+
+ let gssd = 0;
+ for (let i = 0; i < dataSize; ++i) {
+ const diff = sortedData[i] - mean;
+ gssd += diff * diff;
+ }
+ return gssd;
+ }
+
+ /**
+ * A single iteration of Bob Jenkins' One-At-A-Time hashing algorithm.
+ * Used as a deterministic seed for the PRNG.
+ */
+ function hash(x: number): number {
+ x += (x << 10) >>> 0;
+ if (x > 4294967295) x = x & 4294967295;
+ x ^= x >> 6;
+ x += (x << 3) >>> 0;
+ if (x > 4294967295) x = x & 4294967295;
+ x ^= x >> 11;
+ x += (x << 15) >>> 0;
+ if (x > 4294967295) x = x & 4294967295;
+ return x;
+ }
+
+ /**
+ * Seeded PRNG: https://gist.github.com/tommyettinger/46a874533244883189143505d203312c
+ */
+ function mulberry32(a: number): () => number {
+ return () => {
+ let t = (a += 0x6d2b79f5);
+ t = Math.imul(t ^ (t >>> 15), t | 1);
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+ }
+
+ function pickRandomPositions(seed: number): number[] {
+ const rng = mulberry32(seed);
+ const randomPositions = new Set<number>();
+ // Skip index 0: a break at the first element creates an empty first class.
+ const candidatePositions = uniqueValPositions.slice(1);
+ const poolSize = candidatePositions.length;
+ const maxRandNumber = k - 1;
+ while (randomPositions.size < maxRandNumber) {
+ const i = Math.floor(rng() * poolSize);
+ randomPositions.add(candidatePositions[i]);
+ }
+ const positions = Array.from(randomPositions);
+ positions.sort((a, b) => a - b);
+ return positions;
+ }
+
+ function localGvf(randomPositions: number[], gssd: number): number {
+ let tssd = 0;
+
+ for (let i = 0; i < k; ++i) {
+ const s = i === 0 ? 0 : randomPositions[i - 1];
+ const e = i === k - 1 ? dataSize : randomPositions[i];
+
+ let localMean = 0;
+ for (let j = s; j < e; ++j) {
+ localMean += sortedData[j];
+ }
+ localMean = localMean / (e - s);
+
+ let localSSD = 0;
+ for (let j = s; j < e; ++j) {
+ const diff = sortedData[j] - localMean;
+ localSSD += diff * diff;
+ }
+ tssd += localSSD;
+ }
+ return gssd === 0 ? 1 : 1 - tssd / gssd;
+ }
+
+ function computeLocalSSD(idx: number, gssd: number): JenksLocalResult {
+ const randomPositions = pickRandomPositions(hash(idx));
+ return {
+ gvf: localGvf(randomPositions, gssd),
+ breakValues: randomPositions.map(i => sortedData[i])
+ };
+ }
+}
diff --git a/test/browser/components/side-panel/channel-by-value-selctor-test.js b/test/browser/components/side-panel/channel-by-value-selctor-test.js
index ddc7d7fda..794d866d4 100644
--- a/test/browser/components/side-panel/channel-by-value-selctor-test.js
+++ b/test/browser/components/side-panel/channel-by-value-selctor-test.js
@@ -215,12 +215,11 @@ test('Components -> ChannelByValueSelector -> ColorScaleSelector -> ColorBreakDi
'Should not disabled color scale select'
);
- // scale optons
- t.equal(
- wrapper.find(ColorScaleSelector).at(0).find('.list__item').length,
- 4,
- 'should render 4 scale options'
- );
+ // scale options: quantize, quantile, jenks, custom
+ const scaleOptions = wrapper.find(ColorScaleSelector).at(0).find('.list__item');
+ t.equal(scaleOptions.length, 5, 'should render 5 scale options');
+ t.equal(scaleOptions.at(2).text(), 'Jenks Natural Breaks', '3rd scale option should be jenks');
+ t.equal(scaleOptions.at(3).text(), 'Custom Breaks', '4th scale option should be custom');
t.equal(wrapper.find(ColorBreaksPanel).length, 1, 'Should render 1 ColorBreaksPanel');
t.equal(wrapper.find(ColorBreaksDisplay).length, 1, 'Should render 1 ColorBreaksDisplay');
@@ -250,7 +249,7 @@ test('Components -> ChannelByValueSelector -> ColorScaleSelector -> ColorBreakDi
}
// select custom scale
- wrapper.find(ColorScaleSelector).at(0).find('.list__item').at(2).simulate('click');
+ wrapper.find(ColorScaleSelector).at(0).find('.list__item').at(3).simulate('click');
t.ok(setColorUI.calledOnce, 'should call setColorUI');
const expectedArgs = [
@@ -525,7 +524,7 @@ test('Components -> ChannelByValueSelector -> ColorScaleSelector -> ColumnStatsC
};
const customTestCase = {
- optionIndex: 2,
+ optionIndex: 3,
optionName: 'custom',
// uses tick positions from the previous test case!
expectedTickPositions: [0, 0, 1]
diff --git a/test/browser/layer-tests/hexagon-layer-specs.js b/test/browser/layer-tests/hexagon-layer-specs.js
index 775f2c838..b41d34447 100644
--- a/test/browser/layer-tests/hexagon-layer-specs.js
+++ b/test/browser/layer-tests/hexagon-layer-specs.js
@@ -15,6 +15,7 @@ import {
} from 'test/helpers/layer-utils';
import {KeplerGlLayers} from '@kepler.gl/layers';
+import {naturalBreaks} from '@kepler.gl/utils';
const {HexagonLayer} = KeplerGlLayers;
const columns = {
@@ -693,3 +694,36 @@ test('#HexagonLayer -> renderHover', t => {
testRenderLayerCases(t, HexagonLayer, TEST_CASES);
t.end();
});
+
+test('#HexagonLayer -> updateLayerVisualChannel jenks', t => {
+ const layer = new HexagonLayer({dataId: 'blue'});
+ const binValues = [1, 1, 1, 50, 51, 52, 1000, 1001, 1002];
+ const colors = ['#000000', '#888888', '#ffffff'];
+
+ layer.updateLayerConfig({
+ colorScale: 'jenks',
+ aggregatedBins: Object.fromEntries(binValues.map((value, i) => [i, {i, value, counts: 1}])),
+ visConfig: {
+ ...layer.config.visConfig,
+ colorRange: {
+ ...layer.config.visConfig.colorRange,
+ colors
+ }
+ }
+ });
+
+ layer.updateLayerVisualChannel({}, 'color');
+
+ t.deepEqual(
+ layer.config.colorDomain,
+ naturalBreaks(binValues, colors.length),
+ 'Jenks aggregation domain should recompute thresholds from bins when the palette changes'
+ );
+ t.notDeepEqual(
+ layer.config.colorDomain,
+ [1, 1002],
+ 'Jenks aggregation domain should not fall back to [min, max]'
+ );
+
+ t.end();
+});
diff --git a/test/node/utils/aggregation-utils-test.js b/test/node/utils/aggregation-utils-test.js
new file mode 100644
index 000000000..14bca72a0
--- /dev/null
+++ b/test/node/utils/aggregation-utils-test.js
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import test from 'tape';
+import {enrichedRenderLayers} from '../../../src/deckgl-layers/src/layer-utils/aggregation-utils';
+
+function ParentClass() {}
+ParentClass.prototype.renderLayers = function renderLayers() {
+ return 'layers';
+};
+
+function createJenksLayer(binValues, colorCount) {
+ const rawColorBinValues = Float32Array.from(binValues);
+ const props = {
+ jenksScale: true,
+ colorRange: Array.from({length: colorCount}, () => [0, 0, 0])
+ };
+ return {
+ state: {
+ colors: {},
+ rawColorBinValues,
+ aggregator: {binCount: rawColorBinValues.length}
+ },
+ getCurrentLayer: () => ({props})
+ };
+}
+
+test('AggregationUtils -> enrichedRenderLayers caches Jenks breaks', t => {
+ const binValues = [1, 1, 1, 50, 51, 52, 1000, 1001, 1002];
+ const layer = createJenksLayer(binValues, 3);
+
+ t.equal(enrichedRenderLayers(layer, ParentClass), 'layers', 'should call parent renderLayers');
+ const firstCache = layer.state.jenksColorMapCache;
+ t.ok(firstCache, 'should store a Jenks color map cache');
+ t.equal(firstCache.k, 3, 'cache should record the palette size');
+ t.equal(firstCache.source, layer.state.rawColorBinValues, 'cache should key off the bin array');
+ t.ok(layer.state.colors.attribute, 'should classify bins on the first render');
+
+ const classifiedAfterFirst = layer.state.colors.attribute.value;
+ enrichedRenderLayers(layer, ParentClass);
+ t.equal(
+ layer.state.jenksColorMapCache,
+ firstCache,
+ 'should reuse the cached Jenks map when bins and k are unchanged'
+ );
+ t.notEqual(
+ layer.state.colors.attribute.value,
+ classifiedAfterFirst,
+ 'should still reclassify bins on later renders'
+ );
+
+ layer.getCurrentLayer().props.colorRange = Array.from({length: 4}, () => [0, 0, 0]);
+ enrichedRenderLayers(layer, ParentClass);
+ t.notEqual(
+ layer.state.jenksColorMapCache,
+ firstCache,
+ 'should recompute Jenks when the palette size changes'
+ );
+ t.equal(layer.state.jenksColorMapCache.k, 4, 'recomputed cache should use the new palette size');
+
+ t.end();
+});
diff --git a/test/node/utils/data-scale-utils-test.js b/test/node/utils/data-scale-utils-test.js
index c35c79765..51a312579 100644
--- a/test/node/utils/data-scale-utils-test.js
+++ b/test/node/utils/data-scale-utils-test.js
@@ -10,6 +10,8 @@ import {
getQuantileDomain,
getLinearDomain,
getLogDomain,
+ getJenksDomain,
+ naturalBreaks,
createDataContainer,
getThresholdsFromQuantiles,
getDomainStepsbyZoom,
@@ -19,7 +21,7 @@ import {
getCategoricalColorMap
} from '@kepler.gl/utils';
import {StateWFilesFiltersLayerColor} from 'test/helpers/mock-state';
-import {SCALE_FUNC} from '@kepler.gl/constants';
+import {SCALE_FUNC, SCALE_TYPES} from '@kepler.gl/constants';
function numberSort(a, b) {
return a - b;
@@ -122,6 +124,72 @@ test('DataScaleUtils -> getLogDomain', t => {
t.end();
});
+test('DataScaleUtils -> naturalBreaks', t => {
+ t.deepEqual(naturalBreaks([], 3), [], 'empty data should return no breaks');
+ t.deepEqual(naturalBreaks([1, 2, 3], 1), [], 'k <= 1 should return no breaks');
+
+ const clustered = [1, 1, 1, 1, 1, 1, 1, 1, 50, 51, 52, 50, 51, 1000, 1001, 1002];
+ const breaks = naturalBreaks(clustered, 3);
+ t.ok(breaks.length >= 2, 'should return thresholds for 3 classes');
+ t.deepEqual(
+ breaks,
+ breaks.slice().sort((a, b) => a - b),
+ 'breaks should be sorted'
+ );
+ t.ok(breaks[0] > 1 && breaks[0] < 1000, 'first break should split the low cluster');
+ t.ok(
+ breaks[breaks.length - 1] >= 50,
+ 'last break should separate the high cluster from the rest'
+ );
+ t.deepEqual(
+ naturalBreaks(clustered.slice(), 3),
+ breaks,
+ 'seeded permutation should be deterministic'
+ );
+ t.ok(
+ breaks.every(b => b > clustered[0]),
+ 'should not place a break at the first value'
+ );
+
+ const sequential = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+ const sequentialBreaks = naturalBreaks(sequential, 3);
+ t.equal(sequentialBreaks.length, 2, 'should return k-1 interior thresholds');
+ t.ok(
+ sequentialBreaks.every(b => b > 0),
+ 'should not sample a break at index 0'
+ );
+
+ const padded = naturalBreaks([1, 2, 3], 5);
+ t.equal(padded.length, 4, 'should pad to k-1 thresholds when k exceeds unique values');
+ t.deepEqual(padded, [2, 3, 3, 3], 'padded thresholds should be the inner unique edges');
+
+ t.end();
+});
+
+test('DataScaleUtils -> getJenksDomain', t => {
+ const quanData = [1, 4, 2, 3, 1, undefined, null, 0];
+ function valueAccessor(d) {
+ return d.value;
+ }
+ const values = [{value: 1}, {value: 0}, {value: -3}, {value: 10}];
+
+ const fromArray = getJenksDomain(quanData, undefined, 3);
+ t.ok(Array.isArray(fromArray) && fromArray.length > 0, 'should compute jenks domain from array');
+ t.deepEqual(
+ fromArray,
+ fromArray.filter(n => typeof n === 'number' && Number.isFinite(n)),
+ 'jenks domain should contain only finite numbers'
+ );
+
+ const fromAccessor = getJenksDomain(values, valueAccessor, 2);
+ t.ok(fromAccessor.length >= 1, 'should compute jenks domain with a value accessor');
+
+ t.equal(SCALE_TYPES.jenks, 'jenks', 'jenks should be a registered scale type');
+ t.ok(typeof SCALE_FUNC[SCALE_TYPES.jenks] === 'function', 'jenks should use a d3 scale factory');
+
+ t.end();
+});
+
test('DataScaleUtils -> getThresholdsFromQuantiles', t => {
t.deepEqual(
getThresholdsFromQuantiles([0, 1, 2, 3, 4, 5], 3),
diff --git a/test/node/utils/index.js b/test/node/utils/index.js
index 93afc3f60..ac57e683c 100644
--- a/test/node/utils/index.js
+++ b/test/node/utils/index.js
@@ -16,6 +16,7 @@ import './mapbox-gl-style-editor-test';
import './mapbox-utils-test';
import './notifications-utils-test';
import './aggregation-test';
+import './aggregation-utils-test';
import './color-util-test';
import './util-test';
import './export-utils-test';