@mathstack/viz 1.1.5 → 2.1.0

package/src/lib/geographies/config/layers/attribute-data-layer/dimensions/equal-value-ranges-bins/equal-value-ranges-bins.cy.ts

@@ -0,0 +1,307 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @angular-eslint/prefer-standalone */
+import { Component, Input } from '@angular/core';
+import {
+  ChartConfig,
+  GeographiesConfig,
+  VicChartConfigBuilder,
+  VicChartModule,
+  VicGeographiesConfigBuilder,
+  VicGeographiesModule,
+} from '@mathstack/viz';
+import { color } 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 Equal Value Ranges Bins Attribute Data dimension', () => {
+  let geographiesConfig: GeographiesConfig<
+    StateIncomePopulationYearDatum,
+    TestMapGeometryProperties
+  >;
+  beforeEach(() => {
+    geographiesConfig = undefined;
+  });
+  it('Uses dimension defaults and creates bins in the data and colors values accordingly with default colors', () => {
+    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)
+            .equalValueRangesBins((bins) => bins.valueAccessor((d) => d.income))
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      const scale =
+        geographiesConfig.attributeDataLayer.attributeDimension.getScale();
+      const ranges = {
+        white: scale.invertExtent('white'),
+        pink: scale.invertExtent('pink'),
+        red: scale.invertExtent('red'),
+      };
+      const whiteRange = ranges.white[1] - ranges.white[0];
+      const pinkRange = ranges.pink[1] - ranges.pink[0];
+      const redRange = ranges.red[1] - ranges.red[0];
+      expect(whiteRange).to.be.closeTo(pinkRange, 1);
+      expect(pinkRange).to.be.closeTo(redRange, 1);
+      cy.get('.vic-geographies-group path').then((states) => {
+        states.each((_, state) => {
+          const fill = state.getAttribute('fill');
+          const datum = attributeData.find(
+            (d) => d.state === state.classList[0].split('-').join(' ')
+          );
+          if (datum) {
+            if (datum.income < ranges.white[1]) {
+              expect(fill).to.equal('white');
+            } else if (datum.income < ranges.pink[1]) {
+              expect(fill).to.equal('pink');
+            } else {
+              expect(fill).to.equal('red');
+            }
+          }
+        });
+      });
+    });
+  });
+
+  it('colors values lower than user-provided domain with first bin color and values higher than user-provided domain with last bin color', () => {
+    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)
+            .equalValueRangesBins((bins) =>
+              bins.valueAccessor((d) => d.income).domain([50000, 80000])
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      cy.get('.vic-geographies-group path').then((states) => {
+        states.each((_, state) => {
+          const fill = state.getAttribute('fill');
+          const datum = attributeData.find(
+            (d) => d.state === state.classList[0].split('-').join(' ')
+          );
+          if (datum) {
+            if (datum.income < 50000) {
+              expect(fill).to.equal('white');
+            }
+            if (datum.income > 80000) {
+              expect(fill).to.equal('red');
+            }
+          }
+        });
+      });
+    });
+  });
+
+  it('colors the map with the number of bins specified in numBins for features with attribute data and a null color for features without attribute data even if the range provides fewer colors', () => {
+    cy.fixture('usMap.json').then((response) => {
+      const numBins = 6;
+      const nullColor = 'navajowhite';
+      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)
+            .equalValueRangesBins((bins) =>
+              bins
+                .valueAccessor((d) => d.income)
+                .numBins(numBins)
+                .nullColor(nullColor)
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      const colors = [];
+      cy.get('.vic-geographies-group path').then((states) => {
+        states.each((_, state) => {
+          const fill = state.getAttribute('fill');
+          if (!colors.includes(fill)) {
+            colors.push(fill);
+          }
+        });
+        expect(colors.length).to.equal(numBins + 1);
+        expect(colors).to.include(nullColor);
+      });
+    });
+  });
+
+  it('colors the map with the first numBins colors in the range for features with attribute data and the nullColor for features without attribute data if numBins is a smaller number than the length of the range', () => {
+    cy.fixture('usMap.json').then((response) => {
+      const numBins = 2;
+      const nullColor = 'navajowhite';
+      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)
+            .equalValueRangesBins((bins) =>
+              bins
+                .valueAccessor((d) => d.income)
+                .numBins(numBins)
+                .nullColor(nullColor)
+            )
+        )
+        .getConfig();
+      mountGeographiesComponent(geographiesConfig);
+      const colors = [];
+      cy.get('.vic-geographies-group path').then((states) => {
+        states.each((_, state) => {
+          const fill = state.getAttribute('fill');
+          if (!colors.includes(fill)) {
+            colors.push(fill);
+          }
+        });
+        expect(colors.length).to.equal(numBins + 1);
+        expect(colors).to.include(nullColor);
+        expect(colors).to.include(color('white').formatRgb());
+        expect(colors).to.include(color('pink').formatRgb());
+      });
+    });
+  });
+});

