@buildcanada/charts 0.1.0

package/src/grapher/chart/guidedChartUtils.ts

@@ -0,0 +1,82 @@
+import * as React from "react"
+import { GrapherProgrammaticInterface } from "../core/Grapher.js"
+import { GrapherState } from "../core/GrapherState.js"
+import { MultiDimDataPageConfig, Url } from "../../utils/index.js"
+import {
+    GrapherQueryParams,
+    MultiDimDimensionChoices,
+    ChartConfigType,
+} from "../../types/index.js"
+
+export interface ArchiveGuidedChartRegistration {
+    iframeRef: React.RefObject<HTMLIFrameElement | null>
+    baseUrl: string
+    defaultQueryParams: Record<string, string | undefined>
+    chartConfigType: ChartConfigType
+}
+
+export interface GuidedChartContextValue {
+    grapherStateRef: React.RefObject<GrapherState>
+    chartRef?: React.RefObject<HTMLDivElement>
+    onGuidedChartLinkClick?: (href: string) => void
+    registerArchiveChart?: (
+        registration: ArchiveGuidedChartRegistration
+    ) => () => void
+    registerMultiDim?: (registrationData: {
+        config: MultiDimDataPageConfig
+        onSettingsChange: (
+            newSettings: MultiDimDimensionChoices,
+            queryParams: GrapherQueryParams
+        ) => void
+        grapherContainerRef: React.RefObject<HTMLDivElement | null>
+    }) => void
+}
+
+export const GuidedChartContext =
+    React.createContext<GuidedChartContextValue | null>(null)
+
+/**
+ * If called within a `GuidedChartContext`, sets the context's `grapherStateRef`
+ * to a new `GrapherState` instance initialized with the provided config.
+ * If no context is available, returns a local ref initialized with the config.
+ * This is so the `GrapherState` can be controlled from a GuidedChart,
+ * but also allows for local usage when not
+ */
+export function useMaybeGlobalGrapherStateRef(
+    config: GrapherProgrammaticInterface
+): React.RefObject<GrapherState> {
+    const context = React.useContext(GuidedChartContext)
+    const localRef = React.useRef<GrapherState | null>(null)
+
+    // If a context is provided, use it; otherwise, use the local ref
+    const refToUse = context?.grapherStateRef || localRef
+
+    // Only initialize if the ref is empty
+    if (!refToUse.current) {
+        refToUse.current = new GrapherState(config)
+    }
+
+    return refToUse as React.RefObject<GrapherState>
+}
+
+export function useGuidedChartLinkHandler():
+    | ((href: string) => void)
+    | undefined {
+    const context = React.useContext(GuidedChartContext)
+    return context?.onGuidedChartLinkClick
+}
+
+export const buildArchiveGuidedChartSrc = (
+    registration: ArchiveGuidedChartRegistration,
+    guidedUrl: Url
+): string => {
+    const baseUrl = Url.fromURL(registration.baseUrl)
+    const mergedQuery = {
+        ...registration.defaultQueryParams,
+        ...guidedUrl.queryParams,
+    }
+    const updatedUrl = baseUrl.setQueryParams(mergedQuery)
+
+    const hash = guidedUrl.hash || baseUrl.hash
+    return hash ? updatedUrl.update({ hash }).fullUrl : updatedUrl.fullUrl
+}

package/src/grapher/color/BinningStrategies.ts

