@buildcanada/charts 0.1.0

package/src/grapher/lineCharts/LineChartConstants.ts

@@ -0,0 +1,89 @@
+import { DualAxis } from "../axis/Axis"
+import { ChartManager } from "../chart/ChartManager"
+import { CoreValueType, EntityName, Time } from "../../types/index.js"
+import { ChartSeries } from "../chart/ChartInterface"
+import { Color } from "../../utils/index.js"
+import { InteractionState } from "../interaction/InteractionState"
+import { LegendStyleConfig } from "../legend/LegendInteractionState"
+import { GRAPHER_OPACITY_MUTE } from "../core/GrapherConstants"
+
+export const LINE_CHART_CLASS_NAME = "LineChart"
+
+// Line color
+export const DEFAULT_LINE_COLOR = "#000"
+
+// Stroke width
+export const DEFAULT_STROKE_WIDTH = 1.5
+export const VARIABLE_COLOR_STROKE_WIDTH = 2.5
+
+// Marker radius
+export const DEFAULT_MARKER_RADIUS = 1.8
+export const VARIABLE_COLOR_MARKER_RADIUS = 2.2
+export const DISCONNECTED_DOTS_MARKER_RADIUS = 2.6
+export const STATIC_SMALL_MARKER_RADIUS = 3
+
+// Line outline
+export const DEFAULT_LINE_OUTLINE_WIDTH = 0.5
+export const VARIABLE_COLOR_LINE_OUTLINE_WIDTH = 1.0
+
+// Legend
+export const LEGEND_PADDING = 25
+export const NUMERIC_LEGEND_STYLE: LegendStyleConfig = {
+    marker: { default: { stroke: "#ffffff", strokeWidth: 1 } },
+}
+export const CATEGORICAL_LEGEND_STYLE: LegendStyleConfig = {
+    marker: {
+        default: { opacity: 1 },
+        muted: { opacity: GRAPHER_OPACITY_MUTE },
+    },
+    text: { muted: { opacity: GRAPHER_OPACITY_MUTE } },
+}
+
+export interface LinePoint {
+    x: number
+    y: number
+    colorValue?: CoreValueType
+}
+
+export interface PlacedPoint {
+    x: number
+    y: number
+    color: Color
+    time: number
+}
+
+export interface LineChartSeries extends ChartSeries {
+    displayName: string
+    isProjection?: boolean
+    plotMarkersOnly?: boolean
+    points: LinePoint[]
+    entityName: EntityName
+    columnName: string
+    focus: InteractionState
+}
+
+export interface PlacedLineChartSeries extends LineChartSeries {
+    placedPoints: PlacedPoint[]
+}
+
+export interface RenderLineChartSeries extends PlacedLineChartSeries {
+    hover: InteractionState
+}
+
+export interface LinesProps {
+    dualAxis: DualAxis
+    series: RenderLineChartSeries[]
+    hidePoints?: boolean
+    lineStrokeWidth?: number
+    lineOutlineWidth?: number
+    markerRadius?: number
+    isStatic?: boolean
+    multiColor?: boolean
+    backgroundColor?: string
+}
+
+export interface LineChartManager extends ChartManager {
+    highlightedTimesInLineChart?: Time[]
+    lineStrokeWidth?: number
+    canSelectMultipleEntities?: boolean // used to pick an appropriate series name
+}

package/src/grapher/lineCharts/LineChartHelpers.ts