package/src/lib/geographies/config/layers/attribute-data-layer/dimensions/equal-value-ranges-bins/equal-value-ranges-bins.spec.ts

@@ -0,0 +1,104 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { EqualValueRangesAttributeDataDimension } from './equal-value-ranges-bins';
+import { EqualValueRangesBinsBuilder } from './equal-value-ranges-bins-builder';
+
+describe('VicEqualValuesAttributeDataDimension', () => {
+  let dimension: EqualValueRangesAttributeDataDimension<any>;
+  beforeEach(() => {
+    dimension = new EqualValueRangesBinsBuilder<any>()
+      .numBins(3)
+      .formatSpecifier('.1f')
+      .range(['red', 'blue', 'yellow', 'green'])
+      .domain([0, 20])
+      .valueAccessor((d) => d)
+      ._build();
+  });
+
+  describe('setPropertiesFromData', () => {
+    beforeEach(() => {
+      spyOn(dimension as any, 'setDomain');
+      spyOn(dimension as any, 'setValidatedDomainAndNumBins');
+      spyOn(dimension as any, 'setRange');
+    });
+    it('calls setDomain once', () => {
+      dimension.setPropertiesFromData([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+      expect((dimension as any).setDomain).toHaveBeenCalledOnceWith([
+        1, 2, 3, 4, 5, 6, 7, 8, 9,
+      ]);
+    });
+    it('calls setValidatedDomainAndNumBins once', () => {
+      dimension.setPropertiesFromData([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+      expect(
+        (dimension as any).setValidatedDomainAndNumBins
+      ).toHaveBeenCalledTimes(1);
+    });
+    it('calls setRange once', () => {
+      dimension.setPropertiesFromData([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+      expect((dimension as any).setRange).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('integration: setDomain/setValidatedDomainAndNumBins', () => {
+    it('sets the domain to the users value if it exists', () => {
+      (dimension as any).setDomain([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+      (dimension as any).setValidatedDomainAndNumBins();
+      expect((dimension as any).calculatedDomain).toEqual([0, 20]);
+    });
+    it('sets the domain to values if there is no user provided domain', () => {
+      dimension = new EqualValueRangesBinsBuilder<any>()
+        .numBins(3)
+        .formatSpecifier('.1f')
+        .range(['red', 'blue', 'yellow', 'green'])
+        .valueAccessor((d) => d)
+        ._build();
+      (dimension as any).setDomain([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+      expect((dimension as any).calculatedDomain).toEqual([1, 9]);
+    });
+  });
+
+  describe('getValidatedNumBinsAndDomainForIntegerValues', () => {
+    it('returns a numBins that reflects possible values in domain and a domain of [min, max + 1] when numBins is greater than the length of the data', () => {
+      expect(
+        (dimension as any).getValidatedNumBinsAndDomainForIntegerValues(
+          5,
+          [-1, 1]
+        )
+      ).toEqual({ numBins: 3, domain: [-1, 2] });
+    });
+    it('returns the correct values when numBins is less than the length of the data', () => {
+      expect(
+        (dimension as any).getValidatedNumBinsAndDomainForIntegerValues(
+          2,
+          [-1, 33]
+        )
+      ).toEqual({ numBins: 2, domain: [-1, 33] });
+    });
+  });
+
+  describe('integration: getScale', () => {
+    let scale: any;
+    beforeEach(() => {
+      dimension = new EqualValueRangesBinsBuilder<any>()
+        .numBins(4)
+        .formatSpecifier('.1f')
+        .range(['red', 'blue', 'yellow', 'green'])
+        .valueAccessor((d) => d)
+        .nullColor('black')
+        ._build();
+      dimension.setPropertiesFromData([0, 2, 4, 6, 8]);
+      scale = dimension.getScale();
+    });
+    it('correctly sets the domain', () => {
+      expect(scale.domain()).toEqual([0, 8]);
+    });
+    it('correctly sets the range', () => {
+      expect(scale.range()).toEqual(['red', 'blue', 'yellow', 'green']);
+    });
+    it('correctly scales a value in the domain', () => {
+      expect(scale(2)).toEqual('blue');
+    });
+    it('correctly scales a value out of the domain', () => {
+      expect(scale(null)).toEqual('black');
+    });
+  });
+});

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

@@ -0,0 +1,89 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { extent } from 'd3';
+import { BinStrategy } from '../attribute-data-bin-enums';
+import { CalculatedBinsAttributeDataDimension } from '../calculated-bins/calculated-bins';
+import { EqualValueRangesAttributeDataDimensionOptions } from './equal-value-ranges-bins-options';
+
+/**
+ * Configuration object for attribute data that is quantitative and will be binned into equal value ranges. For example, if the data is [0, 1, 2, 4, 60, 100] and numBins is 2, the bin ranges will be [0, 49] and [50, 100].
+ *
+ * The generic parameter is the type of the attribute data.
+ */
+export class EqualValueRangesAttributeDataDimension<
+  Datum,
+  RangeValue extends string | number = string,
+>
+  extends CalculatedBinsAttributeDataDimension<Datum, RangeValue>
+  implements EqualValueRangesAttributeDataDimensionOptions<Datum, RangeValue>
+{
+  override readonly binType: BinStrategy.equalValueRanges;
+  private calculatedDomain: [number, number];
+  readonly domain: [number, number];
+  readonly numBins: number;
+
+  constructor(
+    options: EqualValueRangesAttributeDataDimensionOptions<Datum, RangeValue>
+  ) {
+    super('number');
+    this.binType = BinStrategy.equalValueRanges;
+    safeAssign(this, options);
+    if (!this.valueAccessor) {
+      console.error(
+        'Value accessor is required for EqualValuesAttributeDataDimension'
+      );
+    }
+  }
+
+  setPropertiesFromData(data: Datum[]): void {
+    const values = data.map(this.valueAccessor);
+    this.setDomain(values);
+    this.setValidatedDomainAndNumBins();
+    this.setRange();
+  }
+
+  protected setDomain(values: number[]): void {
+    const domainValues = this.domain ?? values;
+    this.calculatedDomain = extent(domainValues);
+  }
+
+  private setValidatedDomainAndNumBins(): void {
+    if (this.valueFormatIsInteger()) {
+      const validated = this.getValidatedNumBinsAndDomainForIntegerValues(
+        this.numBins,
+        this.calculatedDomain
+      );
+      this.calculatedNumBins = validated.numBins;
+      this.calculatedDomain = validated.domain;
+    } else {
+      this.calculatedNumBins = this.numBins;
+    }
+  }
+
+  protected valueFormatIsInteger(): boolean {
+    return this.formatSpecifier && this.formatSpecifier.includes('0f');
+  }
+
+  protected getValidatedNumBinsAndDomainForIntegerValues(
+    numBins: number,
+    domain: [number, number]
+  ): {
+    numBins: number;
+    domain: [number, number];
+  } {
+    const validated = { numBins, domain };
+    const dataRange = domain.map((x) => Math.round(x));
+    const numDiscreteValues = Math.abs(dataRange[1] - dataRange[0]) + 1;
+    if (numDiscreteValues < numBins) {
+      validated.numBins = numDiscreteValues;
+      validated.domain = [dataRange[0], dataRange[1] + 1];
+    }
+    return validated;
+  }
+
+  getScale() {
+    return this.scale()
+      .domain(this.calculatedDomain)
+      .range(this.range)
+      .unknown(this.nullColor);
+  }
+}

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

@@ -0,0 +1,62 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { interpolateLab, scaleLinear } from 'd3';
+import { AttributeDataDimensionBuilder } from '../attribute-data/attribute-data-dimension-builder';
+import { NoBinsAttributeDataDimension } from './no-bins';
+
+const DEFAULT = {
+  _interpolator: interpolateLab,
+  _nullColor: 'whitesmoke',
+  _range: ['white', 'slategray'],
+  _scale: scaleLinear,
+};
+
+/**
+ * Configuration object for attribute data that is quantitative and does not have bins.
+ *
+ * The generic parameter is the type of the attribute data.
+ */
+export class NoBinsAttributeDataDimensionBuilder<
+  Datum,
+> extends AttributeDataDimensionBuilder<Datum, number> {
+  private _domain: [number, number];
+  private _formatSpecifier: string;
+
+  constructor() {
+    super();
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. The domain of the scale. If not set, the domain will be inferred from the data.
+   */
+  domain(domain: [number, number]): this {
+    this._domain = domain;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Sets a format specifier that will be applied to the value of this dimension using D3 format for display purposes.
+   *
+   * For example, this will format data values shown in a tooltip
+   */
+  formatSpecifier(formatSpecifier: string): this {
+    this._formatSpecifier = formatSpecifier;
+    return this;
+  }
+
+  /**
+   * @internal This method is not intended to be used by consumers of this library.
+   */
+  _build(): NoBinsAttributeDataDimension<Datum> {
+    return new NoBinsAttributeDataDimension({
+      domain: this._domain,
+      formatFunction: this._formatFunction,
+      formatSpecifier: this._formatSpecifier,
+      interpolator: this._interpolator,
+      nullColor: this._nullColor,
+      range: this._range,
+      scale: this._scale,
+      valueAccessor: this._valueAccessor,
+    });
+  }
+}

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

@@ -0,0 +1,8 @@
+import { AttributeDataDimensionOptions } from '../attribute-data/attribute-data-dimension-options';
+
+export interface NoBinsAttributeDataDimensionOptions<
+  Datum,
+> extends AttributeDataDimensionOptions<Datum, number> {
+  domain: [number, number];
+  formatSpecifier: string;
+}