@fundar/data-chart-telling 1.1.0 → 1.3.0

package/docs/plots/evolution/slope.md

@@ -0,0 +1,39 @@
+# SlopePlot
+
+Part of [Plots](../../plots.md).
+
+A line per series between two positions of a category axis, a dot on each end, to read how every series changed between two moments - and how they changed against one another. Its first and last points are labelled before and after the dots, spread apart where they would overlap. It is a [`LinePlot`](line.md) over a category axis, so any number of positions works, but the plot is made for two.
+
+<!-- example: examples/Slope.svelte -->
+
+```svelte
+<script lang="ts">
+	import { SlopePlot } from '@fundar/data-chart-telling';
+	import { AGE_SHARES } from './datasets';
+
+	const censuses = AGE_SHARES.filter(({ year }) => year === 1991 || year === 2022);
+</script>
+
+<!-- Each age group's share of Buenos Aires City's population between two censuses, labelled at both ends. -->
+<SlopePlot
+	width={720}
+	height={400}
+	data={censuses}
+	x="year"
+	y="share"
+	color="ageGroup"
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Slope plot of the share of each age group between two censuses](../../images/slope.png)
+
+- `x` is always a category axis (a point scale, so the first and last positions reach the plot's edges), even for numbers or dates: each distinct value is a position, in the order the data gives them (`scales.x.domain` sets it).
+- `grouping` (or `color`) names the series; the legend toggles them like any other.
+- `styles.values` writes each series' first and last value (`select` picks others: `'first'`, `'last'`, `'min'`, `'max'`). Each label sits out in the margin on a lane, joined to its dot by a connector. The text is `format` of the value and series name.
+- The value axis is hidden, since the labels carry the values; `scales.y.axisDisplay: 'visible'` brings it back. It fits the values without reaching for zero; pin `scales.y.domain` to start it there.
+- The stroke width, dot radius and padding come from `slope` in the [configuration](../../theming.md); `padding` leaves room outside the first and last position. The positions sit at the plot's edges, and the margins grow to fit the labels.
+- `segments` restyle chosen series (`styles: { stroke: { strokeWidth: 4 } }`), as in a line plot.
+- The tooltip reads the position under the pointer, listing every series' value there.

package/docs/plots/evolution/sparkline.md

@@ -0,0 +1,34 @@
+# SparklinePlot
+
+Part of [Plots](../../plots.md).
+
+A small line plot to read a trend at a glance: no axes, no legend, a thin line, and a dot on each series' last point with its value beside it. It is a [`LinePlot`](line.md), so it takes the same data, `segments`, gaps and transforms; with `facet` it draws one sparkline per category, the usual way to use it.
+
+<!-- example: examples/Sparkline.svelte -->
+
+```svelte
+<script lang="ts">
+	import { SparklinePlot } from '@fundar/data-chart-telling';
+	import { REGION_VALUES } from './datasets';
+</script>
+
+<!-- One sparkline per region: monthly inflation as a thin line, with its last value beside a dot. -->
+<SparklinePlot
+	width={360}
+	height={300}
+	data={REGION_VALUES}
+	x="date"
+	y="value"
+	facet={{ by: 'region', columns: 1, gap: 4 }}
+/>
+```
+
+<!-- /example -->
+
+![Sparklines of monthly inflation by region](../../images/sparkline.png)
+
+- The axes are left out (`scales.x.axisDisplay` and `scales.y.axisDisplay` take `'visible'` back) and so is the legend (`legend: true` shows it). The margins are small; `margins` sets them.
+- The last point's value is `styles.values`: `format` writes its text, `show: false` leaves it out, and `select` labels other points (`'first'`, `'min'`, `'max'`).
+- The y axis fits the values without reaching for zero; pin `scales.y.domain` to compare sparklines on one scale, or share it across facets with `facet.scales: 'shared'`.
+- The line's width and the dot's radius come from `sparkline` in the [configuration](../../theming.md).
+- With a `tooltip` or a `hover` marker the sparkline answers the pointer like a line plot does.

package/docs/plots/ranking/bar.md

@@ -0,0 +1,59 @@
+# BarPlot
+
+Part of [Plots](../../plots.md).
+
+Bars where one axis holds the categories and the other the values. Categories on `x` give vertical bars; categories on `y` give horizontal bars.
+
+<!-- example: examples/GroupedBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+</script>
+
+<!-- Vertical bars, grouped by `color`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="province"
+	y="value"
+	color="sex"
+	scales={{ y: { domain: [70, 85] } }}
+/>
+```
+
+<!-- /example -->
+
+![Vertical grouped bars](../../images/grouped-bars.png)
+
+<!-- example: examples/HorizontalBars.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BarPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+</script>
+
+<!-- Horizontal bars: the categories go on `y`, the values on `x`. -->
+<BarPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="value"
+	y="province"
+	color="sex"
+	scales={{ x: { domain: [70, 85] } }}
+/>
+```
+
+<!-- /example -->
+
+![Horizontal grouped bars](../../images/horizontal-bars.png)
+
+- Several series sharing a category sit side by side, each in its slice of the category band. The gap between them is `bar.seriesPadding` in the configuration.
+- `transforms={[{ type: 'stackY' }]}` stacks the series instead. Stacking is always `stackY`, also for horizontal bars, because the value channel is the one stacked.
+- `scales.x.paddingInner` / `paddingOuter` set the spacing between category bands.
+- `styles.values.show` labels each bar; `styles.values.anchor` places the label (`'outside'`, `'start'`, `'middle'`, `'end'`).
+- The tooltip triggers anywhere over a bar's whole band, not just over the visible bar.

package/docs/plots/ranking/bullet.md

@@ -0,0 +1,37 @@
+# BulletPlot
+
+Part of [Plots](../../plots.md).
+
+Per category, a bar for its value, a tick for its `target` and bands behind it - the `ranges` - that grade it: a compact way to read a measure against a goal. It is a [`BarPlot`](bar.md) with the references drawn around its bars. Categories on `x` stand the plot upright; on `y` they lie sideways.
+
+<!-- example: examples/Bullet.svelte -->
+
+```svelte
+<script lang="ts">
+	import { BulletPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_LIFE } from './datasets';
+</script>
+
+<!-- Female life expectancy at birth by province: the bar, against a target of 80 years, over bands for under 76, 76 to 80 and over 80. -->
+<BulletPlot
+	width={720}
+	height={400}
+	data={PROVINCE_LIFE}
+	x="female"
+	y="province"
+	target={80}
+	ranges={[76, 80, 85]}
+	scales={{ x: { domain: [70, 85] } }}
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Bullet plot of female life expectancy by province](../../images/bullet.png)
+
+- `target` is a field of the row, a function of it, or a number the same for every category. A row whose target is not a number has no tick.
+- `ranges` lists the upper bounds of the bands, each a field, a function or a number, in any order. Each band runs from the baseline to its bound; the smallest is the darkest, and a band is drawn over the larger ones.
+- The value axis reaches the bars, the targets and the largest range; pin `scales.x.domain` (or `y`) to start it elsewhere - the bars and bands start at its nearest end.
+- The bar is `barThickness` pixels thick, the bands `rangeWidth` in the colors of `rangeColors`, and the target tick is `targetLength` by `targetWidth` pixels, all from `bullet` in the [configuration](../../theming.md). `styles.bar` (`thickness`), `styles.ranges` (`colors`, `width`) and `styles.target` (`color`, `width`, `length`) override the bar, the bands and the tick for one plot.
+- It takes what a bar plot takes: `styles.values` writes each value (see [Scales](../../scales.md) for `sort`), `segments` restyle the bars of chosen categories, and the tooltip reads the hovered category. It draws one bar per category: for several series, use `facet`.

