@buildcanada/charts 0.1.0

package/src/grapher/mapCharts/MapChartConstants.ts

@@ -0,0 +1,260 @@
+import { ColorScaleBin } from "../color/ColorScaleBin"
+import { Bounds, ColumnSlug } from "../../utils/index.js"
+import {
+    MapRegionName,
+    SeriesName,
+    GlobeRegionName,
+    ProjectionColumnInfo,
+    type GrapherInteractionEvent,
+    Time,
+} from "../../types/index.js"
+import { ChartManager } from "../chart/ChartManager"
+import { MapConfig } from "./MapConfig"
+import { ChartSeries } from "../chart/ChartInterface"
+import { GlobeController } from "./GlobeController"
+import { MapSelectionArray } from "../selection/MapSelectionArray.js"
+import { CoreColumn } from "../../core-table/index.js"
+import * as R from "remeda"
+import { InteractionState } from "../interaction/InteractionState"
+
+export declare type SVGMouseEvent = React.MouseEvent<SVGElement>
+
+export type GeoFeature = GeoJSON.Feature<GeoJSON.GeometryObject>
+export type MapBracket = ColorScaleBin
+
+export const MAP_HOVER_TARGET_RANGE = 20
+
+export const DEFAULT_STROKE_COLOR = "#333"
+export const HOVER_STROKE_COLOR = "#111"
+
+export const DEFAULT_STROKE_WIDTH = 0.3
+export const HOVER_STROKE_WIDTH = 1.5
+export const SELECTED_STROKE_WIDTH = 1
+export const PATTERN_STROKE_WIDTH = 0.7
+
+export const BLUR_FILL_OPACITY = 0.2
+export const BLUR_STROKE_OPACITY = 0.5
+
+export const PROJECTED_DATA_LEGEND_COLOR = "#ffffff"
+
+export const MAP_CHART_CLASSNAME = "MapChart"
+export const CHOROPLETH_MAP_CLASSNAME = "ChoroplethMap"
+export const GEO_FEATURES_CLASSNAME = "GeoFeatures"
+
+export const DEFAULT_GLOBE_ZOOM = 1
+export const GLOBE_MIN_ZOOM = 1
+export const GLOBE_MAX_ZOOM = 5
+export const GLOBE_COUNTRY_ZOOM = 2.5
+
+export const GLOBE_LATITUDE_MIN = -65
+export const GLOBE_LATITUDE_MAX = 65
+
+export const DEFAULT_GLOBE_SIZE = 500 // defined by d3
+export const DEFAULT_GLOBE_ROTATION: [number, number] = [-30, 20] // Atlantic ocean (i.e. Americas & Europe)
+export const DEFAULT_GLOBE_ROTATIONS_FOR_TIME: Record<
+    "UTC_MORNING" | "UTC_MIDDAY" | "UTC_EVENING",
+    [number, number]
+> = {
+    UTC_MORNING: [110, 15], // Asia & Oceania
+    UTC_MIDDAY: [20, 20], // Europe & Africa
+    UTC_EVENING: [-90, 15], // North & South America
+}
+
+export const ANNOTATION_COLOR_DARK = HOVER_STROKE_COLOR
+export const ANNOTATION_COLOR_LIGHT = "#fff"
+
+export const ANNOTATION_FONT_SIZE_INTERNAL_DEFAULT = 11
+export const ANNOTATION_FONT_SIZE_INTERNAL_MIN = 7
+export const ANNOTATION_FONT_SIZE_EXTERNAL_DEFAULT = 8
+export const ANNOTATION_FONT_SIZE_EXTERNAL_MAX = 11
+
+export const ANNOTATION_MARKER_LINE_LENGTH_DEFAULT = 6
+export const ANNOTATION_MARKER_LINE_LENGTH_MAX = 10
+
+export const MAP_REGION_LABELS: Record<MapRegionName, string> = {
+    World: "World",
+    Africa: "Africa",
+    NorthAmerica: "North America",
+    SouthAmerica: "South America",
+    Asia: "Asia",
+    Europe: "Europe",
+    Oceania: "Oceania",
+    Canada: "Canada",
+}
+
+export const MAP_REGION_NAMES = R.invert(MAP_REGION_LABELS)
+
+export interface ChoroplethSeries extends ChartSeries {
+    value: number | string
+    time: number
+    isProjection?: boolean
+}
+
+export type ChoroplethSeriesByName = Map<SeriesName, ChoroplethSeries>
+
+export interface ChoroplethMapManager {
+    choroplethData: ChoroplethSeriesByName
+    choroplethMapBounds: Bounds
+    mapConfig: MapConfig
+    mapColumn: CoreColumn
+    globeController?: GlobeController
+    selectionArray?: MapSelectionArray
+    fontSize?: number
+    getHoverState?: (featureId: string) => InteractionState
+    isSelected?: (featureId: string) => boolean
+    onMapMouseOver?: (d: GeoFeature) => void
+    onMapMouseLeave?: () => void
+    isMapSelectionEnabled?: boolean
+    isStatic?: boolean
+    binColors?: string[]
+    hasProjectedData?: boolean
+    mapViewport?: MapViewport
+    isFaceted?: boolean
+}
+
+export enum RenderFeatureType {
+    Map = "map",
+    Globe = "globe",
+}
+
+export interface RenderFeature {
+    type: RenderFeatureType
+    id: string
+    geo: GeoFeature
+    geoCentroid: [number, number] // unprojected
+    geoBounds: Bounds // unprojected
+}
+
+export interface MapRenderFeature extends RenderFeature {
+    type: RenderFeatureType.Map
+    path: string
+    projBounds: Bounds
+}
+
+export interface GlobeRenderFeature extends RenderFeature {
+    type: RenderFeatureType.Globe
+}
+
+export interface MapChartManager extends ChartManager {
+    mapColumnSlug?: ColumnSlug
+    mapConfig?: MapConfig
+    targetTime?: Time
+    globeController?: GlobeController
+    isMapSelectionEnabled?: boolean
+    highlightedTimesInTooltip?: [Time, Time]
+    mapViewport?: MapViewport
+    isFaceted?: boolean
+    logGrapherInteractionEvent?: (
+        action: GrapherInteractionEvent,
+        target?: string
+    ) => void
+    projectionColumnInfoBySlug?: Map<ColumnSlug, ProjectionColumnInfo>
+}
+
+export interface GlobeViewport {
+    rotation: [number, number]
+    zoom: number
+}
+
+export interface MapViewport {
+    x: number
+    y: number
+    width: number
+    height: number
+    ratio: number
+}
+
+export const GLOBE_VIEWPORTS: Record<GlobeRegionName, GlobeViewport> = {
+    Europe: { rotation: [10, 55], zoom: 2.95 },
+    Africa: { rotation: [20, 0], zoom: 1.55 },
+    NorthAmerica: { rotation: [-94.5, 43], zoom: 1.5 },
+    SouthAmerica: { rotation: [-62, -22], zoom: 1.75 },
+    Asia: { rotation: [81, 26], zoom: 1.85 },
+    Oceania: { rotation: [152.65, -18.8], zoom: 2 },
+    Canada: { rotation: [-100, 60], zoom: 2.5 },
+}
+
+/** Viewport for each region, defined by center and width+height in fractional coordinates */
+export const MAP_VIEWPORTS: Record<MapRegionName, MapViewport> = {
+    World: { x: 0.565, y: 0.5, width: 1.01, height: 1.01, ratio: 2.29 },
+    Europe: { x: 0.53, y: 0.21, width: 0.2, height: 0.2, ratio: 1.77 },
+    Africa: { x: 0.48, y: 0.7, width: 0.21, height: 0.38, ratio: 1.07 },
+    NorthAmerica: { x: 0.46, y: 0.4, width: 0.19, height: 0.35, ratio: 1.12 },
+    SouthAmerica: { x: 0.52, y: 0.815, width: 0.1, height: 0.26, ratio: 0.62 },
+    Asia: { x: 0.74, y: 0.45, width: 0.36, height: 0.5, ratio: 1.65 },
+    Oceania: { x: 0.51, y: 0.75, width: 0.1, height: 0.2, ratio: 1.47 },
+    Canada: { x: 0.5, y: 0.5, width: 1, height: 1.05, ratio: 1.5 },
+}
+
+// Custom viewport for faceted world map, which zooms in a little bit to make best use of the available space
+export const MAP_VIEWPORT_FACETED_WORLD: MapViewport = {
+    x: 0.545,
+    y: 0.5,
+    width: 0.91,
+    height: 1.01,
+    ratio: 2.29,
+}
+
+export interface Circle {
+    cx: number // center x
+    cy: number // center y
+    r: number // radius
+}
+
+export interface Ellipse {
+    cx: number // center x
+    cy: number // center y
+    rx: number // radius on the x-axis
+    ry: number // radius on the y-axis
+}
+
+// ellipse expressed in lon/lat
+export interface EllipseCoords {
+    cx: number
+    cy: number
+    left: number // left x
+    top: number // top y
+}
+
+interface BaseAnnotation {
+    id: string
+    feature: RenderFeature
+    placedBounds: Bounds
+    text: string
+    fontSize: number
+    color: string
+}
+
+export interface InternalAnnotation extends BaseAnnotation {
+    type: "internal"
+    ellipse: Ellipse
+}
+
+export interface ExternalAnnotation extends BaseAnnotation {
+    type: "external"
+    direction: Direction
+    anchor: [number, number]
+}
+
+export type Annotation = InternalAnnotation | ExternalAnnotation
+
+export type Direction =
+    | "left"
+    | "right"
+    | "top"
+    | "bottom"
+    | "leftTop"
+    | "leftBottom"
+    | "rightTop"
+    | "rightBottom"
+
+export type MapColumnInfo =
+    // the map column isn't a projection
+    | { type: "historical"; slug: ColumnSlug }
+    // the map column is a projection without an historical counterpart
+    | { type: "projected"; slug: ColumnSlug }
+    // the map column is a projection and has an historical counterpart
+    | ({
+          type: "historical+projected"
+          slug: ColumnSlug
+      } & ProjectionColumnInfo)

