plot-io 0.2.0__tar.gz → 0.6.0__tar.gz

plot_io-0.6.0/API.md

@@ -0,0 +1,2877 @@
+# plot_io API
+
+Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
+
+1. [Conventions](#1-conventions)
+2. [Figures](#2-figures)
+3. [Plots](#3-plots)
+4. [Axes](#4-axes)
+5. [Series](#5-series)
+6. [Color and size axes](#6-color-and-size-axes)
+7. [Colors, maps and markers](#7-colors-maps-and-markers)
+8. [Output](#8-output)
+9. [Genome tracks](#9-genome-tracks)
+10. [Styles](#10-styles)
+11. [Errors](#11-errors)
+12. [Modules](#12-modules)
+
+## 1. Conventions
+
+* **Model.** A `Figure` holds plots (and colorbars) in a grid; a `Plot` holds series, two
+  axes, a title, a legend and colorbars; a series holds data and style. Nothing is
+  computed until the figure is drawn (`save`, `to_bytes`, `draw`), so settings can change
+  in any order.
+* **Settings.** Every object takes its settings as keywords when created and in
+  `set(**settings)`, which returns the object. `set(name=None)` goes back to the inherited
+  or default value. `get(name)` returns the value as given (`"4.5pt"`, `"var(color)"`),
+  `resolve(name)` the final one (px, degrees, colors), and `explain(name)` where it comes
+  from ([values](#values)). Unknown names and invalid values raise `ValueError` naming
+  the setting (with the nearest valid name).
+* **Inheritance.** Settings marked *inherited* in the tables (font, line width, palette,
+  alpha, `rasterize`, `simplify`) are looked up series → plot → figure → style.
+* **Setting groups.** Settings that travel together are declared once as a group and
+  embedded by each owner: `Font` (family, size, variable-font axes), `TextStyle` (size,
+  weight, style, color of one text element), `Stroke` (color, width, dash style, caps,
+  joins), `Marker`, `FillStyle` (`fill`: on or off, an opacity or a color) and
+  `NumberFormat`. The naming rule: an owner's primary element takes a group unprefixed, a
+  secondary one prefixed, and every member's prefixed name follows its pattern. A
+  scatter's markers are `size`, `edge_color`, …; a line's are `marker_size`,
+  `marker_edge_color`; a box's whiskers are `whisker_color`, `whisker_width`,
+  `whisker_style`; an axis' tick labels are `tick_label_font_size`, `tick_label_weight`,
+  `tick_label_color`. Each table ends with the groups the class embeds and their
+  prefixes; [groups](#setting-groups) lists the members.
+* **Defaults.** Every default is in one dict, `pl.DEFAULTS` (`plot_io/defaults.py`; read
+  it, do not change it: styles set other values): bare names for inherited settings (font size,
+  sans-serif, black text, line width, `simplify="auto"`, the palette, …),
+  `"Class.name"` for the settings of each class and `"Group.member"` for every embedding
+  of a group member (`"Marker.size"`: every marker size). A class without an entry uses
+  its base class's, then the group's. Entries are plain data: a default that follows
+  another setting is written with units, `var()` or `calc()` (a legend's font is `"1em"`,
+  a minor tick `"60%"` of the tick length), and a class default of an inherited setting
+  scales the inherited value with `inherit` (a regression line is
+  `"calc(1.4 * inherit)"`, a fill's opacity `"calc(0.3 * inherit)"`). `"XAxis.name"` and
+  `"YAxis.name"` give one axis its own default.
+* **`"auto"`.** A setting whose default is `"auto"` documents its rule. Rules that follow
+  from the model (a colorbar's orientation from its position, a legend's inner pad from
+  its frame, a genome track's gap) are resolved with the setting: `resolve()` returns the
+  result and `get()` `"auto"`. Rules that need the data or the layout (axis limits,
+  padding, tick count and rotation, number formats, legend placement) are resolved when
+  the figure is drawn.
+* **Resolution.** One cascade finds every value, for `resolve`, `get` and `explain`:
+  1. the value set on the object; for a plot's x or y axis, then the value set on the
+     figure's axis of that role (`fig.x_axis(…)`);
+  2. a rule of the class (a track's axis lines from its content);
+  3. the style's key for the object's class, then for its base classes (`"Series.alpha"`
+     reaches every series), stopping at a class that has a default of its own;
+  4. for inherited settings, the parent's value (unless the class default refers to it
+     with `inherit`);
+  5. the style's key for the setting's group (`"Marker.size"`);
+  6. the class default, then the group default;
+  7. for inherited settings, the style's bare name, then `DEFAULTS`'.
+
+  An owner's key always comes before its group's: `"Line.marker_size"` overrides
+  `"Marker.size"` for lines.
+* **Styles.** `Figure(style=…)` presets settings: a style name or a dict of settings,
+  merged over the inherited defaults (the bare names of `DEFAULTS`). See [Styles](#styles).
+* **Entry points.** `pl.Figure()`, `pl.Plot()` and the series classes (`pl.Scatter()`, …)
+  each create the levels above them: `pl.Scatter(x, y)` makes a plot (`.plot`) in a new
+  figure (`.plot.figure`). `fig.plot(…)` is `pl.Plot(figure=fig, …)` and `p.scatter(…)` is
+  `pl.Scatter(…, plot=p)`. Keywords that belong to a level above go to it when the call
+  creates that level: `pl.Scatter(x, y, width=300, title="T")` makes and sets the plot and
+  the figure. Adding to an existing plot or figure takes the new object's settings only:
+  `p.scatter(x, y, title="T")` raises `ValueError` naming `plot.set(title=…)`. A name
+  present on several levels goes to the lowest.
+* **Units.** Lengths take units (`"1.5in"`, `"0.5em"`, `"60%"`); bare numbers are CSS px
+  (1 px = 1/96 in = 0.75 pt) everywhere. Slot widths (`Bar`, `Box`, `Violin`, `Strip`,
+  `Swarm` `width`) are `"80%"` of the slot or `"0.8d"` in data units. Positions along an
+  axis (a decoration's `min`/`max`) take bare numbers as data values. See
+  [values](#values).
+  Images are `dpi` pixels per inch: `dpi=96` gives one image pixel per px, the default 192
+  two. A dpi up to 16 is a multiple of 96: `dpi=2` is 192. PDF pages are sized in pt (× 0.75).
+* **Data.** Sequences (`None` = missing), `array.array`, or any buffer (numpy arrays are
+  read without importing numpy). NaN or `None` values are missing: scatter skips them,
+  line and fill break there, box ignores them, heatmap cells take `nan_color`.
+  With `data=` (a table), strings in data arguments name its columns
+  ([tables](#tables-data)); dates make time axes ([dates](#dates-and-times)).
+* **Text.** Titles, axis labels and legend entries are strings or rich content: a list of
+  strings and `pl.Span` (vec_io's), e.g. `["Area (m", pl.Span("2",
+  baseline_shift="super", font_scale=0.7), ")"]`.
+* **Named colors.** `"blue"`, `"blue 0.45"`, `"blue 45%"`: 28 scales (`red`, `orange`,
+  `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`,
+  `violet`, `purple`, `fuchsia`, `pink`, `rose`, `slate`, `gray`/`grey`, `zinc`, `neutral`,
+  `stone`, `taupe`, `mauve`, `mist`, `olive`, `black`, `white`), Tailwind CSS 4's OKLCh
+  shades 100–900 at levels 0.1–0.9, white at 0 and black at 1, interpolated in Oklab between
+  and gamut mapped into sRGB as CSS Color 4 specifies;
+  a bare name is level 0.5. They take precedence over CSS's names (`"red"` is `#fb2c36`,
+  not `#ff0000`); other CSS names (`"navy"`) keep their CSS values. `get()` returns the
+  name as given, `resolve()` the hex color.
+* **Colors.** Named colors (above), any color vec_io accepts: CSS names, `"#rrggbb[aa]"`, CSS Color 4 functions
+  (`"rgb(…)"`, `"hsl(…)"`, `"hwb(…)"`, `"lab(…)"`, `"lch(…)"`, `"oklab(…)"`,
+  `"oklch(64.5% 0.246 16.439)"`, `"color(display-p3 1 0 0)"`, …; colors outside sRGB are
+  gamut mapped as browsers do), tuples of numbers in [0, 1] (`(1, 0.5, 0)`; on the 0–255
+  scale write `"rgb(255 128 0)"`), `CMYK` and `Spot`; and `"C0"`, `"C1"`, … for the
+  palette's colors.
+* **Fonts.** `font_family` is a CSS family list; weights (`font_weight`, `label_weight`,
+  `tick_label_weight`) are `normal`, `bold` or 1–1000, styles `normal`, `italic`,
+  `oblique` or `"oblique 10deg"`. With a variable font (vec_io embeds the instance used),
+  the weight sets `wght`, the inherited `font_stretch` (`"condensed"`, `"87.5%"`) sets
+  `wdth`, the style `ital` or `slnt`, `font_optical_sizing="auto"` sets `opsz` from the
+  font size, and `font_variations` (`{"GRAD": 50}`) any axis:
+  `pl.Figure(font_family="Roboto Flex", font_stretch="85%", font_variations={"GRAD": 50})`.
+* **Text and fonts.** Text is shaped by `vec_io.text` (pairs kerned) and its fonts are
+  embedded as subsets; plot text needs an installed outline font. Each character takes
+  the first family of `font_family` that is available (output options `font_dirs`, then
+  `VEC_IO_FONT_DIRS`, then installed fonts unless `system_fonts=False`; a family that is
+  not installed tries its metric aliases first: Helvetica and Arial → Liberation Sans,
+  Arimo, …), then a generic family's list (`sans-serif`: Arial, Helvetica, Liberation
+  Sans, DejaVu Sans, Noto Sans, …), then any font with the character. The default
+  `"SF Pro, Inter, Helvetica, Arial, sans-serif"` is SF Pro where installed, else Inter,
+  else Helvetica or Arial (or an alias of theirs), else the system's sans-serif. With no
+  outline font at all, output raises `NoFontError` (a `ValueError`, from vec_io).
+* **Names.** `pl.` holds the figure and plot classes, the plot types, the value types
+  (`ColorAxis`, `SizeAxis`, `ColorMap`, `SizeMap`, `Palette`, `Density`, `ErrorBars`,
+  `Span`), `facet`, the registries (`register_layer`, `register_marker`,
+  `register_color_map`, `register_palette`, `register_style`), `styles` (the styles
+  module), `set_style`, `use_style` and `DEFAULTS`; see [modules](#12-modules) for the
+  rest. Enum-like settings take strings.
+
+### Values
+
+Every length, angle and number setting takes a value with a unit, a reference to another
+setting, or an expression:
+
+```python
+pl.Plot(width="3in", font_size="9pt", title="T")
+p.x_axis(tick_length="0.5em", minor_tick_length="50%", tick_rotation="0.125turn")
+p.bar(days, counts, width="20h")                   # a duration on a time axis
+p.box(groups, positions=[1, 4, 9], width="0.8d")  # data units (default: 80% of the slot)
+p.errorbar(x, y, y_error=e, cap_length="0.2d")    # data units across the bar
+p.title(font_size="large", color="var(--accent)")
+p.legend(pad="calc(1em - 2px)")
+fig.set(vars={"accent": "#c00"})                   # custom variables, read by var(--name)
+```
+
+| Unit | Meaning |
+|---|---|
+| bare number | px (lengths), degrees (angles) |
+| `px` `pt` `pc` `in` `cm` `mm` `Q` | absolute lengths |
+| `em` | the object's `font_size`; in a `font_size` setting, the parent's |
+| `rem` | the figure's `font_size` |
+| `%` | of the reference the setting's type declares and its table entry names: another setting (`minor_tick_length`: of `tick_length`), or one of the [referents](#referents) |
+| `d`, `data` | along a data axis: data units on linear axes, categories on category axes, seconds on time axes; an error on log, symlog and logit axes. On a time axis `d` is a day |
+| `ms` `s` `min` `h` `d` `w` | durations, as data units of time axes (a `timedelta` too) |
+| `fr` | a share of the room left by fixed tracks, in `Figure.widths`/`heights` |
+| `deg` `grad` `rad` `turn` | angles |
+| `xx-small` … `xx-large`, `smaller`, `larger` | font sizes: × 0.579 … 1.728 of `rem`; ÷/× 1.2 of the parent's |
+
+* **`var(name[, fallback])`** reads another setting of the object, resolved through the
+  usual inheritance. **`inherit`** (or `var()` of the setting's own name) reads the
+  parent's value of the same setting (`alpha="calc(inherit / 2)"`). `var(--name)` reads a custom variable: from the
+  nearest `vars` (figure or plot), else a `"--name"` key of the style. The fallback is used
+  when the value is unset. Loops raise. Text settings (titles, labels, names, formats)
+  never read `var()`.
+* **`calc()`** takes `+ - * /`, parentheses, numbers, dimensions with any unit, `var()`
+  and `inherit`: dimensions add to dimensions and multiply or divide by numbers.
+* **Layout.** `%` of the axes is exact with `reference="axes"` (the axes size is given)
+  and resolved in each [layout](#layout) round otherwise; it is known only while the
+  figure is drawn. A render first resolves every other setting of the figure once (the values
+  drawing reads); settings set while it runs take effect at once. `spacing`, `margin` and fixed `widths`/`heights` in `%` of the figure are solved
+  exactly when the figure size follows from its contents.
+* **Scaling.** `Figure.scaling` multiplies every absolute length (px and physical units)
+  wherever it is given: on objects, in styles, in `DEFAULTS`; not the figure size.
+  `em`, `rem` and font keywords follow `font_size`, which is scaled; `%`, `fr` and `data`
+  are not scaled.
+* **Reading.** `get(name)` returns the value as given, `resolve(name)` the final value
+  (`resolve(name, of=…)` for settings whose `%` reference the caller passes), and
+  `explain(name)` a trace:
+
+#### Referents
+
+What `%` of a length can be of, besides another setting (the tables name it per setting):
+
+<!-- settings:referents -->
+| Key | `%` of |
+|---|---|
+| `em` | the font size |
+| `axes_width` | the axes width |
+| `axes_height` | the axes height |
+| `across` | the axes side across the axis |
+| `along` | the axes side along the axis |
+| `axes` | the axes width (across) or height (down) |
+| `axes_length` | the axes length along the axis |
+| `data_range` | the axis range |
+| `bar_across` | the axes side across the colorbar |
+| `bar_along` | the axes side along the colorbar |
+| `figure` | the figure width (across) or height (down) |
+| `slot` | the slot: one category, or the smallest gap between positions |
+| `slot_part` | each series' part of a shared slot |
+| `box_width` | the box width |
+| `radius` | the radius |
+<!-- /settings -->
+
+#### Setting groups
+
+Members, their names under a prefix `{p}`, and the group defaults (`"Group.member"` keys).
+`"FillStyle.fill"` sets every series fill (bars, boxes, violins, pies, densities,
+contours, genome signals and intervals); `"Marker.fill"` every marker fill.
+
+<!-- settings:groups -->
+| Group | Member | Under a prefix `{p}` | Default |
+|---|---|---|---|
+| `Font` | `font_size` | `{p}font_size` | inherited |
+| `Font` | `font_family` | `{p}font_family` | inherited |
+| `Font` | `font_stretch` | `{p}font_stretch` | inherited |
+| `Font` | `font_variations` | `{p}font_variations` | inherited |
+| `Font` | `font_optical_sizing` | `{p}font_optical_sizing` | inherited |
+| `TextStyle` | `font_size` | `{p}font_size` | '1em' |
+| `TextStyle` | `font_weight` | `{p}weight` | 'normal' |
+| `TextStyle` | `font_style` | `{p}style` | 'normal' |
+| `TextStyle` | `color` | `{p}color` | 'var(text_color)' |
+| `Stroke` | `color` | `{p}color` | — |
+| `Stroke` | `line_width` | `{p}width` | 0.75 |
+| `Stroke` | `line_style` | `{p}style` | 'solid' |
+| `Stroke` | `cap` | `{p}cap` | 'butt' |
+| `Stroke` | `join` | `{p}join` | 'round' |
+| `Marker` | `marker` | `marker (never prefixed)` | 'circle' |
+| `Marker` | `size` | `{p}size` | 4.5 |
+| `Marker` | `color` | `{p}color` | — |
+| `Marker` | `edge_color` | `{p}edge_color` | 'auto' |
+| `Marker` | `edge_width` | `{p}edge_width` | 0.75 |
+| `Marker` | `fill` | `{p}fill` | True |
+| `Marker` | `size_basis` | `size_basis (never prefixed)` | 'area' |
+| `FillStyle` | `fill` | `{p}fill` | — |
+| `NumberFormat` | `decimal_separator` | `{p}decimal_separator` | inherited |
+| `NumberFormat` | `thousands_separator` | `{p}thousands_separator` | inherited |
+| `NumberFormat` | `minus` | `{p}minus` | inherited |
+| `NumberFormat` | `prefix` | `{p}prefix` | inherited |
+| `NumberFormat` | `suffix` | `{p}suffix` | inherited |
+| `NumberFormat` | `precision` | `{p}precision` | inherited |
+<!-- /settings -->
+
+```
+>>> pl.Plot(style="matplotlib").x_axis.explain("tick_spacing")
+Axis.tick_spacing = (46.6667px, 33.3333px) ← ('calc(3.5 * var(tick_label_font_size))', 'calc(2.5 * var(tick_label_font_size))')  (default Axis.tick_spacing)
+  Axis.tick_label_font_size = 13.3333px ← '1em'  (default Axis.tick_label_font_size)
+    Axis.font_size = 13.3333px ← '10.0pt'  (inherited from Figure: style "matplotlib" font_size)
+```
+
+## 2. Figures
+
+```python
+pl.Figure(**settings)
+fig.plot(id=None, **settings)            # the plot with id (created if needed), or the next one
+fig.scatter(x, y, **settings)            # any plot type: a new plot holding it
+fig.title(text, **settings)              # figure title
+fig.x_axis(**settings)                   # settings of every plot's x axis (fig.y_axis: y)
+fig.colorbar(source, id=None, **settings)    # the guide of a color axis, in its own area
+fig.color_axis(**settings)               # a shared color axis (fig.size_axis: size)
+fig.size_legend(source, id=None, values=None, title=None)
+fig.track(**settings)                    # a new track (layout="tracks")
+fig.vline(x, rows=None, **settings)      # through plots and the gaps between them
+fig.vspan(x0, x1=None, rows=None, **settings)
+fig.group(first, last=None, label=None, letter=None)
+fig.plots                                # plots in creation order
+```
+
+A plot type called on the figure (`fig.scatter(…)`, `fig.hist(…)`, `fig.bigwig(…)`) makes
+a new plot holding it and returns the series: the plot's settings that the plot type
+lacks, `title`, `x_axis` and `y_axis` go to the plot.
+
+### Arrangement
+
+* **Grid.** `layout=[[1, 1, 2], [3, 3, 2]]`: each id covers a rectangle of cells; `0` or
+  `None` leaves a cell empty. An id holds a plot or a colorbar. `fig.plot()` returns the
+  next id without a plot, in reading order.
+* **Automatic** (`layout="auto"`, the default). Plots take positions in creation order:
+
+| Settings | Arrangement |
+|---|---|
+| `cols=4` | row by row, at most 4 per row |
+| `rows=4` | column by column, at most 4 per column |
+| `rows=2, cols=3` | a fixed 2 × 3 grid, row by row (full: `ValueError`) |
+| neither | ⌈√n⌉ columns, row by row, chosen when drawn (adding plots can move earlier ones) |
+
+`fill_order` (`"row"` or `"col"`) overrides the fill direction. In automatic arrangement ids
+are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
+
+* **Tracks.** `layout="tracks"`: one column of plots top to bottom in creation order
+  (`cols` 1), sharing x (`share_x="all"`), `spacing` 0 and `width` 480 px unless given;
+  each row is as high as its plot's `height` (a [track](#tracks)'s: a length, a share such
+  as `"1fr"`, or from its content), other plots `1fr`. New plots are tracks
+  (`fig.plot()`, `fig.track()`, `fig.bigwig(…)`). `pl.Tracks(region)` is this layout with
+  a genome x axis ([§9](#9-genome-tracks)).
+
+### Sizes and alignment
+
+* `width` × `height` is the size of the box `reference` names:
+  * `"axes"` (default): each grid cell's axes rectangle; the figure size follows;
+  * `"plot"`: each cell's whole plot box (axes and decorations); the figure size follows;
+  * `"figure"`: the whole figure; the cells share what the decorations leave.
+
+  With only one of `width` and `height`, `aspect_ratio` (width / height, default 5/4)
+  gives the other; with neither, the default is 150 × 120 px. Giving all
+  three raises `ValueError`. Plots with a `data_ratio` (and pies) take the other side from
+  it when only `width` or only `height` is given. `widths`/`heights` are the columns' and
+  rows' ratios (numbers or `fr`), or fixed lengths (`["2in", "1fr", "1fr"]`) that the
+  ratios share the rest around; a plot spanning cells gets their sizes plus the gaps
+  between them.
+* `align="axes"` (default): axis lines line up. Between columns the gutter holds the
+  widest right margin before it, the widest left margin after it and `spacing`.
+* `align="borders"`: plot boxes (axes and decorations) line up, and each plot's axes are
+  what its own decorations leave.
+* `reference` and `align` combine:
+
+| `align` \ `reference` | `"axes"` | `"plot"` | `"figure"` |
+|---|---|---|---|
+| `"axes"` | each cell's axes are `width` | the widest plot box of a column (axes plus the column's largest margins) is `width`; the axes are what is left | the figure is `width`; the axes share what the gutters leave |
+| `"borders"` | a column's box is `width` plus the largest margins in it, so every axes rectangle is at least `width` | each cell's box is `width` | the figure is `width`; the boxes share what the gaps leave |
+
+* Columns (rows) holding only vertical (horizontal) colorbars are as wide as the bar,
+  unless `widths` (`heights`) is given.
+* Margins come from the real text metrics of tick labels, axis labels, titles, outside
+  legends and attached colorbars ([layout](#layout)).
+
+### Layout
+
+* **Bands.** A plot is its axes rectangle with four stacks of bands around it, from the
+  axes outward: tick marks, tick labels, the ×10ᵏ offset (above the y axis), the axis
+  label, twin axes, an outside legend, attached colorbars, the plot title (top) and the
+  plot's `space_above`; outermost on the left, the row label and group bands, as wide as the
+  widest of the plot's grid column. Each band has a thickness and an overhang along its
+  side (tick labels past the ends of the axis, a wide title). A side's margin is its
+  bands' thicknesses, at least the overhangs of the bands across it. Bands stack: each
+  starts past the ones before it (mirrored ticks included), the title past everything on
+  top; only twin axes are drawn at the axes edge.
+* **Grid.** Each line between cells takes the largest margin of the plots there
+  (`align="axes"`), or each plot's axes are what its margins leave of its box
+  (`"borders"`). Colorbars and size legends in their own areas are cells of the grid; the
+  figure title is a band at the top of the figure.
+* **Rounds.** Only what is circular is repeated: an axis' length sets its ticks, whose
+  labels set the margins, which (with `reference="plot"` or `"figure"`) set the length;
+  `data_ratio`; stats binned at the axes' resolution ([hexbin](#hexbin), genome
+  [bins](#9-genome-tracks)); the figure title's band in a figure of fixed height. A round
+  measures every plot for its axes size and solves the grid. Rounds stop when no axes size
+  moves by more than 1/3 px; after 5, a layout still moving (between two tick sets) keeps
+  the last. With `reference="axes"` one round suffices. `position="auto"` legends are
+  placed on the occupancy grid of the placed axes; one moved outside takes a round more.
+* **Geometry.** The layout ends in a frozen geometry: every axes rectangle, tick mark,
+  text run, legend entry and colorbar in px. Drawing reads it and measures nothing: a text
+  run holds its shaped line (shaped once per content and font, memoized in the font
+  database), which is what is drawn; the figure title is laid out once as paragraphs.
+* **One plot.** `p.save()` lays out the whole figure and keeps the plot at its size in it:
+  its axes (`align="axes"`), or its box (`"borders"`: the axes are what its own margins
+  leave), with its outer tick labels and its own row label band.
+
+### Figure title
+
+```python
+fig.title(text, **settings)        # None removes it
+```
+
+A band at the top of the figure: the title's height (all lines, wrapped within its
+width) plus `pad`. The figure grows by the band, except with `reference="figure"`, where
+the plots shrink by it. `over="axes"` aligns it within the leftmost to
+rightmost axes (a left-aligned title starts at the first y axis line), `"figure"` within
+the figure minus `margin`. Rich content styles a second line (`["Title\n",
+pl.Span("subtitle", font_size=7, font_weight="normal")]`). It is drawn last and is not
+part of `Plot.save`. `title=` given to `pl.Plot` sets the plot title. The figure's
+`title_rule_color` draws a rule `title_rule_width` thick above the title, across its
+width.
+
+<!-- settings:FigureTitle -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `text` | — | Title text: a string or rich content; `\n` starts a line. |
+| `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
+| `font_weight` | 'bold' | `normal`, `bold` or a weight 1–1000. |
+| `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `align` | 'center' | Alignment. |
+| `over` | 'axes' | Width it is aligned and wrapped within: from the leftmost to the rightmost axes, or the whole figure. |
+| `pad` | '0.5em' | Gap between the title and the plots; default half the font size. Length. |
+| `color` | 'var(text_color)' | Text color. |
+| `rule_gap` | '0.5em' | Gap between the title and the figure's `title_rule_color`. Length; `%`: of the font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `TextStyle`, `Font`.
+<!-- /settings -->
+
+### Shared axes
+
+```python
+fig = pl.Figure(cols=3, share_x="col", share_y="row")
+fig = pl.Figure(cols=3, share="grid")            # the same
+q = fig.plot(share_x=p)                          # q's x axis joins p's group
+```
+
+`share_x`, `share_y`: `False` (default), `True`/`"all"` (every plot), `"col"` (plots with
+the same column span) or `"row"` (the same row span). `share` sets both; `"grid"` means x
+per column and y per row. A plot's own `share_x`, `share_y` or `share` (another plot)
+overrides the figure's groups for it; groups chain. Colorbars and plots without axes are
+never in a group. `share_color` and `share_size` group plots the same way for their
+series' color and size axes ([color and size axes](#6-color-and-size-axes)).
+
+Within a group the scale (which must be equal), the limits (from all members' series,
+then padding, `include_zero` and `snap`; one explicit `limits` applies to the group, two
+different ones are an error), inversion, ticks and category order (first appearance, in
+plot order) are shared; titles, grid, spines and colors stay per plot. With
+`label_outer` (default for figure-level groups), tick labels and axis titles are drawn
+only on the bottom plot of each column (x; top for `side="top"`) and the left plot of
+each row (y; right for `side="right"`); ticks stay on every plot and inner gutters
+shrink. `Plot.save` of a member keeps the group's limits and shows its labels.
+
+### Figure axes
+
+```python
+fig.x_axis(label="Time (s)", tick_format="int")  # every plot's x axis
+fig.y_axis(scale="log10")
+```
+
+`fig.x_axis` and `fig.y_axis` hold settings that every plot's x (y) axis takes unless the
+axis has its own: they come right after the axis' own values in the cascade
+([§1](#1-conventions)), so they beat styles and defaults. Twins' axes take them too; color
+and size axes do not.
+
+### Rows
+
+```python
+p = fig.plot(y_axis={"label": "Control", "label_position": "band"})   # a row label
+fig.group(p, q, label="Treated", letter="B")    # plots p to q (creation order)
+fig.vline(0, rows=[p, q])                        # through p, q and the gap between them
+fig.vspan(-1, 1)                                 # under every plot
+```
+
+* **Row labels.** The y axis' `label` with `label_position` `"band"` (rotated) or
+  `"left"` (horizontal, right-aligned) sits in a band left of the plot instead of beside
+  the tick labels; `"inside"` puts it inside the axes at the top left; `\n` starts a line.
+  The band is as wide as the widest label of the plots starting in the same grid column,
+  and the labels line up at the widest y axis margin of that column. A plot has one y
+  label: beside its axis or in the band. Tracks put theirs in the band. A plot's
+  `space_above` adds space above it.
+* **Groups.** `fig.group(first, last=None, **settings)`: plots `first` to `last` (plots
+  or their series, in creation order) with a rotated `label` and a bold panel `letter` in a
+  band left of the row labels. With a shared x axis and `label_outer`, the group's last
+  plot shows the tick labels too (the axis title stays under the bottom plot).
+* **Lines and bands.** `fig.vline(x, rows=None)` and `fig.vspan(x0, x1, rows=None)` run
+  from the top of the first of the plots `rows` (a plot, a series, or a list; all by
+  default) to the bottom of the last one, gaps included, in each grid column; `x` is in
+  the drawn units of the first plot's x axis. Bands are drawn under the plots, lines over
+  them. `fig.vspan(region)` takes a genome region (`"chr1:1,400,001-1,450,000"`, a
+  `(chr, start, end)` tuple) as positions, less the x axis' `origin`.
+
+FigureVLine:
+
+<!-- settings:FigureVLine -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | '#4d4d4d' | Line color. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_style` | 'dashed' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
+| `alpha` | 1.0 | Opacity. |
+
+Groups: `Stroke`.
+<!-- /settings -->
+
+FigureVSpan:
+
+<!-- settings:FigureVSpan -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | '#e5e5e5' | Fill color. |
+| `alpha` | 1.0 | Opacity. |
+<!-- /settings -->
+
+FigureGroup:
+
+<!-- settings:FigureGroup -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `label` | — | Group label, rotated, left of the plots' row labels. |
+| `letter` | — | Panel letter at the group's top left. |
+| `font_size` | '1em' | Font size of the label. Length; `%`: of the parent's font size. |
+| `letter_font_size` | '1.4em' | Font size of the letter. Length; `%`: of the font size. |
+| `letter_weight` | 'bold' | Weight of the letter. |
+| `pad` | '0.5em' | Gap right of the group band. Length; `%`: of the font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `text_color` | inherited ('black') | Text color. |
+
+Groups: `TextStyle` (`letter_`).
+<!-- /settings -->
+
+### Facets
+
+```python
+fig, panels = pl.facet(df, col="condition", row="replicate", colorbar="right")
+panels.scatter("x", "y", c="density")            # one layer per panel, on its rows
+panels.hline(0, line_style="dashed")             # decorations on every panel
+panels.map(lambda p, rows: p.hist(rows["x"]))     # anything, per panel
+fig.save("facets.pdf")
+```
+
+`pl.facet(data, col=None, row=None, wrap=None, share="grid", order=None,
+title_format="{name} = {value}", colorbar=None, **figure_settings)` returns an ordinary
+`Figure`, with one plot per combination of `row` and `col` values (first-appearance or
+categorical order; `order={column: [values]}`) in a grid, and the `FacetSet` of those
+panels. `wrap` wraps `col` alone into rows of that many panels. Panels are titled by
+`title_format`.
+
+* **Layers.** A plot type called on the set (`panels.scatter(…)`, any registered one)
+  calls it on every panel with `data=` the panel's rows and returns a `LayerSet` (a list
+  of the series; `.set(**settings)` sets them all, `.plots` their plots). Group levels
+  (`group=`) get the same colors in every panel. Decorations (`hline`, `vline`, `axline`,
+  `hspan`, `vspan`, `text`, `annotate`) go on every panel.
+* **Shared axes** are the figure's ordinary options: `share` (default `"grid"`: x per
+  column, y per row, outer labels only), `share_color` (default `"all"`: the panels'
+  color axes train as one; a `color_map`, `color_limits` or `color_scale` given to the
+  call goes to each series alike) and `share_size` (default `"all"`: one size axis, so
+  one size key, in the top-right panel's legend).
+* **Colorbar.** `colorbar="right"`, `"left"`, `"top"` or `"bottom"` adds a column (or a
+  row, with a horizontal bar) to the grid, holding the colorbar of the first call that maps
+  colors (`panels.colorbar`): the guide of the panels' shared color axis.
+* `panels.panels` maps facet keys (a value, or `(row value, col value)`) to plots;
+  `panels.plot(key)` returns one; iterating the set gives the plots; `panels.subsets()`
+  gives `(key, plot, rows)`.
+
+### Settings
+
+<!-- settings:Figure -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `layout` | 'auto' | `auto`: plots in automatic rows and columns (`rows`, `cols`, `fill_order`); rows of ids (`[[1, 1, 2], [3, 4, 2]]`): each id covers a rectangle of cells, `0`/`None` leaves a cell empty; `tracks`: one column of plots top to bottom in creation order, sharing x, each row as high as its plot's `height` (tracks: from their content; other plots `1fr`). |
+| `rows` | — | Automatic arrangement: rows. |
+| `cols` | — | Automatic arrangement: columns. |
+| `fill_order` | 'auto' | Fill order of the automatic arrangement: `auto` (row by row with `cols`, column by column with `rows`), `row` or `col`. |
+| `align` | 'axes' | `axes`: axis lines line up across plots; `borders`: plot boxes line up. |
+| `widths` | — | Column widths: ratios (numbers or `fr`) sharing the room left by fixed lengths (`"2in"`, `"30%"` of the figure width). |
+| `heights` | — | Row heights, as `widths`. |
+| `width` | '150px' | Width of the `reference` box: one cell's axes, one cell's plot, or the figure. Length. |
+| `height` | 'calc(var(width) / var(aspect_ratio))' | Height of the `reference` box. Length. |
+| `aspect_ratio` | 1.25 | Width / height of the `reference` box (16:9 → `16 / 9`), when only one of `width` and `height` is given. |
+| `reference` | 'axes' | What `width` and `height` measure: `axes` (each grid cell's axes rectangle), `plot` (each cell's whole plot box) or `figure`. |
+| `spacing` | 13.0 | Minimum gap between neighbouring plots. Length; `%`: of the figure width (across) or height (down). |
+| `margin` | 5.0 | Space around the figure. Length; `%`: of the figure width (across) or height (down). |
+| `background` | 'white' | Figure background, default white; `None` or `"none"`: transparent (white in JPEG, which has no transparency). |
+| `dpi` | 192.0 | Resolution of PNG, JPEG, JPEG XL and AVIF output: `96` gives one image pixel per px, the default `192` two; up to 16, a multiple of 96 (`2` is 192). |
+| `quality` | 'auto' | Quality (1–100), as vec_io's: of PNG output (a lossy palette of at most 256 colors), JPEG, JPEG XL and AVIF output, and of rasterized content in PDFs (stored as JPEG); `"lossless"` (not JPEG); `"auto"`: 90 for PNG and JPEG, lossless for JPEG XL, AVIF and PDF content. |
+| `title_rule_color` | — | Color of a rule above the figure title, across its width (The Economist's red bar); default none. |
+| `title_rule_width` | 4.0 | Thickness of the title rule. Length. |
+| `share_x` | — | Plots sharing their x axis: `False`, `True`/`"all"`, `"col"` (same column span) or `"row"` (same row span). |
+| `share_y` | — | Plots sharing their y axis, as `share_x`. |
+| `share` | — | Both axes at once: as `share_x`, or `"grid"` (x per column, y per row); `share_x`/`share_y` override it. |
+| `share_color` | False | Plots whose series' own color axes are one (limits over all their values), as `share_x`. |
+| `share_size` | False | Plots whose series' own size axes are one (limits over all their values, one size key), as `share_x`. |
+| `label_outer` | — | Tick labels and axis titles of shared axes only on the outer plots (bottom of each column, left of each row); default `True` for groups from the figure's settings, `False` for plots paired with `share_x=plot`. |
+| `style` | — | A style name (`"ggplot2"`, …) or a dict of settings with an optional `"base"`; default: the session style (`set_style`, `use_style`), else `"default"`. |
+| `vars` | — | Custom variables, read by `var(--name)` in any setting here and below: `{"accent": "#c00"}`. |
+| `scaling` | 1.0 | Multiplies every font size, line width, marker size, tick length and pad of the style; default 1. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `text_color` | inherited ('black') | Text color. |
+| `line_width` | inherited (0.75) | Default line width. Length. |
+| `palette` | inherited ('tab10_custom') | Colors of series without one. |
+| `alpha` | inherited (1.0) | Default opacity of series. |
+| `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
+| `simplify` | inherited ('auto') | vec_io's `simplify` for every series; default `"auto"`. |
+| `data` | inherited (None) | A table whose columns the series' data arguments name. |
+| `color_map` | inherited ('rainbow_llhh') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`title_rule_`), `Font`, `NumberFormat`.
+<!-- /settings -->
+
+## 3. Plots
+
+```python
+pl.Plot(figure=None, id=None, **settings)   # title="…", x_axis={…}, y_axis={…}
+p.scatter(x, y, **s)   p.line(x, y=None, **s)   p.fill(x, y1, y2=0, **s)
+p.box(values, **s)     p.heatmap(values, **s)   p.colorbar(source=None, **s)
+p.title(text, **s)     p.x_axis(label, **s)     p.y_axis(label, **s)    p.legend(position, **s)
+p.series   p.colorbars   p.figure   p.id
+```
+
+`p.title`, `p.x_axis`, `p.y_axis` and `p.legend` are objects; calling one sets its
+settings and returns it. At creation (and in `p.set`), `title=` sets the title text and
+`x_axis={…}`, `y_axis={…}` set the axes' settings: `pl.Scatter(x, y, x_axis={"scale":
+"log"})`, `fig.bigwig(reader, y_axis={"label": "ATAC"})`. Series are drawn in `z` order (default: call order) inside the
+axes clip.
+
+<!-- settings:Plot -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `spines` | 'bottom left' | Axis lines drawn: any of `left`, `bottom`, `right`, `top`, or `all`, `none`. |
+| `data_ratio` | — | Data aspect ratio: 1 makes one unit as long on both axes. |
+| `background` | — | Background color of the axes area. |
+| `border_color` | — | Color of a frame around the axes area (drawn under the axis lines); default none. |
+| `border_width` | 0.75 | Width of the frame. Length. |
+| `clip` | True | Clip series to the axes area. |
+| `axes` | True | Draw axes; `False` hides both axes, drops padding and fixes the aspect to 1 (set by pie charts). |
+| `share_x` | — | Another plot of the figure whose x axis this plot shares (groups chain); overrides the figure's `share_x`. |
+| `share_y` | — | Another plot whose y axis this plot shares. |
+| `vars` | — | Custom variables, read by `var(--name)` in any setting here and below: `{"accent": "#c00"}`. |
+| `share` | — | Another plot whose x and y axes this plot shares. |
+| `space_above` | 0.0 | Space above the plot, beyond the figure's `spacing`. Length; `%`: of the font size. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `text_color` | inherited ('black') | Text color. |
+| `line_width` | inherited (0.75) | Default line width. Length. |
+| `palette` | inherited ('tab10_custom') | Colors of series without one. |
+| `alpha` | inherited (1.0) | Default opacity of series. |
+| `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
+| `simplify` | inherited ('auto') | vec_io's `simplify` for every series: `"auto"`, `True`, a dpi or `False`. |
+| `color_map` | inherited ('rainbow_llhh') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
+| `data` | inherited (None) | A table (dict, pandas or polars data frame, numpy structured array): strings in the data arguments of series name its columns. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`border_`), `Font`, `NumberFormat`.
+<!-- /settings -->
+
+### Title
+
+<!-- settings:Title -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `text` | — | Title text: a string or rich content. |
+| `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
+| `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
+| `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `color` | 'var(text_color)' | Text color. |
+| `align` | 'center' | Alignment over the axes. |
+| `pad` | 5.0 | Gap above the axes. Length; `%`: of the axes height. |
+| `over` | 'axes' | Width the title is aligned within: the axes, or the axes and the y axis labels. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `TextStyle`, `Font`.
+<!-- /settings -->
+
+### Legend
+
+One entry per series with a `name`, drawn as the series draws itself (marker, line,
+swatch or box), or with `glyph="box"`, `"circle"` or `"line"` in the series color. At
+`top`, `bottom`, `outside_top` and `outside_bottom` entries are side by side unless
+`orientation` or `columns` is set.
+
+**Size keys.** A series whose `size` goes through a [size axis](#6-color-and-size-axes)
+adds a size key, the axis' guide, to its plot's legend, below the series entries: the
+axis' `label` (default: the `size` column name) as a header, then sample markers at their
+real size with their values (the list given as the series' `size_legend`, else the axis'
+`ticks`, else 3–5 nice numbers inside its limits; in its `tick_format`;
+`size_legend=False` drops it). Series sharing one size axis (one `fig.size_axis()`, or own
+axes trained as one by `share_size` or `group=`) share one key, in grey, also across
+plots. The key goes in the legend of the rightmost of their plots, and the topmost of
+those, so it sits at the figure's top right. Users with different `size_map`s get a key
+per map. A single series' key takes its color (grey when its colors are mapped).
+`fig.size_legend(source, id=…, values=None, title=None)` places the key of a size axis
+(or of a series' one) in its own grid area, as colorbars do. It shows every series of
+that axis, and no plot legend repeats it.
+
+`auto` chooses a position once the axes are placed. Every series marks what it draws on a
+64 × 64 grid over the axes: markers (with their size), lines and curves (along their
+whole length), bars, histogram bins, boxes, violins, areas and fills (the area they cover),
+heatmaps, 2-D histograms and contours (the whole axes). Data are sampled beyond 50,000
+points and curves thinned to 4,096 vertices (twin plots' series included). The legend
+goes to the first of `top_right`, `top_left`, `bottom_left`, `bottom_right`, `top`,
+`bottom`, `center_right`, `center_left` whose box covers no marked cell; else to the free
+place (any position inside, one grid cell apart, covering no marked cell) nearest to a
+corner of the axes; else `outside_right`, with room made in the layout, when every
+candidate covers more than 2 % marked cells; else the candidate covering the fewest.
+
+<!-- settings:Legend -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `position` | 'auto' | `auto`, `top_right`, `top_left`, `bottom_right`, `bottom_left`, `top`, `bottom`, `outside_right`, `outside_top`, `outside_bottom` or `none`. |
+| `columns` | 1 | Number of columns. |
+| `frame` | False | Draw a frame and background. |
+| `title` | 'auto' | Legend title; `"auto"`: the `group` column name, if any. |
+| `font_size` | '1em' | Font size. Length; `%`: of the parent's font size. |
+| `color` | 'var(text_color)' | Text color. |
+| `background` | 'white' | Background of a framed legend. |
+| `frame_color` | '#999999' | Frame color. |
+| `frame_width` | 0.5 | Frame line width. Length. |
+| `pad` | 5.0 | Gap to the axes. Length; `%`: of the axes width (across) or height (down). |
+| `frame_radius` | 0.0 | Corner radius of the frame. Length. |
+| `frame_alpha` | 1.0 | Opacity of the frame and background. |
+| `glyph_alpha` | — | Fill opacity of `box` and `circle` symbols, outlined in the opaque color; default: the series' own fill. |
+| `glyph` | 'series' | Entry symbol: as the series draws itself, or a filled `box`, a `circle` or a `line` in the series color. |
+| `orientation` | 'auto' | `horizontal`: entries side by side; `auto`: horizontal at `top`, `bottom`, `outside_top` and `outside_bottom`. |
+| `glyph_length` | '1.4em' | Width of an entry's symbol. Length; `%`: of the font size. |
+| `row_height` | '1.35em' | Height of an entry. Length; `%`: of the font size. |
+| `glyph_gap` | '0.5em' | Gap between a symbol and its text. Length; `%`: of the font size. |
+| `column_gap` | '1em' | Gap between columns. Length; `%`: of the font size. |
+| `title_gap` | '0.3em' | Gap below the title. Length; `%`: of the font size. |
+| `inner_pad` | 'auto' | Space inside the box; `"auto"`: 0.5em with a frame, 0.15em without. Length; `%`: of the font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `TextStyle`, `Stroke` (`frame_`), `Font`.
+<!-- /settings -->
+
+### Decorations
+
+Reference lines, bands, text and annotations. They take no palette color, are in the
+legend only with a `name`, and change the limits only with `extend_limits=True`. They
+are drawn among the series by `z`: spans under the series (`z=-1`), lines and text over
+them (`z=1`).
+
+```python
+p.hline(y, min="0%", max="100%", color="#4d4d4d", line_style="solid", ...)  # min/max: data values or % of the axes
+p.vline(x, ...)
+p.axline((x0, y0), slope=None, point2=None, ...)                    # slope: linear axes only
+p.hspan(y0, y1, color="#e5e5e5", ...); p.vspan(x0, x1, ...)
+p.text(x, y, content, align="left", valign="baseline", rotation=0, coords="data", ...)
+p.annotate(content, xy, xytext=None, text_coords=None, arrow_style="->", ...)
+```
+
+Positions are data values (category names on category axes), or fractions with
+`coords="axes"` or `"figure"`. `text_coords="offset"` gives `xytext` in points from `xy`
+(y up). Text is a string or rich content. Arrows run from the edge of the text box to
+`xy`, `shrink` points short of both.
+
+HLine:
+
+<!-- settings:HLine -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | '#4d4d4d' | Line color. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
+| `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
+| `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | 1.0 | Opacity. |
+| `z` | 1.0 | Drawing order among the series (default 0). |
+| `extend_limits` | False | Include the decoration in the axis limits. |
+| `clip` | True | Clip to the axes area. |
+
+Groups: `Stroke`.
+<!-- /settings -->
+
+AxLine:
+
+<!-- settings:AxLine -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | '#4d4d4d' | Line color. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | 1.0 | Opacity. |
+| `z` | 1.0 | Drawing order among the series (default 0). |
+| `extend_limits` | False | Include the decoration in the axis limits. |
+| `clip` | True | Clip to the axes area. |
+
+Groups: `Stroke`.
+<!-- /settings -->
+
+HSpan:
+
+<!-- settings:HSpan -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | '#e5e5e5' | Fill color. |
+| `edge_color` | — | Outline color; default none. |
+| `edge_width` | 0.0 | Outline width. Length. |
+| `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
+| `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; `%`: of the axes length along the axis; bare numbers: data units. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | 1.0 | Opacity. |
+| `z` | -1.0 | Drawing order among the series (default 0). |
+| `extend_limits` | False | Include the decoration in the axis limits. |
+| `clip` | True | Clip to the axes area. |
+
+Groups: `Stroke` (`edge_`).
+<!-- /settings -->
+
+Text:
+
+<!-- settings:Text -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `align` | 'left' | Horizontal alignment on the point. |
+| `valign` | 'baseline' | Vertical alignment on the point. |
+| `rotation` | 0.0 | Rotation (degrees, counterclockwise). Angle (bare: degrees). |
+| `coords` | 'data' | `data`, `axes` (0–1) or `figure` (0–1). |
+| `color` | 'var(text_color)' | Text color; default `text_color`. |
+| `font_size` | inherited (11.0) | Font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
+| `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `text_color` | inherited ('black') | Text color. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | 1.0 | Opacity. |
+| `z` | 1.0 | Drawing order among the series (default 0). |
+| `extend_limits` | False | Include the decoration in the axis limits. |
+| `clip` | False | Clip to the axes area. |
+
+Groups: `TextStyle`, `Font`.
+<!-- /settings -->
+
+Annotate:
+
+<!-- settings:Annotate -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `align` | 'center' | Horizontal alignment on `xytext`. |
+| `valign` | 'center' | Vertical alignment on `xytext`. |
+| `text_coords` | 'var(coords)' | Coordinates of `xytext`: as `coords`, or `offset` (px from `xy`, y up); default `coords`. |
+| `arrow` | True | Draw an arrow from the text to `xy`. |
+| `arrow_style` | '->' | `->` (open head), `-\|>` (filled head) or `-` (no head). |
+| `arrow_color` | 'var(color)' | Arrow color; default the text color. |
+| `arrow_width` | 0.75 | Arrow line width. Length. |
+| `head_length` | 7.0 | Arrowhead length. Length. |
+| `shrink` | 3.0 | Gap left at both ends of the arrow. Length. |
+
+Groups: `Stroke` (`arrow_`).
+<!-- /settings -->
+
+## 4. Axes
+
+### Scales
+
+| `scale` | Position | Domain |
+|---|---|---|
+| `linear` | v | all |
+| `log`, `log2`, `log10` | ln v, log₂ v, log₁₀ v | v > 0 |
+| `sqrt` | √v | v ≥ 0 |
+| `exp` | eᵛ | v < 709 |
+| `symlog` | sign(v)·log₁₀(1 + abs(v)/`linthresh`) | all |
+| `logit` | log₁₀(p/(1 − p)) | 0 < p < 1 |
+| `time` | seconds since 1970-01-01 UTC | dates and times |
+| `category` | category index | categories |
+| `genome` | position in bp (less the axis' `origin`) | the axis' `region` |
+
+The genome scale is linear, its limits the axis' `region` without padding, its tick labels
+in `unit` (bp, kb or Mb; `unit_in` puts the unit in the label or after each tick label),
+its automatic label the chromosome; genome series set it on an x axis without a scale
+([§9](#9-genome-tracks)).
+
+Values outside the domain are missing on that axis. The three logs place data
+identically; they differ in their ticks. Box and heatmap series with labels make their
+axis a category axis; mixing category and numeric series on one axis raises `ValueError`.
+`symlog` ticks: 0, ±`linthresh`, then decades. Inside the linear region (`linthresh`,
+default 1), minor ticks sit at the finest step of `linthresh`/10, /5, /4 or /2 that keeps
+them as far apart as minor ticks 4 and 5 of a log decade, or are left out. `logit` ticks: 0.5, then 0.1/0.9, 0.01/0.99, …
+
+### Dates and times
+
+`datetime`, `date`, numpy `datetime64` arrays and pandas timestamps given as x or y make a
+`time` axis (also bar positions; bar `width` takes a `timedelta`). Values become seconds
+since the epoch (naive ones read as UTC); aware ones are shown in their zone (`tz`, default
+the zone of the first value). Ticks follow the calendar: years (1, 2, 5, 10, …), months
+(1, 2, 3, 6), days (1, 2, 7, 14), hours (1, 2, 3, 6, 12), minutes, seconds and fractions,
+chosen from the span and `max_ticks`. Labels are concise (`2026`, `Mar`, `Mar 14`,
+`14:30`, `14:30:15`, `15.250`), with January labelled by its year, and the larger unit
+common to every tick written at the end of the axis, as the ×10ᵏ factor is
+(`2026`, `Mar 14, 2026`).
+`tick_format` takes a `strftime` pattern (`"%Y-%m"`) or a function of a `datetime`.
+`limits` take dates and ISO strings (`("2026-01-01", None)`, `"2026-01-01/max"`).
+
+### Secondary axes
+
+```python
+p2 = p.twin_y()                  # its own y axis on the right, p's x axis
+p2.line(t, temperature)
+p2.y_axis(label="Temperature (°C)", scale="log10")
+```
+
+`twin_y()` returns a plot drawn on `p`'s axes rectangle, sharing its x axis (limits from
+the series of both) with its own y axis on the right; `twin_x()` does the same for x (on
+top). The twin's axis adds margin on its side, and outside legends and colorbars move
+beyond it. Its series continue `p`'s palette and appear in `p`'s legend unless the twin's
+legend position is set. Background, title, frame and grid belong to `p` (a twin draws a
+grid only when its axis asks). `p.save` includes its twins.
+
+### Limits
+
+* `"auto"`: the union of the series' extents plus `padding` (0.05 of the range per side,
+  in position space: a factor on log axes; heatmaps take none).
+* `"lo/hi"`: each side `min`, `max`, a number or `q:F` (quantile F of the axis's values):
+  `"0/max"`, `"q:0.01/q:0.99"`. Or `(lo, hi)`, `None` meaning automatic.
+* A single value is widened by ±0.5 in position space. `invert=True` reverses the axis.
+* `include_zero=True` extends automatic limits to 0 (linear and sqrt axes) before padding
+  and `snap`; `"auto"` does so where a series on the axis asks for it, following
+  Vega-Lite's default: both axes of scatter plots, the value axis of lines, areas and
+  boxes, never category axes or heatmaps.
+* `snap` moves automatic limits (after padding) onto major ticks, on linear and log
+  axes; given limits stay. The default `("4%", "8%")` (`(back, out)`, `%` of the axis
+  length or px) extends a limit out to the next tick when it is within 8% of the axis,
+  or pulls it back to a tick it passed by at most 4% when that tick is still outside the
+  data; other limits stay as padded. `True` always extends to the enclosing ticks, as
+  MATLAB and Vega-Lite do; `False` leaves the padded limits.
+
+### Ticks
+
+* **linear:** steps 1, 2, 2.5 or 5 × 10ᵏ, at most `max_ticks` (default: axis length ÷
+  3.5 font sizes on x, 2.5 on y, at most 10); on x the step grows until labels do not
+  overlap.
+* **log10:** decades labelled 10ᵏ, thinned to `max_ticks`, minor ticks 2–9. Below three
+  decades, 1, 2 and 5 × 10ᵏ, labelled as numbers.
+* **log2:** powers of two, labelled as numbers from 2⁻¹⁰ to 2¹⁰, else 2ᵏ; thinned to every
+  2nd, 4th, … power. **log:** powers of e labelled eᵏ.
+* **sqrt, exp:** round values thinned so that neighbours are a tick spacing apart on the
+  page, walking from the end the scale stretches.
+* **category:** one tick per category; labels turn 45° when they overlap
+  (`tick_rotation="auto"`), and every k-th is kept when even that does not fit.
+* Labels of an axis share the fewest decimals that tell them apart. Beyond
+  10^`sci_limits` they are mantissas, and ×10ᵏ is written at the end of the axis:
+  above the top of a y axis, at the right end of an x axis (on the title's row).
+* `ticks=[…]`, `tick_labels=[…]`, `minor_ticks=True|[…]`, `ticks=False`.
+* `tick_format` takes any [number format](#number-formats); the default `"auto"` is the
+  rule above.
+
+Category axes of heatmaps draw labels only (no axis line or ticks) unless `tick_length`
+or the plot's `spines` is set.
+
+* **Grid lines:** `grid` at the major ticks, `minor_grid` at the minor ticks (or halfway
+  between major ticks on linear axes without minor ticks), and `zero_line` at 0 (when 0
+  is within the limits), under the series.
+* **Sides:** `side="top"` (x) or `"right"` (y) moves the ticks, labels and axis line
+  (`spines` is mirrored with them).
+* **Axis lines:** `mirror` repeats the ticks on the opposite side; `spine_offset` moves
+  the axis line, its ticks and labels away from the axes; `spine_trim` draws the line from
+  the first to the last major tick. `color` sets the default of `line_color`,
+  `tick_color`, `tick_label_color` and `label_color`.
+
+<!-- settings:Axis -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `label` | — | Axis title: a string or rich content; `\n` starts a line in a row band. |
+| `label_position` | 'axis' | Where the label of a plot's y axis goes: `axis` (beside the tick labels); in a band left of the plot, lined up with the labels of the other plots of its grid column (row labels): `band` (rotated) or `left` (horizontal, right-aligned); `inside` (top left inside the axes). |
+| `label_font_size` | '1em' | Font size of the label; default: the base font size. Length; `%`: of the font size. |
+| `label_weight` | 'normal' | Axis title weight: `normal`, `bold` or 1–1000. |
+| `label_style` | 'normal' | Axis title style: `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `label_color` | 'var(color)' | Axis title color. |
+| `scale` | — | `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog`, `logit`, `time`, `category` or `genome`; default: `category` for categorical series, `time` for dates, `genome` for genome series, else `linear`. |
+| `region` | — | Genome scale: the region drawn, its limits: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; genome series read it. |
+| `unit` | 'auto' | Genome scale: unit of the tick labels; `auto`: with ticks about a fifth of the span apart, the largest unit in which they are at least 1 apart and at most 1000, else the largest in which they are at most 1000 with at most 3 decimals, else bp. |
+| `unit_in` | 'label' | Genome scale: where the unit is written, in the axis label (`chr2 (Mb)`) or after each tick label (`500kb`). |
+| `origin` | — | The value drawn at 0 for the axis' series (a series' own `x_origin` wins): a number, or `"center"`, `"start"`, `"end"` of the region (genome scale), else of each series' range. Values are drawn at `(v − origin) × x_scale`; limits, ticks and decorations are in the drawn units. |
+| `linthresh` | 1.0 | Half-width of the linear region of a `symlog` axis. |
+| `tz` | — | Time zone of a time axis (a `tzinfo`); default: the zone of the first aware date, else naive (UTC). |
+| `limits` | 'auto' | `"auto"`, `"lo/hi"` or `[lo, hi]` (a tuple too); each side a number, `"min"`, `"max"`, `"q:F"` (a quantile), a date, or `"auto"`/`None`: `"0/max"` is `[0, "max"]`. |
+| `padding` | 'auto' | Space added to automatic limits, as a fraction of the range; `"auto"`: `auto_padding`, or 0 on axes of series drawn to exact limits (box value axes, heatmaps, …) and in plots without axes. Length; `%`: of the axis range. |
+| `auto_padding` | '5%' | The fraction `padding="auto"` adds on each side. Length; `%`: of the axis range. |
+| `sticky` | True | No padding past the baseline of bars and histograms when an automatic limit is on it (matplotlib's sticky edges). |
+| `invert` | False | Reverse the axis. |
+| `ticks` | — | `False` (no ticks) or a list of tick values. |
+| `tick_labels` | — | Labels of `ticks`. |
+| `minor_ticks` | — | `True`, `False` or a list of values; default: on for log10. |
+| `tick_format` | 'auto' | Number format: `auto`, `percent`, `sci`, `eng`, `si`, `int`, a format string or a function; on a genome axis also `chr:pos` (`chr2:143,250,000`). |
+| `tick_rotation` | 'auto' | Label rotation in degrees, or `"auto"` (45° when category labels overlap). Angle (bare: degrees). |
+| `max_ticks` | 'auto' | Most major ticks; `"auto"`: one per `tick_spacing` of axis length, at least 2, at most `auto_max_ticks`. |
+| `tick_spacing` | ('3em', '2em') | Space per automatic tick, in tick label font sizes, on horizontal and vertical axes. Length; `em` and `%`: of `tick_label_font_size`. |
+| `time_tick_spacing` | ('5em', '2.5em') | `tick_spacing` of time axes. Length; `em` and `%`: of `tick_label_font_size`. |
+| `tick_label_gap` | '0.6em' | Smallest gap between neighbouring tick labels side by side: fewer numeric ticks, or category labels rotated and thinned out, below it. Length; `em` and `%`: of `tick_label_font_size`. |
+| `category_label_spacing` | ('1.6em', '1.3em') | Distance between category labels: rotated (horizontal axes) and stacked (vertical axes); labels closer than it are thinned out. Length; `em` and `%`: of `tick_label_font_size`. |
+| `auto_max_ticks` | (10, 8) | Most automatic ticks on numeric and time axes. |
+| `sci_limits` | (-4, 5) | Exponents beyond which labels become mantissas × 10ᵏ. |
+| `tick_length` | 5.0 | Tick length. Length; `%`: of the axes side across the axis. |
+| `minor_tick_length` | '60%' | Minor tick length; default 0.6 × `tick_length`. Length; `%`: of `tick_length`. |
+| `tick_direction` | 'out' | `out`, `in` or `both`. |
+| `tick_color` | 'var(color)' | Tick color. |
+| `tick_width` | 0.75 | Tick line width. Length. |
+| `tick_label_font_size` | '1em' | Font size of tick labels. Length; `%`: of the font size. |
+| `tick_label_weight` | 'normal' | Tick label weight: `normal`, `bold` or 1–1000. |
+| `tick_label_color` | 'var(color)' | Tick label color. |
+| `tick_pad` | 3.0 | Gap between ticks and labels. Length; `%`: of the axes side across the axis. |
+| `label_pad` | 4.0 | Gap between tick labels and the label. Length; `%`: of the axes side across the axis. |
+| `color` | 'var(text_color)' | Color of the axis line, ticks and labels (the default of `line_color`, `tick_color`, `tick_label_color`, `label_color`). |
+| `line_color` | 'var(color)' | Axis line color. |
+| `line_width` | 0.75 | Axis line width. Length. |
+| `side` | x: 'bottom' / y: 'left' | Where the ticks, labels and axis line go: `bottom` or `top` (x axis), `left` or `right` (y axis). |
+| `mirror` | False | Ticks also on the opposite side of the axes. |
+| `spine_offset` | 0.0 | Distance the axis line (with its ticks and labels) is moved away from the axes. Length; `%`: of the axes side across the axis. |
+| `spine_trim` | False | Axis line from the first to the last major tick only. |
+| `include_zero` | False | Extend automatic limits to 0 (linear and sqrt scales), before padding and `snap`: `True`, or `"auto"` where a series on the axis asks for it (Vega-Lite's rule: scatter axes, the value axis of lines, areas and boxes). |
+| `zero_line` | False | A line across the plot at 0. |
+| `zero_line_color` | 'var(line_color)' | Zero line color; default `line_color`. |
+| `zero_line_width` | 'var(line_width)' | Zero line width; default `line_width`. Length. |
+| `snap` | ('4%', '8%') | Automatic limits on major ticks (linear and log scales): `True`, out to the enclosing ticks; `(back, out)`, out to a tick within `out` (`%` of the axis), or back to one within `back` that is still outside the data; `False`: as padded. Length; `%`: of the axis range. |
+| `grid` | False | Major grid lines across the plot. |
+| `grid_color` | '#dddddd' | Grid line color. |
+| `grid_width` | 0.5 | Grid line width. Length. |
+| `grid_style` | 'solid' | Grid line style or dash list. Length. |
+| `minor_grid` | False | Minor grid lines: at the minor ticks, or halfway between major ticks on linear axes without minor ticks. |
+| `minor_grid_color` | 'var(grid_color)' | Minor grid color; default `grid_color`. |
+| `minor_grid_width` | '50%' | Minor grid width; default half `grid_width`. Length; `%`: of `grid_width`. |
+| `minor_grid_style` | 'var(grid_style)' | Minor grid style; default `grid_style`. Length. |
+| `visible` | True | Draw the axis (ticks, labels). |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `text_color` | inherited ('black') | Text color. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `TextStyle` (`label_`), `Stroke` (`tick_`), `TextStyle` (`tick_label_`), `Stroke` (`line_`), `Stroke` (`zero_line_`), `Stroke` (`grid_`), `Stroke` (`minor_grid_`), `Font`, `NumberFormat`.
+<!-- /settings -->
+
+## 5. Series
+
+All series take `name`, `alpha`, `z`, `rasterize` and `simplify` (see [Output](#8-output)).
+Series without their own color take the plot's next palette color, in call order; series
+with several value sets (histograms, densities, areas, pies) take one per set.
+
+* **Layers.** A series is a preset of layers: each a stat (columns computed from the
+  data: bins, densities, quartiles, fits, contours…), a position (stack, dodge, jitter,
+  swarm, rows of intervals), and one of eight geoms that draws the columns (points,
+  paths, bands, rectangles, polygons, segments, cells, text). A box plot is rectangles,
+  segments and points from one box stat; it has one legend entry. Positions run once per
+  plot over all its series, before the axes are fitted.
+* **Orientation.** Every series with x and y data takes `orientation="horizontal"`
+  (scatter, line, fill, area, bar, hist, kde, ecdf, box, violin, strip, swarm, errorbar,
+  stem, regression): its x data go along the y axis, its y data along the x axis, and it
+  draws the same marks with x and y swapped (curves along y, steps included). Grids
+  (heatmap, hist2d, hexbin, contour, 2-D kde) and pies have none: swap their arguments.
+* **New types.** `pl.register_layer(name, factory)` adds `plot.<name>(…)`, which calls
+  `factory(…, plot=plot)`. A factory that is a `pl.Series` subclass implements
+  `layers()`, returning its `Call` (layers, legend entries, what the axes, maps and
+  palette need; see `plot_io/layers/`); its class name is a style class. The genome types
+  are registered so (`plot.bigwig(…)`, …).
+
+* **Category slots.** Box and violin series, bar series, and strip and swarm series form
+  three dodge groups: the series of a group that have a category split its slot (`width`)
+  side by side, in call order; `dodge=False` overlays a series; `gap` leaves part of each
+  share empty (`"10%"`). `width` is a `%` of the slot (one category, or the smallest gap
+  between numeric `positions`), a length (px), or data units (`"0.8d"`). Stacked bars
+  count as one, and so do split violins.
+* **Stacking.** `stack=True` (bars, histograms, densities) puts a series on the previous
+  stacked series of its kind in the plot, per category or bin; positive and negative
+  values stack apart; `stack="normalize"` divides each position by its total.
+* **Derived data.** Histograms, densities, ECDFs, violins, 2-D bins, contours and
+  regressions compute their data once (in C, by plot_io's kernels) and keep it until
+  a setting changes; `series.stats` exposes it.
+* **Shifted and rescaled coordinates.** `x_origin`, `x_scale` and `x_extent` (and `y_…`)
+  draw a series' values `v` at `(v − origin) × scale`, without changing the data:
+  `p.line(profile, x_origin="center")` draws positions 0…1000 at −500…500, `x_scale=10`
+  makes bins of 10 (−5000…5000), and `x_extent="-5000/5000"` maps the series' smallest x
+  to −5000 and its largest to 5000 (replacing origin and scale). `"center"` is the middle
+  of the series' range, `"start"`/`"end"` its smallest/largest value. Limits, ticks and
+  decorations (`p.vline(0)`) are in the drawn units. An axis' `origin`
+  (`p.x_axis(origin="center")`, `fig.x_axis(…)` for every plot) applies to every series on
+  it that has no `x_origin` of its own (on a genome axis, `"center"` is the middle of its
+  region). Category axes ignore them, and they need a linear, time or genome axis.
+
+<!-- settings:Transforms -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `x_origin` | — | The x value drawn at 0: a number, `"center"` (the middle of the series' x range), `"start"` or `"end"` (its smallest or largest x); unset: the x axis' `origin`. Values are drawn at `(x − x_origin) × x_scale`. |
+| `x_scale` | 1.0 | Factor on x values after `x_origin` (e.g. bp per bin); default 1. |
+| `x_extent` | — | The span the series' x range is drawn over, `"lo/hi"` or `[lo, hi]`: its smallest x at `lo`, its largest at `hi`; replaces `x_origin` and `x_scale`. |
+| `y_origin` | — | The y value drawn at 0: a number, `"center"` (the middle of the series' y range), `"start"` or `"end"` (its smallest or largest y); unset: the y axis' `origin`. Values are drawn at `(y − y_origin) × y_scale`. |
+| `y_scale` | 1.0 | Factor on y values after `y_origin` (e.g. bp per bin); default 1. |
+| `y_extent` | — | The span the series' y range is drawn over, `"lo/hi"` or `[lo, hi]`: its smallest y at `lo`, its largest at `hi`; replaces `y_origin` and `y_scale`. |
+<!-- /settings -->
+
+### Tables (`data=`)
+
+```python
+p.scatter("umap_x", "umap_y", data=genes, c="density", group="cluster")
+pl.Box("expression", data=df, x="tissue", group="sex")
+p = pl.Plot(data=df); p.scatter("a", "b")       # data inherited by the plot's series
+```
+
+`data` is any object returning a column for `data[name]`: a dict of sequences, a pandas
+or polars data frame, a numpy structured array. Columns are read through `__getitem__`
+(and `to_numpy()` when present); no table library is imported. With `data`, a string in
+a positional data argument or in `color`, `edge_color`, `size`, `alpha`, `group`,
+`draw_order`, `x_error`, `y_error`, `weights`, `positions`, `x`, `y` or `names` names a
+column. Positional arguments, `group`, `weights` and `positions` must be columns; in
+`color`, a color name that is no column stays a color (a column wins, with a warning if
+the name is also a color). Axis titles default to the column names drawn on the axes,
+the colorbar label to the `color` column, the legend title to the `group` column.
+`data` is also a plot and figure setting, inherited by their series. Pandas categorical
+columns keep their category order for groups and category axes.
+
+Box, violin, strip and swarm also take long data: `values` flat, with the category of each
+value in `x` (`y` when horizontal).
+
+### Groups (`group=`)
+
+```python
+g = p.scatter(x, y, group=labels, marker="auto")   # one series per group
+g = p.line(t, y, group=subject, line_style="auto")
+g["a"].set(color="black"); g.set(alpha=0.6)
+```
+
+`group` takes a label per point. The call returns a `SeriesGroup`, a list of one series per
+group (first-appearance order, the categorical order of a pandas column, or
+`group_order=[…]`), each with the rows of every per-point argument that belong to it,
+the group label as `name` and the next palette color (`group_colors={label: color}` sets
+some). `marker="auto"` cycles marker shapes and `line_style="auto"` line styles over the
+groups. Missing labels (`None`, NaN) form a `"nan"` group, or are dropped with
+`group_missing="drop"`. `set()` on the group applies to every member; `group[label]` (or
+an index) is one member; `labels` lists them. For box, violin, bar, strip and swarm the
+groups are dodged within each category slot. Densities (`"density"`) are computed per
+member, and `draw_order` sorts within each member.
+
+### Scatter
+
+```python
+pl.Scatter(x, y, plot=None, **settings)
+```
+
+`color`, `edge_color`, `size`, `marker` take one value or one per point. Numbers per
+point in `color` and `edge_color` are mapped through `color_map` (alias `cmap`; default:
+the style's map); numbers in `size` are diameters, or values mapped through `size_map`
+(alias `smap`) when it is set. See [values](#values-in-color-and-size).
+
+* `size` is a diameter (a length; per-point numbers are px). With `size_basis="area"` (default) every shape has the
+  area of the circle of that diameter: a square of size 4 is drawn 3.54 px wide.
+* Error bars: `x_error`/`y_error` take a value, a sequence, `(low, high)` sequences or
+  `ErrorBars(values, color=None, line_width=None, cap_length=None)` (cap: the series'
+  `cap_length`, else 4 px).
+
+<!-- settings:Scatter -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
+| `size` | 4.5 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
+| `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
+| `edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `size_map` | — | The sizes numbers in `size` are drawn with: a `SizeMap` (alias `smap`); without it (or `size_axis`), numbers are sizes in px. |
+| `size_limits` | — | Limits of the series' size axis, as an axis' `limits`; unset: `"auto"`. |
+| `size_scale` | — | Scale of the series' size axis; unset: `linear`. |
+| `size_axis` | — | A shared `SizeAxis` (`figure.size_axis(…)`) in place of the series' own: it holds the sizes, limits and scale. |
+| `size_legend` | True | With mapped sizes: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
+| `draw_order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `alpha_range`. |
+| `alpha_range` | (0.2, 1.0) | Opacities of the least and most dense points when `alpha` is a density. |
+| `x_error` | — | Horizontal error bars: a value, a sequence, `(low, high)` or `ErrorBars`. |
+| `y_error` | — | Vertical error bars. |
+| `orientation` | 'vertical' | `vertical` (x along the x axis) or `horizontal` (x along the y axis). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Marker`, `Font`.
+<!-- /settings -->
+
+### Line
+
+```python
+pl.Line(x, y=None, plot=None, **settings)    # y 2-D: one line per row; x omitted: 0, 1, 2, …
+```
+
+Named line styles scale with the width. Markers (`marker`, `marker_size`,
+`marker_color`, …) are drawn at the points when `marker` or `show_markers` is set.
+Numbers per point (or `"density"`, of a single line) in `marker_color` and
+`marker_edge_color` go through the series' [color axis](#6-color-and-size-axes)
+(`color_map`, `color_limits`, `color_scale`, `color_axis`; `p.colorbar(line)`), as
+`color` does on Scatter; the line keeps `color`, and the legend's marker takes the
+gradient's middle color.
+
+* `interpolation`: `linear`; `step-pre`, `step-post`, `step-mid`; `monotone` (a cubic
+  through every point that never overshoots, Fritsch–Carlson; `spline` where x is not
+  monotonic); `spline` (centripetal Catmull–Rom, may overshoot). Each segment is one exact
+  Bézier, computed on the page after the axis scales, by vec_io in C. Steps and curves
+  are not decimated by `simplify`.
+* `missing`: `break` (default) ends a run at a missing value (NaN, `None`, or outside the
+  axis scale's domain); runs are drawn on their own and a one-point run draws nothing.
+  `skip` connects the points on either side.
+
+<!-- settings:Line -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | — | Line color; default: the next palette color. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list; named styles scale with the width. Length. |
+| `cap` | 'butt' | Line cap. |
+| `join` | 'round' | Line join. |
+| `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
+| `missing` | 'break' | Missing values: `break` the line there, or `skip` them and connect their neighbours. |
+| `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
+| `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
+| `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
+| `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `x_error` | — | Horizontal error bars at the points. |
+| `y_error` | — | Vertical error bars at the points. |
+| `show_markers` | False | Draw markers at the points (also turned on by setting `marker`). |
+| `orientation` | 'vertical' | `vertical` (x along the x axis) or `horizontal` (x along the y axis). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke`, `Marker` (`marker_`), `Font`.
+<!-- /settings -->
+
+### Fill
+
+```python
+pl.Fill(x, y1, y2=0, plot=None, **settings)   # y1 may be two rows [upper, lower]
+```
+
+`interpolation` and `missing` work as for lines, on both edges (a point is missing when
+x, y1 or y2 is), so a band with the settings of its line matches it, horizontal ones
+included (`fill(y, x1, x2, orientation="horizontal")`: the curves run along y).
+`color_below` colors the parts where `y1` is below `y2` (a difference between two curves,
+each side in its color).
+
+<!-- settings:Fill -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | — | Fill color; default: the next palette color. |
+| `color_below` | — | Fill color where `y1` is below `y2` (crossings found on straight segments); default `color` everywhere. |
+| `alpha` | 'calc(0.3 * inherit)' | Opacity; default 0.3 × the plot's. |
+| `edge_color` | — | Outline color; default none. |
+| `edge_width` | 'var(line_width)' | Outline width; default the line width. Length. |
+| `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
+| `missing` | 'break' | Missing values: `break` the line there, or `skip` them and connect their neighbours. |
+| `orientation` | 'vertical' | `vertical`: between y curves; `horizontal`: between x curves. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke` (`edge_`), `Font`.
+<!-- /settings -->
+
+### Box
+
+```python
+pl.Box(values, positions=None, plot=None, **settings)
+box.stats            # {category: BoxStats(count, mean, q1, median, q3, low, high, outliers)}
+```
+
+`values`: a dict `{category: values}`, a list of arrays (categories `0, 1, …` or
+`categories=`), or one array. `positions` places the boxes on a numeric axis instead.
+Quartiles interpolate linearly (numpy's default); whiskers reach the furthest data within
+`whiskers` × IQR, or the range, or percentiles; points beyond are outliers. Box series of
+a plot share each category's slot side by side, in call order, among those having that
+category.
+
+<!-- settings:Box -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | — | Box fill: a color, one per box (list or dict by category), or numbers per box (list or dict) mapped through `color_map`; default: the next palette color. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `edge_color` | 'series' | Box outline, whiskers, caps and median: a color, `"series"` (each box's own color) or `"auto"` (a grey 0.6 × as light as the series' lightest color, as seaborn). |
+| `edge_width` | 0.75 | Outline width. Length. |
+| `whisker_color` | — | Whisker and cap color; default `edge_color`. |
+| `whisker_width` | 'var(edge_width)' | Whisker and cap width; default `edge_width`. Length. |
+| `whisker_style` | 'solid' | Whisker line style: `solid`, `dashed`, `dotted`, `dashdot` or a dash list (caps stay solid). Length. |
+| `median_color` | — | Median line color; default `edge_color`. |
+| `median_width` | 'calc(3 * var(edge_width))' | Median line width. Length. |
+| `max_width` | '60%' | Largest width of the series' part of a slot (as `width`); default none. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `width` | '80%' | Box width: `%` of the slot, a length (bare numbers: px), `d` data units, or a duration on time axes. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `cap_length` | '50%' | Whisker cap width (`%` of the box width). Length; `%`: of the box width. |
+| `whiskers` | 1.5 | Whisker reach: a multiple of the IQR, `"range"`, or percentiles `(lo, hi)`. |
+| `outliers` | True | Draw points beyond the whiskers. |
+| `saturation` | 1.0 | Saturation of the box fills (1: the colors as given; seaborn uses 0.75). |
+| `fill` | 0.25 | Box fill: an opacity of the box color, times `alpha` (lines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `mean` | False | Draw the mean as a marker. |
+| `mean_marker` | 'diamond' | Marker of the mean. |
+| `mean_color` | 'white' | Fill of the mean marker (outline: `edge_color`). |
+| `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
+| `dodge` | True | Box and violin series sharing a category share its slot side by side; `False` overlays them. |
+| `gap` | '10%' | Fraction of each box's part of a shared slot left empty. Length; `%`: of each series' part of a shared slot. |
+| `categories` | — | Category names of a list of arrays. |
+| `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
+| `marker_size` | 3.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
+| `marker_color` | — | Outlier fill: a color, or colors per outlier. |
+| `marker_edge_color` | — | Outlier outline: as the fill, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `marker_edge_width` | 0.5 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke` (`edge_`), `Stroke` (`whisker_`), `Stroke` (`median_`), `FillStyle`, `Marker` (`marker_`), `Font`.
+<!-- /settings -->
+
+### Heatmap
+
+```python
+pl.Heatmap(values, x=None, y=None, plot=None, **settings)
+```
+
+`values` is 2-D, row 0 first; a 3-D `(h, w, 3|4)` grid is drawn as colors. `x`/`y`:
+`None` (cell indices), labels (a category axis), n cell centres or n + 1 edges (uneven
+spacing and any axis scale allowed). `color_map` (alias `cmap`), `color_limits` and
+`color_scale` configure the series' [color axis](#6-color-and-size-axes).
+`value_labels=True` writes each value, formatted by `value_label_format` (any
+[number format](#number-formats); `"auto"`: 3 significant digits, the same decimals for
+all cells), in black or white, whichever contrasts more (at most 2,500 cells unless
+`value_labels="all"`). `kind`: `image`, `cells` or `smooth`.
+
+<!-- settings:Heatmap -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `kind` | 'image' | `image` (one image pixel per cell), `cells` (rectangles) or `smooth` (interpolated). |
+| `nan_color` | — | Color of missing cells; default: the map's `bad` (transparent). |
+| `origin` | 'top' | `top`: row 0 at the top (y axis inverted); `bottom`: at the bottom. |
+| `value_labels` | False | Write each cell's value (`"all"` above 2,500 cells). |
+| `value_label_format` | 'auto' | Number format of cell labels (`auto`: 3 significant digits, the same decimals for all cells). |
+| `value_label_font_size` | '0.9em' | Font size of cell labels. Length; `%`: of the font size. |
+| `colorbar` | False | Attach a colorbar to the plot. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `TextStyle` (`value_label_`), `Font`, `NumberFormat`.
+<!-- /settings -->
+
+### Bar
+
+```python
+pl.Bar(x, height=None, plot=None, **settings)
+```
+
+`x`: categories (a category axis) or numbers (bars centred on them, `width` in data units); a dict `{category: height}`; or heights alone (at 0, 1, …). `value_labels` writes the values outside, inside or at the centre of the bars, formatted by `value_label_format`; `fill` is the opacity of the bars' fill (or a color); `error` adds error bars at the bar ends. Value axes include 0 (`include_zero="auto"`).
+
+<!-- settings:Bar -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | — | Bar fill: a color, one per bar (list or dict by category), or numbers per bar (list or dict) mapped through `color_map`; default: the next palette color. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `edge_color` | 'series' | Outline color: a color, `"series"` (each bar's own color, at `alpha`) or none. |
+| `edge_width` | 'var(line_width)' | Outline width. Length. |
+| `fill` | 0.25 | Fill: an opacity of each bar's color, times `alpha` (outlines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `seam_color` | 'white' | Where outlined bars touch (dodged or adjacent), the shared edge in this color; `none`: both outlines as drawn. Between the parts of a stack, the line is the outline of the part nearer the baseline. |
+| `max_width` | — | Largest width of the series' part of a slot (as `width`); default none. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `width` | '80%' | Bar width: `%` of the slot, a length (bare numbers: px), `d` data units, or a duration (or `timedelta`) on time axes. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `bottom` | 0.0 | Base of the bars: a value or one per bar. |
+| `orientation` | 'vertical' | `vertical` (bars rise from the x axis) or `horizontal`. |
+| `stack` | False | `True`: on top of the previous stacked bars of the plot; `"normalize"`: stacks scaled to 1. |
+| `dodge` | True | Bar series sharing a category share its slot side by side; `False` overlays them. |
+| `gap` | 0.0 | Fraction of each bar's part of a shared slot left empty. Length; `%`: of each series' part of a shared slot. |
+| `saturation` | 1.0 | Saturation of the fills (seaborn: 0.75). |
+| `error` | — | Error bars at the bar ends: a value, a sequence, `(low, high)` or `ErrorBars`. |
+| `error_color` | '#333333' | Error bar color. |
+| `error_width` | 0.75 | Error bar line width. Length. |
+| `value_labels` | False | Value labels: `True`/`"outside"`, `"inside"`, `"center"`. Outside labels widen automatic limits so they fit in the axes; a label too large for its bar goes outside, or is left out on a stacked bar. |
+| `value_label_format` | 'auto' | Number format of the value labels. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`edge_`), `FillStyle`, `Stroke` (`error_`), `Font`, `NumberFormat`.
+<!-- /settings -->
+
+### Hist
+
+```python
+pl.Hist(values, plot=None, **settings)
+```
+
+`values`: one array, or several (a dict, a list of arrays) sharing the bins. `bins`: a count, edges, or numpy's rules (`auto` is numpy 2's). Bins are even on the axis scale (`bins_scale="axis"`): on a log axis, in log space. `stat` turns counts into densities (area 1), probabilities, percents or counts per unit; `cumulative` accumulates them. Several sets overlay (opacity 0.5), stack (`stack=True`) or dodge (`dodge=True`). `hist.stats`: `edges`, `counts` and `heights` per set.
+
+<!-- settings:Hist -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `bins` | 'auto' | A count, edges, or a rule: `auto`, `fd`, `sturges`, `scott`, `sqrt`, `rice`, `doane` (numpy's). |
+| `range` | — | Range of the bins; default the data range. |
+| `weights` | — | A weight per value (per set for several sets). |
+| `stat` | 'count' | `count`, `density` (area 1), `probability`, `percent` or `frequency` (count per unit). |
+| `cumulative` | False | Accumulate the bins. |
+| `kind` | 'stepfilled' | `bar` (adjacent bars), `step` (outline) or `stepfilled`. |
+| `bins_scale` | 'axis' | `axis`: bins even on the axis scale (log axes: in log space); `linear`: even in data units. |
+| `orientation` | 'vertical' | `vertical` (bins along x) or `horizontal`. |
+| `stack` | False | Stack the sets (and other stacked histograms with the same bins). |
+| `dodge` | False | Put the sets side by side within each bin. |
+| `color` | — | Fill color, or one per set; default palette colors. |
+| `edge_color` | — | Bar outline color; default none. |
+| `edge_width` | 0.0 | Bar outline width. Length. |
+| `line_color` | — | Step and outline color; default each set's color. |
+| `line_width` | inherited (0.75) | Step line width. Length. |
+| `outline` | True | `bar` and `stepfilled` kinds: the outer outline of each set, in `line_color` (dodged bars: each bar's outline). |
+| `alpha` | 'auto' | Opacity; `"auto"`: 0.5 for overlaid sets, else the plot's. |
+| `saturation` | 1.0 | Saturation of the fills. |
+| `value_labels` | False | Value labels on bars. |
+| `value_label_format` | 'auto' | Number format of the value labels. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`edge_`), `Stroke` (`line_`), `Font`, `NumberFormat`.
+<!-- /settings -->
+
+### Kde
+
+```python
+pl.Kde(values, plot=None, **settings)
+```
+
+A Gaussian kernel density of each set on a common grid of `points` points, extending `cut` bandwidths past the data (within `range`). `fill` fills under each curve (`True`: at 0.25, an opacity, or a color). `bandwidth`: `scott` (default), `silverman` (as scipy's `gaussian_kde`) or a number, times `adjust`. On log axes the density is computed in log space, per log unit. `kde.stats`: `grid`, `densities`, `bandwidths`.
+
+<!-- settings:Kde -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `bandwidth` | 'scott' | `scott`, `silverman`, or a bandwidth in data units. |
+| `adjust` | 1.0 | Factor applied to the bandwidth. |
+| `cut` | 3.0 | The curve extends this many bandwidths past the data. |
+| `range` | — | Limits of the curve (within the data plus `cut`); default none. |
+| `points` | 512 | Number of points of the curve. |
+| `cumulative` | False | Plot the cumulative distribution. |
+| `fill` | False | Fill under the curve: an opacity of its color, `True` (0.25), a color, or `False` (stacked curves: 0.25). |
+| `weights` | — | A weight per value (per set for several sets). |
+| `orientation` | 'vertical' | `vertical` (values along x) or `horizontal`. |
+| `stack` | False | Stack the sets (seaborn's `multiple="stack"`). |
+| `color` | — | Color, or one per set; default palette colors. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_style` | 'solid' | Line style. Length. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `FillStyle`, `Stroke`, `Font`.
+<!-- /settings -->
+
+### Kde2d
+
+```python
+p.kde(x, y, levels=10, fill=False, thresh=0.05, **settings)    # or pl.Kde(x, y), pl.Kde2d(x, y)
+```
+
+Density contours of points (seaborn's `kdeplot(x=, y=)`): the 2-D Gaussian density
+(bandwidth as [`Density`](#point-density): scipy's covariance times Scott's factor, or
+Silverman's, a number or a matrix, times `adjust`) on a `points` × `points` grid over
+the data plus `cut` bandwidths, in axis positions (log axes in log space). With a number
+of `levels`, contour k of n encloses an equal share of the mass, from 1 − `thresh` (the
+outermost) up; a list gives density values. Unfilled lines take the next palette color,
+or `palette` (one color or colors per level), unless `color_map` is set; `fill=True`
+colors the bands through
+`color_map`, with the top band up to the maximum. Drawn by the contour code (lines,
+labels, colorbar).
+
+<!-- settings:Kde2d -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `levels` | 10 | A number of iso-proportion levels (contour k of n encloses k/n of the mass, above `thresh`), or density values. |
+| `thresh` | 0.05 | Lowest iso-proportion: the outermost contour encloses 1 − `thresh` of the mass. |
+| `bandwidth` | 'scott' | `"scott"`, `"silverman"`, a number or a 2 × 2 matrix, as `Density`. |
+| `adjust` | 1.0 | Factor of the bandwidth. |
+| `cut` | 3.0 | Grid extends this many bandwidths past the data. |
+| `points` | 128 | Grid points per side. |
+| `colorbar` | False | Attach a colorbar to the plot. |
+<!-- /settings -->
+
+### Ecdf
+
+```python
+pl.Ecdf(values, plot=None, **settings)
+```
+
+A step line through the sorted values of each set: `stat` `proportion`, `count` or `percent`; `complementary` plots 1 − F.
+
+<!-- settings:Ecdf -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `weights` | — | A weight per value (per set for several sets). |
+| `stat` | 'proportion' | `proportion` (0–1), `count` or `percent`. |
+| `complementary` | False | Plot 1 − F (survival). |
+| `orientation` | 'vertical' | `vertical`: values along x; `horizontal`: along y. |
+| `color` | — | Line color, or one per set; default palette colors. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `line_style` | 'solid' | Line style. Length. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke`, `Font`.
+<!-- /settings -->
+
+### Violin
+
+```python
+pl.Violin(values, positions=None, plot=None, **settings)
+```
+
+`values` as box plots take them. Each violin is the density of its category, mirrored; `width_scale` gives equal areas (default), areas proportional to the counts, or equal widths. `inner` draws a thin box with whiskers and a median dot, dashed quartiles, the points, or nothing (`False`). With `split=True`, two violin series share each slot as facing halves.
+
+<!-- settings:Violin -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `color` | — | Fill: a color, one per violin (list or dict by category), or numbers per violin mapped through `color_map`; default the next palette color. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `edge_color` | 'series' | Outline and inner color: a color or `"series"` (each violin's own color, at `alpha`). |
+| `edge_width` | 0.75 | Outline width. Length. |
+| `saturation` | 1.0 | Saturation of the fills. |
+| `alpha` | 1.0 | Opacity of the violins. |
+| `fill` | 0.25 | Fill: an opacity of each violin's color, times `alpha` (outlines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `max_width` | — | Largest width of the series' part of a slot (as `width`); default none. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `width` | '80%' | Violin width: `%` of the slot, a length (bare numbers: px), `d` data units, or a duration on time axes. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `bandwidth` | 'scott' | `scott`, `silverman` or a number. |
+| `adjust` | 1.0 | Factor applied to the bandwidth. |
+| `cut` | 2.0 | The density extends this many bandwidths past the data. |
+| `points` | 512 | Points per violin outline. |
+| `width_scale` | 'area' | `area`: equal areas; `count`: area proportional to the number of values; `width`: equal widths. |
+| `inner` | 'box' | Inside each violin: `box` (a thin box, whiskers and a median dot), `quartiles` (dashed lines), `points`, or `False` (nothing). |
+| `split` | False | Two violin series share each slot as facing halves. |
+| `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
+| `dodge` | True | Violin and box series sharing a category share its slot side by side; `False` overlays them. |
+| `gap` | '10%' | Fraction of each part of a shared slot left empty. Length; `%`: of each series' part of a shared slot. |
+| `categories` | — | Category names of a list of arrays. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke` (`edge_`), `FillStyle`, `Font`.
+<!-- /settings -->
+
+### Strip and swarm
+
+```python
+pl.Strip(values, positions=None, plot=None, **settings)
+pl.Swarm(values, positions=None, plot=None, **settings)
+```
+
+Points of each category's values: `Strip` spreads them by uniform jitter (± `jitter`, `%` of the slot width, from `seed`), `Swarm` places them side by side without overlaps (points that do not fit go to the slot edge, with a warning). Marker settings as `Scatter`. `Swarm` takes the same settings as `Strip` except `jitter` and `seed`.
+
+<!-- settings:Strip -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
+| `size` | 4.5 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
+| `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
+| `edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `size_map` | — | The sizes numbers in `size` are drawn with: a `SizeMap` (alias `smap`); without it (or `size_axis`), numbers are sizes in px. |
+| `size_limits` | — | Limits of the series' size axis, as an axis' `limits`; unset: `"auto"`. |
+| `size_scale` | — | Scale of the series' size axis; unset: `linear`. |
+| `size_axis` | — | A shared `SizeAxis` (`figure.size_axis(…)`) in place of the series' own: it holds the sizes, limits and scale. |
+| `size_legend` | True | With mapped sizes: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
+| `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
+| `max_width` | — | Largest width of the series' part of a slot (as `width`); default none. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `width` | '80%' | Width the points spread over: `%` of the slot, a length (bare numbers: px), `d` data units, or a duration on time axes. Length; `%`: of the slot: one category, or the smallest gap between positions; `d`: data units. |
+| `dodge` | True | Point series sharing a category share its slot side by side; `False` overlays them. |
+| `gap` | 0.0 | Fraction of each part of a shared slot left empty. Length; `%`: of each series' part of a shared slot. |
+| `categories` | — | Category names of a list of arrays. |
+| `jitter` | '10%' | Half-width of the jitter (`%` of the slot width). Length; `%`: of the slot: one category, or the smallest gap between positions. |
+| `seed` | 0 | Seed of the jitter. |
+| `draw_order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `alpha_range`. |
+| `alpha_range` | (0.2, 1.0) | Opacities of the least and most dense points when `alpha` is a density. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Marker`, `Font`.
+<!-- /settings -->
+
+### Area
+
+```python
+pl.Area(x, ys, plot=None, **settings)
+```
+
+Layers (rows of `ys`, or a dict `{name: values}`, one legend entry each) stacked on `baseline`: `zero`, `sym`, `wiggle` or `weighted_wiggle` (matplotlib's stackplot baselines). `interpolation` and `missing` as `Fill`.
+
+<!-- settings:Area -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `baseline` | 'zero' | `zero`, `sym` (symmetric around 0), `wiggle` or `weighted_wiggle` (streamgraphs, as matplotlib's stackplot). |
+| `stack` | True | Stack the layers; `False` overlays them from 0. |
+| `color` | — | A color, or one per layer; default palette colors. |
+| `alpha` | 0.25 | Opacity of the fills. |
+| `edge_color` | 'series' | Outline color of each layer's top: a color, `"series"` (each layer's own color) or none. |
+| `edge_width` | 'var(line_width)' | Outline width; default the line width. Length. |
+| `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
+| `missing` | 'break' | Missing values: `break` the line there, or `skip` them and connect their neighbours. |
+| `orientation` | 'vertical' | `vertical` (layers along x) or `horizontal` (along y). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke` (`edge_`), `Font`.
+<!-- /settings -->
+
+### Errorbar
+
+```python
+pl.Errorbar(x, y, plot=None, **settings)
+```
+
+Error bars on their own (markers only with `marker=`); `y_error_style="band"` fills the band between the y error ends instead. Numbers in `marker_color` map through the series' color axis, as on [Line](#line).
+
+<!-- settings:Errorbar -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `marker` | — | Marker at the points; default none. |
+| `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
+| `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
+| `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `color` | — | Bar color; default: the next palette color. |
+| `line_width` | inherited (0.75) | Bar width. Length. |
+| `cap_length` | 4.0 | Cap width (`data`: in data units across the bar); 0: no caps. Length; `d`: data units. |
+| `x_error` | — | Horizontal errors. |
+| `y_error` | — | Vertical errors. |
+| `y_error_style` | 'bars' | `bars`, or `band`: a filled band between the y error ends (points sorted by x). |
+| `band_alpha` | 0.25 | Opacity of a band. |
+| `orientation` | 'vertical' | `vertical` (x along the x axis) or `horizontal` (x along the y axis). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Marker` (`marker_`), `Font`.
+<!-- /settings -->
+
+### Stem
+
+```python
+pl.Stem(x, y=None, plot=None, **settings)
+```
+
+Stems from `baseline` to each value with a marker (lollipops), and a baseline line. Numbers in `marker_color` map through the series' color axis, as on [Line](#line).
+
+<!-- settings:Stem -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
+| `marker_size` | 5.0 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
+| `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
+| `marker_edge_color` | — | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `marker_edge_width` | 0.0 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `color` | — | Stem and marker color; default: the next palette color. |
+| `line_width` | inherited (0.75) | Stem width. Length. |
+| `baseline` | 0.0 | Value the stems start from. |
+| `baseline_color` | '#4d4d4d' | Baseline color; `none`: no baseline. |
+| `baseline_width` | 0.75 | Baseline width. Length. |
+| `orientation` | 'vertical' | `vertical` stems (values on y) or `horizontal`. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Marker` (`marker_`), `Stroke` (`baseline_`), `Font`.
+<!-- /settings -->
+
+### Regression
+
+```python
+pl.Regression(x, y, plot=None, **settings)
+```
+
+A least-squares polynomial of `order` with the confidence band of the mean (Student's t), or a LOWESS curve (`lowess=True`, no band); `logx` fits against log x; `range` sets the x range of the polynomial curve (default the data's), drawn in `points` points. The points are drawn too unless `scatter=False` (marker settings with the `marker_` prefix; numbers in `marker_color` map through the series' color axis, as on [Line](#line)). `regression.stats`: `coefficients` (lowest power first), `r2`, `se`, and the curve.
+
+<!-- settings:Regression -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `order` | 1 | Polynomial order (1–5). |
+| `lowess` | False | Fit a LOWESS curve instead (no band). |
+| `frac` | 0.6666666666666666 | Fraction of the points in each LOWESS fit. |
+| `ci` | 95.0 | Confidence level of the band (%); `None`: no band. |
+| `logx` | False | Fit y against log(x) (x > 0). |
+| `scatter` | True | Draw the points too. |
+| `range` | — | x range of the fitted polynomial (and band); default the data range. |
+| `points` | 100 | Points of the fitted curve. |
+| `color` | — | Line, band and point color; default the next palette color. |
+| `line_width` | 'calc(1.4 * inherit)' | Line width; default 1.4 × the plot's. Length. |
+| `line_style` | 'solid' | Line style or dash list. Length. |
+| `band_alpha` | 0.2 | Opacity of the band. |
+| `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
+| `marker_size` | 4.5 | Marker size: the diameter of the circle of equal area, in px; one value or one per point. Length. |
+| `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
+| `marker_edge_color` | 'auto' | Outline: as the fill color, or `"auto"` (white around filled markers; hollow ones outlined in their color). |
+| `marker_edge_width` | 0.75 | Outline width; 0: no outline. Length. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color; an opacity (0–1): filled at that opacity and outlined in the color. |
+| `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `orientation` | 'vertical' | `vertical` (y on x) or `horizontal` (the fit drawn with x along the y axis). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke`, `Marker` (`marker_`), `Font`.
+<!-- /settings -->
+
+### Hist2d
+
+```python
+pl.Hist2d(x, y, plot=None, **settings)
+```
+
+Counts in rectangular bins (even on the axis scales), drawn as a heatmap with the heatmap's settings; bins below `min_count` are transparent; a colorbar source.
+
+<!-- settings:Hist2d -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `bins` | ('auto', 'auto') | Bins of both axes, or `(x bins, y bins)`: counts, edges or rules (as `Hist`). |
+| `range` | — | `((x0, x1), (y0, y1))`; default the data range. |
+| `weights` | — | A weight per point. |
+| `stat` | 'count' | `count`, `density` (volume 1), `probability` or `percent`. |
+| `min_count` | 1.0 | Bins below this count are transparent. |
+| `origin` | 'bottom' | Row of the first y bin. |
+<!-- /settings -->
+
+### Hexbin
+
+```python
+pl.Hexbin(x, y, plot=None, **settings)
+```
+
+Counts in regular hexagons: `bins` hexagons across the axes width, on a lattice laid out
+in page units for the axes the layout places, so the hexagons tile exactly whatever the
+axes' aspect. The counts depend on the axes, and the color axis on the counts: the layout
+counts again when a round places the axes differently ([layout](#layout)). Points outside
+the axes are not counted. Colored by `cmap`; a colorbar source.
+
+<!-- settings:Hexbin -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `bins` | 30 | Hexagons across the axes width. |
+| `weights` | — | A weight per point (sums). |
+| `stat` | 'count' | `count`, `probability` or `percent`. |
+| `min_count` | 1.0 | Hexagons below this count are not drawn. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `edge_color` | — | Hexagon outline color; default none. |
+| `edge_width` | 0.0 | Outline width. Length. |
+| `colorbar` | False | Attach a colorbar to the plot. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Stroke` (`edge_`), `Font`.
+<!-- /settings -->
+
+### Contour
+
+```python
+pl.Contour(values, x=None, y=None, plot=None, **settings)
+```
+
+Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `levels`: a number of nice values over the data, or the values. Lines take the map's colors, or `palette` (one color, or colors per level in turn: a list or a palette name); `negative_style` dashes negative levels drawn in one color; `value_labels` writes the levels on the lines. Bands are colored by their middle value.
+
+<!-- settings:Contour -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `levels` | 10 | A number of levels (nice values over the data) or the level values. |
+| `fill` | False | Fill the bands between levels: `True`, an opacity (0–1, times `alpha`), or `False`. |
+| `lines` | True | Draw the iso-lines. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `palette` | — | Line color, or colors taken per level in turn (a list or a palette name), instead of the map. |
+| `line_width` | 'calc(0.6 * inherit)' | Line width; default 0.6 × the plot's. Length. |
+| `line_style` | 'solid' | Line style. Length. |
+| `negative_style` | — | Line style of negative levels drawn with a single color (matplotlib: dashed). |
+| `alpha` | 1.0 | Opacity. |
+| `value_labels` | False | Write the level values on the lines. |
+| `value_label_format` | 'auto' | Number format of the value labels. |
+| `value_label_font_size` | '0.8em' | Label font size. Length; `%`: of the font size. |
+| `colorbar` | False | Attach a colorbar to the plot. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `FillStyle`, `Stroke`, `TextStyle` (`value_label_`), `Font`, `NumberFormat`.
+<!-- /settings -->
+
+### Pie
+
+```python
+pl.Pie(values, plot=None, **settings)
+```
+
+Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a plot drawn without axes (`Plot.axes=False`, aspect 1). `hole` makes a donut (`"40%"` of the radius), `explode` moves wedges out (`%` of the radius, one value or one per wedge). Names go outside (pushed apart so that they do not overlap), inside, or into the legend (`name_position="none"`, the legend then outside right); `palette` colors them in turn; `value_labels` writes percents or values inside, or outside with a leader line when a wedge is too thin.
+
+<!-- settings:Pie -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `names` | — | Wedge names (default: the dict's keys). |
+| `palette` | — | Wedge colors, taken in turn: a list of colors or a palette name; default the plot's palette. |
+| `start` | 90.0 | Angle where the first wedge starts (degrees, 0: 3 o'clock, 90: 12 o'clock). Angle (bare: degrees). |
+| `counterclockwise` | True | Direction of the wedges. |
+| `hole` | 0.0 | Radius of the hole (`%` of the radius): a donut. Length; `%`: of the radius. |
+| `explode` | — | Offset of the wedges from the centre (`%` of the radius): one value or one per wedge. Length; `%`: of the radius. |
+| `sort` | False | Sort the wedges by decreasing value. |
+| `name_position` | 'outside' | Where the names go: `outside`, `inside` or `none` (in the legend instead). |
+| `value_labels` | False | Write each wedge's `percent` or `value` inside it (outside, with a leader line, when it does not fit). |
+| `label_spacing` | '1.25em' | Smallest distance between outside labels on a side. Length; `%`: of the font size. |
+| `value_label_format` | 'auto' | Number format of the value labels (percentages: of 100). |
+| `edge_color` | 'series' | Wedge outline color: a color, `"series"` (each wedge's own color) or `none`. |
+| `edge_width` | 1.25 | Wedge outline width. Length. |
+| `alpha` | 1.0 | Opacity. |
+| `fill` | 0.25 | Wedge fill: an opacity of each wedge's color, times `alpha` (outlines keep `alpha`); `True` (opaque), a color, or `False`. |
+| `seam_color` | 'white' | The edges neighbouring wedges share, in this color; `none`: both outlines as drawn. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
+| `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
+| `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
+| `prefix` | inherited ('') | Text before every number. |
+| `suffix` | inherited ('') | Text after every number. |
+| `precision` | inherited (None) | Significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed). |
+
+Groups: `Stroke` (`edge_`), `FillStyle`, `Font`, `NumberFormat`.
+<!-- /settings -->
+
+## 6. Color and size axes
+
+Numbers given as colors (per point, per cell, per category, or a density) go through a
+**color axis** before they become colors, as positions go through an x axis: its scale
+and limits take each value to [0, 1], and its gradient (a `ColorMap`) gives the color.
+Sizes go through a **size axis** the same way, with a `SizeMap` (diameters) in place of
+the gradient. A colorbar is the guide of a color axis, a size key that of a size axis.
+
+```python
+h = p.heatmap(v, cmap="magma", color_limits="q:0.01/q:0.99", color_scale="log")
+h.color_axis                                        # the series' own color axis
+ca = fig.color_axis(color_map="magma", limits="0/max")   # a shared one
+p.heatmap(v, color_axis=ca)
+q.scatter(x, y, c=z, color_axis=ca)
+fig.colorbar(ca, id=5, label="energy")
+fig = pl.Figure(cols=3, share_color="row")          # each row's plots: one color axis
+fig = pl.Figure(cols=3, share_size="all")           # one size axis, one size key
+```
+
+* **Own axes.** A series that maps values has its own color axis, `series.color_axis`
+  (and size axis, `series.size_axis`). Its `scale` is the series' `color_scale`, its
+  `limits` the series' `color_limits` (axis syntax: `"auto"`, the values' range;
+  `"0/max"`, `"q:0.01/q:0.99"`, `[lo, hi]`), its gradient the series' `color_map`
+  (inherited: the plot's, the figure's, the style's). Its other settings (ticks,
+  `tick_format`, `label`, fonts) are drawn by its colorbar. A `scale` or `limits` set on
+  the axis itself wins over the series' settings.
+* **Shared axes.** `fig.color_axis(**settings)` (`fig.size_axis(**settings)`) makes an
+  axis that series take as `color_axis=` (`size_axis=`). It holds the gradient
+  (`color_map`; sizes: `size_map`), the scale and the limits; its automatic limits cover
+  every series using it, and those series take no `color_map`, `color_limits` or
+  `color_scale` of their own (an error). A `pl.ColorAxis(**settings)` made alone joins
+  the figure of the first series given it. The members of a `group=` call share one axis
+  of each kind.
+* **`share_color`.** The figure's `share_color` (`False`, `True`/`"all"`, `"col"` or
+  `"row"`, as `share_x`) makes the own color axes of each group's plots one axis: limits
+  over all their values; one `color_limits` (or scale) applies to the group, two
+  different ones are an error. Each series keeps its gradient. Facet figures share
+  color this way (`"all"` by default).
+* **`share_size`** does the same for the own size axes: limits over all the group's
+  values, one `size_limits` (or `size_scale`) for the group, and one size key for the
+  group ([legend](#legend)). Each series keeps its `size_map`. Facet figures share size
+  too (`"all"`).
+* **Training.** Before the layout, each axis is resolved from the values it maps, by the
+  code of x and y axes: the scale's domain, `limits` and quantiles, `include_zero`, no
+  padding (unless `padding` is set). Values past the limits take the gradient's
+  `under`/`over` colors and missing values its `bad` color (sizes: the `SizeMap`'s).
+
+Color and size axes have the settings of [axes](#4-axes); these differ:
+
+<!-- settings:ColorAxis -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `scale` | — | Scale of the mapped values: `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog` or `logit`; default `linear`. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+<!-- /settings -->
+
+<!-- settings:SizeAxis -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `scale` | — | Scale of the mapped values: `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog` or `logit`; default `linear`. |
+| `size_map` | — | The sizes: a `SizeMap` or a pair of diameters; default `SizeMap()`. |
+<!-- /settings -->
+
+### Colorbars
+
+```python
+p.colorbar(source=None, **settings)          # attached to a side of the plot
+fig.colorbar(source, id=None, **settings)    # in its own grid area
+cb.axis                                      # the color axis shown
+```
+
+`source` is a mapped series (its color axis; default: the plot's last mapped series) or
+a color axis. The bar draws the axis' gradient between its trained limits, with the
+axis' ticks, number format and fonts, and a label: `label`, else the axis' `label`, else
+the name of the color column or density. Attached bars take margin on their side, so axes
+stay aligned. A bar in its own area runs along the neighbouring axes (`align="axes"`) or
+boxes (`"borders"`). Axis settings given to a bar go to its axis:
+`p.colorbar(h, label="z", tick_format="{:.0%}")` sets `h.color_axis`'s tick format.
+
+<!-- settings:Colorbar -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `position` | 'right' | Side of the plot an attached bar takes. |
+| `orientation` | 'auto' | Bar direction; `"auto"`: vertical, or horizontal for bars attached at the top or bottom. |
+| `thickness` | 13.0 | Bar thickness (`%` of the attached axes side across it). Length; `%`: of the axes side across the colorbar. |
+| `length` | '100%' | Bar length as a fraction of the axes side (attached bars). Length; `%`: of the axes side along the colorbar. |
+| `pad` | 11.0 | Gap between the axes and an attached bar. Length; `%`: of the axes side across the colorbar. |
+| `label` | — | Bar label: a string or rich content; default: the axis' `label`, else the name of the color column or density. |
+| `extend` | 'auto' | Ends in the under/over colors: `auto` shows them when the limits clip the data. |
+| `extend_shape` | 'block' | `block`: a separate block at the end of the bar, within its length; `triangle`: a triangle past the bar's end. |
+| `frame` | False | Outline the bar. |
+| `frame_color` | '#666666' | Outline color. |
+| `frame_width` | 0.5 | Outline width. Length. |
+
+Groups: `Stroke` (`frame_`).
+<!-- /settings -->
+
+## 7. Colors, maps and markers
+
+### Colors and palette
+
+Colors are anything vec_io accepts (CSS names, `#hex`, `(r, g, b[, a])` floats,
+`CMYK`, `Spot`) or `"C0"`, `"C1"`, … for palette entries; `"none"` paints nothing. The
+default palette (`"tab10_custom"`, `plot_io.color.palettes.PALETTE`) is tab10's ten hues as named colors: sky,
+amber, emerald, rose, purple 0.4, yellow 0.7, pink 0.4, gray, lime, cyan.
+
+`palette` takes a `pl.Palette`, a registered name (`"tab10"`; `"tab10_r"` reversed), a
+list of colors (or one comma-separated string: `"red, teal 0.7"`), or a function `n -> colors`, called with the number of series of the plot
+that take a palette color.
+
+```python
+pl.Palette(colors="tab10_custom", name=None)    # a name, colors, a Palette or n -> colors
+pl.register_palette(name, palette)           # a Palette, colors or a function
+pl.palette_names()
+```
+
+| `Palette` | |
+|---|---|
+| `colors(n=None)` | the colors: all, or `n` (a list repeats, as series reuse it; a function is called with `n`) |
+| `len(p)`, `p[i]`, `p[a:b]`, `iter(p)` | lists only: count; a color (indices wrap); a sub-palette |
+| `reversed()`, `lighter(k=0.25)`, `darker(k=0.25)` | copies: reversed; each color moved by `k` toward white or black in Oklab |
+
+`ColorMap.to_palette(n)` samples a gradient into `n` colors, at the centers of `n` equal
+parts: `palette=pl.ColorMap("viridis").to_palette(5)` for ordered categories.
+
+| Palette | Colors |
+|---|---|
+| `tab10_custom` | plot_io's default: tab10's hues as named colors (10) |
+| `okabe_ito` | Okabe–Ito's eight colorblind-safe colors plus indigo and dark brown, chosen as the pair farthest from every other color (in Oklab) under normal and simulated protan, deutan and tritan vision (10) |
+| `tab10` | matplotlib ≥ 2.0, d3's category10 (10) |
+| `matplotlib_classic` | matplotlib 1.x: b, g, r, c, m, y, k (7) |
+| `tableau10` | Vega-Lite's default (10) |
+| `deep`, `muted`, `pastel`, `bright`, `dark`, `colorblind` | seaborn (10 each) |
+| `hue` | ggplot2's `hue_pal()`: n hues 360/n apart from 15°, chroma 100, luminance 65 (CIE LCh(uv)) |
+| `matlab` | MATLAB R2014b+ `lines` (7) |
+| `chartjs` | Chart.js 4 (7) |
+| `plotly` | plotly's default colorway (10) |
+| `observable10` | Observable Plot (d3's observable10) (10) |
+| `office` | Excel 2013+ Office theme (10) |
+| `economist` | The Economist (ggthemes, pre-2017) (10) |
+| `fivethirtyeight` | matplotlib's fivethirtyeight style (6) |
+| `greys` | black to light grey (4) |
+| `set1`, `set2`, `set3`, `paired`, `accent`, `dark2`, `pastel1`, `pastel2` | ColorBrewer's qualitative schemes by Brewer (Apache-2.0) (8–12) |
+| `batlow`, `batlowk`, `batloww`, `devon`, `lajolla`, `bamako`, `davos`, `bilbao`, `nuuk`, `oslo`, `grayc`, `hawaii`, `lapaz`, `tokyo`, `buda`, `acton`, `turku`, `imola`, `glasgow`, `lipari`, `navia` | Crameri's categorical Scientific colour maps 8 (MIT): the first colors differ most (100) |
+
+### Color maps
+
+```python
+pl.ColorMap(colors="rainbow_llhh", positions=None, under=None, over=None, bad=None,
+            space=None, name=None, interpolation=None, widen_colors=1, widen_sides=1.0)
+pl.register_color_map(name, color_map)
+pl.color_map_names()
+```
+
+| Member | |
+|---|---|
+| `colors` | a name (`viridis`, `magma`, `inferno`, `plasma`, `cividis`, `coolwarm`, `grey`, `rocket`, `mako`, `flare`, `crest`, `vlag`, `icefire`, `jet`, `parula`, `turbo`, `ggplot2`, the rainbows, ColorBrewer's and Crameri's maps below, in any case (`"RdBu"`, `"batlowK"`); `_r` reverses), a list of colors (evenly spaced or at `positions`; or one string, comma-separated: `"violet 0.4, sky 0.4, green 0.4"`), a `ColorMap` (copied) or a function `t -> color` |
+| `under`, `over`, `bad` | colors below 0 and above 1, past the color axis' limits (default: the end colors), and of missing values (default: transparent) |
+| `space` | interpolation between the colors: `"oklab"` (default, for every map: perceptually even) or `"srgb"` |
+| `interpolation` | `"linear"` (default): between neighboring colors; `"nearest"`: equal steps, one per color (`n` colors, `n` bins; with `positions`, each step starts at its position; a value on an edge takes the upper step); `"smooth"`: a Bézier curve with the colors as control points, through the first and last only (no `positions`); `"spline"`: a monotone cubic curve through every color (PCHIP in Oklab: no overshoot between colors) |
+| `widen_colors`, `widen_sides` | each inner color of a list repeated `widen_colors` times, each end color `round(widen_sides × widen_colors)` times: wider bands around the colors |
+| `cm(t)`, `colors_at(ts)` | color at t ∈ [0, 1]; bulk colors (C: continuous maps through a table of 4,096 colors, steps exactly) |
+| `table(n)`, `cells(values, lo, hi, mode)` | n colors sampled evenly; what heatmap cells hand vec_io's `draw_cells` (C): palette indices into `table(255)` (`table(253)` plus the under and over colors), or for `smooth` positions along `table(256)` (steps: the step colors and their bounds) |
+| `reversed()`, `resampled(n)`, `truncated(lo, hi)`, `with_extremes(…)` | copies: reversed; n flat steps; a part stretched to [0, 1]; new extremes |
+| `to_palette(n)` | a `Palette` of `n` colors sampled at the centers of `n` equal parts |
+
+Bundled data: viridis, magma, inferno and plasma by van der Walt and Smith (CC0); cividis
+by Nuñez, Anderton and Renslow; coolwarm by Moreland; rocket, mako, flare, crest, vlag and
+icefire from seaborn by Waskom (BSD-3-Clause); jet from matplotlib; a parula-like map;
+turbo by Mikhailov (Google, Apache-2.0);
+the rainbows, built from named colors with `widen_colors=6, widen_sides=0.6` and
+`interpolation="smooth"` (violet, sky,
+green, yellow, orange, rose): `rainbow` (all at level 0.4), `rainbow_neutral` (0.5),
+`rainbow_l0hh` (from white, then levels 0.1 to 0.6), `rainbow_llhh` (0.16 to 0.6),
+`rainbow_llh` (0.16 to 0.4), `rainbow_hlh` (dark ends, light middle); diverging maps from
+named colors: `blue_white_red` (sky, white, rose), `blue_white_red_hc` (levels 0.6 at the
+ends), `blue_gray_red` (a gray 0.2 middle), `blue_gray_red_hc`;
+ColorBrewer's schemes by Brewer (Apache-2.0): sequential `blues`, `bugn`, `bupu`, `gnbu`,
+`greens`, `greys`, `oranges`, `orrd`, `pubu`, `pubugn`, `purd`, `purples`, `rdpu`, `reds`,
+`ylgn`, `ylgnbu`, `ylorbr`, `ylorrd` (9 colors) and diverging `brbg`, `piyg`, `prgn`, `puor`,
+`rdbu`, `rdgy`, `rdylbu`, `rdylgn`, `spectral` (11 colors); Crameri's Scientific colour maps
+8 (MIT; Crameri, Shephard and Heron 2020): sequential `batlow`, `batlowk`, `batloww`,
+`devon`, `lajolla`, `bamako`, `davos`, `bilbao`, `nuuk`, `oslo`, `grayc`, `hawaii`, `lapaz`,
+`tokyo`, `buda`, `acton`, `turku`, `imola`, `glasgow`, `lipari`, `navia`, diverging `broc`,
+`cork`, `vik`, `lisbon`, `tofino`, `berlin`, `roma`, `bam`, `vanimo`, `managua`,
+multi-sequential `oleron`, `bukavu`, `fes` and cyclic `romao`, `bamo`, `broco`, `corko`,
+`viko` (256 colors each);
+`ggplot2` is ggplot2's continuous default (`#132B43` → `#56B1F7`). The
+`color_map` setting (alias `cmap`; inherited, default `"rainbow_llhh"`) is the gradient of
+heatmaps, contours and numbers given as colors. A `ColorMap` is a gradient over [0, 1]
+only: the values' limits and scale are their [color axis](#6-color-and-size-axes)'s, so
+series given one `ColorMap` object keep limits of their own; a shared color axis shares
+limits.
+
+### Size maps
+
+```python
+pl.SizeMap(sizes=(3, 13), by="area", under=None, over=None, bad=None)
+```
+
+`sizes` are the diameters at the limits of the [size axis](#6-color-and-size-axes).
+`by="area"` moves the area linearly between the end areas (with `sizes=(0, d)` and
+`size_limits="0/max"`, area is proportional to the value); `by="diameter"` moves the
+diameter. `under`/`over` default to the end sizes; `"none"` leaves those points out.
+`bad` (missing values) leaves them out by default. `size_map` also takes a pair of
+diameters.
+
+### Values in color and size
+
+| Given to `color` (also `edge_color`, `marker_color`, `marker_edge_color`) | Meaning |
+|---|---|
+| a color string, `CMYK`, `Spot`, or a **tuple** of 3 or 4 numbers | one color |
+| a list of colors | one color per point |
+| a **list, array or other buffer of numbers** | one value per point, mapped through the color axis |
+| an `(n, 3)` or `(n, 4)` buffer | one color per point |
+| `"density"` or `pl.Density(…)` | the points' density, mapped through the color axis |
+| a dict `{category: number}` or `{category: color}` (box, bar, violin) | per category |
+
+A tuple of numbers is always one color and a list of numbers is always values, so
+`color=[0.2, 0.4, 0.6]` with a point count other than 3 is an error (use a tuple for one
+RGB color). A `ColorMap` goes in `color_map`, not `color`. Values go through the series'
+color axis wherever a series maps them: points (Scatter, Strip, Swarm `color` and
+`edge_color`; the markers of Line, Errorbar, Stem and Regression), cells, categories (Box,
+Bar, Violin `color`). A box's outliers are computed, so its `marker_color` and
+`marker_edge_color` take colors only. A line's `color` and every `edge_color` of bars,
+boxes, violins, pies and hexagons are one color. Values elsewhere are errors that name the
+setting.
+
+`size` takes a diameter (a length), diameters per point (px), or values per point mapped
+through the size axis when the series has a `size_map` or a `size_axis`; `"density"` is
+always mapped (default sizes `SizeMap()`). A `SizeMap` goes in `size_map`. `marker_size`
+(lines, error bars, stems, regressions, box outliers) is diameters in px only: those
+series have no size axis.
+
+Aliases, on every class with the setting: `c` = `color`, `s` = `size`, `cmap` =
+`color_map`, `smap` = `size_map` (also in style keys). Giving both names is an error.
+
+### Point density
+
+```python
+p.scatter(x, y, c="density", draw_order="density")       # densest points drawn last
+p.scatter(x, y, c=pl.Density(adjust=0.5, normalize="max"), cmap="magma")
+pl.Density(bandwidth="scott", adjust=1.0, normalize="pdf", method="auto", grid=512)
+```
+
+The 2-D Gaussian kernel density at each point of the series, as scipy's
+`gaussian_kde(np.array([x, y]))(np.array([x, y]))`: the kernel covariance is the data
+covariance times Scott's factor n^(-1/6) (`"silverman"`: Silverman's), or a number
+(isotropic standard deviation) or a 2 × 2 matrix; `adjust` multiplies it. It is computed
+on the axis positions (log axes in log space); NaN points get NaN. `normalize`: `"pdf"`
+(scipy's values), `"count"` (points per unit area) or `"max"` (0–1); colors are the same
+under automatic limits. `method`: `"exact"` (the sum over all points, multithreaded in
+C, equal to scipy's), `"grid"` (binned, blurred and read back, about 1e-4 relative) or
+`"auto"` (exact up to 20,000 points). A `Density` (or `"density"`) is accepted by
+`color`, `edge_color`, `size` (through the size axis, default `SizeMap()`), `alpha` (mapped
+linearly to `alpha_range`, default (0.2, 1)) and `draw_order`, and by `marker_color` and
+`marker_edge_color` of Line (one line), Errorbar, Stem and Regression; one object computes each
+series' own density, cached until a setting changes, and exposed as
+`series.stats["density"]`. The colorbar label defaults to `"density"`.
+
+### Drawing order
+
+`draw_order` on scatter, strip and swarm: `None` (call order), `"density"` (ascending: the
+densest points are drawn last), `"-density"`, or sort keys per point (ascending; give
+`-z` for descending). Every per-point column (positions, colors, sizes, markers, opacities)
+is reordered together; the sort is stable and NaN keys come first. Setting `color` to a
+density does not reorder by itself.
+
+### Number formats
+
+One format applies wherever a number becomes text: `tick_format` (plot and colorbar
+axes) and `value_label_format` (value labels of bars, histograms, heatmaps, contours and
+pies).
+
+| Format | 1234.5, 0.05, −2 as one label set |
+|---|---|
+| `"auto"` (default) | `1234.50`, `0.05`, `-2.00`: the fewest equal decimals; on axes, a ×10ᵏ factor beyond `sci_limits`, elsewhere each label in scientific form |
+| a format string | `"{:.1f} ms"` → `1234.5 ms` (`str.format`, one field) |
+| a function | `value -> str` or `value -> rich content` |
+| `"percent"` | `123450%`, `5%`, `-200%` |
+| `"sci"` | `1.2345×10³`, `5.0000×10⁻²`, `-2.0000` (no ×10⁰) |
+| `"eng"` | `1.2345×10³`, `50.0000×10⁻³`, `-2.0000` (exponents multiples of 3) |
+| `"si"` | `1.2345k`, `50.0000m`, `-2.0000` (y … Y, µ for 10⁻⁶) |
+| `"int"` | `1235`, `0`, `-2` |
+
+Every preset chooses the decimals for all labels together, so they line up (`1.0k`,
+`1.5k`, `2.0k`); halves round away from zero (`1234.5` → `1235`), and a value rounding
+to the next power is written in it (`9.96` at 2 digits → `10`). NaN gives an empty label.
+Format strings and functions get the raw value; separators, minus and affixes then apply
+to the numbers in their result (rich content is used as is).
+
+Inherited settings (figure → plot → axis; series → its color axis):
+
+| Setting | Default | Values |
+|---|---|---|
+| `decimal_separator` | `"."` | any string |
+| `thousands_separator` | `""` | any string (`","`, `"."`, `" "`; a thin space U+2009 needs an embedded font) |
+| `minus` | `"hyphen"` | `"hyphen"` (`-`, every font; exponents too) or `"minus"` (U+2212, taken from an installed font, which is then embedded) |
+| `prefix`, `suffix` | `""` | text around every number |
+| `precision` | unset | significant digits of `auto`, `sci`, `eng`, `si` (unset: as needed to tell the labels apart) |
+
+### Markers
+
+| Name | Area of the unit shape |
+|---|---|
+| `circle` | π/4 |
+| `square` | 1 |
+| `diamond` | 0.5 |
+| `triangle_up`, `triangle_down`, `triangle_left`, `triangle_right` | √3/4 |
+| `plus` | 0.51 |
+| `cross` | 0.5754 |
+
+Aliases: `triangle`, `o`, `s`, `d`, `^`, `v`, `<`, `>`, `+`, `x`. A `vec_io.Path` or SVG
+path data in a unit box centred on the origin also works. `pl.register_marker(name, path)`
+adds a shape (its area measured from the outline); `plot_io.markers.marker_path(name)` returns a path
+for vec_io's `draw_markers`; `plot_io.markers.marker_area(name)` its area.
+
+## 8. Output
+
+```python
+fig.save(path, **options)          # .pdf, .png, .jpg/.jpeg, .jxl, .avif
+fig.to_bytes(format="pdf", **options)
+fig.draw(canvas, x=0, y=0)         # on any vec_io canvas (its document's fonts); returns (width, height) in px
+fig.size()                         # (width, height) in px
+p.save(path, …)   p.to_bytes(…)   p.draw(canvas, …)   # one plot alone, at its size in the figure
+```
+
+The figure is drawn once on a page of a vec_io document in px; each output is made from
+it with its own options:
+
+| Options | Of |
+|---|---|
+| `title`, `author`, `subject`, `keywords`, `creator`, `creation_date`, `pdf_a`, `color_mode`, `ink_limit`, `icc_profile`, `base_dir` | the document (vec_io `Document`) |
+| `font_dirs`, `system_fonts` | the fonts text is shaped and embedded with ([fonts](#1-conventions)) |
+| `quality` | the figure's `quality` when not given: 1–100, `"lossless"` (not JPEG) or `"auto"`, the default: PNG 90, a palette of at most 256 colors; JPEG 90; JPEG XL, AVIF and rasterized content in a PDF lossless |
+| `compression` | `"fast"`, `"balanced"` (default), `"best"`: the encoder's effort (PDF streams and images, PNG, JPEG, JPEG XL, AVIF) |
+| `simplify` | the output's `simplify` for content without its own (series have theirs, below) |
+| `compress`, `font_hinting` | PDF: compressed streams (default) or a readable file; TrueType hinting kept in embedded subsets (default: left out) |
+| `dpi`, `background` | images: resolution (default 192: two image pixels per px); a color under the figure (default the figure's, white; `None` is transparent, white in JPEG) |
+
+JPEG XL output (`.jxl`) needs libjxl, AVIF output (`.avif`) libavif 1.x. Images inside a
+PDF (rasterized series, heatmaps) are stored losslessly or as JPEG (`quality`), never as
+JPEG XL, so every PDF reader shows them. Fonts are embedded subsets without hinting: a
+typical figure's text adds a few KB per face. A plot
+saved alone keeps its size in the figure (axes or box, by `align`), its limits and ticks
+(those of its shared axes too), its title, legend and attached colorbars, and shows its
+outer tick labels ([layout](#layout)).
+
+PNG quality: by default (`quality="auto"`) PNGs are palette images at quality 90: the plot's
+own colors stay exact, only antialiasing and gradients are approximated, and an image 256
+colors cannot render well enough stays lossless. The 21 example PNGs total 0.74 MB this way,
+1.57 MB with `quality="lossless"` and 1.38 MB lossless with `compression="best"` (same pixels,
+slower). Notebook previews are lossless.
+
+### Large data
+
+* Series map their data to page coordinates in C (`kernels.scaled`) and draw with
+  one bulk vec_io call (markers, lines, areas, segments).
+* `simplify` (series, plot or figure; default `"auto"`) goes to each of the series' vec_io
+  calls, and vec_io applies it per output. PDF: `"auto"` decimates lines with many points
+  per pixel column and culls markers that later markers hide when that pays off (vec_io
+  decides per call from the data); `True` or a dpi always simplifies at that resolution;
+  `False` never. PNG, JPEG, JPEG XL and AVIF draw everything (rasterizing hidden content
+  costs less than culling it, and the pixels are the same) and decimate lines for their
+  resolution, unless `False`.
+* `rasterize=True` or a dpi draws the series in a vec_io group the PDF holds as an image;
+  axes and text stay vectors. Image output draws the group as vectors at its own
+  resolution.
+
+Timings (`tools/bench.py`, 8 threads, PDF written):
+
+| Case | Time |
+|---|---|
+| `import plot_io` (vec_io included) | 0.06 s |
+| empty figure, 4 plots with ticks and labels | 0.005 s |
+| scatter, 100k points, one color | 0.02 s |
+| scatter, 1M points, colors from a `ColorMap` | 0.25 s |
+| scatter, 1M points, `c=values`, PDF / PNG at 150 dpi | 0.56 s / 0.43 s |
+| line, 1M points (`simplify=False` / `True`) | 0.08 s / 0.03 s |
+| box plots, 10 categories × 1M values | 0.09 s |
+| heatmap 1000 × 1000 (`image`) with a colorbar | 0.06 s |
+| heatmap 200 × 200, uneven cells (`cells`) | 0.04 s |
+| scatter, 1M points, `rasterize=300` | 0.22 s |
+| `simplify="auto"` on 1M points it does not cull: overhead | < 0.01 s |
+
+## 9. Genome tracks
+
+```python
+fig = pl.Tracks("chr2:143,120,001-143,780,000", width="5in")
+fig.hic(gwseq_io.open("cells.hic"), y_axis={"label": "Hi-C"}, depth=500_000)
+fig.gtf(gwseq_io.open("gencode.gtf.gz"), gene_type="protein_coding")
+fig.bed(gwseq_io.open_peaks("sites.tsv"), y_axis={"label": "Sites"})
+sets = fig.track(stacked=True)                     # one track, a named row per file
+for c in ("con", "pio"):
+    sets.bed(gwseq_io.open_peaks(f"{c}.tsv"), name=c)
+p = fig.track(y_axis={"label": "A/B"})             # an empty track: series overlaid
+before = p.bigwig(gwseq_io.open("before.bw"), name="before", color="sky", fill_to=False)
+p.bigwig(gwseq_io.open("after.bw"), name="after", color="rose", fill_to=before)
+fig.bigwig(gwseq_io.open("atac.bw"), y_axis={"label": "ATAC"})
+fig.vline(143_400_000)                             # through every track and the gaps
+fig.save("locus.pdf")
+fig.save("other.pdf", region=("chr2", 80_000_000, 81_000_000))
+```
+
+Genome tracks are made of general pieces:
+
+* **A tracks figure.** `pl.Tracks(region, **settings)` is a `Figure` with
+  `layout="tracks"` ([§2](#arrangement)): one column of plots, top to bottom in creation
+  order, sharing x (`share_x="all"`, tick labels and the axis title under the bottom plot
+  only), `spacing` 0, `width` 480 px. Its `region`, `unit`, `unit_in` and `origin` go to
+  `fig.x_axis`, the settings of every plot's x axis ([figure axes](#figure-axes)), with
+  `scale="genome"`; the other keywords are the figure's.
+* **Tracks.** A `Track` is a plot preset: a `height` from its content, `space_above` it,
+  axis lines left and bottom (Hi-C: bottom only), at most 4 y ticks and the y axis'
+  `label` in the row band (`label_position="band"`, `label_pad="0.5em"`). `fig.track(**settings)`
+  returns an empty one; a plot type called on the figure (`fig.bigwig`, `fig.bed`,
+  `fig.genes`, `fig.gtf`, `fig.hic`, also `fig.line`, …) adds a track holding it and returns
+  the series (`.plot` is the track; the track's settings, `title`, `x_axis` and `y_axis`
+  go to it, and
+  `name` names the series, its legend entry, as everywhere). Called on a track
+  (`p.bigwig(…)`, `p.line(…)`, `p.hline(…)`), plot types overlay in it.
+* **The genome scale.** An x axis with `scale="genome"` is linear in bp: its limits are its
+  `region` (less its `origin`), without padding, its tick labels in bp, kb or Mb, its
+  automatic label the chromosome (`chr2 (Mb)`). A genome series asks its x axis for it
+  when the axis has no scale of its own, so the genome series work on any plot too
+  (`pl.Plot().bigwig(reader, region=…)`: the series' own `region`).
+* **Genome layers.** `bigwig`, `bed`, `genes`, `gtf` and `hic` are plot types like the
+  others, drawn with the shared geoms: a signal's bins as a step line, a band and bars;
+  intervals and gene models as rectangles, lines and names; contacts as a grid of cells
+  under a 45° transform.
+* **Row labels, groups, lines through rows** are figure features ([§2](#rows)):
+  the y axis' `label` is a row label lined up across the tracks, `fig.group(first, last, label=…,
+  letter=…)` labels consecutive tracks (with x tick labels under the last one), and
+  `fig.vline(x, rows=…)`, `fig.vspan(x0, x1, rows=…)` run through the tracks and the gaps.
+
+Details:
+
+* **Region.** `region` is a string, 1-based and inclusive
+  (`"chr2:143,120,001-143,780,000"`; positions may carry a unit: `"chr1:1.2M-1.5M"`,
+  `"chr1:500kb-2Mb"`, with `k`, `M`, `G` and an optional `b`, any case, and `,` or `_`
+  between thousands), a `(chr, start, end)` tuple or list (0-based, half-open; the same
+  position strings), or a mapping with `chr`, `start` and `end`; `plot_io.genome.parse_region` gives the
+  `Region` (`chr`, `start`, `end`). A series reads its own `region`, else its x axis'.
+  Data are read when the figure is drawn, for the region drawn: `save`, `to_bytes`, `draw`
+  and `size` take `region=` to draw another one (it replaces `fig.x_axis`'s region for
+  that call).
+* **x axis.** Ticks under every track (but a Hi-C triangle with `direction="down"`), tick
+  labels and the axis label (`chr2 (Mb)`) under the bottom track; a group's last track has
+  tick labels too; `fig.set(label_outer=False)` labels every track. `unit` (`auto`, `bp`,
+  `kb`, `Mb`) and `unit_in` (`"label"`: `chr2 (Mb)` under `143.2 143.3 …`; `"ticks"`:
+  `-500kb 0 500kb`) set the labels; `tick_format="chr:pos"` writes positions
+  (`chr2:143,250,000`, in bp with `,` between thousands unless `unit` is set:
+  `chr2:143.25Mb`), the position itself even with an `origin`, and leaves the automatic
+  label out; `fig.x_axis(label=…)` replaces the label, and in a
+  string `{chr}`, `{unit}`, `{start}`, `{end}` are filled in (`""`: none). `origin` (a
+  position, `"center"`, `"start"` or `"end"` of the region) is drawn at 0: every series on
+  the axis is drawn less it ([transforms](#5-series)), and limits, ticks and decorations
+  are distances from it (`fig.vline(0)`, `fig.vspan(-1000, 1000)`); a region given to
+  `fig.vspan` is in positions.
+* **y axis.** An interval track's y axis has a tick per named series (`fig.bed(…,
+  name=…)`; each `name` of a `stacked` track) at the middle of its rows, the name as its
+  label; without names, and on Hi-C tracks, the y axis is hidden (`y_axis(visible=True)`
+  shows it).
+* **Heights.** A track's `height`: a length, a share (`"1fr"`, of the room the fixed heights
+  leave in a figure of given height, `reference="figure"`), or `auto`: the Hi-C triangle's
+  height (square cells; `max_height`, a length or a percentage of the width such as
+  `"33%"`, caps it, and `fit` clips the distances above or squashes the triangle), the rows
+  of intervals × `row_height` plus the y axis padding above and below, or `auto_height`
+  for signals. The figure height follows. `space_above` is the space above a track:
+  `auto_space_above` above every track but the first.
+* **Stacked intervals.** A track with `stacked=True` puts each interval series on rows of
+  its own, top to bottom, named left of its rows; they take no legend entries.
+* **Bins.** `bins` of `bigwig` and `hic`: a width on the axes (`"0.5px"`, the default: two
+  bins per px of the axes width; Hi-C: the finest resolution whose cells are at least that
+  wide), a size (`"10kb"`, `"5000bp"`, `"5000d"`), or a count (`200`). A size is read on
+  the genome-wide grid of that size: the region grows outward to it
+  (`snap_to_grid="expand"`), and the first and last bins are then cut to the region. A
+  count cuts the region itself into that many bins. The bins (and Hi-C `height="auto"`, interval rows) follow the axes width the
+  layout places: with the default `reference="axes"` it is `width`, so each file is read
+  once per draw; with `reference="plot"` or `"figure"`, the data are read again for the
+  width the first round places (reads are cached by their bins).
+* **Shared y.** `share_y=other_track` on a track, or `fig.set(share_y="bigwig")` to put
+  every track with a `bigwig` series on one scale (a figure's `share_x`/`share_y` takes a
+  plot type's name).
+
+### Readers
+
+plot_io does not import gwseq_io: it reads any object with the methods of gwseq_io's
+readers, recognised by their `type` attribute (`"bigwig"`, `"bigbed"`, `"bed"`, `"peaks"`,
+`"gtf"`, `"gff3"`, `"hic"`), else by their methods. The calls, which another reader can implement:
+
+| Data | Methods called |
+|---|---|
+| signal (bigWig; the coverage of bigBed, BED and peaks readers) | `read_values([(chr, start, end)], bin_count=n, bin_mode=…, def_value=…, zoom="auto")`, or with `bin_size=b, snap_to_grid="expand"` and the row's bounds from `resolve_regions([(chr, start, end)], bin_size=b, snap_to_grid="expand")` (without it, `snap_to_grid=False, full_bin=True`): one row of values |
+| intervals (bigBed, BED, peaks) | `read_entries([(chr, start, end)], as_cols=True, col_count=…)`: a dict (or a list of one dict) of columns; `col_count` from `auto_sql` when the reader has it |
+| annotation (GTF, GFF3) | `read_transcripts([(chr, start, end)], as_cols=True, gene_type=…, transcript_type=…)`: a dict (or a list of one dict) of transcript columns: `start`, `end`, `strand`, `transcript_id`, `transcript_name`, `gene_id`, `gene_name`, `cds_start`, `cds_end` (−1 when non-coding), `exon_starts`, `exon_ends`, `exon_offsets` |
+| contacts (Hi-C) | `bin_sizes`, `normalizations`, `read_values((chr, start, end), bin_size=b, snap_to_grid="expand", normalization=…, matrix_type=…, max_distance=…)` (or `bin_count=n` instead of the first two): a square matrix; bounds from `resolve_regions((chr, start, end), bin_size=b, snap_to_grid="expand")["rows"]` |
+
+Results are read as buffers (numpy arrays included) without importing numpy. A path
+instead of a reader raises `TypeError` (open it with `gwseq_io.open`, or
+`gwseq_io.open_peaks` for a TSV of locations), as do BAM and CRAM readers (pile the reads
+up into a bigWig first). A reader's error is raised with the track's label in the
+message.
+
+### BigWig
+
+```python
+pl.BigWig(reader=None, plot=None, *, x=None, y=None, **settings)
+```
+
+A step line along the bins, filled to `fill_to`. `reader` is a signal reader, a function
+`f(chr, start, end, bins)` returning the values, or `None` with `y` (values evenly over
+the region) and optionally `x` (bin centres, or n + 1 edges, in bp). The color is black
+when the series is alone in its track, palette colors when overlaid. `fill_to=<series>`
+fills between two signals, each part in the fill color of the series on top. For more,
+the track's `fill_mode` fills between all its signals, in place of their `fill_to`:
+`"in_between(up)"` (or `"in_between"`) fills each band between two neighbouring signals
+in the color of the one just above, `"in_between(down)"` of the one just below;
+`"in_between(max)"` fills from the lowest signal to the highest in the color of the top
+one, `"in_between(min)"` of the bottom one. The colors follow wherever the order changes
+(lines get points where they cross), and 0 is not kept on the y axis:
+
+```python
+t = fig.track(y_axis={"label": "Lamin A/C"}, fill_mode="in_between(up)")
+t.bigwig(neo_reader, name="Neo", color="sky")
+t.bigwig(pax7_reader, name="Pax7", color="rose")
+```
+
+<!-- settings:BigWig -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `region` | — | The region read: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; unset: the x axis' `region`. |
+| `bins` | '0.5px' | A bin count over the region (exactly, not on a grid); a bin size (`"10kb"`, `"5000bp"`), read on the genome-wide grid of the size (the row grown to it, then cut to the region); or a bin width on the axes (`"0.5px"`: two bins per px, read as a count). |
+| `bin_mode` | 'mean' | Reduction per bin: `mean`, `max` (keeps narrow peaks), `min`, `sum`, … (gwseq_io's). |
+| `def_value` | 0.0 | Value of bases no record covers; NaN breaks the line there. |
+| `kind` | 'step' | `step` (a step line along the bins), `line` (through the bin centres) or `bar` (one rectangle per bin). |
+| `fill_to` | 0.0 | Fill between the signal and a value, another series of the track (colored by whichever is above), or `False`. |
+| `fill` | 0.2 | Fill (to `fill_to`): an opacity of the line color, `True` (opaque), a color, or `False`. |
+| `color` | — | Line color; default black alone in its track, the next palette color when overlaid. |
+| `transform` | — | A function applied to each value (log, scaling). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `FillStyle`, `Font`.
+<!-- /settings -->
+
+### Bed and Genes
+
+```python
+pl.Bed(reader, plot=None, **settings)
+pl.Genes(reader, plot=None, **settings)    # Bed with kind="genes", rows expanded, names on,
+                                           # filled solid without outlines
+```
+
+`reader` is an interval reader, or the columns themselves: a dict, a DataFrame, or rows
+(dicts, or tuples in BED order). Used columns: `chr` (when given, rows of other
+chromosomes are left out), `start`, `end`, `name`, `score`, `strand`, `thickStart`,
+`thickEnd`, `itemRgb` (`reserved` in bigBeds), `blockCount`, `blockSizes`, `blockStarts`.
+`genes` draws each BED12 model as a line, thin boxes for UTRs and thick boxes for coding
+exons, chevrons on introns (`strand`), and its name in italics with a strand mark
+(`Pcsk2 ›`). Names go left of their feature and are dropped where they would collide;
+with `rows="expand"` packing leaves room for them (`names=False`: none). `name_region` names only the
+features overlapping it (a locus within a wider view), and packing then makes room only
+for those names. Features are outlined in their color (`outline`, `line_width`) over their
+`fill` (an opacity of their color, 0.3; `False` for outlines only), the outline inside the feature's extent: a
+feature narrower than two borders is one line, `line_width` wide. `recolor` snaps the features' colors
+(`itemRgb` ones included) to the named colors (`"blue 0.4"`, §7): `True` takes the
+closest of all shades, a level such as `0.4` the closest color's shade at that level, so
+every feature has the same lightness.
+
+<!-- settings:Bed -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `region` | — | The region read: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; unset: the x axis' `region`. |
+| `kind` | 'boxes' | `boxes` (intervals, 8/13.2 of a row high: 8 px in the default row) or `genes` (BED12 models: exons as high, UTRs half, introns). |
+| `rows` | 'collapse' | `collapse`: one row; `expand`: overlapping features (and their labels) packed onto rows. |
+| `min_width` | 0.75 | Narrowest drawn feature (1-bp sites stay visible). Length. |
+| `color` | 'black' | A color, `"item_rgb"` (the `itemRgb` column) or `"score"` (the `score` column through `color_map`). |
+| `recolor` | False | Replace each feature's color by the closest named color (`True`: the closest shade; a level 0–1: the closest color's shade at that level); `False`: as given. Not with `color="score"`. |
+| `names` | False | Feature names (`name`) left of the features, dropped where they collide. |
+| `name_region` | — | Only features overlapping this region (as `region` takes it) get names; `None`: all. |
+| `strand` | False | Strand chevrons on boxes and introns. |
+| `outline` | True | Outline features in their color (`line_width` wide). |
+| `fill` | 0.3 | Fill of the features: an opacity of their color (times `alpha`), `True` (opaque), a color, or `False` (outlines only). |
+| `row_height` | '1.2em' | Height of a row; the track's automatic height is rows × it, plus the y axis padding. Length; `%`: of the font size. |
+| `name_font_size` | '0.85em' | Font size of feature names. Length; `%`: of the font size. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | — | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | — | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `line_width` | inherited (0.75) | Line width. Length. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `FillStyle`, `TextStyle` (`name_`), `Font`.
+<!-- /settings -->
+
+`Genes` (only its own defaults):
+
+<!-- settings:Genes -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `kind` | 'genes' | `boxes` (intervals, 8/13.2 of a row high: 8 px in the default row) or `genes` (BED12 models: exons as high, UTRs half, introns). |
+| `rows` | 'expand' | `collapse`: one row; `expand`: overlapping features (and their labels) packed onto rows. |
+| `names` | True | Feature names (`name`) left of the features, dropped where they collide. |
+| `strand` | True | Strand chevrons on boxes and introns. |
+| `outline` | False | Outline features in their color (`line_width` wide). |
+| `fill` | True | Fill of the features: an opacity of their color (times `alpha`), `True` (opaque), a color, or `False` (outlines only). |
+
+Groups: `FillStyle`.
+<!-- /settings -->
+
+### Gtf
+
+```python
+pl.Gtf(reader, plot=None, **settings)      # Genes from a GTF or GFF3 reader
+```
+
+`reader` is a GTF or GFF3 reader (`gwseq_io.open("gencode.gtf.gz")`, bgzipped and indexed;
+`gwseq_io.index_gtf` makes one from any GTF), or BED12 columns as `Genes` takes them. The
+transcripts overlapping the region come whole, with their exons outside it. With
+`model="gene"` each gene is one model: its transcripts' exons merged, coding from the
+first CDS start to the last CDS end (the stop codon included), named by `gene_name`;
+`model="transcript"` draws every transcript, named by `transcript_name`. An id names what
+has no name. `gene_type` and `transcript_type` keep those biotypes. A `Bed` or `Genes`
+given a GTF reader raises `TypeError` pointing here.
+
+`Gtf` (only its own settings and defaults):
+
+<!-- settings:Gtf -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `model` | 'gene' | `gene`: one model per gene, its transcripts' exons merged and coding from the first CDS start to the last CDS end, named by `gene_name`; `transcript`: one per transcript, named by `transcript_name` (ids where there is no name). |
+| `gene_type` | — | Gene biotypes kept (`"protein_coding"`, a list); `None`: all. |
+| `transcript_type` | — | Transcript biotypes kept; `None`: all. |
+<!-- /settings -->
+
+### HiC
+
+```python
+pl.HiC(reader, plot=None, **settings)
+```
+
+The upper triangle of the contact matrix, the diagonal on the x axis, each cell a
+diamond: the matrix is drawn as an image under a 45° transform and clipped to the track.
+`reader` is a Hi-C reader, or a square matrix over the region. `bins="0.5px"` (the
+default) takes the finest of the reader's `bin_sizes` whose cells are at least 0.5 px wide;
+the cells of a size (`bins="5kb"`) sit on the file's grid, those past the region cut by
+the track's edges, and `bins=n` reads n cells over the region exactly. Its color axis' limits default
+to quantiles of the cells drawn (`color_limits="q:0.01/q:0.99"`), on a log scale
+(`color_scale="log"`; cells of 0 take the map's low end; cells without a value take
+`nan_color`, transparent), through the figure's `color_map`.
+
+<!-- settings:HiC -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `region` | — | The region read: `"chr2:143,120,001-143,780,000"` (1-based, inclusive), `(chr, start, end)` (0-based, half-open) or a mapping; unset: the x axis' `region`. |
+| `depth` | — | Largest distance shown (bp); default the region's span (the whole triangle). |
+| `bins` | '0.5px' | A bin count over the region (exactly, from the coarsest resolution giving that many); one of the reader's `bin_sizes` (`"10kb"`), read on its grid (the region grown to it, then cut by the track); or a cell width on the axes (`"0.5px"`): the finest resolution whose cells are at least that wide. |
+| `normalization` | 'none' | `"none"` or one of the reader's `normalizations`. |
+| `matrix_type` | 'observed' | `observed`, `oe` (observed / expected) or `expected`. |
+| `color_map` | inherited ('rainbow_llhh') | The gradient numbers given as colors are drawn with: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `color_limits` | 'q:0.01/q:0.99' | Limits of the series' color axis, as an axis' `limits`: `"-2/2"`, `"0/max"`, `"q:0.01/q:0.99"`; unset: `"auto"`, the values' range. |
+| `color_scale` | 'log' | Scale of the series' color axis (`log`, `sqrt`, …); unset: `linear`. |
+| `color_axis` | — | A shared `ColorAxis` (`figure.color_axis(…)`) in place of the series' own: it holds the map, limits and scale. |
+| `nan_color` | — | Color of cells without a value; default: the map's `bad` (transparent). |
+| `direction` | 'up' | `up`: the apex up; `down`: the triangle hangs from the top. |
+| `max_height` | — | Largest height of the track: a percentage of its width (`"33%"`) or a length; `None`: the triangle's (square cells). |
+| `fit` | 'clip' | How the triangle fits a height below its own (`max_height`, or the track's `height`): `clip` keeps square cells and cuts the distances above; `squash` flattens the whole triangle. |
+| `colorbar` | False | Attach a colorbar to the track. |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
+| `z` | — | Drawing order (higher on top); default: call order. |
+| `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
+| `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: vec_io's `simplify`. |
+| `text_color` | inherited ('black') | Text color. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+
+Groups: `Font`.
+<!-- /settings -->
+
+### Tracks
+
+`pl.Tracks(region=None, **settings)` returns the figure; `Track` has the settings of `Plot`,
+these added or with other defaults:
+
+<!-- settings:Track -->
+| Setting | Default | Meaning |
+|---|---|---|
+| `space_above` | 'auto' | Space above the track; `auto`: none for the first track, else `auto_space_above`. Length; `%`: of the font size. |
+| `height` | 'auto' | Height of the track's axes: a length, a share of the room the fixed heights leave (`"1fr"`, with the figure's height given), or `auto`: Hi-C from its `depth` (square cells), intervals rows × `row_height`, else `auto_height`. |
+| `auto_height` | '4.5em' | Height of signal and empty tracks with `height="auto"`. Length; `%`: of the font size. |
+| `auto_space_above` | '0.6em' | The space `space_above="auto"` leaves. Length; `%`: of the font size. |
+| `stacked` | False | Interval series on rows of their own, top to bottom, each named left of its rows by its `name`. |
+| `fill_mode` | — | Fill between the track's signals (replacing their `fill_to`): `"in_between(up)"` (or `"in_between"`), each band between two neighbouring signals in the fill color of the one above; `(down)`, of the one below; `(max)`, one band from the lowest signal to the highest in the color of the top one; `(min)`, of the bottom one. `None`: each signal's `fill_to`. |
+<!-- /settings -->
+
+## 10. Styles
+
+A style presets settings: `Figure(style=…)` (also accepted by `pl.Plot` and the series
+classes, which pass it to their figure). Explicit settings always win over the style.
+
+```python
+fig = pl.Figure(style="default")
+fig = pl.Figure(style={"base": "default", "font_size": 9, "Axis.grid": True})
+fig = pl.Figure(style={"base": ["house", "talk"], "palette": ["#333", "#c00"]})
+
+pl.register_style("house", {"font_family": "Helvetica", "Legend.frame": True})
+pl.set_style("house")                  # figures created afterwards
+with pl.use_style({"font_size": 10}):  # figures created inside the block
+    ...
+pl.styles.names()                      # registered names
+pl.styles.settings("house")            # the resolved dict (base theme included)
+```
+
+* **Keys.** Names of inherited settings (`"font_size"`, `"palette"`), `"Class.name"` for
+  any setting of a class and its subclasses (`Figure`, `FigureTitle`, `Plot`, `Title`,
+  `Legend`, `Axis` (plot, color and size axes), `Colorbar`, every series class, `Series` for
+  all of them, every decoration class, `Decoration` for all of them, the genome classes),
+  or `"Group.member"` for every embedding of a group member (`"Marker.size"`,
+  `"Stroke.line_width"`, `"TextStyle.font_weight"`).
+  `"Colorbar.<axis setting>"` (`"Colorbar.tick_direction"`, `"Colorbar.tick_color"`, …)
+  applies to color axes (the colorbars' axes) only, and `"XAxis.<setting>"`, `"YAxis.<setting>"` to the x or
+  y axis of plots only; each wins over `"Axis.<setting>"` there.
+  Keys starting with `--` are custom variables (`"--accent": "#c00"`), read by
+  `var(--accent)`. Values are checked when the style is registered or set.
+* **`"base"`.** A style name or a list of names, applied left to right (later ones win);
+  the dict's own keys are applied over them. Registered styles use the same form.
+* **Resolution.** The cascade of [conventions](#1-conventions): the object's own value,
+  class rules, `"Class.name"` keys along the class hierarchy, the parent (inherited
+  settings), `"Group.member"` keys, the class and group defaults, then the bare name. The
+  effective theme is the inherited defaults (the bare names of `DEFAULTS`) with the
+  expanded style merged over it.
+* **Default.** Without `style`, a figure takes the session style current when it is
+  created (`use_style` innermost, else `set_style`), else `"default"`, which adds nothing
+  to `DEFAULTS`.
+* **`scaling`.** A figure setting (default 1, or `"Figure.scaling"` in the style) that
+  multiplies every absolute length: font sizes, line widths, marker sizes, tick lengths,
+  pads and gaps, from the defaults, the style or set on objects (not the figure size).
+  Lengths in `em` follow the scaled font size.
+
+Bundled styles (`pl.styles.names()`), each the defaults of a library expressed in these
+settings (colors, fonts, grid, axis lines, ticks, legend and title placement, palette,
+color map, default series looks). They never change plot sizes or the minus sign
+(`style={"base": "matplotlib", "minus": "minus"}` gets matplotlib's).
+
+| Style | Follows | Variants |
+|---|---|---|
+| `default` | `DEFAULTS` | — |
+| `matplotlib` | matplotlib ≥ 2.0 defaults (tab10, viridis, four spines, rounded legend frame) | `matplotlib-classic` (1.x: ticks in on all sides, b g r c m y k, jet) |
+| `seaborn` | seaborn darkgrid, notebook context, deep, rocket | `seaborn-darkgrid`, `-whitegrid`, `-dark`, `-white`, `-ticks`; `-paper`, `-talk`, `-poster` (scaling 0.8, 1.5, 2) |
+| `ggplot2` | `theme_grey()`: grey panel, white grid with minor lines, left title, legend outside, `hue` palette | `ggplot2-bw`, `-light`, `-minimal`, `-classic` |
+| `altair` | Vega-Lite: grey axis lines and grid, view frame, bold titles, hollow points, tableau10, YlGnBu, nice limits | — |
+| `matlab` | MATLAB R2014b+: ticks in, `lines` colors, parula, hollow circles, nice limits, framed legend | `matlab-box` (box on) |
+| `chartjs` | Chart.js 4: light grid, grey text, legend boxes on top, translucent points | — |
+| `plotly` | plotly: blue-grey panel, white grid, no ticks, left title, plasma | `plotly-white` |
+| `bokeh` | Bokeh 3: light grid and frame, italic axis titles, bold left titles, Category10, framed legend top right | — |
+| `observable` | Observable Plot: no axis lines or grid, 10 px system font, hollow points, observable10, turbo | — |
+| `excel` | Excel 2013+: Calibri-like font, grey text, horizontal grid only, Office palette, legend below | — |
+| `fivethirtyeight` | matplotlib's `fivethirtyeight`: `#f0f0f0` background, large text, thick lines, grid, no ticks | — |
+| `economist` | ggthemes' `theme_economist`: blue-grey background, white horizontal grid, y labels on the right, red rule above the figure title | — |
+| `tufte` | ggthemes' `theme_tufte` with a range frame: serif, no grid, axis lines trimmed to the ticks and offset, greys | — |
+
+Values come from matplotlib's and seaborn's rcParams, ggplot2's `theme-defaults.R`, the
+Vega and Vega-Lite default configs, Chart.js's defaults, plotly's templates and MATLAB's
+documented default properties. What cannot be expressed: legend titles naming a variable
+(series carry no variable names).
+
+## 11. Errors
+
+| Exception | Raised for |
+|---|---|
+| `NoFontError` (a `ValueError`, `vec_io.text.NoFontError`) | text with no outline font available at all ([fonts](#1-conventions)) |
+| `ValueError` | unknown settings or invalid values; mismatched data lengths; grids whose ids are not rectangles; ids outside the grid or taken; a full `rows` × `cols` arrangement; `width` with `plot_width`; a grid `layout` with `rows`/`cols`; ratios of the wrong length; mixed category and numeric series on an axis; limits outside a scale's domain; a colorbar without a mapped source, or of a `ColorMap`; `color_map`, `color_limits` or `color_scale` with a shared `color_axis`; shared color axes with different limits or scales; heatmap value labels on more than 2,500 cells; unknown formats or output options, or options of another format (`dpi` for a PDF, `compress` for an image); unknown bin rules or decreasing bin edges; negative pie values; pies with axis series on one plot; `axline` slopes on non-linear axes; decoration positions that are not categories of a category axis |
+
+## 12. Modules
+
+`pl.__all__` (51 names) is the API. These modules are public too:
+`plot_io.styles` (`pl.styles`: `names`, `settings`, `register_style`, `set_style`,
+`use_style`), `plot_io.genome` (`parse_region`, `Region`), `plot_io.markers`
+(`marker_path`, `marker_area`), `plot_io.color.palettes` (`PALETTE`), and the modules of
+the types calls return: `plot_io.facets` (`FacetSet`, `LayerSet`), `plot_io.tables`
+(`SeriesGroup`), `plot_io.colorbar` (`Colorbar`). The others are internal: their names
+may change in any release.
+
+| Module | Role |
+|---|---|
+| `settings.py` | `Setting`, `Settings` (validation, the cascade, explain), class rules and `"auto"` rules, keyword routing, validators |
+| `groups.py` | setting groups (`Font`, `TextStyle`, `Stroke`, `Marker`, `FillStyle`, `NumberFormat`) and their embedding under a prefix |
+| `defaults.py`, `units.py` | `DEFAULTS`; units, `var()`/`calc()`/`inherit`, `%` referents, `explain` traces |
+| `spec.py` | a render's specs (the model resolved once, frozen), layout boxes, palette colors and trained color and size axes |
+| `figure.py`, `plot.py` | `Figure` (arrangement, tracks layout, figure axes, sizes, output), `Plot`, `Title`, `Legend` |
+| `rows.py` | row labels in a band left of the plots, groups of rows (`FigureGroup`), lines and bands through rows (`FigureVLine`, `FigureVSpan`) |
+| `axis.py`, `scales.py`, `limits.py`, `ticks.py` | axes, scale functions, limits syntax, tick choice and labels |
+| `states.py` | the render's state of each plot: calls, palette, axes and their limits, legend, colorbars |
+| `layout.py`, `geometry.py` | the box model: bands measured around each plot's axes, the grid solved in rounds, the frozen geometry (`layout.layout(fig, fonts)`: text shaped with a font database, no canvas) |
+| `render.py` | drawing from the geometry; the page of a px document and its outputs (`doc.to_bytes`, `page.render(…).encode`) |
+| `mapped.py` | color and size axes (`ColorAxis`, `SizeAxis`): own and shared axes of series, their training |
+| `legend.py`, `colorbar.py` | legend (with size keys) and colorbar: measured, placed, drawn |
+| `layers/` | plot types as layers: `base.py` (`Series`, the model of a call; `data=`/`group=`), `core.py` (`Layer`, `Call`, `Table`), `stats.py` (columns from data), `positions.py` (stack, dodge, jitter, swarm, packing), `geoms.py` (the eight geoms: extent, drawing, legend symbol, occupancy, hit area), `pipeline.py` (calls per plot, palette training), `paint.py` (colors, mapped values, markers), `context.py` (drawing context, the x↔y swap); `register_layer` |
+| `presets/` | the plot types (`Scatter`, `Box`, …): settings, and the layers each draws; error bars |
+| `labels.py`, `shapes.py`, `seams.py` | value labels, bulk rectangles and polygons, seams between touching outlines |
+| `stats.py` | bins, densities, contours, LOWESS and swarm layout, adapted to plot_io's needs |
+| `kernels.py`, `_native/` | the numeric kernels (statistics, scaling, gathering) and their C library `plio`: sources, built binaries, bindings generated from `src/plio_api.h` (see `_native/README.md`) |
+| `decorations.py` | reference lines, spans, text and annotations |
+| `color/` | colors: `values.py` (the `color` validator, named color scales, palette references, alpha, saturation, luminance), `palettes.py` (palettes: the discrete colors series take in turn; registry, ggplot2's hues), `maps.py` (`ColorMap`: the gradients of color axes and the palette indices or positions of heatmap cells, evaluated in plot_io's C library), `data.py` (bundled map and palette colors) |
+| `sizemaps.py` | `SizeMap`: the diameters of size axes |
+| `markers.py`, `lines.py`, `text.py` | marker shapes, line dash styles, one-line text through `vec_io.text`: shaped lines (memoized in the font database, rich content per render), placed runs drawn as shaped, the title's paragraphs |
+| `styles/` | style registry and expansion; bundled styles (point libraries in `pt`) |
+| `values.py`, `density.py` | values given to `color`/`size` and their rules; `Density` (point density) |
+| `tables.py`, `facets.py` | columns of tables, `group=` splitting (`SeriesGroup`); `facet`, `FacetSet`, `LayerSet` |
+| `sharing.py`, `times.py` | shared axes; dates and times on axes |
+| `genome/` | genome tracks: `layout.py` (`Tracks`, the `Track` preset), `scale.py` (the genome scale: tick labels, label, origin), `tracks.py` (`BigWig`, `Bed`, `Genes`, `Gtf`, `HiC`: layers over stats `region_signal`, `intervals`, `contact_matrix`; registered layers), `sources.py` (reading readers by their methods), `regions.py`, `pack.py` (rows of intervals) |
+| `_backend.py` | the vec_io calls plot_io relies on (buffer intake, font databases shared between renders, path areas) |