@@ -0,0 +1,184 @@
+import * as _ from "lodash-es"
+import { OwidTable } from "../../core-table/index.js"
+import {
+    AxisAlign,
+    AxisConfigInterface,
+    ColumnSlug,
+    EntityName,
+    PrimitiveType,
+    ScaleType,
+    SeriesName,
+    SeriesStrategy,
+} from "../../types/index.js"
+import {
+    LineChartSeries,
+    PlacedLineChartSeries,
+    PlacedPoint,
+    RenderLineChartSeries,
+} from "./LineChartConstants"
+import { DualAxis } from "../axis/Axis"
+import { LineChartState } from "./LineChartState"
+import { darkenColorForLine } from "../color/ColorUtils"
+import {
+    byHoverThenFocusState,
+    getHoverStateForSeries,
+} from "../chart/ChartUtils"
+
+export type AnnotationsMap = Map<PrimitiveType, Set<PrimitiveType>>
+
+export interface GetSeriesNameArgs {
+    entityName: EntityName
+    columnName: string
+    seriesStrategy: SeriesStrategy
+    hasMultipleEntitiesSelected?: boolean
+    allowsMultiEntitySelection?: boolean
+}
+
+/**
+ * Unique identifier for a series that is shared between line and slope charts
+ * since focus states are built on top of it.
+ */
+export function getSeriesName({
+    entityName,
+    columnName,
+    seriesStrategy,
+    hasMultipleEntitiesSelected,
+    allowsMultiEntitySelection,
+}: GetSeriesNameArgs): SeriesName {
+    // When plotting entities as series, use the entity name as the unique identifier
+    if (seriesStrategy === SeriesStrategy.entity) return entityName
+
+    // When plotting columns as series, use the column name. Prepend the entity
+    // name if multiple entities can be selected or are currently selected to
+    // ensure unique series names across all possible selection states
+    return allowsMultiEntitySelection || hasMultipleEntitiesSelected
+        ? `${entityName} - ${columnName}`
+        : columnName
+}
+
+export function getDisplayName({
+    entityName,
+    columnName,
+    seriesStrategy,
+    hasMultipleEntitiesSelected,
+}: Omit<GetSeriesNameArgs, "canSelectMultipleEntities">): SeriesName {
+    // When plotting entities as series, each series represents one entity
+    if (seriesStrategy === SeriesStrategy.entity) return entityName
+
+    // When plotting columns as series, show just the column name by default.
+    // Only prepend the entity name when multiple entities are currently selected
+    // (this is different from series names that always include the entity name)
+    return hasMultipleEntitiesSelected
+        ? `${entityName} – ${columnName}` // Uses en dash for display
+        : columnName
+}
+
+export function getColorKey({
+    entityName,
+    columnName,
+    seriesStrategy,
+    hasMultipleEntitiesSelected,
+}: Omit<GetSeriesNameArgs, "canSelectMultipleEntities">): SeriesName {
+    // When plotting entities as series, each entity gets its own color
+    if (seriesStrategy === SeriesStrategy.entity) return entityName
+
+    // When plotting columns as series, show just the column name by default.
+    // Only prepend the entity name when multiple entities are currently selected
+    // (this is different from series names that always include the entity name)
+    return hasMultipleEntitiesSelected
+        ? `${entityName} - ${columnName}`
+        : columnName
+}
+
+export function getAnnotationsMap(
+    table: OwidTable,
+    slug: ColumnSlug
+): AnnotationsMap | undefined {
+    return table
+        .getAnnotationColumnForColumn(slug)
+        ?.getUniqueValuesGroupedBy(table.entityNameSlug)
+}
+
+export function getAnnotationsForSeries(
+    annotationsMap: AnnotationsMap | undefined,
+    seriesName: SeriesName
+): string | undefined {
+    const annotations = annotationsMap?.get(seriesName)
+    if (!annotations) return undefined
+    return Array.from(annotations.values())
+        .filter((anno) => anno)
+        .join(" & ")
+}
+
+export function getYAxisConfigDefaults(
+    config?: AxisConfigInterface
+): AxisConfigInterface {
+    return {
+        nice: config?.scaleType !== ScaleType.log,
+        // if we only have a single y value (probably 0), we want the
+        // horizontal axis to be at the bottom of the chart.
+        // see https://github.com/owid/owid-grapher/pull/975#issuecomment-890798547
+        singleValueAxisPointAlign: AxisAlign.start,
+        // default to 0 if not set
+        min: 0,
+    }
+}
+
+export function toPlacedLineChartSeries(
+    series: readonly LineChartSeries[],
+    { chartState, dualAxis }: { chartState: LineChartState; dualAxis: DualAxis }
+): PlacedLineChartSeries[] {
+    const { horizontalAxis, verticalAxis } = dualAxis
+
+    return series.toReversed().map((series) => {
+        const placedPoints = series.points.map((point): PlacedPoint => {
+            const color = chartState.hasColorScale
+                ? darkenColorForLine(
+                      chartState.getColorScaleColor(point.colorValue)
+                  )
+                : series.color
+
+            return {
+                time: point.x,
+                x: _.round(horizontalAxis.place(point.x), 1),
+                y: _.round(verticalAxis.place(point.y), 1),
+                color,
+            }
+        })
+        return { ...series, placedPoints }
+    })
+}
+
+export function toRenderLineChartSeries(
+    placedSeries: PlacedLineChartSeries[],
+    {
+        isFocusModeActive = false,
+        isHoverModeActive = false,
+        hoveredSeriesNames = [],
+    }: {
+        isFocusModeActive?: boolean
+        isHoverModeActive?: boolean
+        hoveredSeriesNames?: SeriesName[]
+    }
+): RenderLineChartSeries[] {
+    let series: RenderLineChartSeries[] = placedSeries.map((series) => {
+        return {
+            ...series,
+            hover: getHoverStateForSeries(series, {
+                isHoverModeActive,
+                hoveredSeriesNames,
+            }),
+        }
+    })
+
+    // draw lines on top of markers-only series
+    series = _.sortBy(series, (series) => !series.plotMarkersOnly)
+
+    // sort by interaction state so that foreground series
+    // are drawn on top of background series
+    if (isFocusModeActive || isHoverModeActive) {
+        series = _.sortBy(series, byHoverThenFocusState)
+    }
+
+    return series
+}

