Skip to content

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

13.2 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project

import test from 'tape-catch';

import {
  ChartType,
  LayerChartType,
  BinType,
  buildBigNumber,
  buildGroupedBins,
  buildHeatmapCells,
  buildPivotTable,
  buildTimeSeries,
  createChart,
  propsForChartDatasetChange,
  toChartableDataset,
  computeDatasetChart,
  formatNumber,
  displayBinKey,
  getHoverRowIndexes
} from '@kepler.gl/charts';

function mockDataset(rows) {
  const fields = [
    {name: 'category', type: 'string'},
    {name: 'value', type: 'real'},
    {name: 'time', type: 'timestamp'},
    {name: 'id', type: 'string'}
  ];
  return {
    id: 'test',
    label: 'Test',
    color: [18, 147, 154],
    allIndexes: rows.map((_, i) => i),
    filteredIndex: rows.map((_, i) => i),
    fields,
    getValue: (name, idx) => rows[idx][name]
  };
}

test('charts -> createChart builders', t => {
  const dataset = mockDataset([{category: 'A', value: 10, time: new Date('2020-01-01'), id: '1'}]);
  t.equal(createChart({type: ChartType.bigNumber, dataset}).type, ChartType.bigNumber);
  t.equal(createChart({type: ChartType.barChart, dataset}).type, ChartType.barChart);
  t.equal(createChart({type: ChartType.horizontalBar, dataset}).type, ChartType.horizontalBar);
  t.equal(createChart({type: ChartType.lineChart, dataset}).type, ChartType.lineChart);
  t.equal(createChart({type: ChartType.heatmapChart, dataset}).type, ChartType.heatmapChart);
  t.equal(createChart({type: ChartType.pivotTable, dataset}).type, ChartType.pivotTable);
  t.equal(
    createChart({type: LayerChartType.BREAKDOWN_BY_CATEGORY, dataset, layerId: 'l1'})
      .layerChartType,
    LayerChartType.BREAKDOWN_BY_CATEGORY
  );
  t.equal(createChart({type: LayerChartType.TIME_SERIES, dataset}), null);
  t.end();
});