@@ -0,0 +1,484 @@
+import {
+    automaticBinningStrategies,
+    AutomaticBinningStrategy,
+    MidpointMode,
+    ResolvedBinningStrategy,
+} from "../../types/index.js"
+import {
+    firstOfNonEmptyArray,
+    lastOfNonEmptyArray,
+} from "../../utils/index.js"
+import { quantile } from "d3"
+import { sortedUniq } from "lodash-es"
+import * as R from "remeda"
+import { match, P } from "ts-pattern"
+import {
+    isLogBinningStrategy,
+    runLogBinningStrategy,
+} from "./BinningStrategyLogarithmic.js"
+import {
+    isEqualSizeBinningStrategy,
+    runEqualSizeBinningStrategy,
+} from "./BinningStrategyEqualSizeBins.js"
+
+/**
+ * Strategies:
+ * - The log scales result in log-like steps, e.g. 1, 2, 5, 10, ...
+ *   They are fully defined given a minValue, maxValue and steps, and
+ *   then generate as many bins as needed to cover the range.
+ *   `log-auto` chooses the step size automatically in order to get a decent number of bins.
+ * - The equal size bins result in evenly spaced steps, e.g. 0, 1, 2, 3, ...
+ *   They are defined by a minValue, maxValue, and a rough target number of bins.
+ *   `equalSizeBins-few-bins` chooses a small number of bins, while
+ *   `equalSizeBins-many-bins` chooses a large number of bins.
+ *   They then generate nice round bin thresholds given the input data.
+ * - `equalSizeBins-percent` is a special case, where for data that looks like percent
+ *   from 0% to 100% we want to mostly use 0%, 10%, 20%, etc. bins.
+ *
+ * Midpoints:
+ *  Sometimes, we do have a midpoint in our data. In many cases, a natural midpoint is zero
+ *  (e.g. for year-over-year change, net migration, temperature anomaly, etc.), but other
+ *  midpoints also make sense (e.g. for sex ratio, or survey responses ranging 0-10).
+ *  If we have a midpoint, then we want to account for it when binning, and generate bins
+ *  that are centered or symmetric around the midpoint.
+ */
+
+export interface BinningStrategyConfig {
+    strategy: AutomaticBinningStrategy
+    minValue?: number
+    maxValue?: number
+    sortedValues: number[]
+    isPercent?: boolean
+    numDecimalPlaces?: number
+    midpointMode?: MidpointMode
+    midpoint?: number
+    createBinForMidpoint?: boolean
+}
+
+export interface ResolvedBinningStrategyConfig {
+    strategy: ResolvedBinningStrategy
+    minValue?: number
+    maxValue?: number
+    numDecimalPlaces?: number
+    sortedValues: number[]
+    midpointMode: MidpointMode
+    midpoint: number
+}
+
+interface BinningStrategyOutput {
+    bins: number[]
+    midpoint?: number
+}
+
+// If the log10 difference between the min and max values is less than or equal to 1.2,
+// the data is considered to be close enough in magnitude to use equal-size bins.
+// This threshold was chosen empirically.
+const AUTO_EQUAL_BINS_MAX_MAGNITUDE_DIFF = 1.2
+
+/**
+ * Calculates the log10 difference between two numbers, i.e. compute x such that lowerValue * 10^x = upperValue.
+ */
+export const calcMagnitudeDiff = (
+    lowerValue: number,
+    upperValue: number
+): number => {
+    if (lowerValue > upperValue)
+        throw new Error("lowerValue must be less than upperValue")
+
+    return Math.log10(upperValue) - Math.log10(lowerValue)
+}
+
+export const pruneUnusedBins = (
+    bins: number[],
+    { minValue, maxValue }: { minValue?: number; maxValue?: number }
+): number[] => {
+    if (minValue !== undefined) {
+        bins = R.dropWhile(
+            bins,
+            (v, i) => bins[i + 1] !== undefined && bins[i + 1] <= minValue
+        )
+    }
+
+    if (maxValue !== undefined) {
+        bins = R.dropLastWhile(
+            bins,
+            (v, i) => bins[i - 1] !== undefined && bins[i - 1] >= maxValue
+        )
+    }
+
+    return bins
+}
+
+export const runBinningStrategy = (
+    conf: BinningStrategyConfig
+): BinningStrategyOutput => {
+    if (conf.sortedValues.length === 0) {
+        return { bins: [0] }
+    }
+
+    conf.midpoint ??= 0
+
+    const hasValuesBelowMidpoint = conf.sortedValues[0] < conf.midpoint
+    const hasValuesAboveMidpoint =
+        lastOfNonEmptyArray(conf.sortedValues) > conf.midpoint
+    const hasValuesBelowAndAboveMidpoint =
+        hasValuesBelowMidpoint && hasValuesAboveMidpoint
+
+    if (hasValuesBelowAndAboveMidpoint && conf.midpointMode === undefined) {
+        // Default to symmetric midpoint if there are negative and positive values
+        conf.midpointMode ??= "symmetric"
+    }
+
+    conf.midpointMode ??= "none"
+
+    let resolvedStrategy: ResolvedBinningStrategy
+    if (conf.strategy === "auto") {
+        resolvedStrategy = autoChooseBinningStrategy(conf)
+    } else {
+        resolvedStrategy = conf.strategy as ResolvedBinningStrategy
+    }
+
+    const validationResult = hasValidConfigForBinningStrategy(
+        conf.strategy,
+        conf
+    )
+    if (!validationResult.valid) return { bins: [0] } // Placeholder binning for invalid configurations
+
+    let bins = runBinningStrategyAroundMidpoint({
+        ...conf,
+        midpointMode: conf.midpointMode,
+        midpoint: conf.midpoint,
+        strategy: resolvedStrategy,
+    })
+
+    if (conf.createBinForMidpoint) {
+        const midpointIdx = R.sortedIndex(bins, conf.midpoint)
+        bins = bins.toSpliced(midpointIdx, 0, conf.midpoint)
+    }
+
+    return {
+        bins,
+        midpoint: conf.midpointMode !== "none" ? conf.midpoint : undefined,
+    }
+}
+
+type MinMaxValueResult =
+    | { valid: true }
+    | { valid: false; reason: string; field: string }
+
+export const hasValidConfigForBinningStrategy = (
+    strategy: AutomaticBinningStrategy,
+    config: { minValue?: number; maxValue?: number; midpoint?: number }
+): MinMaxValueResult => {
+    const { minValue, maxValue, midpoint } = config
+
+    if (!automaticBinningStrategies.includes(strategy))
+        return {
+            valid: false,
+            reason: `Binning: Invalid strategy '${strategy}'`,
+            field: "binningStrategy",
+        }
+
+    if (
+        minValue !== undefined &&
+        maxValue !== undefined &&
+        maxValue < minValue
+    ) {
+        return {
+            valid: false,
+            reason: "Binning: minValue is greater than maxValue",
+            field: "minValue",
+        }
+    }
+
+    return match(strategy)
+        .with("auto", () => {
+            return { valid: true } as const
+        })
+        .when(isEqualSizeBinningStrategy, () => {
+            return { valid: true } as const
+        })
+        .when(isLogBinningStrategy, () => {
+            if (minValue !== undefined && minValue <= 0) {
+                return {
+                    valid: false,
+                    reason: "Binning: Logarithmic binning requires non-zero positive minValue",
+                    field: "minValue",
+                } as const
+            }
+            if (maxValue !== undefined && maxValue <= 0) {
+                return {
+                    valid: false,
+                    reason: "Binning: Logarithmic binning requires non-zero positive maxValue",
+                    field: "maxValue",
+                } as const
+            }
+            if (midpoint !== undefined && midpoint !== 0) {
+                return {
+                    valid: false,
+                    reason: "Binning: Logarithmic binning does not support midpoints other than 0",
+                    field: "midpoint",
+                } as const
+            }
+            return { valid: true } as const
+        })
+        .exhaustive()
+}
+
+/**
+ * minValue and maxValue may either be explicitly given, or automatically computed from the data.
+ * If auto-computed, they are based on some very much heuristic rules, based on quantiles etc.
+ *
+ * This also means that these lines contain a bunch of magic numbers, which have been chosen like so
+ * because they work well in practice for most cases.
+ */
+export const computeMinMaxForStrategy = (
+    strategy: ResolvedBinningStrategy,
+    sortedValues: number[],
+    conf?: Partial<ResolvedBinningStrategyConfig>
+): { minValue: number; maxValue: number } => {
+    let { minValue, maxValue } = conf || {}
+    if (
+        conf?.midpointMode !== "none" &&
+        minValue !== undefined &&
+        conf?.midpoint !== undefined
+    ) {
+        // Ensure that the midpoint is within the min/max range, otherwise we'll get very weird results when mirroring around the midpoint
+        minValue = Math.max(minValue, conf.midpoint)
+    }
+    if (minValue !== undefined && maxValue !== undefined) {
+        maxValue = Math.max(minValue, maxValue)
+        return { minValue, maxValue }
+    }
+
+    match(strategy)
+        .with("equalSizeBins-percent", () => {
+            // Percent strategy always uses 0 to 100
+            minValue ??= 0
+            maxValue ??= 100
+        })
+        .when(isEqualSizeBinningStrategy, () => {
+            const uniqValues = sortedUniq(sortedValues)
+            minValue ??= quantile(uniqValues, 0.05)
+            maxValue ??= quantile(uniqValues, 0.95)
+        })
+        .when(isLogBinningStrategy, () => {
+            const posValues = R.dropWhile(sortedValues, (v) => v <= 0)
+            if (posValues.length === 0) {
+                throw new Error("Log binning strategy requires positive values")
+            }
+
+            const uniqValues = sortedUniq(posValues)
+            minValue ??= quantile(uniqValues, 0.15)
+            maxValue ??= quantile(uniqValues, 0.995)
+
+            if (minValue === undefined || maxValue === undefined)
+                throw new Error("Couldn't obtain minValue or maxValue")
+
+            // Ensure that the min/max values are at least as high as the number of decimals precision.
+            // E.g. if we have 1 decimal place, the minimum value should be at least 0.1
+            if (conf?.numDecimalPlaces !== undefined) {
+                if (minValue > 0)
+                    minValue = Math.max(
+                        minValue,
+                        Math.pow(10, -conf.numDecimalPlaces)
+                    )
+                if (maxValue < 0)
+                    maxValue = Math.min(
+                        maxValue,
+                        -Math.pow(10, -conf.numDecimalPlaces)
+                    )
+            }
+        })
+        .exhaustive()
+
+    if (minValue === undefined || maxValue === undefined)
+        throw new Error("Couldn't obtain minValue or maxValue")
+
+    // Ensure that we have minValue <= maxValue
+    maxValue = Math.max(minValue, maxValue)
+    return { minValue, maxValue }
+}
+
+const runBinningStrategyAroundMidpoint = (
+    conf: ResolvedBinningStrategyConfig
+): number[] => {
+    if (
+        isLogBinningStrategy(conf.strategy) &&
+        conf.midpointMode !== "none" &&
+        conf.midpoint !== 0
+    ) {
+        throw new Error(
+            "Log binning strategy does not support midpoints other than 0"
+        )
+    }
+
+    const minValue = firstOfNonEmptyArray(conf.sortedValues)
+    const maxValue = lastOfNonEmptyArray(conf.sortedValues)
+
+    const bins = match(conf.midpointMode)
+        .with("none", () => {
+            return runResolvedBinningStrategy(conf, { hasMidpoint: false })
+        })
+        .with(P.union("symmetric", "asymmetric"), () => {
+            const leftRange = Math.max(conf.midpoint - minValue, 0)
+            const rightRange = Math.max(maxValue - conf.midpoint, 0)
+            const biggerRange = Math.max(leftRange, rightRange)
+
+            let posValues: number[]
+            if (biggerRange === leftRange) {
+                posValues = R.takeWhile(
+                    conf.sortedValues,
+                    (v) => v < conf.midpoint
+                )
+                    .map((v) => conf.midpoint - v)
+                    .reverse()
+            } else {
+                posValues = R.dropWhile(
+                    conf.sortedValues,
+                    (v) => v <= conf.midpoint
+                ).map((v) => v - conf.midpoint)
+            }
+
+            const binsRight = runResolvedBinningStrategy(
+                { ...conf, sortedValues: posValues },
+                { hasMidpoint: true }
+            )
+            const bins = mirrorBinsAroundMidpoint(binsRight, conf.midpoint)
+
+            if (conf.midpointMode === "symmetric") {
+                return bins
+            } else {
+                // asymmetric: create bins the same way, but then prune any unused ones
+
+                return pruneUnusedBins(bins, {
+                    minValue,
+                    maxValue,
+                })
+            }
+        })
+        .with("same-num-bins", () => {
+            const leftValues = R.takeWhile(
+                conf.sortedValues,
+                (v) => v < conf.midpoint
+            )
+                .map((v) => conf.midpoint - v)
+                .reverse()
+
+            const rightValues = R.dropWhile(
+                conf.sortedValues,
+                (v) => v <= conf.midpoint
+            ).map((v) => v - conf.midpoint)
+
+            const binsRight = runResolvedBinningStrategy(
+                { ...conf, sortedValues: rightValues },
+                { hasMidpoint: true }
+            ).filter((v) => v !== 0)
+            const binsLeft = runResolvedBinningStrategy(
+                { ...conf, sortedValues: leftValues },
+                { hasMidpoint: true }
+            ).filter((v) => v !== 0)
+
+            return [
+                ...binsLeft.map((v) => conf.midpoint - v).reverse(),
+                conf.midpoint,
+                ...binsRight.map((v) => v + conf.midpoint),
+            ]
+        })
+        .with(undefined, () => {
+            throw new Error("Invalid unresolved midpoint mode")
+        })
+        .exhaustive()
+
+    return bins
+}
+
+const runResolvedBinningStrategy = (
+    conf: ResolvedBinningStrategyConfig,
+    { hasMidpoint }: { hasMidpoint: boolean }
+): number[] => {
+    const { minValue, maxValue } = computeMinMaxForStrategy(
+        conf.strategy,
+        conf.sortedValues,
+        conf
+    )
+    return match(conf.strategy)
+        .when(isEqualSizeBinningStrategy, () =>
+            runEqualSizeBinningStrategy(
+                { ...conf, minValue, maxValue },
+                { hasMidpoint }
+            )
+        )
+        .when(isLogBinningStrategy, () =>
+            runLogBinningStrategy(
+                { ...conf, minValue, maxValue },
+                { hasMidpoint }
+            )
+        )
+        .exhaustive()
+}
+
+const autoChooseBinningStrategy = (
+    conf: BinningStrategyConfig
+): ResolvedBinningStrategy => {
+    if (conf.midpointMode !== "none") {
+        return "equalSizeBins-normal"
+    }
+
+    const posValuesOnly = R.dropWhile(conf.sortedValues, (v) => v <= 0)
+    if (posValuesOnly.length === 0) {
+        // All values are negative or zero, use equal size bins as a simple fallback (this is rare anyways)
+        return "equalSizeBins-normal"
+    }
+
+    // If either minValue or maxValue is non-positive, we cannot use log bins
+    const hasNegativeMinOrMaxValue =
+        (conf.minValue !== undefined && conf.minValue <= 0) ||
+        (conf.maxValue !== undefined && conf.maxValue <= 0)
+
+    let minValueForLog, maxValueForLog
+    if (hasNegativeMinOrMaxValue) {
+        minValueForLog = maxValueForLog = 0
+    } else {
+        const { minValue, maxValue } = computeMinMaxForStrategy(
+            "log-auto",
+            posValuesOnly,
+            { minValue: conf.minValue, maxValue: conf.maxValue }
+        )
+        minValueForLog = minValue
+        maxValueForLog = maxValue
+    }
+
+    const magnitudeDiff = calcMagnitudeDiff(minValueForLog, maxValueForLog)
+
+    if (
+        magnitudeDiff < AUTO_EQUAL_BINS_MAX_MAGNITUDE_DIFF ||
+        hasNegativeMinOrMaxValue
+    ) {
+        if (conf.isPercent) {
+            const lastValue = lastOfNonEmptyArray(posValuesOnly)
+            const percentile99 = quantile(posValuesOnly, 0.99)
+            if (
+                lastValue <= 100 &&
+                percentile99 !== undefined &&
+                percentile99 >= 60
+            ) {
+                return "equalSizeBins-percent"
+            }
+        }
+
+        return "equalSizeBins-normal"
+    }
+
+    return "log-auto"
+}
+
+export const mirrorBinsAroundMidpoint = (
+    binOffsets: number[],
+    midpoint: number
+): number[] => {
+    const filteredRightBins = binOffsets.filter((v) => v !== 0)
+    const leftBins = filteredRightBins.map((v) => midpoint - v).reverse()
+    const rightBins = filteredRightBins.map((v) => v + midpoint)
+    return [...leftBins, midpoint, ...rightBins]
+}

