@buildcanada/charts 0.1.0

package/src/grapher/color/BinningStrategyLogarithmic.ts

@@ -0,0 +1,121 @@
+import { numberMagnitude, RequiredBy } from "../../utils/index.js"
+import {
+    BinningStrategyIncludingManual,
+    LogBinningStrategy,
+    ResolvedLogBinningStrategy,
+} from "../../types/index.js"
+import {
+    calcMagnitudeDiff,
+    pruneUnusedBins,
+    ResolvedBinningStrategyConfig,
+} from "./BinningStrategies.js"
+import * as R from "remeda"
+import { match } from "ts-pattern"
+
+export const isLogBinningStrategy = (
+    strategy: BinningStrategyIncludingManual
+): strategy is LogBinningStrategy => strategy.startsWith("log-")
+
+/**
+ * Automatically chooses a log binning strategy based on the magnitude difference between the min and max values.
+ * Very roughly, the resulting number of bins is roughly magnitudeDiff * numberOfLogSteps.
+ *
+ * The threshold numbers in here are chosen empirically by experimentation.
+ * The main idea is that we want to ideally have 5-8 bins, and with the number of resulting bins very roughly
+ * being `magnitudeDiff * numberOfLogSteps`, we arrive roughly at these thresholds:
+ * - for magnitudeDiff < 2.6, and 3 log steps, we'll end up with up to 8 bins
+ * - for magnitudeDiff between 2.6 and 3.6, and 2 log steps, we'll end up with 5 to 8 bins
+ * - for magnitudeDiff >= 3.6, and 1 log step, we'll end up with >=4 bins
+ * - ... there's probably also cases where we can end up with more than 8 bins, but these should be pretty rare
+ *   (and in these case, the authors can still manually choose a different strategy)
+ */
+const autoChooseLogBinningStrategy = (
+    magnitudeDiff: number
+): ResolvedLogBinningStrategy => {
+    if (magnitudeDiff >= 3.6) {
+        return "log-10"
+    }
+    if (magnitudeDiff >= 2.6) {
+        return "log-1-3"
+    }
+    return "log-1-2-5"
+}
+
+export const runLogBinningStrategy = (
+    conf: RequiredBy<ResolvedBinningStrategyConfig, "minValue" | "maxValue">,
+    { hasMidpoint }: { hasMidpoint?: boolean } = {}
+): number[] => {
+    const { minValue, maxValue } = conf
+
+    if (minValue <= 0 || maxValue <= 0) {
+        throw new Error("Log binning strategy only supports positive values")
+    }
+
+    let resolvedStrategy: ResolvedLogBinningStrategy
+    if (conf.strategy === "log-auto") {
+        let magnitudeDiff = calcMagnitudeDiff(minValue, maxValue)
+        if (hasMidpoint) magnitudeDiff *= 1.8 // If there is a midpoint, we want to create fewer bins than we would otherwise
+        resolvedStrategy = autoChooseLogBinningStrategy(magnitudeDiff)
+    } else {
+        resolvedStrategy = conf.strategy as ResolvedLogBinningStrategy
+    }
+
+    const bins = match(resolvedStrategy)
+        .with("log-10", () =>
+            createLogBins({ minValue, maxValue, logSteps: [1] })
+        )
+        .with("log-1-3", () =>
+            createLogBins({ minValue, maxValue, logSteps: [1, 3] })
+        )
+        .with("log-1-2-5", () =>
+            createLogBins({ minValue, maxValue, logSteps: [1, 2, 5] })
+        )
+        .exhaustive()
+
+    // Add the midpoint (most likely zero) if it is not already included in a bin
+    if (
+        !hasMidpoint &&
+        conf.midpoint !== undefined &&
+        bins[0] > conf.midpoint
+    ) {
+        bins.unshift(conf.midpoint)
+    }
+
+    return bins
+}
+
+const createLogBins = ({
+    minValue,
+    maxValue,
+    logSteps,
+}: {
+    minValue: number
+    maxValue: number
+    logSteps: number[]
+}): number[] => {
+    if (minValue <= 0 || maxValue <= 0) {
+        throw new Error("createLogBins only supports positive values")
+    }
+
+    // We need the -1 here to convert between magnitude and logarithms.
+    // Magnitude is defined such that magnitude(1) = 1, whereas log10(1) = 0.
+    // Because we generate factors as 10^magnitude, we need to adjust the values accordingly.
+    const exponentMin = numberMagnitude(minValue) - 1
+    const exponentMax = numberMagnitude(maxValue) - 1
+
+    const candidates = R.range(exponentMin, exponentMax + 1).flatMap(
+        (magnitude) => {
+            const factor = Math.pow(10, magnitude)
+            return logSteps.map((step) => step * factor)
+        }
+    )
+
+    // Adding this extra value at the end is useful if we have, for example, maxValue = 99.
+    // Then the candidates above will go up to 50 (if logSteps includes 5), and here we'll then
+    // add 100 to the mix.
+    if ((R.last(candidates) ?? 0) < maxValue) {
+        candidates.push(1 * Math.pow(10, exponentMax + 1))
+    }
+
+    return pruneUnusedBins(candidates, { minValue, maxValue })
+}