test('charts -> boolean unique bins keep scalar boolean filter values', t => {
  const rows = [
    {flag: true, value: 1},
    {flag: false, value: 2},
    {flag: true, value: 3}
  ];
  const dataset = {
    id: 'bools',
    label: 'Bools',
    allIndexes: [0, 1, 2],
    filteredIndex: [0, 1, 2],
    fields: [
      {name: 'flag', type: 'boolean'},
      {name: 'value', type: 'real'}
    ],
    getValue: (name, idx) => rows[idx][name]
  };
  const bins = buildGroupedBins({
    dataset,
    applyFilters: true,
    binAxis: {field: {name: 'flag', type: 'boolean'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: {name: 'value', type: 'real'}, aggregation: 'sum'}
  });
  const byKey = Object.fromEntries(bins.map(bin => [String(bin.key), bin]));
  t.deepEqual(byKey.true.filterValue, [true]);
  t.deepEqual(byKey.false.filterValue, [false]);
  t.equal(byKey.true.value, 4);
  t.end();
});

test('charts -> bar without category field is empty', t => {
  const dataset = mockDataset([{category: 'A', value: 10, time: new Date('2020-01-01'), id: '1'}]);
  const chart = createChart({type: ChartType.barChart, dataset});
  chart.xAxis = {field: null, aggregation: BinType.uniqueBin};
  const view = computeDatasetChart(chart, dataset);
  t.equal(view.kind, 'bars');
  t.deepEqual(view.bins, []);
  t.end();
});

test('charts -> buildBigNumber count and sum', t => {
  const dataset = mockDataset([
    {category: 'A', value: 10, time: new Date('2020-01-01'), id: '1'},
    {category: 'B', value: 5, time: new Date('2020-01-02'), id: '1'}
  ]);
  t.equal(buildBigNumber({dataset, applyFilters: true}).value, 2);
  t.equal(
    buildBigNumber({
      dataset,
      applyFilters: true,
      axis: {field: {name: 'value', type: 'real'}, aggregation: 'sum'}
    }).value,
    15
  );
  t.end();
});

test('charts -> buildBigNumber percentiles and countUnique', t => {
  const dataset = mockDataset([
    {category: 'A', value: 10, time: new Date('2020-01-01'), id: '1'},
    {category: 'A', value: 20, time: new Date('2020-01-01'), id: '2'},
    {category: 'B', value: 30, time: new Date('2020-01-02'), id: '3'},
    {category: 'C', value: 40, time: new Date('2020-01-02'), id: '4'}
  ]);
  t.equal(
    buildBigNumber({
      dataset,
      applyFilters: true,
      axis: {field: {name: 'value', type: 'real'}, aggregation: 'p50'}
    }).value,
    25
  );
  t.equal(
    buildBigNumber({
      dataset,
      applyFilters: true,
      axis: {field: {name: 'category', type: 'string'}, aggregation: 'countUnique'}
    }).value,
    3
  );
  t.end();
});

test('charts -> buildGroupedBins unique categories', t => {
  const dataset = mockDataset([
    {category: 'A', value: 10, time: new Date('2020-01-01'), id: '1'},
    {category: 'A', value: 2, time: new Date('2020-01-01'), id: '1'},
    {category: 'B', value: 5, time: new Date('2020-01-02'), id: '2'}
  ]);
  const bins = buildGroupedBins({
    dataset,
    applyFilters: true,
    binAxis: {field: {name: 'category', type: 'string'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: {name: 'value', type: 'real'}, aggregation: 'sum'}
  });
  const byKey = Object.fromEntries(bins.map(bin => [bin.key, bin.value]));
  t.equal(byKey.A, 12);
  t.equal(byKey.B, 5);
  t.end();
});

test('charts -> numeric bin axis spans full domain', t => {
  const dataset = mockDataset([
    {category: 'A', value: 2.54, time: new Date('2020-01-01'), id: '1'},
    {category: 'A', value: 2.55, time: new Date('2020-01-01'), id: '2'},
    {category: 'A', value: 2.56, time: new Date('2020-01-01'), id: '3'},
    {category: 'B', value: 5, time: new Date('2020-01-02'), id: '4'},
    {category: 'C', value: 8, time: new Date('2020-01-02'), id: '5'}
  ]);
  const bins = buildGroupedBins({
    dataset,
    applyFilters: true,
    // uniqueBin leftover should still histogram real fields
    binAxis: {field: {name: 'value', type: 'real'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: null, aggregation: 'count'},
    numGroups: 5,
    sort: 'dataOrder',
    truncate: false
  });
  t.ok(bins.length >= 2, 'should produce multiple numeric bins');
  const first = displayBinKey(String(bins[0].key));
  const last = displayBinKey(String(bins[bins.length - 1].key));
  t.ok(/2(\.\d+)?/.test(first), `first bin starts near min, got ${first}`);
  t.ok(/[78]/.test(last), `last bin reaches max, got ${last}`);
  t.end();
});

test('charts -> numeric bins keep distinct keys when compact labels collide', t => {
  const rows = Array.from({length: 20}, (_, i) => ({
    category: 'A',
    value: 1e6 + i * 500,
    time: new Date('2020-01-01'),
    id: String(i)
  }));
  const dataset = mockDataset(rows);
  const bins = buildGroupedBins({
    dataset,
    applyFilters: true,
    binAxis: {field: {name: 'value', type: 'real'}, aggregation: BinType.numericBin},
    valueAxis: {field: null, aggregation: 'count'},
    numGroups: 10,
    sort: 'dataOrder',
    truncate: false
  });
  const keys = bins.map(bin => bin.key);
  t.equal(new Set(keys).size, keys.length, 'numeric bin keys must be unique');
  t.ok(bins.length >= 8, `expected ~10 bins, got ${bins.length}`);
  t.end();
});

test('charts -> heatmap and pivot table', t => {
  const dataset = mockDataset([
    {category: 'A', value: 10, time: new Date('2020-01-01'), id: 'x'},
    {category: 'B', value: 4, time: new Date('2020-01-01'), id: 'x'},
    {category: 'A', value: 1, time: new Date('2020-01-01'), id: 'y'}
  ]);
  const cells = buildHeatmapCells({
    dataset,
    applyFilters: true,
    xAxis: {field: {name: 'id', type: 'string'}, aggregation: BinType.uniqueBin},
    yAxis: {field: {name: 'category', type: 'string'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: {name: 'value', type: 'real'}, aggregation: 'sum'}
  });
  t.ok(cells.some(cell => cell.x === 'x' && cell.y === 'A' && cell.value === 10));
  const table = buildPivotTable({
    dataset,
    applyFilters: true,
    xAxis: {field: {name: 'id', type: 'string'}, aggregation: BinType.uniqueBin},
    yAxis: {field: {name: 'category', type: 'string'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: {name: 'value', type: 'real'}, aggregation: 'sum'}
  });
  t.equal(table.values.A.x, 10);
  t.equal(table.values.A.y, 1);
  t.end();
});

test('charts -> time series and hover indexes', t => {
  const dataset = mockDataset([
    {category: 'A', value: 10, time: new Date('2020-01-01T00:00:00Z'), id: '1'},
    {category: 'A', value: 5, time: new Date('2020-01-02T00:00:00Z'), id: '1'},
    {category: 'B', value: 99, time: new Date('2020-01-02T00:00:00Z'), id: '2'}
  ]);
  const bins = buildTimeSeries({
    dataset,
    indexes: [0, 1],
    xAxis: {field: {name: 'time', type: 'timestamp'}, aggregation: BinType.timeBin},
    yAxis: {field: {name: 'value', type: 'real'}, aggregation: 'sum'},
    interval: 'day'
  });
  t.equal(bins.length, 2);
  const chart = createChart({
    type: LayerChartType.BREAKDOWN_BY_CATEGORY,
    dataset,
    layerId: 'l1'
  });
  chart.chartDisplay.idField = 'id';
  t.deepEqual(getHoverRowIndexes(dataset, chart, 0), [0, 1]);
  t.end();
});

test('charts -> extra aggregations', t => {
  const dataset = mockDataset([
    {category: 'A', value: 10, time: new Date('2020-01-01'), id: '1'},
    {category: 'A', value: 2, time: new Date('2020-01-01'), id: '1'},
    {category: 'B', value: 5, time: new Date('2020-01-02'), id: '2'}
  ]);
  const unique = buildGroupedBins({
    dataset,
    applyFilters: true,
    binAxis: {field: {name: 'category', type: 'string'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: {name: 'value', type: 'real'}, aggregation: 'countUnique'}
  });
  t.equal(unique.find(bin => bin.key === 'A').value, 2);
  const mode = buildGroupedBins({
    dataset,
    applyFilters: true,
    binAxis: {field: {name: 'category', type: 'string'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: {name: 'value', type: 'real'}, aggregation: 'mode'}
  });
  t.ok(mode.find(bin => bin.key === 'A'));
  const stdev = buildGroupedBins({
    dataset,
    applyFilters: true,
    binAxis: {field: {name: 'category', type: 'string'}, aggregation: BinType.uniqueBin},
    valueAxis: {field: {name: 'value', type: 'real'}, aggregation: 'stdev'}
  });
  t.ok(stdev.find(bin => bin.key === 'A').value > 0);
  t.end();
});

test('charts -> integer categorical fields', t => {
  const fields = [
    {name: 'code', type: 'integer'},
    {name: 'value', type: 'real'}
  ];
  const rows = [
    {code: 1, value: 10},
    {code: 2, value: 5}
  ];
  const dataset = {
    id: 'codes',
    label: 'Codes',
    allIndexes: [0, 1],
    filteredIndex: [0, 1],
    fields,
    getValue: (name, idx) => rows[idx][name]
  };
  const chart = createChart({type: ChartType.barChart, dataset});
  t.equal(chart.xAxis.field.name, 'code');
  t.end();
});

test('charts -> computeDatasetChart big number', t => {
  const dataset = mockDataset([{category: 'A', value: 3, time: new Date('2020-01-01'), id: '1'}]);
  const chart = createChart({type: ChartType.bigNumber, dataset});
  const view = computeDatasetChart(chart, dataset);
  t.equal(view.kind, 'bigNumber');
  t.ok(typeof view.value === 'number');
  t.end();
});

test('charts -> formatNumber uses compact SI instead of scientific notation', t => {
  t.equal(formatNumber(767000), '767k');
  t.equal(formatNumber(123456), '123.5k');
  t.equal(formatNumber(1500000), '1.5M');
  t.equal(formatNumber(9999), '9,999');
  t.equal(formatNumber(42), '42');
  t.equal(formatNumber(3.14159), '3.142');
  t.equal(formatNumber(-1500000), '-1.5M');
  t.end();
});

test('charts -> toChartableDataset does not look up missing fields', t => {
  const missingLookups = [];
  const raw = {
    id: 'new-ds',
    allIndexes: [0, 1, 2],
    filteredIndex: [0, 1, 2],
    fields: [{name: 'mag', type: 'real'}],
    getValue: name => {
      missingLookups.push(name);
      return null;
    }
  };
  const dataset = toChartableDataset(raw);
  t.equal(dataset.getValue('Join_Count', 0), null);
  t.equal(dataset.getValue('Join_Count', 1), null);
  t.deepEqual(missingLookups, [], 'KeplerTable.getValue must not run for unknown fields');
  t.equal(dataset.getValue('mag', 0), null);
  t.deepEqual(missingLookups, ['mag']);
  t.end();
});

test('charts -> switching dataset rebuilds line-chart axes from the new table', t => {
  const oldDataset = mockDataset([
    {category: 'A', value: 1, time: new Date('2020-01-01'), id: '1'}
  ]);
  const chart = createChart({type: ChartType.lineChart, dataset: oldDataset, dataId: 'old'});
  chart.xAxis = {field: {name: 'Join_Count', type: 'integer'}, aggregation: BinType.uniqueBin};
  chart.yAxis = {field: {name: 'Join_Count', type: 'integer'}, aggregation: 'sum'};
  const nextDataset = mockDataset([
    {category: 'B', value: 2, time: new Date('2021-01-01'), id: '2'}
  ]);
  nextDataset.id = 'new';
  const props = propsForChartDatasetChange(chart, nextDataset, {dataId: 'new'});
  t.equal(props.dataId, 'new');
  t.notEqual(props.xAxis.field.name, 'Join_Count');
  t.ok(nextDataset.fields.some(field => field.name === props.xAxis.field.name));
  t.notEqual(props.yAxis.field && props.yAxis.field.name, 'Join_Count');
  const view = computeDatasetChart({...chart, ...props}, nextDataset);
  t.equal(view.kind, 'line');
  t.ok(view.bins.length > 0);
  t.end();
});

test('charts -> stale line-chart field does not emit bins', t => {
  const dataset = mockDataset([{category: 'A', value: 1, time: new Date('2020-01-01'), id: '1'}]);
  const chart = createChart({type: ChartType.lineChart, dataset});
  chart.xAxis = {field: {name: 'Join_Count', type: 'integer'}, aggregation: BinType.uniqueBin};
  const view = computeDatasetChart(chart, dataset);
  t.equal(view.kind, 'line');
  t.deepEqual(view.bins, []);
  t.end();
});