package/src/grapher/color/BinningStrategyEqualSizeBins.ts

@@ -0,0 +1,132 @@
+import {
+    BinningStrategyIncludingManual,
+    EqualSizeBinningStrategy,
+    ResolvedBinningStrategy,
+} from "../../types/index.js"
+import {
+    normaliseToSingleDigitNumber,
+    RequiredBy,
+    roundSigFig,
+} from "../../utils/index.js"
+import * as R from "remeda"
+import { match, P } from "ts-pattern"
+import { ResolvedBinningStrategyConfig } from "./BinningStrategies.js"
+
+export const isEqualSizeBinningStrategy = (
+    strategy: BinningStrategyIncludingManual | ResolvedBinningStrategy
+): strategy is EqualSizeBinningStrategy => strategy.startsWith("equalSizeBins-")
+
+export const runEqualSizeBinningStrategy = (
+    conf: RequiredBy<ResolvedBinningStrategyConfig, "minValue" | "maxValue">,
+    { hasMidpoint }: { hasMidpoint?: boolean } = {}
+): number[] => {
+    if (!isEqualSizeBinningStrategy(conf.strategy)) {
+        throw new Error("Invalid strategy")
+    }
+
+    const { minValue, maxValue } = conf
+    const targetBinCount = getTargetBinCountForEqualSizeBinsStrategy(
+        conf.strategy,
+        { hasMidpoint }
+    )
+    return createEqualSizeBins({ minValue, maxValue, targetBinCount })
+}
+
+/**
+ * The equal-size binning strategies all operate with a range of target bins depending on the strategy.
+ * For example, [5, 9] means that there should be at least 5 bins and at most 9.
+ * If there is a midpoint, the number of bins needs to be adjusted downward, because we are potentially
+ * creating up to twice as many bins overall.
+ */
+const getTargetBinCountForEqualSizeBinsStrategy = (
+    strategy: EqualSizeBinningStrategy,
+    { hasMidpoint }: { hasMidpoint?: boolean } = {}
+): readonly [number, number] => {
+    return match(strategy)
+        .with("equalSizeBins-few-bins", () =>
+            hasMidpoint ? ([1, 3] as const) : ([2, 5] as const)
+        )
+        .with("equalSizeBins-normal", () =>
+            hasMidpoint ? ([3, 6] as const) : ([5, 9] as const)
+        )
+        .with(
+            P.union("equalSizeBins-many-bins", "equalSizeBins-percent"),
+            () => (hasMidpoint ? ([4, 8] as const) : ([8, 12] as const))
+        )
+        .exhaustive()
+}
+
+export const createEqualSizeBins = ({
+    minValue,
+    maxValue,
+    targetBinCount,
+}: {
+    minValue: number
+    maxValue: number
+    targetBinCount: readonly number[]
+}): number[] => {
+    if (minValue > maxValue) {
+        throw new Error("minValue must be less than maxValue")
+    }
+
+    const range = maxValue - minValue
+
+    // Normalise the range to be within 1 and 10
+    const { normalised: normalisedRange, factor } =
+        normaliseToSingleDigitNumber(range)
+
+    // These are all common and "good" step sizes
+    const stepSizeCandidates = [1, 0.1, 0.5, 0.2, 2, 3, 0.3, 0.75, 0.25]
+
+    // Compute the number of bins we would get for each candidate step size
+    const stepSizeInfo = stepSizeCandidates.map((candidateStepSize) => {
+        // if (normalisedRange === 0) return true
+
+        const numSteps = Math.ceil(normalisedRange / candidateStepSize)
+        return { stepSize: candidateStepSize, numSteps }
+        // return numSteps >= targetBinCount[0] && numSteps <= targetBinCount[1]
+    })
+
+    // Find the first step size that gives us the target bin count
+    let stepSize = stepSizeInfo.find(
+        (info) =>
+            info.numSteps >= targetBinCount[0] &&
+            info.numSteps <= targetBinCount[1]
+    )?.stepSize
+
+    if (stepSize === undefined) {
+        // It could be interesting to see which charts cause this
+        console.warn(
+            "Equal size binning: Couldn't find a step size fitting targetBinCount; instead using next-best candidate",
+            { targetBinCount, minValue, maxValue }
+        )
+
+        // prefer too many bins over too few (by weighing "too many" less highly than "too few")
+        const stepSizeDifference = (candidate: number): number =>
+            Math.max(candidate - targetBinCount[1], 0) * 1 + // this is how many more bins there are than targetBinCount specifies
+            Math.max(targetBinCount[0] - candidate, 0) * 2 // and this is how many fewer there are
+
+        // Find the step size that minimizes the distance function, i.e. such that we are not much above/below what targetBinCount requests
+        stepSize = R.firstBy(stepSizeInfo, (info) =>
+            stepSizeDifference(info.numSteps)
+        )?.stepSize
+    }
+
+    if (stepSize === undefined) {
+        // This should never happen
+        throw new Error("Could not find a valid step size")
+    }
+
+    const actualStepSize = stepSize * factor
+
+    // Round min value to step size, e.g. if the step size is 20 then this would round 50 down to 40
+    const minValueRounded =
+        Math.floor(minValue / actualStepSize) * actualStepSize
+
+    const steps = Math.ceil((maxValue - minValueRounded) / actualStepSize)
+
+    return R.range(0, steps + 1).map((i) => {
+        const value = i * actualStepSize
+        return minValueRounded + roundSigFig(value, 3) // to avoid floating point issues
+    })
+}