package/src/grapher/color/CategoricalColorAssigner.ts

@@ -0,0 +1,97 @@
+import * as R from "remeda"
+import { Color } from "../../utils/index.js"
+import { ColorScheme } from "./ColorScheme"
+import { getLeastUsedColor } from "./ColorUtils"
+
+type CategoryId = string
+export type CategoricalColorMap = Map<CategoryId, Color>
+export type CategoricalColorMapReadonly = ReadonlyMap<CategoryId, Color>
+
+export interface CategoricalColorAssignerProps {
+    colorScheme: ColorScheme
+    invertColorScheme?: boolean
+
+    /** The custom color mappings (most likely author-specified) to use. */
+    colorMap?: CategoricalColorMap
+
+    /**
+     * A cache for custom colors or automatically selected colors for each identifier
+     * encountered.
+     *
+     * In the Grapher, this is persisted across charts, so that a line chart
+     * that turns into a bar chart will have a matching color scheme across
+     * both states.
+     */
+    autoColorMapCache?: CategoricalColorMap
+
+    numColorsInUse?: number
+}
+
+/**
+ * Assigns custom categorical colors, e.g. specified by an author for entities or variables.
+ *
+ * When an identifier doesn't have an assigned color, it uses the least used color in the scheme.
+ *
+ * Keeps a cache so that identical identifiers are assigned consistent colors. See
+ * Grapher#seriesColorMap for an example of a cache.
+ */
+export class CategoricalColorAssigner {
+    private colorScheme: ColorScheme
+    private invertColorScheme: boolean
+    private colorMap: CategoricalColorMapReadonly
+    private autoColorMapCache: CategoricalColorMap
+    private numColorsInUse?: number
+
+    constructor(props: CategoricalColorAssignerProps) {
+        this.colorScheme = props.colorScheme
+        this.invertColorScheme = props.invertColorScheme ?? false
+        this.colorMap = props.colorMap ?? new Map()
+        this.autoColorMapCache = props.autoColorMapCache ?? new Map()
+        this.numColorsInUse = props.numColorsInUse
+    }
+
+    private get usedColors(): Color[] {
+        const merged: CategoricalColorMap = new Map([
+            ...this.autoColorMapCache,
+            ...this.colorMap,
+        ])
+        return Array.from(merged.values())
+    }
+
+    private get availableColors(): Color[] {
+        // copy the colors array because we might need to reverse it
+        const colors =
+            (this.numColorsInUse !== undefined
+                ? this.colorScheme.getColors(this.numColorsInUse)
+                : R.last(this.colorScheme.colorSets)
+            )?.slice() ?? []
+        if (this.invertColorScheme) return colors.toReversed()
+        else return colors
+    }
+
+    private get leastUsedColor(): Color {
+        const leastUsedColor = getLeastUsedColor(
+            this.availableColors,
+            this.usedColors
+        )
+        // TODO handle this better?
+        if (leastUsedColor === undefined) {
+            // eslint-disable-next-line no-console
+            console.trace("Least used color is undefined, using black.", {
+                availableColors: this.availableColors,
+                usedColors: this.usedColors,
+            })
+        }
+        return leastUsedColor ?? "#000"
+    }
+
+    assign(id: CategoryId): Color {
+        let color = this.colorMap.get(id)
+        if (color === undefined) color = this.autoColorMapCache.get(id)
+        if (color === undefined && this.colorScheme.colorMap)
+            color = this.colorScheme.colorMap[id]
+        if (color === undefined) color = this.leastUsedColor
+        this.autoColorMapCache.set(id, color)
+        return color
+    }
+}

