@mathstack/viz 1.1.4 → 2.0.3

package/src/lib/geographies/config/layers/attribute-data-layer/dimensions/custom-breaks/custom-breaks-bins.spec.ts

@@ -0,0 +1,82 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { CustomBreaksBinsAttributeDataDimension } from './custom-breaks-bins';
+import { CustomBreaksBinsAttributeDataDimensionBuilder } from './custom-breaks-bins-builder';
+
+describe('VicCustomBreaksAttributeDataDimension', () => {
+  let dimension: CustomBreaksBinsAttributeDataDimension<any>;
+  beforeEach(() => {
+    dimension = new CustomBreaksBinsAttributeDataDimensionBuilder<any>()
+      .breakValues([0, 2, 5, 10, 50])
+      .range(['red', 'blue', 'yellow', 'green'])
+      .valueAccessor((d) => d)
+      ._build();
+  });
+
+  describe('setPropertiesFromData', () => {
+    beforeEach(() => {
+      spyOn(dimension as any, 'setDomain');
+      spyOn(dimension as any, 'setNumBins');
+      spyOn(dimension as any, 'setRange');
+    });
+    it('calls setDomainAndBins once', () => {
+      dimension.setPropertiesFromData();
+      expect((dimension as any).setDomain).toHaveBeenCalledTimes(1);
+    });
+    it('calls setBins once', () => {
+      dimension.setPropertiesFromData();
+      expect((dimension as any).setNumBins).toHaveBeenCalledTimes(1);
+    });
+    it('calls setRange once', () => {
+      dimension.setPropertiesFromData();
+      expect((dimension as any).setRange).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('setDomain', () => {
+    beforeEach(() => {
+      (dimension as any).breakValues = [0, 2, 5, 10, 50];
+      (dimension as any).setDomain();
+    });
+    it('sets the domain to the correct value', () => {
+      expect((dimension as any).calculatedDomain).toEqual([2, 5, 10, 50]);
+    });
+  });
+
+  describe('setNumBins', () => {
+    it('sets the numBins to the correct value', () => {
+      (dimension as any).breakValues = [0, 2, 5, 10, 50];
+      (dimension as any).setNumBins();
+      expect((dimension as any).calculatedNumBins).toEqual(4);
+    });
+  });
+
+  describe('integration: the scale generates the expected color for a value with the default scale (D3 scaleThreshold)', () => {
+    type IceCream = { price: number; flavor: string; state: string };
+    let dimension: CustomBreaksBinsAttributeDataDimension<IceCream>;
+    const data: IceCream[] = [
+      { price: 7.99, flavor: 'chocolate', state: 'AL' },
+      { price: 5, flavor: 'chocolate', state: 'AK' },
+      { price: 3.98, flavor: 'chocolate', state: 'AR' },
+      { price: 8, flavor: 'vanilla', state: 'AZ' },
+      { price: 11, flavor: 'vanilla', state: 'CA' },
+      { price: 4.99, flavor: 'strawberry', state: 'CO' },
+      { price: 4.5, flavor: 'strawberry', state: 'CT' },
+      { price: 7, flavor: 'strawberry', state: 'DE' },
+    ];
+    it('using custom break values and one color per bin provided as range', () => {
+      dimension = new CustomBreaksBinsAttributeDataDimensionBuilder<IceCream>()
+        .valueAccessor((d) => d.price)
+        .breakValues([2.5, 5, 7.5, 10, 12.5])
+        .range(['red', 'blue', 'yellow', 'green'])
+        .nullColor('black')
+        ._build();
+      dimension.setPropertiesFromData();
+      const scale = dimension.getScale();
+      expect(scale(data[0].price)).toEqual('yellow');
+      expect(scale(data[1].price)).toEqual('blue');
+      expect(scale(data[2].price)).toEqual('red');
+      expect(scale(data[3].price)).toEqual('yellow');
+      expect(scale(data[4].price)).toEqual('green');
+    });
+  });
+});

package/src/lib/geographies/config/layers/attribute-data-layer/dimensions/custom-breaks/custom-breaks-bins.ts

@@ -0,0 +1,81 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { range, scaleLinear } from 'd3';
+import { BinStrategy } from '../attribute-data-bin-enums';
+import { AttributeDataDimension } from '../attribute-data/attribute-data-dimension';
+import { CustomBreaksBinsAttributeDataDimensionOptions } from './custom-breaks-bins-options';
+
+/**
+ * Configuration object for attribute data that is quantitative and will be binned into custom breaks.
+ *
+ * For example, if the data is [0, 1, 2, 4, 60, 100] and breakValues is [0, 2, 5, 10, 50], the bin ranges will be [0, 2], [2, 5], [5, 10], [10, 50], [50, 100].
+ *
+ * The generic parameter is the type of the attribute data.
+ */
+export class CustomBreaksBinsAttributeDataDimension<
+  Datum,
+  RangeValue extends string | number = string,
+>
+  extends AttributeDataDimension<Datum, number, RangeValue>
+  implements CustomBreaksBinsAttributeDataDimensionOptions<Datum, RangeValue>
+{
+  override readonly binType: BinStrategy.customBreaks;
+  readonly breakValues: number[];
+  private calculatedNumBins: number;
+  private calculatedDomain: number[];
+  readonly formatSpecifier: string;
+
+  constructor(
+    options: CustomBreaksBinsAttributeDataDimensionOptions<Datum, RangeValue>
+  ) {
+    super('number');
+    this.binType = BinStrategy.customBreaks;
+    safeAssign(this, options);
+    if (!this.valueAccessor) {
+      console.error(
+        'Value accessor is required for CustomBreaksAttributeDataDimension'
+      );
+    }
+    if (!this.breakValues) {
+      console.error(
+        'breakValues are required for CustomBreaksAttributeDataDimension'
+      );
+    }
+    if (this.breakValues.length < 2) {
+      console.error(
+        'breakValues must have at least two values for CustomBreaksAttributeDataDimension'
+      );
+    }
+    this.breakValues = this.breakValues.slice().sort((a, b) => a - b);
+  }
+
+  setPropertiesFromData(): void {
+    this.setDomain();
+    this.setNumBins();
+    this.setRange();
+  }
+
+  protected setDomain(): void {
+    this.calculatedDomain = this.breakValues.slice(1);
+  }
+
+  private setNumBins(): void {
+    this.calculatedNumBins = this.breakValues.length - 1;
+  }
+
+  protected setRange(): void {
+    if (this.range.length < this.calculatedNumBins) {
+      const scale = scaleLinear<RangeValue>()
+        .domain([0, this.calculatedNumBins - 1])
+        .range(this.range);
+      this.range = range(this.calculatedNumBins).map((i) => scale(i));
+    }
+  }
+
+  getScale() {
+    // the D3.ScaleThreshold domain is an array of naturally ordered values, which are typically numbers but could also be strings. Thus if scale is called with a string value here, it scale will return the first value of the range, not the nullColor. See https://d3js.org/d3-scale/threshold#threshold_domain.
+    return this.scale()
+      .domain(this.calculatedDomain)
+      .range(this.range)
+      .unknown(this.nullColor);
+  }
+}

package/src/lib/geographies/config/layers/attribute-data-layer/dimensions/custom-breaks/custom-breaks.cy.ts

@@ -0,0 +1,378 @@
+/* eslint-disable @angular-eslint/prefer-standalone */
+import { Component, Input } from '@angular/core';
+import {
+  ChartConfig,
+  GeographiesConfig,
+  VicChartConfigBuilder,
+  VicChartModule,
+  VicGeographiesConfigBuilder,
+  VicGeographiesModule,
+} from '@mathstack/viz';
+import { geoMercator } from 'd3';
+import {
+  FeatureCollection,
+  GeoJsonProperties,
+  MultiPolygon,
+  Polygon,
+} from 'geojson';
+import { beforeEach, cy, describe, expect, it } from 'local-cypress';
+import * as topojson from 'topojson-client';
+import { GeometryCollection, Objects, Topology } from 'topojson-specification';
+import {
+  StateIncomePopulationYearDatum,
+  stateIncomePopulationYearData,
+} from '../../../../../../testing/data/state-population-income-year-data';
+
+const margin = { top: 36, right: 36, bottom: 36, left: 36 };
+const chartHeight = 400;
+const chartWidth = 600;
+const attributeData = stateIncomePopulationYearData
+  .filter((x) => x.year === 2020)
+  .filter((x) => x.state !== 'Puerto Rico');
+
+interface TestMapGeometryProperties extends GeoJsonProperties {
+  name: string;
+  id: string;
+}
+
+interface TestMapObjects extends Objects {
+  country: GeometryCollection<TestMapGeometryProperties>;
+  states: GeometryCollection<TestMapGeometryProperties>;
+}
+
+type TestUsMapTopology = Topology<TestMapObjects>;
+
+// ***********************************************************
+// Geographies component set up
+// ***********************************************************
+@Component({
+  // eslint-disable-next-line @angular-eslint/component-selector
+  selector: 'app-test-geographies',
+  template: `
+    <vic-map-chart [config]="chartConfig">
+      <svg:g
+        vic-primary-marks-geographies
+        svg-elements
+        [config]="geographiesConfig"
+        [vicGeographiesHoverActions]="hoverActions"
+        (vicGeographiesHoverOutput)="updateTooltipForNewOutput($event)"
+      ></svg:g>
+    </vic-map-chart>
+  `,
+  styles: [],
+  imports: [VicChartModule, VicGeographiesModule],
+})
+class TestGeographiesComponent {
+  @Input() geographiesConfig: GeographiesConfig<
+    StateIncomePopulationYearDatum,
+    TestMapGeometryProperties
+  >;
+  chartConfig: ChartConfig = new VicChartConfigBuilder()
+    .margin(margin)
+    .maxWidth(chartWidth)
+    .maxHeight(chartHeight)
+    .scalingStrategy('responsive-width')
+    .getConfig();
+}
+
+const mountGeographiesComponent = (
+  geographiesConfig: GeographiesConfig<
+    StateIncomePopulationYearDatum,
+    TestMapGeometryProperties
+  >
+): void => {
+  cy.mount(TestGeographiesComponent, {
+    componentProperties: {
+      geographiesConfig: geographiesConfig,
+    },
+  });
+};
+
+// ***********************************************************
+// Test dimension
+// ***********************************************************
+describe('the Custom Breaks Attribute Data dimension', () => {
+  let geographiesConfig: GeographiesConfig<
+    StateIncomePopulationYearDatum,
+    TestMapGeometryProperties
+  >;
+  beforeEach(() => {
+    geographiesConfig = undefined;
+  });
+  it('User provides break values - it colors states according to break values', () => {
+    const breakValues = [40000, 55000, 70000, 85000, 100000];
+    const rangeValues = ['red', 'orange', 'yellow', 'green'];
+    cy.fixture('usMap.json').then((response) => {
+      const usMap: TestUsMapTopology = response;
+      const usBoundary = topojson.feature(
+        usMap,
+        usMap.objects.country
+      ) as FeatureCollection<MultiPolygon, TestMapGeometryProperties>;
+      const states = topojson.feature(
+        usMap,
+        usMap.objects.states
+      ) as FeatureCollection<MultiPolygon | Polygon, TestMapGeometryProperties>;
+      geographiesConfig = new VicGeographiesConfigBuilder<
+        StateIncomePopulationYearDatum,
+        TestMapGeometryProperties
+      >()
+        .boundary(usBoundary)
+        .featureIndexAccessor((d) => d.properties.name)
+        .attributeDataLayer((dimension) =>
+          dimension
+            .data(attributeData)
+            .class((d) => d.name.split(' ').join('-'))
+            .geographies(states.features)
+            .geographyIndexAccessor((d) => d.state)
+            .customBreaksBins((bins) =>
+              bins
+                .valueAccessor((d) => d.income)
+                .breakValues(breakValues)
+                .range(rangeValues)
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      rangeValues.forEach((color, i) => {
+        const statesInAttributeData = attributeData
+          .filter(
+            (d) => d.income < breakValues[i + 1] && d.income >= breakValues[i]
+          )
+          .map((d) => d.state);
+        statesInAttributeData.forEach((state) => {
+          cy.get(
+            `.vic-geographies-group.${state.split(' ').join('-')} path`
+          ).then((path) => {
+            expect(path.attr('fill')).to.eq(color);
+          });
+        });
+      });
+    });
+  });
+
+  it('User provides break values that do not cover full data range -- values below first value use first color, values above last value use last color', () => {
+    const breakValues = [50000, 60000, 70000, 80000];
+    const rangeValues = ['red', 'orange', 'yellow'];
+    cy.fixture('usMap.json').then((response) => {
+      const usMap: TestUsMapTopology = response;
+      const usBoundary = topojson.feature(
+        usMap,
+        usMap.objects.country
+      ) as FeatureCollection<MultiPolygon, TestMapGeometryProperties>;
+      const states = topojson.feature(
+        usMap,
+        usMap.objects.states
+      ) as FeatureCollection<MultiPolygon | Polygon, TestMapGeometryProperties>;
+      geographiesConfig = new VicGeographiesConfigBuilder<
+        StateIncomePopulationYearDatum,
+        TestMapGeometryProperties
+      >()
+        .boundary(usBoundary)
+        .featureIndexAccessor((d) => d.properties.name)
+        .attributeDataLayer((dimension) =>
+          dimension
+            .data(attributeData)
+            .class((d) => d.name.split(' ').join('-'))
+            .geographies(states.features)
+            .geographyIndexAccessor((d) => d.state)
+            .customBreaksBins((bins) =>
+              bins
+                .valueAccessor((d) => d.income)
+                .breakValues(breakValues)
+                .range(rangeValues)
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      const belowValues = attributeData
+        .filter((d) => d.income < breakValues[0])
+        .map((d) => d.state.replace(/\s/g, '-'));
+      const aboveValues = attributeData
+        .filter((d) => d.income >= breakValues[breakValues.length - 1])
+        .map((d) => d.state.replace(/\s/g, '-'));
+      [
+        { data: belowValues, color: rangeValues[0] },
+        { data: aboveValues, color: rangeValues[rangeValues.length - 1] },
+      ].forEach((group) => {
+        group.data.forEach((state) => {
+          cy.get(
+            `.vic-geographies-group.${state.split(' ').join('-')} path`
+          ).then((path) => {
+            expect(path.attr('fill')).to.eq(group.color);
+          });
+        });
+      });
+    });
+  });
+
+  it('User provides break values that are not in order - it colors states according to break values as though they were in ascending order', () => {
+    const breakValues = [40000, 55000, 70000, 85000, 100000];
+    const rangeValues = ['red', 'orange', 'yellow', 'green'];
+    cy.fixture('usMap.json').then((response) => {
+      const usMap: TestUsMapTopology = response;
+      const usBoundary = topojson.feature(
+        usMap,
+        usMap.objects.country
+      ) as FeatureCollection<MultiPolygon, TestMapGeometryProperties>;
+      const states = topojson.feature(
+        usMap,
+        usMap.objects.states
+      ) as FeatureCollection<MultiPolygon | Polygon, TestMapGeometryProperties>;
+      geographiesConfig = new VicGeographiesConfigBuilder<
+        StateIncomePopulationYearDatum,
+        TestMapGeometryProperties
+      >()
+        .boundary(usBoundary)
+        .featureIndexAccessor((d) => d.properties.name)
+        .attributeDataLayer((dimension) =>
+          dimension
+            .data(attributeData)
+            .class((d) => d.name.split(' ').join('-'))
+            .geographies(states.features)
+            .geographyIndexAccessor((d) => d.state)
+            .customBreaksBins((bins) =>
+              bins
+                .valueAccessor((d) => d.income)
+                .breakValues([
+                  breakValues[1],
+                  breakValues[0],
+                  breakValues[2],
+                  breakValues[4],
+                  breakValues[3],
+                ])
+                .range(rangeValues)
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      rangeValues.forEach((color, i) => {
+        const statesInAttributeData = attributeData
+          .filter(
+            (d) => d.income < breakValues[i + 1] && d.income >= breakValues[i]
+          )
+          .map((d) => d.state);
+        statesInAttributeData.forEach((state) => {
+          cy.get(
+            `.vic-geographies-group.${state.split(' ').join('-')} path`
+          ).then((path) => {
+            expect(path.attr('fill')).to.eq(color);
+          });
+        });
+      });
+    });
+  });
+
+  it('it colors undefined, null, and non-quant values with null color', () => {
+    const breakValues = [40000, 55000, 70000, 85000, 100000];
+    const rangeValues = ['red', 'orange', 'yellow', 'green'];
+    cy.fixture('usMap.json').then((response) => {
+      const usMap: TestUsMapTopology = response;
+      const usBoundary = topojson.feature(
+        usMap,
+        usMap.objects.country
+      ) as FeatureCollection<MultiPolygon, TestMapGeometryProperties>;
+      const states = topojson.feature(
+        usMap,
+        usMap.objects.states
+      ) as FeatureCollection<MultiPolygon | Polygon, TestMapGeometryProperties>;
+      const dataWithFalsyValues = attributeData.map((d) => {
+        if (d.state === 'Texas') {
+          return { ...d, income: null };
+        } else if (d.state === 'California') {
+          return { ...d, income: undefined };
+        } else if (d.state === 'Florida') {
+          return { ...d, income: 'Not a number' as unknown as number };
+        } else {
+          return d;
+        }
+      });
+      const nullColor = 'chartreuse';
+      geographiesConfig = new VicGeographiesConfigBuilder<
+        StateIncomePopulationYearDatum,
+        TestMapGeometryProperties
+      >()
+        .boundary(usBoundary)
+        .featureIndexAccessor((d) => d.properties.name)
+        .attributeDataLayer((dimension) =>
+          dimension
+            .data(dataWithFalsyValues)
+            .class((d) => d.name.split(' ').join('-'))
+            .geographies(states.features)
+            .geographyIndexAccessor((d) => d.state)
+            .customBreaksBins((bins) =>
+              bins
+                .valueAccessor((d) => d.income)
+                .breakValues(breakValues)
+                .range(rangeValues)
+                .nullColor(nullColor)
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      cy.get(`.vic-geographies-group.Florida path`).then((path) => {
+        expect(path.attr('fill')).to.eq(rangeValues[0]);
+      });
+      cy.get(`.vic-geographies-group.Texas path`).then((path) => {
+        expect(path.attr('fill')).to.eq(nullColor);
+      });
+      cy.get(`.vic-geographies-group.California path`).then((path) => {
+        expect(path.attr('fill')).to.eq(nullColor);
+      });
+    });
+  });
+
+  it('it colors geographies not in attribute data with the null color', () => {
+    // island territories like American Samoa, Guam, etc. are not in the attribute data but are in the geojson
+    // they will be drawn with any projection but let's use geoMercator to make them a bit more visible-ish
+    const breakValues = [40000, 55000, 70000, 85000, 100000];
+    const rangeValues = ['red', 'orange', 'yellow', 'green'];
+    cy.fixture('usMap.json').then((response) => {
+      const usMap: TestUsMapTopology = response;
+      const usBoundary = topojson.feature(
+        usMap,
+        usMap.objects.country
+      ) as FeatureCollection<MultiPolygon, TestMapGeometryProperties>;
+      const states = topojson.feature(
+        usMap,
+        usMap.objects.states
+      ) as FeatureCollection<MultiPolygon | Polygon, TestMapGeometryProperties>;
+      const nullColor = 'chartreuse';
+      geographiesConfig = new VicGeographiesConfigBuilder<
+        StateIncomePopulationYearDatum,
+        TestMapGeometryProperties
+      >()
+        .boundary(usBoundary)
+        .projection(geoMercator())
+        .featureIndexAccessor((d) => d.properties.name)
+        .attributeDataLayer((dimension) =>
+          dimension
+            .data(attributeData)
+            .class((d) => d.name.split(' ').join('-'))
+            .geographies(states.features)
+            .geographyIndexAccessor((d) => d.state)
+            .customBreaksBins((bins) =>
+              bins
+                .valueAccessor((d) => d.income)
+                .breakValues(breakValues)
+                .range(rangeValues)
+                .nullColor(nullColor)
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      const geographiesNotInAttributeData = states.features
+        .filter(
+          (x) =>
+            attributeData.findIndex((d) => d.state === x.properties.name) === -1
+        )
+        .map((x) => x.properties.name);
+      geographiesNotInAttributeData.forEach((state) => {
+        cy.get(
+          `.vic-geographies-group.${state.split(' ').join('-')} path`
+        ).then((path) => {
+          expect(path.attr('fill')).to.eq(nullColor);
+        });
+      });
+    });
+  });
+});

package/src/lib/geographies/config/layers/attribute-data-layer/dimensions/equal-frequencies-bins/equal-frequencies-bins-builder.ts

@@ -0,0 +1,50 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { interpolateLab, scaleQuantile } from 'd3';
+import { CalculatedBinsAttributeDataDimensionBuilder } from '../calculated-bins/calculated-bins-builder';
+import { EqualFrequenciesAttributeDataDimension } from './equal-frequencies-bins';
+
+const DEFAULT = {
+  _interpolator: interpolateLab,
+  _nullColor: 'whitesmoke',
+  _numBins: 4,
+  _range: ['white', 'blue'],
+  _scale: scaleQuantile,
+};
+
+export class EqualFrequenciesAttributeDataDimensionBuilder<
+  Datum,
+  RangeValue extends string | number = string,
+> extends CalculatedBinsAttributeDataDimensionBuilder<Datum, RangeValue> {
+  private _numBins: number;
+
+  constructor() {
+    super();
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. The number of bins to create.
+   *
+   * @default 4
+   */
+  numBins(numBins: number): this {
+    this._numBins = numBins;
+    return this;
+  }
+
+  /**
+   * @internal This method is not intended to be used by consumers of this library.
+   */
+  _build(): EqualFrequenciesAttributeDataDimension<Datum, RangeValue> {
+    return new EqualFrequenciesAttributeDataDimension({
+      formatFunction: this._formatFunction,
+      formatSpecifier: this._formatSpecifier,
+      interpolator: this._interpolator,
+      nullColor: this._nullColor,
+      numBins: this._numBins,
+      range: this._range,
+      scale: this._scale,
+      valueAccessor: this._valueAccessor,
+    });
+  }
+}

package/src/lib/geographies/config/layers/attribute-data-layer/dimensions/equal-frequencies-bins/equal-frequencies-bins-options.ts

@@ -0,0 +1,8 @@
+import { CalculatedBinsAttributeDataDimensionOptions } from '../calculated-bins/calculated-bins-options';
+
+export interface EqualFrequenciesAttributeDataDimensionOptions<
+  Datum,
+  RangeValue extends string | number = string,
+> extends CalculatedBinsAttributeDataDimensionOptions<Datum, RangeValue> {
+  numBins: number;
+}