package/src/grapher/lineCharts/LineChartState.ts

@@ -0,0 +1,394 @@
+import * as _ from "lodash-es"
+import * as R from "remeda"
+import { Color } from "../../utils/index.js"
+import { computed, makeObservable } from "mobx"
+import {
+    ScaleType,
+    EntityName,
+    SeriesStrategy,
+    FacetStrategy,
+    CoreValueType,
+    MissingDataStrategy,
+    ColorScaleConfigInterface,
+    ColorSchemeName,
+    ChartErrorInfo,
+} from "../../types/index.js"
+import { ColorSchemes } from "../color/ColorSchemes"
+import { ChartState } from "../chart/ChartInterface"
+import {
+    LineChartSeries,
+    LineChartManager,
+    LinePoint,
+    DEFAULT_LINE_COLOR,
+} from "./LineChartConstants"
+import {
+    OwidTable,
+    CoreColumn,
+    isNotErrorValue,
+} from "../../core-table/index.js"
+import {
+    autoDetectSeriesStrategy,
+    autoDetectYColumnSlugs,
+    getDefaultFailMessage,
+    getShortNameForEntity,
+    makeSelectionArray,
+} from "../chart/ChartUtils"
+import { ColorScheme } from "../color/ColorScheme"
+import { SelectionArray } from "../selection/SelectionArray"
+import { ColorScale, ColorScaleManager } from "../color/ColorScale"
+import { ColorScaleConfig } from "../color/ColorScaleConfig"
+import { OWID_NO_DATA_GRAY } from "../color/ColorConstants"
+import { CategoricalColorAssigner } from "../color/CategoricalColorAssigner"
+import { getColorKey, getDisplayName, getSeriesName } from "./LineChartHelpers"
+import { FocusArray } from "../focus/FocusArray"
+import { AxisConfig } from "../axis/AxisConfig"
+import { HorizontalAxis, VerticalAxis } from "../axis/Axis"
+
+export class LineChartState implements ChartState, ColorScaleManager {
+    manager: LineChartManager
+
+    colorScale: ColorScale
+    defaultBaseColorScheme = ColorSchemeName.OwidDistinctLines
+    defaultNoDataColor = OWID_NO_DATA_GRAY
+
+    constructor({ manager }: { manager: LineChartManager }) {
+        this.manager = manager
+        this.colorScale = manager.colorScaleOverride ?? new ColorScale(this)
+        makeObservable(this)
+    }
+
+    @computed get inputTable(): OwidTable {
+        return this.manager.table
+    }
+
+    @computed get transformedTableFromGrapher(): OwidTable {
+        return (
+            this.manager.transformedTable ??
+            this.transformTable(this.inputTable)
+        )
+    }
+
+    @computed get transformedTable(): OwidTable {
+        let table = this.transformedTableFromGrapher
+        // The % growth transform cannot be applied in transformTable() because it will filter out
+        // any rows before startHandleTimeBound and change the timeline bounds.
+        const { isRelativeMode, startTime } = this.manager
+        if (isRelativeMode && startTime !== undefined) {
+            table = table.toTotalGrowthForEachColumnComparedToStartTime(
+                startTime,
+                this.manager.yColumnSlugs ?? []
+            )
+        }
+        return table
+    }
+
+    transformTable(table: OwidTable): OwidTable {
+        table = table.filterByEntityNames(
+            this.selectionArray.selectedEntityNames
+        )
+
+        // TODO: remove this filter once we don't have mixed type columns in datasets
+        // Currently we set skipParsing=true on these columns to be backwards-compatible
+        table = table.replaceNonNumericCellsWithErrorValues(this.yColumnSlugs)
+
+        if (this.isLogScale)
+            table = table.replaceNonPositiveCellsForLogScale(this.yColumnSlugs)
+
+        if (this.colorColumnSlug) {
+            table = table
+                // TODO: remove this filter once we don't have mixed type columns in datasets
+                // Currently we set skipParsing=true on these columns to be backwards-compatible
+                .replaceNonNumericCellsWithErrorValues([this.colorColumnSlug])
+                .interpolateColumnWithTolerance(this.colorColumnSlug)
+        }
+
+        // drop all data when the author chose to hide entities with missing data and
+        // at least one of the variables has no data for the current entity
+        if (
+            this.missingDataStrategy === MissingDataStrategy.hide &&
+            table.hasAnyColumnNoValidValue(this.yColumnSlugs)
+        ) {
+            table = table.dropAllRows()
+        }
+
+        return table
+    }
+
+    transformTableForSelection(table: OwidTable): OwidTable {
+        // if entities with partial data are not plotted,
+        // make sure they don't show up in the entity selector
+        if (this.missingDataStrategy === MissingDataStrategy.hide) {
+            table = table
+                .replaceNonNumericCellsWithErrorValues(this.yColumnSlugs)
+                .dropEntitiesThatHaveNoDataInSomeColumn(this.yColumnSlugs)
+        }
+
+        return table
+    }
+
+    @computed get selectionArray(): SelectionArray {
+        return makeSelectionArray(this.manager.selection)
+    }
+
+    @computed get focusArray(): FocusArray {
+        return this.manager.focusArray ?? new FocusArray()
+    }
+
+    @computed get isFocusModeActive(): boolean {
+        return this.focusArray.hasFocusedSeries
+    }
+
+    @computed get yColumnSlugs(): string[] {
+        return autoDetectYColumnSlugs(this.manager)
+    }
+
+    @computed get colorColumnSlug(): string | undefined {
+        // Line charts only support numeric variables as color dimension
+        return this.manager.numericColorColumnSlug
+    }
+
+    @computed get yColumns(): CoreColumn[] {
+        return this.yColumnSlugs.map((slug) => this.transformedTable.get(slug))
+    }
+
+    @computed get formatColumn(): CoreColumn {
+        return this.yColumns[0]
+    }
+
+    @computed get colorColumn(): CoreColumn {
+        return this.transformedTable.get(this.colorColumnSlug)
+    }
+
+    @computed get isLogScale(): boolean {
+        return this.manager.yAxisConfig?.scaleType === ScaleType.log
+    }
+
+    @computed get colorScheme(): ColorScheme {
+        return (
+            (this.manager.baseColorScheme
+                ? ColorSchemes.get(this.manager.baseColorScheme)
+                : null) ?? ColorSchemes.get(this.defaultBaseColorScheme)
+        )
+    }
+
+    @computed get colorScaleColumn(): CoreColumn {
+        return (
+            // For faceted charts, we have to get the values of inputTable before it's filtered by
+            // the faceting logic.
+            this.manager.colorScaleColumnOverride ?? // We need to use inputTable in order to get consistent coloring for a variable across
+            // charts, e.g. each continent being assigned to the same color.
+            // inputTable is unfiltered, so it contains every value that exists in the variable.
+            this.inputTable.get(this.colorColumnSlug)
+        )
+    }
+
+    @computed get colorScaleConfig(): ColorScaleConfigInterface | undefined {
+        return (
+            ColorScaleConfig.fromDSL(this.colorColumn.def) ??
+            this.manager.colorScale
+        )
+    }
+
+    @computed get categoricalColorAssigner(): CategoricalColorAssigner {
+        return new CategoricalColorAssigner({
+            colorScheme: this.colorScheme,
+            invertColorScheme: this.manager.invertColorScheme,
+            colorMap:
+                this.seriesStrategy === SeriesStrategy.entity
+                    ? this.inputTable.entityNameColorIndex
+                    : this.inputTable.columnDisplayNameToColorMap,
+            autoColorMapCache: this.manager.seriesColorMap,
+        })
+    }
+
+    @computed get hasColorScale(): boolean {
+        return !this.colorColumn.isMissing
+    }
+
+    getColorScaleColor(value: CoreValueType | undefined): Color {
+        return this.colorScale.getColor(value) ?? DEFAULT_LINE_COLOR
+    }
+
+    @computed get hasNoDataBin(): boolean {
+        if (!this.hasColorScale) return false
+        return this.colorColumn.valuesIncludingErrorValues.some(
+            (value) => !isNotErrorValue(value)
+        )
+    }
+
+    @computed get missingDataStrategy(): MissingDataStrategy {
+        return this.manager.missingDataStrategy || MissingDataStrategy.auto
+    }
+
+    @computed get seriesStrategy(): SeriesStrategy {
+        return autoDetectSeriesStrategy(this.manager, true)
+    }
+
+    @computed get series(): readonly LineChartSeries[] {
+        const series = this.yColumns.flatMap((col) =>
+            col.uniqEntityNames.map(
+                (entityName): LineChartSeries =>
+                    this.constructSingleSeries(entityName, col)
+            )
+        )
+
+        // The lines should be plotted in the order of the selected entities
+        const { selectedEntityNames } = this.selectionArray
+        const entityIndex = new Map(
+            selectedEntityNames.map((name, index) => [name, index])
+        )
+        const sortedSeries = _.sortBy(series, (series) =>
+            entityIndex.get(series.seriesName)
+        )
+
+        return sortedSeries
+    }
+
+    @computed get availableFacetStrategies(): FacetStrategy[] {
+        const strategies: FacetStrategy[] = [FacetStrategy.none]
+
+        if (this.selectionArray.numSelectedEntities > 1)
+            strategies.push(FacetStrategy.entity)
+
+        const numNonProjectionColumns = this.yColumns.filter(
+            (c) => !c.display?.isProjection
+        ).length
+        if (numNonProjectionColumns > 1) strategies.push(FacetStrategy.metric)
+
+        return strategies
+    }
+
+    private constructSingleSeries(
+        entityName: EntityName,
+        column: CoreColumn
+    ): LineChartSeries {
+        const {
+            manager: { canSelectMultipleEntities },
+            transformedTable: { availableEntityNames },
+            seriesStrategy,
+            hasColorScale,
+            colorColumn,
+        } = this
+
+        // Construct the points
+        const timeValues = column.originalTimeColumn.valuesIncludingErrorValues
+        const values = column.valuesIncludingErrorValues
+        const colorValues = colorColumn.valuesIncludingErrorValues
+        // If Y and Color are the same column, we need to get rid of any duplicate rows.
+        // Duplicates occur because Y doesn't have tolerance applied, but Color does.
+        const rowIndexes = _.sortedUniqBy(
+            this.transformedTable.rowIndicesByEntityName
+                .get(entityName)!
+                .filter((index) => _.isNumber(values[index])),
+            (index) => timeValues[index]
+        )
+        const points = rowIndexes.map((index) => {
+            const point: LinePoint = {
+                x: timeValues[index] as number,
+                y: values[index] as number,
+            }
+            if (hasColorScale) {
+                const colorValue = colorValues[index]
+                point.colorValue = isNotErrorValue(colorValue)
+                    ? colorValue
+                    : undefined
+            }
+            return point
+        })
+
+        // Construct series properties
+        const columnName = column.nonEmptyDisplayName
+        const hasMultipleEntitiesSelected = availableEntityNames.length > 1
+        const seriesName = getSeriesName({
+            entityName,
+            columnName,
+            seriesStrategy,
+            hasMultipleEntitiesSelected,
+            allowsMultiEntitySelection: canSelectMultipleEntities,
+        })
+        const shortEntityName = getShortNameForEntity(entityName)
+        const displayName = getDisplayName({
+            entityName: shortEntityName ?? entityName,
+            columnName,
+            seriesStrategy,
+            hasMultipleEntitiesSelected,
+        })
+
+        let seriesColor: Color
+        if (hasColorScale) {
+            const colorValue = R.last(points)?.colorValue
+            seriesColor = this.getColorScaleColor(colorValue)
+        } else {
+            seriesColor = this.categoricalColorAssigner.assign(
+                getColorKey({
+                    entityName,
+                    columnName,
+                    seriesStrategy,
+                    hasMultipleEntitiesSelected,
+                })
+            )
+        }
+
+        return {
+            points,
+            seriesName,
+            entityName,
+            columnName,
+            displayName,
+            isProjection: column.isProjection,
+            plotMarkersOnly: column.display?.plotMarkersOnlyInLineChart,
+            color: seriesColor,
+            focus: this.focusArray.state(seriesName),
+        }
+    }
+
+    toHorizontalAxis(config: AxisConfig): HorizontalAxis {
+        const axis = config.toHorizontalAxis()
+
+        // Update domain
+        axis.updateDomainPreservingUserSettings(
+            this.transformedTable.timeDomainFor(this.yColumnSlugs)
+        )
+
+        axis.scaleType = ScaleType.linear
+        axis.formatColumn = this.inputTable.timeColumn
+        axis.hideFractionalTicks = true
+
+        return axis
+    }
+
+    toVerticalAxis(config: AxisConfig): VerticalAxis {
+        const axis = config.toVerticalAxis()
+
+        // Update domain
+        const yDomain = this.transformedTable.domainFor(this.yColumnSlugs)
+        axis.updateDomainPreservingUserSettings([
+            Math.min(axis.domain[0], yDomain[0]),
+            Math.max(axis.domain[1], yDomain[1]),
+        ])
+
+        // All y axis points are integral, don't show fractional ticks in that case
+        axis.hideFractionalTicks = this.yColumns.every(
+            (yColumn) => yColumn.isAllIntegers
+        )
+
+        // Line charts don't have a y-axis label
+        axis.label = ""
+
+        axis.formatColumn = this.formatColumn
+
+        return axis
+    }
+
+    @computed get errorInfo(): ChartErrorInfo {
+        const message = getDefaultFailMessage(this.manager)
+        if (message) return { reason: message }
+
+        const { entityTypePlural = "entities" } = this.manager
+        if (!this.series.length)
+            return {
+                reason: `No data for the selected ${entityTypePlural}`,
+            }
+        return { reason: "" }
+    }
+}