package/src/grapher/color/ColorBrewerSchemes.ts

@@ -0,0 +1,80 @@
+import colorbrewer from "colorbrewer"
+import {
+    Color,
+    ColorSchemeInterface,
+    ColorSchemeName,
+} from "../../types/index.js"
+
+type ColorSchemeProps = { displayName: string; singleColorScale: boolean }
+
+const ColorBrewerSchemeIndex: {
+    [key in ColorSchemeName]?: ColorSchemeProps
+} = {
+    YlGn: { displayName: "Yellow-Green shades", singleColorScale: true },
+    YlGnBu: {
+        displayName: "Yellow-Green-Blue shades",
+        singleColorScale: false,
+    },
+    GnBu: { displayName: "Green-Blue shades", singleColorScale: true },
+    BuGn: { displayName: "Blue-Green shades", singleColorScale: true },
+    PuBuGn: {
+        displayName: "Purple-Blue-Green shades",
+        singleColorScale: false,
+    },
+    BuPu: { displayName: "Blue-Purple shades", singleColorScale: true },
+    RdPu: { displayName: "Red-Purple shades", singleColorScale: true },
+    PuRd: { displayName: "Purple-Red shades", singleColorScale: true },
+    OrRd: { displayName: "Orange-Red shades", singleColorScale: true },
+    YlOrRd: {
+        displayName: "Yellow-Orange-Red shades",
+        singleColorScale: true,
+    },
+    YlOrBr: {
+        displayName: "Yellow-Orange-Brown shades",
+        singleColorScale: true,
+    },
+    Purples: { displayName: "Purple shades", singleColorScale: true },
+    Blues: { displayName: "Blue shades", singleColorScale: true },
+    Greens: { displayName: "Green shades", singleColorScale: true },
+    Oranges: { displayName: "Orange shades", singleColorScale: true },
+    Reds: { displayName: "Red shades", singleColorScale: true },
+    Greys: { displayName: "Grey shades", singleColorScale: true },
+    PuOr: { displayName: "Purple-Orange", singleColorScale: false },
+    BrBG: { displayName: "Brown-Blue-Green", singleColorScale: false },
+    PRGn: { displayName: "Purple-Red-Green", singleColorScale: false },
+    PiYG: { displayName: "Magenta-Yellow-Green", singleColorScale: false },
+    RdBu: { displayName: "Red-Blue", singleColorScale: false },
+    RdGy: { displayName: "Red-Grey", singleColorScale: false },
+    RdYlBu: { displayName: "Red-Yellow-Blue", singleColorScale: false },
+    Spectral: { displayName: "Spectral colors", singleColorScale: false },
+    RdYlGn: { displayName: "Red-Yellow-Green", singleColorScale: false },
+    Accent: { displayName: "Accents", singleColorScale: false },
+    Dark2: { displayName: "Dark colors", singleColorScale: false },
+    Paired: { displayName: "Paired colors", singleColorScale: false },
+    Pastel1: { displayName: "Pastel 1 colors", singleColorScale: false },
+    Pastel2: { displayName: "Pastel 2 colors", singleColorScale: false },
+    Set1: { displayName: "Set 1 colors", singleColorScale: false },
+    Set2: { displayName: "Set 2 colors", singleColorScale: false },
+    Set3: { displayName: "Set 3 colors", singleColorScale: false },
+    PuBu: { displayName: "Purple-Blue shades", singleColorScale: true },
+} as const
+
+export const getColorBrewerScheme: (
+    name: string
+) => ColorSchemeInterface | undefined = (name: string) => {
+    const props = ColorBrewerSchemeIndex[name as ColorSchemeName]
+    const colorSets = (colorbrewer as any)[name]
+
+    if (!props || !colorSets) return undefined
+
+    const colorSetsArray: Color[][] = []
+    Object.keys(colorSets).forEach(
+        (numColors) => (colorSetsArray[+numColors] = colorSets[numColors])
+    )
+    return {
+        name,
+        displayName: props.displayName,
+        colorSets: colorSetsArray,
+        singleColorScale: props.singleColorScale,
+    }
+}