package/src/grapher/mapCharts/MapChartState.ts

@@ -0,0 +1,416 @@
+import * as R from "remeda"
+import { computed, makeObservable } from "mobx"
+import { ChartState } from "../chart/ChartInterface"
+import {
+    ChoroplethSeries,
+    ChoroplethSeriesByName,
+    MAP_REGION_LABELS,
+    MapChartManager,
+    MapColumnInfo,
+} from "./MapChartConstants"
+import {
+    CoreColumn,
+    ErrorValueTypes,
+    OwidTable,
+} from "../../core-table/index.js"
+import { match, P } from "ts-pattern"
+import {
+    ChartErrorInfo,
+    Color,
+    ColorSchemeName,
+    ColumnSlug,
+    EntityName,
+    MapRegionName,
+    PrimitiveType,
+    TickFormattingOptions,
+    Time,
+} from "../../types/index.js"
+import {
+    anyToString,
+    checkHasMembers,
+    isPresent,
+    mappableCountries,
+    regions,
+} from "../../utils/index.js"
+import { MapConfig } from "./MapConfig"
+import { combineHistoricalAndProjectionColumns } from "../chart/ChartUtils"
+import {
+    getCountriesByRegion,
+    isOnTheCanadaMap,
+    isOnTheMap,
+} from "./MapHelpers"
+import { MapSelectionArray } from "../selection/MapSelectionArray"
+import { ColorScale, ColorScaleManager } from "../color/ColorScale"
+import { ColorScaleConfig } from "../color/ColorScaleConfig"
+
+export type MapFormatValueForTooltip = (
+    d: PrimitiveType,
+    options?: TickFormattingOptions
+) => {
+    label: string
+    isCategorical: boolean
+}
+
+export class MapChartState implements ChartState, ColorScaleManager {
+    manager: MapChartManager
+
+    colorScale: ColorScale
+    defaultBaseColorScheme = ColorSchemeName.BuGn
+    hasNoDataBin = true
+
+    constructor({ manager }: { manager: MapChartManager }) {
+        this.manager = manager
+        this.colorScale = new ColorScale(this)
+        makeObservable(this)
+    }
+
+    transformTable(table: OwidTable): OwidTable {
+        // Drop non-mappable entities from the table
+        table = this.dropNonMapEntities(table)
+
+        return match(this.mapColumnInfo)
+            .with({ type: P.union("historical", "projected") }, (info) =>
+                this.transformTableForSingleMapColumn(table, info)
+            )
+            .with({ type: "historical+projected" }, (info) =>
+                this.transformTableForCombinedMapColumn(table, info)
+            )
+            .exhaustive()
+    }
+
+    private transformTableForSingleMapColumn(
+        table: OwidTable,
+        mapColumnInfo: Extract<
+            MapColumnInfo,
+            { type: "historical" | "projected" }
+        >
+    ): OwidTable {
+        return table
+            .dropRowsWithErrorValuesForColumn(mapColumnInfo.slug)
+            .interpolateColumnWithTolerance(mapColumnInfo.slug, {
+                toleranceOverride: this.mapConfig.timeTolerance,
+                toleranceStrategyOverride: this.mapConfig.toleranceStrategy,
+            })
+    }
+
+    private transformTableForCombinedMapColumn(
+        table: OwidTable,
+        mapColumnInfo: Extract<MapColumnInfo, { type: "historical+projected" }>
+    ): OwidTable {
+        const { historicalSlug, projectedSlug, combinedSlug } = mapColumnInfo
+
+        // Interpolate both columns separately
+        table = table
+            .interpolateColumnWithTolerance(projectedSlug, {
+                toleranceOverride: this.mapConfig.timeTolerance,
+                toleranceStrategyOverride: this.mapConfig.toleranceStrategy,
+            })
+            .interpolateColumnWithTolerance(historicalSlug, {
+                toleranceOverride: this.mapConfig.timeTolerance,
+                toleranceStrategyOverride: this.mapConfig.toleranceStrategy,
+            })
+
+        // Combine the projection column with its historical stem into one column
+        table = combineHistoricalAndProjectionColumns(table, mapColumnInfo, {
+            shouldAddIsProjectionColumn: true,
+        })
+
+        // Drop rows with error values for the combined column
+        table = table.dropRowsWithErrorValuesForColumn(combinedSlug)
+
+        return table
+    }
+
+    transformTableForSelection(table: OwidTable): OwidTable {
+        table = this.addMissingMapEntities(table)
+        table = this.dropNonMapEntitiesForSelection(table)
+        table = this.dropAntarctica(table)
+        return table
+    }
+
+    private dropAntarctica(table: OwidTable): OwidTable {
+        // We prefer to not offer Antarctica in the entity selector on the map
+        // tab to avoid confusion since it's shown on the globe, but not on the map.
+        return table.filterByEntityNamesUsingIncludeExcludePattern({
+            excluded: ["Antarctica"],
+        })
+    }
+
+    private dropNonMapEntities(table: OwidTable): OwidTable {
+        // For Canada region, filter by Canadian provinces/territories
+        if (this.mapConfig.region === MapRegionName.Canada) {
+            const entityNamesToSelect =
+                table.availableEntityNames.filter(isOnTheCanadaMap)
+            return table.filterByEntityNames(entityNamesToSelect)
+        }
+
+        // For world and other regions, filter by world map entities
+        const entityNamesToSelect =
+            table.availableEntityNames.filter(isOnTheMap)
+        return table.filterByEntityNames(entityNamesToSelect)
+    }
+
+    private dropNonMapEntitiesForSelection(table: OwidTable): OwidTable {
+        const { selectionArray, mapConfig } = this
+
+        const allMappableCountryNames = mappableCountries.map((c) => c.name)
+        const allRegionNames = regions
+            .filter((r) => checkHasMembers(r) && r.code !== "OWID_WRL")
+            .map((r) => r.name)
+
+        const mappableCountryNameSet = new Set(allMappableCountryNames)
+
+        // If in 2D mode and a continent is selected, then all countries
+        // outside of the selected continent are disabled on the map
+        // and thus also not selectable
+        if (this.mapConfig.is2dContinentActive()) {
+            const countriesInRegionSet = getCountriesByRegion(
+                MAP_REGION_LABELS[mapConfig.region]
+            )
+            if (!countriesInRegionSet) return table
+
+            const countriesInRegion = Array.from(countriesInRegionSet)
+            const mappableCountriesInRegion = countriesInRegion.filter(
+                (countryName) => mappableCountryNameSet.has(countryName)
+            )
+
+            return table.filterByEntityNames(
+                R.unique([
+                    // only keep countries in the region
+                    ...mappableCountriesInRegion,
+                    // keep the user's selection
+                    ...selectionArray.selectedEntityNames,
+                ])
+            )
+        }
+
+        // if no regions are currently selected, keep all mappable countries and regions
+        if (!selectionArray.hasRegions) {
+            return table.filterByEntityNames([
+                ...allRegionNames,
+                ...allMappableCountryNames,
+            ])
+        }
+
+        return table.filterByEntityNames(
+            R.unique([
+                // keep all regions
+                ...allRegionNames,
+                // only keep those countries that are within the selected regions
+                ...selectionArray.countryNamesForSelectedRegions,
+                // keep the user's selection
+                ...selectionArray.selectedEntityNames,
+            ])
+        )
+    }
+
+    private addMissingMapEntities(table: OwidTable): OwidTable {
+        // the given table might not have data for all mappable countries, but
+        // on the map tab, we do want every country to be selectable, even if
+        // it doesn't have data for any of the years. that's why we add a
+        // missing-data row for every mappable country that isn't in the table
+
+        const missingMappableCountries = mappableCountries.filter(
+            (country) => !table.availableEntityNameSet.has(country.name)
+        )
+
+        const rows = missingMappableCountries.map((country) => ({
+            entityName: country.name,
+            time: table.maxTime!, // arbitrary time
+            value: ErrorValueTypes.MissingValuePlaceholder,
+        }))
+        table = table.appendRows(
+            rows,
+            `Append rows for mappable countries without data: ${rows.map((row) => row.entityName).join(", ")}`
+        )
+
+        return table
+    }
+
+    @computed get inputTable(): OwidTable {
+        const { mapColumnInfo } = this
+        const { table } = this.manager
+
+        // For historical+projected data, we need to create the combined column
+        // on the input table. This ensures the color scale has access to the
+        // complete range of data across both columns
+        return mapColumnInfo.type === "historical+projected"
+            ? combineHistoricalAndProjectionColumns(table, mapColumnInfo)
+            : table
+    }
+
+    @computed get transformedTableFromGrapher(): OwidTable {
+        return (
+            this.manager.transformedTable ??
+            this.transformTable(this.inputTable)
+        )
+    }
+
+    @computed get transformedTable(): OwidTable {
+        let table = this.transformedTableFromGrapher
+
+        // A target time is set for faceted maps
+        if (this.manager.targetTime !== undefined) {
+            table = table.filterByTargetTimes(
+                [this.manager.targetTime],
+                this.mapConfig.timeTolerance ??
+                    table.get(this.mapColumnSlug).tolerance
+            )
+        }
+
+        return table
+    }
+
+    @computed get selectionArray(): MapSelectionArray {
+        return this.mapConfig.selection
+    }
+
+    @computed get mapColumn(): CoreColumn {
+        return this.transformedTable.get(this.mapColumnSlug)
+    }
+
+    @computed get mapColumnInfo(): MapColumnInfo {
+        const mapColumnSlug = this.manager.mapColumnSlug!
+
+        // If projection info is available, then we can stitch together the
+        // historical and projected columns
+        const projectionInfo =
+            this.manager.projectionColumnInfoBySlug?.get(mapColumnSlug)
+        if (projectionInfo) {
+            return {
+                type: "historical+projected",
+                slug: projectionInfo.combinedSlug,
+                ...projectionInfo,
+            }
+        }
+
+        const type = this.manager.table.get(mapColumnSlug).isProjection
+            ? "projected"
+            : "historical"
+
+        return { type, slug: mapColumnSlug }
+    }
+
+    @computed get mapConfig(): MapConfig {
+        return this.manager.mapConfig || new MapConfig()
+    }
+
+    @computed get mapColumnSlug(): ColumnSlug {
+        return this.mapColumnInfo.slug
+    }
+
+    // The map column without tolerance and timeline filtering applied
+    @computed get mapColumnUntransformed(): CoreColumn {
+        return this.dropNonMapEntities(this.inputTable).get(this.mapColumnSlug)
+    }
+
+    @computed get colorScaleConfig(): ColorScaleConfig {
+        return (
+            ColorScaleConfig.fromDSL(this.mapColumn.def) ??
+            this.mapConfig.colorScale
+        )
+    }
+
+    @computed get colorScaleColumn(): CoreColumn {
+        // Use the table before any transforms to collect all possible values over time.
+        // Otherwise the legend changes as you slide the timeline handle.
+        return this.mapColumnUntransformed
+    }
+
+    @computed get hasProjectedData(): boolean {
+        return this.mapColumnInfo.type !== "historical"
+    }
+
+    @computed get hasProjectedDataBin(): boolean {
+        return this.hasProjectedData
+    }
+
+    @computed get targetTime(): number | undefined {
+        return this.manager.targetTime ?? this.manager.endTime
+    }
+
+    @computed get columnIsProjection(): CoreColumn | undefined {
+        const slugForIsProjectionColumn =
+            this.mapColumnInfo?.type === "historical+projected"
+                ? this.mapColumnInfo.slugForIsProjectionColumn
+                : undefined
+
+        return slugForIsProjectionColumn
+            ? this.transformedTable.get(slugForIsProjectionColumn)
+            : undefined
+    }
+
+    private checkIsProjection(
+        entityName: EntityName,
+        originalTime: Time
+    ): boolean {
+        return match(this.mapColumnInfo.type)
+            .with("historical", () => false)
+            .with("projected", () => true)
+            .with("historical+projected", () =>
+                this.columnIsProjection?.valueByEntityNameAndOriginalTime
+                    .get(entityName)
+                    ?.get(originalTime)
+            )
+            .exhaustive()
+    }
+
+    @computed get noDataColor(): Color {
+        return this.colorScale.noDataColor
+    }
+
+    @computed get series(): ChoroplethSeries[] {
+        const { mapColumn, targetTime } = this
+        if (mapColumn.isMissing) return []
+        if (targetTime === undefined) return []
+
+        return mapColumn.owidRows
+            .map((row) => {
+                const { entityName, value, originalTime } = row
+                const color =
+                    this.colorScale.getColor(value) || this.noDataColor
+                const isProjection = this.checkIsProjection(
+                    entityName,
+                    originalTime
+                )
+                return {
+                    seriesName: entityName,
+                    time: originalTime,
+                    value,
+                    color,
+                    isProjection,
+                } satisfies ChoroplethSeries
+            })
+            .filter(isPresent)
+    }
+
+    @computed get seriesMap(): ChoroplethSeriesByName {
+        return new Map(this.series.map((series) => [series.seriesName, series]))
+    }
+
+    @computed get formatValueForTooltip(): MapFormatValueForTooltip {
+        const { mapConfig, colorScale } = this
+
+        return (d: PrimitiveType, options?: TickFormattingOptions) => {
+            if (mapConfig.tooltipUseCustomLabels) {
+                // Find the bin (and its label) that this value belongs to
+                const bin = colorScale.getBinForValue(d)
+                const label = bin?.label
+                if (label !== undefined && label !== "")
+                    return { label, isCategorical: true }
+            }
+
+            if (typeof d === "number") {
+                const label = this.mapColumn.formatValueShort(d, options)
+                return { label, isCategorical: false }
+            } else {
+                return { label: anyToString(d), isCategorical: true }
+            }
+        }
+    }
+
+    @computed get errorInfo(): ChartErrorInfo {
+        if (this.mapColumn.isMissing) return { reason: "Missing map column" }
+        return { reason: "" }
+    }
+}

package/src/grapher/mapCharts/MapChartThumbnail.tsx

@@ -0,0 +1,25 @@
+import React from "react"
+import { computed, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { ChartInterface } from "../chart/ChartInterface"
+import { MapChartState } from "./MapChartState"
+import { MapChart, MapChartProps } from "./MapChart"
+
+@observer
+export class MapChartThumbnail
+    extends React.Component<MapChartProps>
+    implements ChartInterface
+{
+    constructor(props: MapChartProps) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @computed get chartState(): MapChartState {
+        return this.props.chartState
+    }
+
+    override render(): React.ReactElement {
+        return <MapChart {...this.props} />
+    }
+}