package/docs/plots/ranking/cleveland.md

@@ -0,0 +1,54 @@
+# ClevelandPlot
+
+Part of [Plots](../../plots.md).
+
+The general form of the family: per category, one dot for each series that has a value there, joined by a connector from the lowest to the highest. A [`LollipopPlot`](lollipop.md) is its one-series case and a [`DumbbellPlot`](dumbbell.md) its two-series case, which check their series and point here when they need more. Categories on `x` stand the rows upright; on `y` they lie sideways.
+
+<!-- example: examples/Cleveland.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ClevelandPlot } from '@fundar/data-chart-telling';
+	import { AGE_SHARES } from './datasets';
+</script>
+
+<!-- One dot per census year in each age group, joined from the lowest share to the highest. The years follow one another, so they take a sequential blues ramp. -->
+<ClevelandPlot
+	width={720}
+	height={400}
+	data={AGE_SHARES}
+	x="share"
+	y="ageGroup"
+	grouping="year"
+	scales={{ color: { scheme: 'blues', schemeRange: [0.3, 1] } }}
+/>
+```
+
+<!-- /example -->
+
+![Cleveland dot plot of age group shares across census years](../../images/cleveland.png)
+
+- `grouping` (or `color`) gives one dot per group in each category. Numeric fields need `grouping` to split into series; `color` on a number draws a continuous ramp instead.
+- `scales.color.scheme: 'blues'` colors the series on a sequential ramp, which reads better than the default palette when the series follow one another, such as years; `schemeRange: [0.3, 1]` skips the ramp's near-white start.
+- The connector spans the lowest and the highest dot of each category, so a series the legend omits leaves the range.
+- The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
+- Its defaults come from `cleveland` in the [configuration](../../theming.md): the connector is a neutral gray, 5 px thick.
+- `styles.values` writes each value: past the highest dot and the lowest of its category, and beside those between them. `select` (`'first'`, `'last'`, `'min'`, `'max'`, or a list) labels only those dots of each category, `series` only those series, and `color: 'series'` writes each label in its dot's series color. `format(value, seriesName, row)` also gets the row, so a label can name its category (see [Styles and segments](../../styles-and-segments.md#value-labels)).
+- `segments` restyle the dots of chosen categories, as in [`DumbbellPlot`](dumbbell.md).
+- The tooltip reads one category at a time, listing every series.
+
+## Connectors
+
+`styles.connector` styles the line each category draws between its dots, on `DumbbellPlot`, `ClevelandPlot` and `LollipopPlot`:
+
+| Field        | Meaning                                                                                                                                                                                                                                                                                        |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `from`, `to` | Where a difference runs between: `to` minus `from`. Each is a series name, `'first'` or `'last'` (the defaults), or `'min'` or `'max'` for the category's lowest and highest dot - `from: 'min', to: 'max'` makes the whole connector the stretch. On a lollipop, the value minus the baseline |
+| `width`      | Thickness in px, `'dots'` for a band as thick as the dots are wide, or a function of the connector                                                                                                                                                                                             |
+| `color`      | One color; `{ by: 'sign', positive, negative, zero }`; `{ by: 'difference' \| 'length', scheme, pivot, ... }` (a color scale, diverging around `pivot: 0` by default for a difference); or a function                                                                                          |
+| `opacity`    | 0-1, or a function of the connector                                                                                                                                                                                                                                                            |
+| `arrow`      | `true`, or `{ headLength, headAngle }`: draws the `from`-`to` stretch as an arrow pointing at the `to` dot, the way the value moved, instead of a line. It is as thick as `width` says, else `connector.arrow.width` in the configuration (2 px)                                               |
+| `outside`    | How the part of a connector outside the `from`-`to` stretch looks, where the dots of the other series lie: a color, or `{ color, opacity }`. Default: the neutral connector color, faded                                                                                                       |
+| `label`      | `true`, or `{ text, format, anchor, fontStyle }`: `text` is the `'difference'` (signed, the default), the `'length'`, or a function; `anchor` is `'outside'` (beside the connector) or `'middle'` (on it, for a thick one)                                                                     |
+
+With more than two series, the connector spans the lowest and the highest dot, but only the stretch between the `from` and `to` dots takes `color`, `opacity` and the label (centered on it); the rest is `outside`. A function gets the connector: `{ category, from, to, length, difference, span, series }`, `span` being that stretch. A lone dot's stem keeps its series' color unless `color` is set, and a segment's own `stroke` wins over both.

package/docs/plots/ranking/dumbbell.md

@@ -0,0 +1,39 @@
+# DumbbellPlot
+
+Part of [Plots](../../plots.md).
+
+Two dots per category, one for each of two series, joined by a connector: the gap between them is what the eye reads, such as a before and an after, or two groups. Categories on `x` stand the rows upright; on `y` they lie sideways. A plot with any other number of series warns and points to [`LollipopPlot`](lollipop.md) (one) or [`ClevelandPlot`](cleveland.md) (any number).
+
+<!-- example: examples/Dumbbell.svelte -->
+
+```svelte
+<script lang="ts">
+	import { DumbbellPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+</script>
+
+<!-- Two dots per province, one per sex, joined by a connector: the gap in life expectancy at birth. -->
+<DumbbellPlot
+	width={720}
+	height={400}
+	data={PROVINCE_VALUES}
+	x="value"
+	y="province"
+	color="sex"
+	scales={{ x: { domain: [70, 85] } }}
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Dumbbell plot of life expectancy by province and sex](../../images/dumbbell.png)
+
+- `grouping` (or `color`) names the two series; the legend toggles them like any other.
+- The value axis fits the values without reaching for zero; pin `scales.y.domain` to start it at zero.
+- Categories keep the order the data gives them; `scales.x.domain` (or `y`) orders them, and `scales.x.sort` orders them by what they hold: `{ by: 'range' }` by the gap between their dots, `{ by: 'value', series }` by one series' value (see [Scales](../../scales.md)).
+- `r` sizes the dots by a field (`r="population"`; area follows the value, and the legend gets a size section) or fixes their radius in pixels (`r={8}`).
+- The connector is a neutral gray as thick as the dots are wide (`stemWidth: 'dots'`), a band; its default color and width, the dot radius and the padding come from `dumbbell` in the [configuration](../../theming.md). `styles.connector` restyles it per category (see [Connectors](cleveland.md#connectors)). `styles.connector.arrow` draws it as an arrow from one series to the other, pointing the way the value moved.
+- `styles.values` writes each value past its dot, away from the other one. A label past the lowest dot can reach the axis labels when that dot sits at the edge of the axis; pin `scales.y.domain` (or `x`) wide enough to leave it room.
+- `segments` restyle the dots of chosen categories (`styles: { dots: { dotRadius: 9 } }`, `areas: [{ x: { from: 'Salta', to: 'Salta' } }]`).
+- The tooltip reads one category at a time, listing its two values.

package/docs/plots/ranking/forest.md

@@ -0,0 +1,40 @@
+# ForestPlot
+
+Part of [Plots](../../plots.md).
+
+Per row, a dot - an estimate - on a stem that spans its interval: a mean with its range, a coefficient with its confidence interval. Each row gives its interval as `lower` and `upper` fields, or as an `error` that reaches that far either side of its value. Categories on `y` lie sideways, the usual way of a forest plot; on `x` they stand upright. It is a mode of [`ClevelandPlot`](cleveland.md): one row per category, and a plot with several warns and points to [`facet`](../../concepts.md) or `ClevelandPlot`.
+
+<!-- example: examples/Forest.svelte -->
+
+```svelte
+<script lang="ts">
+	import { ForestPlot } from '@fundar/data-chart-telling';
+	import { INFLATION_RANGES } from './datasets';
+</script>
+
+<!-- One row per region and year: the mean monthly inflation as a dot, on a stem from its lowest to its highest month. -->
+<ForestPlot
+	width={720}
+	height={480}
+	data={INFLATION_RANGES}
+	x="mean"
+	y="period"
+	lower="min"
+	upper="max"
+	color="region"
+	scales={{ x: { label: 'Monthly inflation (%)' } }}
+/>
+```
+
+<!-- /example -->
+
+![Forest plot of monthly inflation by region and year](../../images/forest.png)
+
+- `lower` and `upper` name the fields of the interval's ends, `error` the half-width of an interval centered on the value. When both are given, `lower` and `upper` win; a row without an interval draws its dot alone, and an interval is widened to hold its value.
+- The value axis fits the intervals, not the estimates alone, without reaching for zero; pin `scales.x.domain` (or `y`) to start it at zero.
+- Rows keep the order the data gives them; `scales.y.sort` orders them: `{ by: 'value' }` by their estimate, `{ by: 'range' }` by the width of their interval, each across all rows or, with `grouped: true`, within each region (see [Scales](../../scales.md)).
+- The stem and its caps - a short tick across each end, on by default - come from `forest` and `connector` in the [configuration](../../theming.md). `styles.connector` restyles them (see [Connectors](cleveland.md#connectors)); `styles.connector.caps` is `false` to leave the stems open, or `{ length }` in pixels.
+- A reference line, such as the line of no effect, is a `rule` marker: `markers={[{ type: 'rule', axis: 'x', value: 0 }]}`.
+- `styles.values` writes each estimate beside its dot.
+- `segments` restyle the stems and dots of chosen rows.
+- The tooltip reads the hovered row.

package/docs/plots/ranking/lollipop.md

@@ -0,0 +1,39 @@
+# LollipopPlot
+
+Part of [Plots](../../plots.md).
+
+One value per category, drawn as a dot on a thin stem that rises from the baseline: a lighter alternative to bars when there are many categories. String values on `x` stand the lollipops upright; on `y` they lie sideways.
+
+<!-- example: examples/Lollipop.svelte -->
+
+```svelte
+<script lang="ts">
+	import { LollipopPlot } from '@fundar/data-chart-telling';
+	import { PROVINCE_VALUES } from './datasets';
+
+	const female = PROVINCE_VALUES.filter((row) => row.sex === 'female');
+</script>
+
+<!-- One dot on a stem per province: female life expectancy at birth, with its value beside it. -->
+<LollipopPlot
+	width={720}
+	height={400}
+	data={female}
+	x="value"
+	y="province"
+	scales={{ x: { domain: [70, 85] } }}
+	styles={{ values: { show: true } }}
+/>
+```
+
+<!-- /example -->
+
+![Lollipop plot of life expectancy by province](../../images/lollipop.png)
+
+- `grouping` (or `color`) draws one set of lollipops per group, as long as each category has a value in only one of them - coloring by the category field itself is the usual case. A category with values in several groups warns: that is a [`DumbbellPlot`](dumbbell.md) (two) or a [`ClevelandPlot`](cleveland.md) (any number).
+- Categories keep the order the data gives them; `scales.x.domain` (or `y`) orders them, and `scales.x.sort` orders them by what they hold: `{ by: 'range' }` by the gap between their dots, `{ by: 'value', series }` by one series' value (see [Scales](../../scales.md)).
+- The value axis reaches zero, where the stems start; pinning `scales.y.domain` moves the baseline to the nearest end of it, and a negative value hangs below zero.
+- `scales.x.paddingInner` / `paddingOuter` set the room around each lollipop; the defaults, with the dot radius and the stem width (a thin 2 px line), come from `lollipop` in the [configuration](../../theming.md).
+- `styles.values` writes each value just past its dot.
+- `segments` restyle whole categories: `styles: { stroke: {...}, dots: {...} }` restyle their stems and dots (`areas: [{ x: { from: 'Salta', to: 'Salta' } }]`).
+- The tooltip reads one lollipop at a time, along the category axis.