package/src/grapher/color/ColorConstants.ts

@@ -0,0 +1,20 @@
+// gray shades
+export const GRAY_100 = "#2d2e2d"
+export const GRAY_90 = "#4e4e4e"
+export const GRAY_80 = "#5b5b5b"
+export const GRAY_70 = "#767676"
+export const GRAY_60 = "#a1a1a1"
+export const GRAY_50 = "#c6c6c6"
+export const GRAY_30 = "#dadada"
+export const GRAY_20 = "#e7e7e7"
+export const GRAY_10 = "#f2f2f2"
+export const GRAY_5 = "#f7f7f7"
+
+export const GRAPHER_BACKGROUND_DEFAULT = "#ffffff"
+export const GRAPHER_BACKGROUND_BEIGE = "#fbf9f3"
+
+export const GRAPHER_DARK_TEXT = GRAY_80
+export const GRAPHER_LIGHT_TEXT = GRAY_70
+
+export const OWID_NO_DATA_GRAY = "#6e7581"
+export const OWID_ERROR_COLOR = "ff0002"

package/src/grapher/color/ColorScale.ts

@@ -0,0 +1,339 @@
+import * as _ from "lodash-es"
+import { computed, toJS, makeObservable } from "mobx"
+import { ColorScaleConfig } from "./ColorScaleConfig"
+import { mapNullToUndefined, sortNumeric } from "../../utils/index.js"
+import { pairs } from "d3-array"
+import { ColorSchemes } from "../color/ColorSchemes"
+import { ColorScheme } from "../color/ColorScheme"
+import { ColorScaleBin, NumericBin, CategoricalBin } from "./ColorScaleBin"
+import { OWID_NO_DATA_GRAY } from "./ColorConstants"
+import {
+    ColorScaleConfigInterface,
+    ColorSchemeName,
+    Color,
+    CoreValueType,
+    OwidVariableRoundingMode,
+} from "../../types/index.js"
+import { CoreColumn } from "../../core-table/index.js"
+import * as R from "remeda"
+import { runBinningStrategy } from "./BinningStrategies.js"
+
+export const NO_DATA_LABEL = "No data"
+export const PROJECTED_DATA_LABEL = "Projected data"
+
+export interface ColorScaleManager {
+    colorScaleConfig?: ColorScaleConfigInterface
+    hasNoDataBin?: boolean
+    hasProjectedDataBin?: boolean
+    defaultNoDataColor?: string
+    defaultBaseColorScheme?: ColorSchemeName
+    colorScaleColumn?: CoreColumn
+}
+
+export class ColorScale {
+    private manager: Readonly<ColorScaleManager>
+    constructor(manager: ColorScaleManager = {}) {
+        makeObservable(this)
+        this.manager = manager
+    }
+
+    // Config accessors
+
+    @computed get config(): ColorScaleConfigInterface {
+        return this.manager.colorScaleConfig ?? new ColorScaleConfig()
+    }
+
+    @computed get customNumericValues(): number[] {
+        return this.config.customNumericValues ?? []
+    }
+
+    @computed get customNumericColorsActive(): boolean {
+        return this.config.customNumericColorsActive ?? false
+    }
+
+    @computed get customNumericColors(): (Color | undefined)[] {
+        return this.customNumericColorsActive
+            ? mapNullToUndefined(this.config.customNumericColors)
+            : []
+    }
+
+    @computed get customHiddenCategories(): {
+        [key: string]: true | undefined
+    } {
+        return this.config.customHiddenCategories ?? {}
+    }
+
+    @computed get customNumericLabels(): (string | undefined)[] {
+        if (!this.isManualBuckets) return []
+
+        const labels =
+            mapNullToUndefined(toJS(this.config.customNumericLabels)) || []
+        while (labels.length < this.numNumericBins) labels.push(undefined)
+        return labels
+    }
+
+    @computed get isColorSchemeInverted(): boolean {
+        return this.config.colorSchemeInvert ?? false
+    }
+
+    @computed private get customCategoryLabels(): {
+        [key: string]: string | undefined
+    } {
+        return this.config.customCategoryLabels ?? {}
+    }
+
+    @computed get baseColorScheme(): ColorSchemeName {
+        return (
+            this.config.baseColorScheme ??
+            this.manager.defaultBaseColorScheme ??
+            ColorSchemeName.BuGn
+        )
+    }
+
+    @computed private get defaultColorScheme(): ColorScheme {
+        return ColorSchemes.get(ColorSchemeName.BuGn)
+    }
+
+    @computed private get defaultNoDataColor(): Color {
+        return this.manager.defaultNoDataColor ?? OWID_NO_DATA_GRAY
+    }
+
+    @computed get colorScaleColumn(): CoreColumn | undefined {
+        return this.manager.colorScaleColumn
+    }
+
+    @computed get legendDescription(): string | undefined {
+        return this.config.legendDescription
+    }
+
+    // Transforms
+
+    @computed private get hasNoDataBin(): boolean {
+        return this.manager.hasNoDataBin || false
+    }
+
+    @computed private get hasProjectedDataBin(): boolean {
+        return this.manager.hasProjectedDataBin || false
+    }
+
+    @computed get sortedNumericValues(): number[] {
+        return sortNumeric(
+            this.colorScaleColumn?.values.filter(R.isNumber) ?? []
+        )
+    }
+
+    @computed private get minPossibleValue(): number | undefined {
+        return R.first(this.sortedNumericValues)
+    }
+
+    @computed private get maxPossibleValue(): number | undefined {
+        return R.last(this.sortedNumericValues)
+    }
+
+    @computed private get categoricalValues(): string[] {
+        return this.colorScaleColumn?.sortedUniqNonEmptyStringVals ?? []
+    }
+
+    @computed private get colorScheme(): ColorScheme {
+        return ColorSchemes.get(this.baseColorScheme) ?? this.defaultColorScheme
+    }
+
+    @computed get singleColorScale(): boolean {
+        return this.colorScheme.singleColorScale
+    }
+
+    @computed private get manualBinThresholds(): number[] {
+        if (!this.sortedNumericValues.length || this.numNumericBins <= 0)
+            return []
+
+        return this.customNumericValues
+    }
+
+    // When automatic classification is turned on, this takes the numeric map data
+    // and works out some discrete ranges to assign colors to
+    @computed get autoBinThresholds(): number[] {
+        if (this.config.binningStrategy === "manual") {
+            throw new Error(
+                "Cannot compute automatic bin thresholds when binning is set to manual"
+            )
+        }
+        return runBinningStrategy({
+            sortedValues: this.sortedNumericValues,
+            isPercent: this.colorScaleColumn?.shortUnit === "%",
+            numDecimalPlaces: this.colorScaleColumn?.numDecimalPlaces,
+
+            strategy: this.config.binningStrategy,
+            createBinForMidpoint: this.config.createBinForMidpoint,
+            minValue: this.config.minValue,
+            maxValue: this.config.maxValue,
+            midpoint: this.config.midpoint,
+            midpointMode: this.config.midpointMode,
+        }).bins
+    }
+
+    @computed private get bucketThresholds(): number[] {
+        return this.isManualBuckets
+            ? this.manualBinThresholds
+            : this.autoBinThresholds
+    }
+
+    // Ensure there's always a custom color for "No data"
+    @computed private get customCategoryColors(): { [key: string]: Color } {
+        return {
+            [NO_DATA_LABEL]: this.defaultNoDataColor, // default 'no data' color
+            ...this.config.customCategoryColors,
+        }
+    }
+
+    @computed get noDataColor(): Color {
+        return this.customCategoryColors[NO_DATA_LABEL]
+    }
+
+    @computed get baseColors(): Color[] {
+        const { categoricalValues, colorScheme, isColorSchemeInverted } = this
+        const numColors = this.numNumericBins + categoricalValues.length
+        const colors = colorScheme.getColors(numColors)
+
+        if (isColorSchemeInverted) return colors.toReversed()
+        else return colors
+    }
+
+    @computed get isManualBuckets(): boolean {
+        return this.config.binningStrategy === "manual"
+    }
+
+    @computed get numNumericBins(): number {
+        if (!this.sortedNumericValues.length) return 0
+
+        return this.isManualBuckets
+            ? Math.max(this.customNumericValues.length - 1, 0)
+            : this.autoBinThresholds.length - 1
+    }
+
+    @computed private get numericLegendBins(): NumericBin[] {
+        const {
+            customNumericLabels,
+            minPossibleValue,
+            maxPossibleValue,
+            customNumericColors,
+            bucketThresholds,
+            baseColors,
+        } = this
+
+        if (minPossibleValue === undefined || maxPossibleValue === undefined)
+            return []
+
+        return pairs(bucketThresholds).map(([min, max], index) => {
+            const baseColor = baseColors[index]
+            const color = customNumericColors[index] ?? baseColor
+            const label = customNumericLabels[index]
+
+            const roundingOptions = {
+                roundingMode: OwidVariableRoundingMode.decimalPlaces,
+            }
+            const displayMin =
+                this.colorScaleColumn?.formatValueShort(min, roundingOptions) ??
+                min.toString()
+            const displayMax =
+                this.colorScaleColumn?.formatValueShort(max, roundingOptions) ??
+                max.toString()
+
+            const isFirst = index === 0
+            const isLast = index === bucketThresholds.length - 2
+            return new NumericBin({
+                isFirst,
+                isOpenLeft: isFirst && min > minPossibleValue,
+                isOpenRight: isLast && max < maxPossibleValue,
+                min,
+                max,
+                color,
+                label,
+                displayMin,
+                displayMax,
+            })
+        })
+    }
+
+    @computed get legendBins(): ColorScaleBin[] {
+        // todo: turn comment into unit test
+        // Will eventually produce something like this:
+        // [{ min: 10, max: 20, minText: "10%", maxText: "20%", color: '#faeaef' },
+        //  { min: 20, max: 30, minText: "20%", maxText: "30%", color: '#fefabc' },
+        //  { value: 'Foobar', text: "Foobar Boop", color: '#bbbbbb'}]
+        return [
+            ...this.numericLegendBins,
+            ...this.categoricalLegendBins,
+        ] as ColorScaleBin[]
+    }
+
+    @computed get categoricalLegendBins(): CategoricalBin[] {
+        const {
+            bucketThresholds,
+            baseColors,
+            hasNoDataBin,
+            hasProjectedDataBin,
+            categoricalValues,
+            customCategoryColors,
+            customCategoryLabels,
+            customHiddenCategories,
+            colorScheme,
+        } = this
+
+        let allCategoricalValues = categoricalValues
+
+        // Inject "No data" bin
+        if (hasNoDataBin && !allCategoricalValues.includes(NO_DATA_LABEL)) {
+            // The color scheme colors get applied in order, starting from first, and we only use
+            // as many colors as there are categorical values (excluding "No data").
+            // So in order to leave it colorless, we want to append the "No data" label last.
+            // -@danielgavrilov, 2020-06-02
+            allCategoricalValues = [...allCategoricalValues, NO_DATA_LABEL]
+        }
+
+        // Inject "Projected data" bin
+        if (hasProjectedDataBin) {
+            allCategoricalValues = [
+                ...allCategoricalValues,
+                PROJECTED_DATA_LABEL,
+            ]
+        }
+
+        return allCategoricalValues.map((value, index) => {
+            const boundingOffset = _.isEmpty(bucketThresholds)
+                ? 0
+                : bucketThresholds.length - 1
+
+            // Use colorMap if available and the value exists in it
+            let baseColor: Color | undefined
+            if (colorScheme.colorMap && value in colorScheme.colorMap) {
+                baseColor = colorScheme.colorMap[value]
+            } else {
+                baseColor = baseColors[index + boundingOffset]
+            }
+
+            const color = customCategoryColors[value] ?? baseColor
+            const label = customCategoryLabels[value] ?? value
+
+            return new CategoricalBin({
+                index,
+                value,
+                color,
+                label,
+                isHidden: !!customHiddenCategories[value],
+            })
+        })
+    }
+
+    getBinForValue(
+        value: CoreValueType | undefined
+    ): ColorScaleBin | undefined {
+        return value === undefined
+            ? undefined
+            : this.legendBins.find((bin) => bin.contains(value))
+    }
+
+    getColor(value: CoreValueType | undefined): string | undefined {
+        if (value === undefined) return this.noDataColor
+        return this.getBinForValue(value)?.color
+    }
+}