plot-io 0.7.0__tar.gz → 0.9.0__tar.gz

{plot_io-0.7.0 → plot_io-0.9.0}/API.md

@@ -19,20 +19,24 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
 
 * **Model.** A `Figure` holds plots (and colorbars) in a grid, and titles; a `Plot` holds
   series, two axes, titles, 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
+  computed until the figure is drawn (`save`, `write`, `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).
+  the setting (with the nearest valid name; `alpha=` names `opacity=`).
 * **Inheritance.** Settings marked *inherited* in the tables (font, line width, palette,
-  alpha, `rasterize`, `simplify`) are looked up series → plot → figure → style.
+  `opacity`, `rasterize`, `simplify`) are looked up series → plot → figure → style.
+* **Shorthands.** A setting has one full name and at most one shorthand; marker names have
+  shorthands too ([shorthands](#shorthands)). Giving a shorthand with its full name is an
+  error.
+
 * **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
+  joins), `Marker`, `FillStyle` (`fill`: on, off or a color; `fill_opacity`) 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`,
@@ -40,9 +44,10 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `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, …),
+* **Defaults.** Every default is in one read-only mapping, `pl.DEFAULTS`
+  (`plot_io/defaults.py`), the `"default"` style that ends every figure's
+  [style chain](#10-styles); 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
@@ -59,20 +64,25 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   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).
+     figure's axis of that role (`fig.x_axis(…)`); for a series' own color or size axis,
+     the series' `color_scale`, `color_limits`, … ;
+  2. each style of the figure's chain, nearest first: its key for the object's class,
+     then for its base classes (`"Series.opacity"` reaches every series), stopping at a
+     class that has a default of its own, then its key for the setting's group
+     (`"Marker.size"`). A rule of the class, a default it computes from the model (a
+     track's axis lines from its content, the width, spacing, columns and shared x of
+     tracks), comes after the keys of its class and of more specific ones
+     (`"Track.spines"`, `"Figure.width"`) and before those of its base classes
+     (`"Plot.spines"`);
+  3. for inherited settings, the parent's value;
+  4. the class default, then the group default (first, when it refers to the parent's
+     value with `inherit`);
+  5. for inherited settings, the bare name: the nearest style's, else `DEFAULTS`'.
+
+  Within one style, or within `DEFAULTS`, an owner's key 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, in
+  front of `DEFAULTS`. See [Styles](#10-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
@@ -86,8 +96,17 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `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 384
-  four. A dpi up to 16 is a multiple of 96: `dpi=2` is 192. PDF pages are sized in pt (× 0.75).
+  PDF pages are sized in pt (× 0.75).
+* **Resolutions.** A dpi is dots per inch: a number (`150`, `16`), or a multiple of 96
+  written `"2x"` (192 dpi), wherever a resolution is taken (`dpi`, `default_dpi`,
+  `rasterize`, `simplify`, `flatten`'s `dpi`). Images are `dpi` pixels per inch (the
+  figure's `default_dpi`, `"4x"`, when an output gives none): `96` gives one image pixel per
+  px, `"4x"` four.
+* **Opacity and alpha.** `opacity` (and `fill_opacity`, `band_opacity`, `frame_opacity`,
+  `glyph_opacity`, `opacity_range`) multiplies what is drawn; alpha is the alpha channel of
+  a color (`"#rrggbbaa"`, `"rgb(… / 0.5)"`), kept and multiplied by the opacity. `fill` is
+  `True` (the owner's color), a color or `False`; its opacity is `fill_opacity`, for a
+  color too, as in SVG (`fill="red", fill_opacity=1` for an opaque red fill).
 * **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`.
@@ -128,8 +147,9 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   `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
+  the first family of `font_family` that is available (the `fonts` setting or output
+  option, a vec_io `Fonts`: its `dirs`, then `VEC_IO_FONT_DIRS`, then installed fonts unless
+  `system=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
@@ -141,11 +161,41 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   multiple of the font size; default 1), the glyphs centered in it, so the gaps around
   text do not change with the font; `"normal"` takes the font's ascent and descent.
 * **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.
+  (`ColorAxis`, `SizeAxis`, `ColorMap`, `SizeMap`, `Palette`, `Density`, `Errors`,
+  `Span`), `facet`, `registry` (below), `Series`, `set_style`, `use_style` and `DEFAULTS`;
+  see [modules](#12-modules) for the rest. Enum-like settings take strings.
+* **Registries.** `pl.registry` groups the named things: `registry.color_maps`,
+  `palettes`, `markers`, `styles` and `layers` (plot types), each with `add(name, value)`,
+  `names()` and `get(name)` (`ValueError` for an unknown name) and `name in registry.…`.
+* **Guides.** Titles, legends and colorbars follow one pattern. A figure has
+  `fig.add_title`, `fig.add_legend` and `fig.add_colorbar` (in the lanes beside a set of
+  plots, `side=`) and `fig.colorbar_area` (a colorbar in its own grid area); a plot has
+  `p.add_title`, `p.add_legend` (the plot's legend, `p.legend`) and `p.add_colorbar`
+  (attached, `side=`); `fig.plot(legend=…, colorbar=…)` calls them for the common case.
+
+### Shorthands
+
+`settings.ALIASES` (setting names, on every class with the full setting) and
+`settings.MARKER_ALIASES` (marker names):
+
+<!-- settings:shorthands -->
+| Shorthand | Stands for |
+|---|---|
+| `c=` | `color=` |
+| `s=` | `size=` |
+| `cmap=` | `color_map=` |
+| `smap=` | `size_map=` |
+| `marker="o"` | `"circle"` |
+| `marker="s"` | `"square"` |
+| `marker="d"` | `"diamond"` |
+| `marker="^"` | `"triangle_up"` |
+| `marker="v"` | `"triangle_down"` |
+| `marker="<"` | `"triangle_left"` |
+| `marker=">"` | `"triangle_right"` |
+| `marker="+"` | `"plus"` |
+| `marker="x"` | `"cross"` |
+| `marker="triangle"` | `"triangle_up"` |
+<!-- /settings -->
 
 ### Values
 
@@ -159,7 +209,7 @@ 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)")
+p.add_legend(pad="calc(1em - 2px)")
 fig.set(vars={"accent": "#c00"})                   # custom variables, read by var(--name)
 ```
 
@@ -178,7 +228,7 @@ fig.set(vars={"accent": "#c00"})                   # custom variables, read by v
 
 * **`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
+  parent's value of the same setting (`opacity="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()`.
@@ -225,8 +275,9 @@ What `%` of a length can be of, besides another setting (the tables name it per
 #### 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.
+`"FillStyle.fill_opacity"` sets the opacity of every series fill (bars, boxes, violins,
+pies, densities, contours, genome signals and intervals); `"Marker.fill"` turns every
+marker fill on or off.
 
 <!-- settings:groups -->
 | Group | Member | Under a prefix `{p}` | Default |
@@ -253,8 +304,10 @@ contours, genome signals and intervals); `"Marker.fill"` every marker fill.
 | `Marker` | `edge_color` | `{p}edge_color` | 'auto' |
 | `Marker` | `edge_width` | `{p}edge_width` | 0.5 |
 | `Marker` | `fill` | `{p}fill` | True |
+| `Marker` | `fill_opacity` | `{p}fill_opacity` | 1.0 |
 | `Marker` | `size_basis` | `size_basis (never prefixed)` | 'area' |
 | `FillStyle` | `fill` | `{p}fill` | — |
+| `FillStyle` | `fill_opacity` | `{p}fill_opacity` | — |
 | `NumberFormat` | `decimal_separator` | `{p}decimal_separator` | inherited |
 | `NumberFormat` | `thousands_separator` | `{p}thousands_separator` | inherited |
 | `NumberFormat` | `minus` | `{p}minus` | inherited |
@@ -281,7 +334,7 @@ fig.add_title(text, plots=None, side="top", **settings)   # another, over plots
 fig.add_legend(plots=None, side="right", **settings)      # a legend of plots' entries
 fig.x_axis(**settings)                   # settings of every plot's x axis (fig.y_axis: y)
 fig.add_colorbar(source=None, plots=None, side="bottom", **settings)  # beside plots
-fig.colorbar(source, id=None, **settings)    # the guide of a color axis, in its own area
+fig.colorbar_area(source, id=None, **settings)   # a color axis' guide 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")
@@ -353,14 +406,17 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 ### 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's titles and (on top)
-  the plot's `space_above`; outermost on the left, the row label band and the band of
-  [group](#rows) letters, 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 titles past everything on
-  their side; only twin axes are drawn at the axes edge.
+  axes outward: tick marks, tick labels, the axis label, twin axes, the y axis' ×10ᵏ
+  offset (on top, past the x axis and twin x axes there), an outside legend, attached
+  colorbars, the plot's titles and (on top) the plot's `space_above`; outermost on the
+  left, the row label band and the band of [group](#rows) letters, 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 or axis label). 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 titles past
+  everything on their side; only twin axes are drawn at the axes edge. An axis label
+  (a string) longer than the plot's box along its axis (the axes and the other axis'
+  ticks and tick labels) wraps at spaces to that length.
 * **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
@@ -452,7 +508,7 @@ fig.add_title("Batch 1", plots=[a, d], side="left")
 |---|---|---|
 | `text` | — | Title text: a string or rich content; `\n` starts a line. |
 | `side` | 'top' | `top`, `bottom`, `left` or `right`. |
-| `align` | 'center' | Alignment along the side: `start`, `center`, `end` (`left` and `right`: `start` and `end`); along the left and right sides, `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
+| `align` | 'center' | Alignment along the side: `start`, `center`, `end`, or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right; there `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
 | `over` | 'axes' | Span it is aligned and wrapped within: from the first to the last axes of its plots, their boxes, or the whole figure. |
 | `rotation` | 'auto' | `auto`: 0 on top and bottom, 90 on the left (reads upward), −90 on the right (reads downward); or 0, 90, −90. |
 | `pad` | '0.5em' | Gap between the title and the plots. Length. |
@@ -553,7 +609,7 @@ FigureVLine:
 | `color` | '#4d4d4d' | Line color. |
 | `line_width` | inherited (0.5) | Line width. Length. |
 | `line_style` | 'dashed' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 
 Groups: `Stroke`.
 <!-- /settings -->
@@ -564,7 +620,7 @@ FigureVSpan:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#e5e5e5' | Fill color. |
-| `alpha` | 1.0 | Opacity. |
+| `opacity` | 1.0 | Opacity. |
 <!-- /settings -->
 
 FigureGroup:
@@ -613,9 +669,10 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
   call goes to each series alike) and `share_size` (default `"all"`: one size axis, so
   one size key) and `share_legend` (default `"all"`: one legend for the panels' entries,
   on the right, [figure legends](#figure-legends)).
-* **Colorbar.** `colorbar="right"`, `"left"`, `"top"` or `"bottom"` adds a column (or a
-  row, with a horizontal colorbar) to the grid, holding the colorbar of the first call that maps
-  colors (`panels.colorbar`): the guide of the panels' shared color axis.
+* **Colorbar.** `colorbar="right"`, `"left"`, `"top"` or `"bottom"` adds the colorbar of
+  the first call that maps colors (`panels.colorbar`, a
+  [figure colorbar](#colorbars) over every panel, `fig.add_colorbar`) on that side: 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)`.
@@ -632,15 +689,16 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
 | `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. |
+| `width` | '150px' | Width of the `reference` box: one cell's axes, one cell's plot, or the figure; a paper size names its width (`"a4"`, `"letter"`, `"a4-landscape"`). Length. |
+| `height` | 'calc(var(width) / var(aspect_ratio))' | Height of the `reference` box (a paper size: its height). 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` | 384.0 | Resolution of PNG, JPEG, JPEG XL and AVIF output: `96` gives one image pixel per px, the default `384` four; 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. |
+| `background` | 'white' | Figure background, default the style's (white); `"none"` or `"transparent"`: transparent (white in JPEG, which has no transparency). `None` unsets it. |
+| `fonts` | — | Where fonts come from: a vec_io `Fonts` or a dict of its fields (`dirs`, `system`, `downloads`: `True`, `False` or `"cache"`, `db`); unset: `VEC_IO_FONT_DIRS`, installed fonts and `VEC_IO_FONT_DOWNLOADS` (downloads on by default). |
+| `default_dpi` | '4x' | Resolution of PNG, JPEG, JPEG XL and AVIF output when `save`/`write` give no `dpi`: dots per inch, or a multiple of 96 (`"2x"` is 192); `96` gives one image pixel per px, the default `"4x"` four. PDF, EPS and SVG output never use it. |
+| `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 PDF and SVG output (stored as JPEG); `"lossless"` (not JPEG); `"auto"`: 90 for PNG and JPEG, lossless for JPEG XL, AVIF and PDF content. |
 | `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. |
@@ -661,7 +719,7 @@ panels. `wrap` wraps `col` alone into rows of that many panels. Panels are title
 | `text_color` | inherited ('black') | Text color. |
 | `line_width` | inherited (0.5) | Default line width. Length. |
 | `palette` | inherited ('tab10_custom') | Colors of series without one. |
-| `alpha` | inherited (1.0) | Default opacity of series. |
+| `opacity` | 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. |
@@ -679,17 +737,21 @@ Groups: `Font`, `NumberFormat`.
 ## 3. Plots
 
 ```python
-pl.Plot(figure=None, id=None, **settings)   # title="…", x_axis={…}, y_axis={…}
+pl.Plot(figure=None, id=None, **settings)   # title=, x_axis={…}, y_axis={…}, legend=, colorbar=
 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.box(values, **s)     p.heatmap(values, **s)   p.dots(color, size=None, **s)
+p.title(text, **s)     p.x_axis(label, **s)     p.y_axis(label, **s)
 p.add_title(text, side="top", **s)              # another title, returned
+p.add_legend(position=None, **s)                # the plot's legend (p.legend), returned
+p.add_colorbar(source=None, side=None, **s)     # an attached colorbar, returned
 p.series   p.titles   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":
+`p.title`, `p.x_axis` and `p.y_axis` are objects; calling one sets its settings and
+returns it (`p.legend` is set by `p.add_legend`, or `p.legend.set`). At creation (and in
+`p.set`), `title=` sets the title text, `x_axis={…}`, `y_axis={…}` set the axes' settings,
+`legend=` (a position, a dict of legend settings or `False`) calls `add_legend` and
+`colorbar=` (`True`, a side or a dict of colorbar settings) `add_colorbar`: `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.
 
@@ -718,7 +780,7 @@ axes clip.
 | `text_color` | inherited ('black') | Text color. |
 | `line_width` | inherited (0.5) | Default line width. Length. |
 | `palette` | inherited ('tab10_custom') | Colors of series without one. |
-| `alpha` | inherited (1.0) | Default opacity of series. |
+| `opacity` | 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. |
@@ -754,12 +816,17 @@ nearest the axes on top and on the left and right, the first at the bottom. Left
 read upward, right titles downward (`rotation="auto"`); `rotation=0` sets them
 horizontal, beside the axes.
 
+`align` takes the vocabulary of figure legends and colorbars: `start`, `center`, `end`, or
+an end by name. On top and bottom, `start` is the left end (`left`, `right` name the
+ends); on the left and right, `start` is where the text begins (the bottom for text
+reading upward, else the top) and `top`, `bottom` name the ends.
+
 <!-- settings:Title -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `text` | — | Title text: a string or rich content; `\n` starts a line. |
 | `side` | 'top' | `top`, `bottom`, `left` or `right`. |
-| `align` | 'center' | Alignment along the side: `start`, `center`, `end` (`left` and `right`: `start` and `end`); along the left and right sides, `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
+| `align` | 'center' | Alignment along the side: `start`, `center`, `end`, or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right; there `start` is where rotated text begins (the bottom at 90, the top at −90 and 0). |
 | `over` | 'axes' | Span the title is aligned within: the axes, or the axes and the axis labels beside them (the y axis' on top and bottom, the x axis' on the left and right). |
 | `rotation` | 'auto' | `auto`: 0 on top and bottom, 90 on the left (reads upward), −90 on the right (reads downward); or 0, 90, −90. |
 | `pad` | 5.0 | Gap between the title and what it covers. Length; `%`: of the axes height. |
@@ -784,21 +851,29 @@ Groups: `TextStyle`, `Font`.
 
 ### Legend
 
+```python
+p.add_legend("top_left", frame=True)          # the plot's legend, p.legend; returns it
+fig.plot(legend="outside_right")              # the same, when the plot is made
+```
+
 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).
+`orientation` or `columns` is set. Outside the axes, without `columns`, entries wrap
+within the axes' length along their side: into rows as wide as the axes on top and
+bottom, into columns as tall as the axes on the right.
+
+**Size keys in the legend.** A series whose `size` goes through a
+[size axis](#6-color-and-size-axes) has a size key, the axis' guide: by default a key
+like a colorbar's ([size keys](#size-keys)); with `size_key="legend"`, rows in 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 axis'
+`ticks`, else 3–5 nice numbers inside its limits; in its `tick_format`). 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.
@@ -817,7 +892,7 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 <!-- 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`. |
+| `position` | 'auto' | `auto`, `top_right`, `top_left`, `bottom_right`, `bottom_left`, `top`, `bottom`, `center_right`, `center_left`, `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. |
@@ -828,8 +903,8 @@ candidate covers more than 2 % marked cells; else the candidate covering the few
 | `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. |
+| `frame_opacity` | 1.0 | Opacity of the frame and background. |
+| `glyph_opacity` | — | 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. |
@@ -871,7 +946,8 @@ error naming it).
   entries shows no legend. A plot whose `legend.position` is set keeps its legend whole
   (the figure legend shows its entries too).
 * **Place.** `side` (`top`, `bottom`, `left`, `right`) and `align` along the side
-  (`start`, `center`, `end`) within the axes of its plots, kept within the figure; the
+  (`start`: the left or top end, `center`, `end`; or `left`, `right` on top and bottom,
+  `top`, `bottom` on the left and right) within the axes of its plots, kept within the figure; the
   figure grows when the legend is longer than its content. On top and bottom, entries
   are side by side in rows as wide as the span (unless `columns` is set); on the left and
   right, in a column (`columns`).
@@ -893,7 +969,7 @@ Figure legends have the settings of plot legends but `position`, `orientation`,
 | Setting | Default | Meaning |
 |---|---|---|
 | `side` | 'right' | `top`, `bottom`, `left` or `right` of its plots. |
-| `align` | 'center' | Alignment along the side: `start` (left, or top), `center`, `end` (right, or bottom). |
+| `align` | 'center' | Alignment along the side: `start` (left, or top), `center`, `end` (right, or bottom), or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right. |
 | `order` | — | Place in its side's lanes, as figure titles' `order`: lower is nearer the plots. |
 | `pad` | 5.0 | Gap between the legend and the plots. Length. |
 | `title` | 'auto' | Legend title; `"auto"`: the `group` column name of its plots' series, if any. |
@@ -931,7 +1007,7 @@ HLine:
 | `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. |
+| `opacity` | 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. |
@@ -948,7 +1024,7 @@ AxLine:
 | `line_width` | inherited (0.5) | 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. |
+| `opacity` | 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. |
@@ -967,7 +1043,7 @@ HSpan:
 | `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. |
+| `opacity` | 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. |
@@ -996,7 +1072,7 @@ Text:
 | `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. |
+| `opacity` | 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. |
@@ -1083,9 +1159,13 @@ grid only when its axis asks). `p.save` includes its twins.
 
 * `"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.
+* `"lo/hi"`: each side `min`, `max` (any case), a number, an ISO date or time, or `q:F`
+  (quantile F of the axis's values): `"0/max"`, `"q:0.01/q:0.99"`,
+  `"2024-01-01T10:00Z/2024-02-01"`. Or `(lo, hi)`, `None` meaning automatic.
+* A single value is widened by ±0.5 in position space; a single time by one unit of its
+  data each side (a day at midnight, else an hour, a minute, a second).
+* `invert=True` reverses the axis; so do limits given high to low, `(2, 0)` (with
+  `invert=True` too, the axis is reversed once).
 * `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
@@ -1147,7 +1227,7 @@ grid only when its axis asks). `p.save` includes its twins.
 | `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. |
+| `invert` | False | Reverse the axis (limits given high to low, `(2, 0)`, reverse it too). |
 | `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. |
@@ -1211,7 +1291,7 @@ Groups: `TextStyle` (`label_`), `Stroke` (`tick_`), `TextStyle` (`tick_label_`),
 
 ## 5. Series
 
-All series take `name`, `alpha`, `z`, `rasterize` and `simplify` (see [Output](#8-output)).
+All series take `name`, `opacity`, `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.
 
@@ -1226,7 +1306,7 @@ with several value sets (histograms, densities, areas, pies) take one per set.
   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
+* **New types.** `pl.registry.layers.add(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
@@ -1240,10 +1320,21 @@ with several value sets (histograms, densities, areas, pies) take one per set.
   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.
+  values stack apart; `stack="normalize"` divides each position by its total. Stacked
+  densities share one grid (the union of their spans).
+* **Fill and opacity.** `fill` turns a series' fills on (`True`: their own colors, or a
+  color) or off (`False`) on every plot type that fills, and `fill_opacity` is their
+  opacity; `opacity` is the opacity of the whole series (fills, lines and outlines),
+  multiplying `fill_opacity`.
 * **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.
+  regressions compute their data once (in C, by plot_io's kernels) and keep it while
+  the settings they read resolve to the same values (a style change recomputes it);
+  `series.stats` exposes it. On an axis with a scale they are computed in the axis'
+  space: bins are even there, and densities (`hist` and `hist2d` `stat="density"`,
+  `kde`, `violin`, 2-D `kde`) are per axis unit (on a log axis, per log unit), so a
+  histogram and a density of the same data agree. Degenerate data draw nothing (an
+  empty set, all NaN) or, for a density without a bandwidth (one value, all equal), no
+  curve and a warning; a violin of one value is a line at 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`
@@ -1277,7 +1368,7 @@ p = pl.Plot(data=df); p.scatter("a", "b")       # data inherited by the plot's s
 `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`,
+a positional data argument or in `color`, `edge_color`, `size`, `opacity`, `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
@@ -1287,14 +1378,26 @@ the colorbar label to the `color` column, the legend title to the `group` column
 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).
+value in `x` (`y` when horizontal). [Dots](#dots) take one row per cell.
+
+```python
+t = pl.group_summary(values, groups, names=None, threshold=0.0, mean="all")
+p.dots(data=t, x="name", y="group", color="mean", size="fraction", size_limits="0/1")
+```
+
+`group_summary` summarizes an observations × variables matrix (rows: observations; a 2-D
+buffer or a list of rows) per group: columns `group`, `name` (the variable; default its
+index), `mean` and `fraction` (the share of the group's observations above `threshold`).
+`mean="expressed"` averages only the observations above `threshold` (none: a missing
+mean). Groups in order of first appearance (a categorical: its order); missing labels are
+left out.
 
 ### 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)
+g["a"].set(color="black"); g.set(opacity=0.6)
 ```
 
 `group` takes a label per point. The call returns a `SeriesGroup`, a list of one series per
@@ -1322,7 +1425,7 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 * `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'
+  `Errors(values, color=None, line_width=None, cap_length=None)` (cap: the series'
   `cap_length`, else 4 px).
 
 <!-- settings:Scatter -->
@@ -1333,7 +1436,8 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `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.5 | 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. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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. |
@@ -1343,11 +1447,11 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `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). |
+| `size_key` | 'key' | With mapped sizes: a key attached to the plot, as a colorbar's (`"key"`), sample rows in the legend (`"legend"`), none (`False`), or the values to show (a list: a key with a marker at each). |
 | `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`. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `opacity_range`. |
+| `opacity_range` | (0.2, 1.0) | Opacities of the least and most dense points when `opacity` is a density. |
+| `x_error` | — | Horizontal error bars: a value, a sequence, `(low, high)` or `Errors`. |
 | `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. |
@@ -1376,7 +1480,7 @@ 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_map`, `color_limits`, `color_scale`, `color_axis`; `p.add_colorbar(line)`), as
 `color` does on Scatter; the line keeps `color`, and the legend's marker takes the
 gradient's middle color.
 
@@ -1404,7 +1508,8 @@ gradient's middle color.
 | `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.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. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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. |
@@ -1415,7 +1520,7 @@ gradient's middle color.
 | `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. |
+| `opacity` | 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`. |
@@ -1448,7 +1553,7 @@ each side in its color).
 |---|---|---|
 | `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. |
+| `opacity` | '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). |
@@ -1493,7 +1598,7 @@ category.
 | `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.5 | Outline width. Length. |
+| `edge_width` | 'var(line_width)' | 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. |
@@ -1505,7 +1610,8 @@ category.
 | `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`. |
+| `fill` | True | Fill: `True` (the box's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (lines keep `opacity`). |
 | `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`). |
@@ -1518,10 +1624,11 @@ category.
 | `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. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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. |
+| `opacity` | 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`. |
@@ -1567,7 +1674,7 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 | `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. |
+| `opacity` | 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`. |
@@ -1589,13 +1696,80 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 Groups: `TextStyle` (`value_label_`), `Font`, `NumberFormat`.
 <!-- /settings -->
 
+### Dots
+
+```python
+pl.Dots(color=None, size=None, x=None, y=None, plot=None, **settings)
+p.dots(mean, size=fraction, x=genes, y=clusters, cmap="magma", size_limits="0/1")
+p.dots(data=table, x="gene", y="cluster", color="mean", size="fraction")
+```
+
+One dot per cell of a grid (a dot plot): `color` and `size` are 2-D grids of values (row
+0 first) of one shape, or one value (a color, a diameter). `x`/`y` label the columns and
+rows, as a heatmap's: labels (category axes), `None` (indices), centres or edges. Values
+always map: colors through the series' [color axis](#6-color-and-size-axes) (a colorbar
+by default), sizes through its size axis (`size_map` `(0, 12)` px and `size_limits`
+`"0/max"`: area ∝ value; fractions: `"0/1"`) and its [size key](#size-keys), on the
+colorbar's line when both fit. A missing size leaves the cell empty; a missing color
+takes the map's `bad`.
+
+* **Long data.** `x`, `y` and `color`/`size` per cell (columns with `data=`, or
+  sequences), one row per cell; two rows for one cell are an error, cells without a row
+  get no dot. Categories in order of first appearance (pandas or polars categoricals:
+  theirs); `x_categories=`/`y_categories=` lists select and order them.
+* **`scale_color`.** `"rows"` / `"columns"` rescales color values to 0–1 in each row or
+  column before mapping (one variable's range per column).
+* **Cells.** The axes' width (`Figure(width=…)`) sets the space per column; rotated
+  labels closer than `category_label_spacing` are thinned out. `data_ratio=1` on the plot
+  makes cells square.
+
+<!-- settings:Dots -->
+| 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.5 | Outline width; 0: no outline. Length. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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` | (0.0, 12.0) | The sizes numbers in `size` are drawn with: a `SizeMap` (alias `smap`); without it (or `size_axis`), numbers are sizes in px. |
+| `size_limits` | '0/max' | 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_key` | 'key' | With mapped sizes: a key attached to the plot, as a colorbar's (`"key"`), sample rows in the legend (`"legend"`), none (`False`), or the values to show (a list: a key with a marker at each). |
+| `scale_color` | — | `rows` / `columns`: color values rescaled to 0–1 in each row or column before mapping; unset: as given. |
+| `origin` | 'top' | `top`: row 0 at the top (y axis inverted); `bottom`: at the bottom. |
+| `colorbar` | True | Attach a colorbar to the plot (with color values). |
+| `name` | — | Legend entry; unset: not in the legend. |
+| `opacity` | 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 ('Helvetica, Nimbus Sans, Arial, Liberation Sans, Arimo') | 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`. |
+| `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
+| `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
+
+Groups: `Marker`, `Font`.
+<!-- /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"`).
+`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_opacity` is the opacity of the bars' fill (`fill`: a color in place of theirs); `error` adds error bars at the bar ends. Value axes include 0 (`include_zero="auto"`).
 
 <!-- settings:Bar -->
 | Setting | Default | Meaning |
@@ -1605,9 +1779,10 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `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_color` | 'series' | Outline color: a color, `"series"` (each bar's own color, at `opacity`) 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`. |
+| `fill` | True | Fill: `True` (each bar's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (outlines keep `opacity`). |
 | `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. |
@@ -1617,13 +1792,13 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `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` | — | Error bars at the bar ends: a value, a sequence, `(low, high)` or `Errors`. |
 | `error_color` | '#333333' | Error bar color. |
 | `error_width` | 0.5 | 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. |
+| `opacity` | 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`. |
@@ -1651,7 +1826,7 @@ Groups: `Stroke` (`edge_`), `FillStyle`, `Stroke` (`error_`), `Font`, `NumberFor
 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.
+`values`: one array, or several (a dict, a list of arrays) sharing the bins; dates draw on a time axis. `bins`: a count (at most 10⁶), edges, or numpy's rules (`auto` is numpy 2's; a rule asking for more than 10⁶ bins is an error). Bins are even on the axis scale (`bins_scale="axis"`): on a log axis, in log space; edges or a `range` outside the axis' scale (0 on a log axis) are refused. `stat` turns counts into densities (area 1), probabilities, percents or counts per unit, per unit of the axis' space; `cumulative` accumulates them. Several sets overlay (`fill="auto"`: opacity 0.5), stack (`stack=True`) or dodge (`dodge=True`). Bars have no outline by default (`edge_width` 0). `hist.stats`: `edges`, `counts` and `heights` per set.
 
 <!-- settings:Hist -->
 | Setting | Default | Meaning |
@@ -1659,24 +1834,26 @@ pl.Hist(values, plot=None, **settings)
 | `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). |
+| `stat` | 'count' | `count`, `density` (area 1), `probability`, `percent` or `frequency` (count per unit); densities and frequencies per unit of the axis' space (log axes: per log unit, as `kde`). |
 | `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. |
+| `color` | — | Fill color, one per set (a list, or a dict by set name); default palette colors. |
 | `edge_color` | — | Bar outline color; default none. |
-| `edge_width` | 0.0 | Bar outline width. Length. |
+| `edge_width` | 0.0 | Bar outline width; default 0 (none). Length. |
 | `line_color` | — | Step and outline color; default each set's color. |
 | `line_width` | inherited (0.5) | 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. |
+| `fill` | True | Fill: `True` (each set's color), a color, or `False` (none). |
+| `fill_opacity` | 'auto' | Opacity of the fills, times `opacity` (lines keep `opacity`); `"auto"`: 0.5 for overlaid sets, else 1. |
 | `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. |
+| `opacity` | 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`. |
@@ -1704,7 +1881,7 @@ Groups: `Stroke` (`edge_`), `Stroke` (`line_`), `Font`, `NumberFormat`.
 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`.
+A Gaussian kernel density of each set on a common grid of `points` points, extending `cut` bandwidths past the data (within `range`); dates draw on a time axis. `fill` fills under each curve (`True`, or a color; at `fill_opacity`, 0.25). `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. A set without a bandwidth (no values, one, all equal) or a `range` outside the data has no curve (NaN densities), with a warning. `kde.stats`: `grid`, `densities`, `bandwidths`.
 
 <!-- settings:Kde -->
 | Setting | Default | Meaning |
@@ -1715,15 +1892,16 @@ A Gaussian kernel density of each set on a common grid of `points` points, exten
 | `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). |
+| `fill` | False | Fill under the curve: `True` (its color), a color, or `False` (stacked curves are filled anyway). |
+| `fill_opacity` | 0.25 | Opacity of the fill (0–1). |
 | `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. |
+| `color` | — | Color, one per set (a list, or a dict by set name); default palette colors. |
 | `line_width` | inherited (0.5) | 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. |
+| `opacity` | 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`. |
@@ -1749,8 +1927,9 @@ Density contours of points (seaborn's `kdeplot(x=, y=)`): the 2-D Gaussian densi
 (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,
+n of `levels`, level k (0 … n − 1) encloses 1 − p of the mass, p = `thresh` + (1 −
+`thresh`)·k/(n − 1): the outermost 1 − `thresh`, the last at the density's maximum; 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,
@@ -1759,7 +1938,7 @@ 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. |
+| `levels` | 10 | A number n of iso-proportion levels: level k (0 … n − 1) encloses 1 − p of the mass, p = `thresh` + (1 − `thresh`)·k/(n − 1) (the outermost 1 − `thresh`, the last at the density's maximum); 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. |
@@ -1774,7 +1953,7 @@ labels, colorbar).
 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.
+A step line through the sorted values of each set: `stat` `proportion`, `count` or `percent`; `complementary` plots 1 − F. `color`: one, a list (one per set) or a dict by set name.
 
 <!-- settings:Ecdf -->
 | Setting | Default | Meaning |
@@ -1783,11 +1962,11 @@ A step line through the sorted values of each set: `stat` `proportion`, `count`
 | `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. |
+| `color` | — | Line color, one per set (a list, or a dict by set name); default palette colors. |
 | `line_width` | inherited (0.5) | 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. |
+| `opacity` | 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`. |
@@ -1809,7 +1988,7 @@ Groups: `Stroke`, `Font`.
 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.
+`values` as box plots take them. Each violin is the density of its category, mirrored, in the value axis' space (log axes: in log space); `width_scale` gives equal areas (default), areas proportional to the counts, or equal widths. A category of one value (or all equal) is a line at it, with a warning. `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 |
@@ -1819,11 +1998,11 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | `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.5 | Outline width. Length. |
+| `edge_color` | 'series' | Outline and inner color: a color or `"series"` (each violin's own color, at `opacity`). |
+| `edge_width` | 'var(line_width)' | 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`. |
+| `fill` | True | Fill: `True` (each violin's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (outlines keep `opacity`). |
 | `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. |
@@ -1838,6 +2017,7 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | `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. |
+| `opacity` | 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`. |
@@ -1870,7 +2050,8 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `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.5 | 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. |
+| `fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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. |
@@ -1880,7 +2061,7 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `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). |
+| `size_key` | 'key' | With mapped sizes: a key attached to the plot, as a colorbar's (`"key"`), sample rows in the legend (`"legend"`), none (`False`), or the values to show (a list: a key with a marker at each). |
 | `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. |
@@ -1890,8 +2071,8 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `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. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `opacity_range`. |
+| `opacity_range` | (0.2, 1.0) | Opacities of the least and most dense points when `opacity` 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. |
@@ -1914,21 +2095,23 @@ Groups: `Marker`, `Font`.
 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`.
+Layers (rows of `ys`, a dict `{name: values}`, one legend entry each, or one flat sequence) stacked on `baseline`: `zero`, `sym`, `wiggle` or `weighted_wiggle` (matplotlib's stackplot baselines). `fill_opacity` is the fills' opacity, `opacity` the whole series'. `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. |
+| `color` | — | A color, one per layer (a list, or a dict by layer name); default palette colors. |
+| `fill` | True | Fill: `True` (each layer's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fill, times `opacity` (outlines keep `opacity`). |
 | `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. |
+| `opacity` | 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`. |
@@ -1941,7 +2124,7 @@ Layers (rows of `ys`, or a dict `{name: values}`, one legend entry each) stacked
 | `line_height` | inherited (1.0) | Height of a line of text: a multiple of the font size (`1.2`), a percentage of it, or `normal` (the font's ascent and descent). Text boxes and the gaps around them follow it, with the glyphs centered. |
 | `markup` | inherited (True) | Read markup in strings (`<b>`, `<i>`, `<sup>`, …: see [conventions](#1-conventions)); `False`: strings stay literal. |
 
-Groups: `Stroke` (`edge_`), `Font`.
+Groups: `FillStyle`, `Stroke` (`edge_`), `Font`.
 <!-- /settings -->
 
 ### Errorbar
@@ -1960,7 +2143,8 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | `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.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. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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. |
@@ -1972,10 +2156,10 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | `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. |
+| `band_opacity` | 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. |
+| `opacity` | 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`. |
@@ -2007,7 +2191,8 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 | `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. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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. |
@@ -2020,7 +2205,7 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 | `baseline_width` | 0.5 | 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. |
+| `opacity` | 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`. |
@@ -2042,7 +2227,7 @@ Groups: `Marker` (`marker_`), `Stroke` (`baseline_`), `Font`.
 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.
+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. With fewer distinct x values than `order` + 1, the order is lowered (one distinct x: no fit), with a warning. 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 |
@@ -2058,13 +2243,14 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `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. |
+| `band_opacity` | 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.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. |
+| `marker_fill` | True | `True`: filled with the color; `False`: hollow, outlined in the color. |
+| `marker_fill_opacity` | 1.0 | Opacity of the fill; below 1 the marker is also outlined in its 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. |
@@ -2072,7 +2258,7 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `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. |
+| `opacity` | 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`. |
@@ -2094,7 +2280,7 @@ Groups: `Stroke`, `Marker` (`marker_`), `Font`.
 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.
+Counts in rectangular bins (even on the axis scales), drawn as a heatmap with the heatmap's settings; bins below `min_count` are transparent; `stat="density"` per unit area of the axes' space; a colorbar source.
 
 <!-- settings:Hist2d -->
 | Setting | Default | Meaning |
@@ -2134,7 +2320,7 @@ the axes are not counted. Colored by `cmap`; a colorbar source.
 | `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. |
+| `opacity` | 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`. |
@@ -2162,7 +2348,8 @@ Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `level
 | 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`. |
+| `fill` | False | Fill the bands between levels: `True` or `False`. |
+| `fill_opacity` | 1.0 | Opacity of the bands, times `opacity`. |
 | `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. |
@@ -2172,7 +2359,7 @@ Iso-lines (`lines`) and filled bands (`fill`) of a grid at nodes `x`/`y`. `level
 | `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. |
+| `opacity` | 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. |
@@ -2223,8 +2410,9 @@ Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a pl
 | `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`. |
+| `opacity` | 1.0 | Opacity. |
+| `fill` | True | Wedge fill: `True` (each wedge's color), a color, or `False`. |
+| `fill_opacity` | 0.25 | Opacity of the fills, times `opacity` (outlines keep `opacity`). |
 | `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. |
@@ -2262,7 +2450,7 @@ 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.colorbar_area(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
 ```
@@ -2288,12 +2476,16 @@ fig = pl.Figure(cols=3, share_size="all")           # one size axis, one size ke
   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"`). A figure legend covering every plot of a key takes the key.
+  group, beside its plots as a shared colorbar ([size keys](#size-keys); in the
+  [legend](#legend) with `size_key="legend"`, where a figure legend covering every plot
+  of a key takes it). 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).
+  `under`/`over` colors and missing values its `bad` color (sizes: the `SizeMap`'s);
+  colors outside the scale's domain (0 on a log scale) take the `bad` color too, with a
+  warning naming their count.
 
 Color and size axes have the settings of [axes](#4-axes); these differ:
 
@@ -2314,9 +2506,10 @@ Color and size axes have the settings of [axes](#4-axes); these differ:
 ### Colorbars
 
 ```python
-p.colorbar(source=None, side="bottom", **settings)       # attached to a side of the plot
+p.add_colorbar(source=None, side="bottom", **settings)       # attached to a side of the plot
+fig.plot(colorbar=True)                                  # the same, when the plot is made
 fig.add_colorbar(source=None, plots=None, side="bottom", **settings)   # beside plots
-fig.colorbar(source, id=None, **settings)                # in its own grid area
+fig.colorbar_area(source, id=None, **settings)           # in its own grid area
 fig.colorbars                                            # those of add_colorbar
 cb.axis                                                  # the color axis shown
 ```
@@ -2349,8 +2542,8 @@ the name of the color column or density.
   `values`, the gaps and `label_position` are a key's.
 * **Attached.** A band of the plot's box on its `side` (default `bottom`;
   `orientation="auto"`: horizontal on top and bottom, vertical on the left and right),
-  placed along the side by `align` (`"auto"`: the end on top and bottom, the center on
-  the left and right). On one side, from the axes outward: an outside legend, the
+  placed along the side by `align` (default `center`; `start` is the left or top end, as
+  for figure legends). On one side, from the axes outward: an outside legend, the
   colorbars (by `order`, else in creation order), the titles. A key longer than its axes
   side passes its ends, and the margins there grow.
 * **Lanes.** `fig.add_colorbar` puts a colorbar beside a set of plots (plots or their
@@ -2368,20 +2561,20 @@ the name of the color column or density.
   else on the right. It takes the settings of the first one but its place. An attached
   colorbar whose `side` is set stays, as do those of plots that are not a grid
   rectangle.
-* **Own area.** `fig.colorbar(source, id=…)` is vertical in its grid area (`orientation`):
+* **Own area.** `fig.colorbar_area(source, id=…)` is vertical in its grid area (`orientation`):
   a key placed along it by `align`, a bar running along the neighbouring axes
   (`align="axes"`) or boxes (`"borders"`).
 * `p.save()` (one plot alone) leaves out figure colorbars: the plot's attached colorbars
   show again.
 
 Axis settings given to a colorbar go to its axis:
-`p.colorbar(h, label="z", tick_format="{:.0%}")` sets `h.color_axis`'s tick format.
+`p.add_colorbar(h, label="z", tick_format="{:.0%}")` sets `h.color_axis`'s tick format.
 
 <!-- settings:Colorbar -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `side` | 'bottom' | Side of the plot (or of the plots) it sits on. |
-| `align` | 'center' | Place along its side: `start` (left, or top), `center`, `end` (right, or bottom). |
+| `align` | 'center' | Place along its side: `start` (left, or top), `center`, `end` (right, or bottom), or an end by name: `left`, `right` on top and bottom, `top`, `bottom` on the left and right. |
 | `order` | — | Place among the colorbars of its side: lower is nearer the axes; unset: creation order. |
 | `style` | 'key' | `key`: one line of the limits around a short bar with round ends, then the label; `bar`: a long bar with the axis' ticks. |
 | `orientation` | 'auto' | Direction; `"auto"`: horizontal on top and bottom, vertical on the left and right and in an area of its own. |
@@ -2396,6 +2589,8 @@ Axis settings given to a colorbar go to its axis:
 | `extend` | 'auto' | Ends in the under/over colors: `auto` shows them when the limits clip the data. |
 | `extend_shape` | 'auto' | `dot`: a dot past the key's end; `block`: a separate block at the end (within a bar's length); `triangle`: a triangle past the end; `"auto"`: `dot` on a key, `block` on a bar. |
 | `frame` | False | Outline the bar (and its ends), following its shape. |
+| `count` | 3 | A size key's markers below its high limit (`values="limits"`). |
+| `marker_gap` | '0.4em' | Gap between a size key's markers (edge to edge). Length; `%`: of the font size. |
 | `frame_color` | '#666666' | Outline color. |
 | `frame_width` | 0.5 | Outline width. Length. |
 
@@ -2411,6 +2606,40 @@ Figure colorbars (`fig.add_colorbar`) have the settings of colorbars, and:
 | `pad` | 'auto' | Gap between the colorbar and the plots; `"auto"`: 0.8em on a key, 11 px on a bar. Length. |
 <!-- /settings -->
 
+### Size keys
+
+```python
+p.scatter(x, y, size=w, size_map=(0, 12))           # a size key under the plot
+p.add_colorbar(s.size_axis, side="right", count=3)      # a size key placed by hand
+s.set(size_key=[10, 50, 100])                       # a marker at each value, labelled
+```
+
+A colorbar of a size axis is a size key: a key whose bar is sample markers of increasing
+size, `0%  ·  •  ●  100%  Expressing`. Every series mapping sizes has one by default
+(`size_key="key"`), attached to its plot under the axes, after the plot's colorbars; a
+colorbar of the plot showing the same size axis, or a `fig.size_legend` area, replaces
+it.
+
+* **Markers.** `count` (3) markers at values evenly spaced below the high limit (in the
+  scale's terms), the high limit's own marker left out; when the low limit's size is
+  zero, the first marker is the next value (at 0–1: ¼, ½, ¾).
+  `marker_gap` (0.4em) between their edges; the line is as tall as the largest. The
+  series' marker shape, in grey, or the series' color when one series of one color uses
+  the axis. Vertical (on the left and right): largest at the top.
+* **Values.** The limits at the ends in the axis' `tick_format` (`"percent"` for
+  fractions); `values="ticks"`, or a series' `size_key` list: a marker at each value
+  (the axis' ticks, else 3–5 nice numbers), its value under it (right of a vertical
+  key).
+* **Label**: `label`, else the axis' `label`, else the `size` column name.
+* **One line.** On top or bottom, a horizontal key joins the line of the keys before it
+  on that side when the line still fits the axes width, `2 × label_gap` apart, middle
+  lines aligned: a dot plot's color and size keys side by side.
+* **Shared.** As colorbars: plots sharing a size axis (`share_size`, or one
+  `fig.size_axis()` in two plots or more) get one key beside them, in the lanes.
+* The other settings are a key's (`side`, `align`, `order`, `pad`, `value_gap`,
+  `label_gap`, `label_position`); `style`, `thickness`, `length` and `extend` do not
+  apply.
+
 ## 7. Colors, maps and markers
 
 ### Colors and palette
@@ -2426,8 +2655,8 @@ 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()
+pl.registry.palettes.add(name, palette)     # a Palette, colors or a function
+pl.registry.palettes.names()   pl.registry.palettes.get(name)   # a Palette
 ```
 
 | `Palette` | |
@@ -2464,8 +2693,8 @@ parts: `palette=pl.ColorMap("viridis").to_palette(5)` for ordered categories.
 ```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()
+pl.registry.color_maps.add(name, color_map)
+pl.registry.color_maps.names()   pl.registry.color_maps.get(name)   # a ColorMap ("_r": reversed)
 ```
 
 | Member | |
@@ -2568,8 +2797,8 @@ on the axis positions (log axes in log space); NaN points get NaN. `normalize`:
 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
+`color`, `edge_color`, `size` (through the size axis, default `SizeMap()`), `opacity`
+(mapped linearly to `opacity_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"`.
@@ -2626,39 +2855,58 @@ Inherited settings (figure → plot → axis; series → its color axis):
 | `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.
+Shorthands: `triangle`, `o`, `s`, `d`, `^`, `v`, `<`, `>`, `+`, `x`
+([shorthands](#shorthands)). A `vec_io.Path` or SVG path data in a unit box centred on the
+origin also works. `pl.registry.markers.add(name, path)` adds a shape (its area measured
+from the outline), `pl.registry.markers.get(name)` returns its path; `plot_io.markers.resolve(name)` returns
+its unit path for vec_io's `draw_markers` and its area; `plot_io.markers.marker_area(name)`
+the area.
 
 ## 8. Output
 
 ```python
-fig.save(path, **options)          # .pdf, .eps, .png, .jpg/.jpeg, .jxl, .avif
-fig.to_bytes(format="pdf", **options)
+fig.save(file, *, region=None, format=None, **options)   # .pdf, .eps, .svg, .png, .jpg/.jpeg, .jxl, .avif
+fig.write(kind, *, region=None, **options)                # bytes: "pdf", "eps", "svg", "png", …
 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
+p.save(file, …)   p.write(kind, …)   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:
+`save` writes to a path or a binary file object, in `format` (`"pdf"`, `"eps"`, `"svg"`,
+`"png"`, `"jpeg"`/`"jpg"`, `"jxl"`, `"avif"`) or by the path's extension; a path without
+one of these extensions and no `format` raises `ValueError`, as does a file object without
+`format`. `region` draws a genome region instead of the x axes' (figures and plots).
+
+The figure is drawn once on a page of a vec_io document in px; each output is that
+document written by `vec_io.Document.write` with its options (option objects of
+`vec_io.options`, or dicts of their fields). plot_io reads `quality`, `dpi`,
+`default_dpi`, `background`, `simplify` and `fonts` (below) and passes the others; an option
+of another format (`font_hinting` for PNG) or an unknown one raises vec_io's `OptionError`
+(a `ValueError`). vec_io's `view` and `pages` are refused: a figure's size is its own
+(`width`, `height`, `margin`).
 
 | 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)) |
+| `fonts` | the fonts text is shaped and embedded with ([fonts](#1-conventions)): a vec_io `Fonts` or a dict of its fields (`dirs`, `system`, `downloads`, `db`); default the figure's `fonts` |
 | `text_as_paths` | text drawn as the outlines of its glyphs: no font embedded, text not selectable (default `False`) |
-| `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 and EPS: compressed streams (default) or a readable file; TrueType hinting kept in embedded subsets (default: left out) |
-| `flatten_transparency`, `flatten_fallback`, `flatten_dpi`, `flatten_budget`, `flatten_cell` | PDF: translucent content drawn as opaque vectors (default off), and what cannot be (vec_io's transparency flattening: an image by default); EPS: always flattened, the others tune it |
-| `dpi`, `background` | images: resolution (default 384: four image pixels per px); a color under the figure (default the figure's, white; `None` is transparent, white in JPEG) |
+| `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 or SVG lossless. It goes into `images` (PDF, EPS, SVG) or the format's option (`png`, …) unless a dict there sets its own; an option object is used as given |
+| `compression` | PDF and EPS: `"fast"`, `"balanced"` (default), `"small"`: the encoder's effort for streams and image samples; `None`: uncompressed streams, a readable file. Images: `png={"compression": …}`, … |
+| `simplify` | the figure's `simplify` for this output: every series without its own follows it ([large data](#large-data)) |
+| `font_hinting` | PDF and EPS: TrueType hinting kept in embedded subsets (default: left out) |
+| `flatten` | PDF, EPS and SVG: a vec_io `Flatten` or a dict of its fields (`transparency`, `fallback`, `dpi`, `budget`, `cell`): translucent content drawn as opaque vectors (PDF and SVG: off by default; EPS: always), and what cannot be (an image by default, at `dpi`; a dict's `dpi` takes `"2x"`) |
+| `dpi` | the output's resolution (dots per inch, or `"2x"`: 192). Images: rendered at it. PDF, EPS and SVG: their images (rasterized series, heatmaps drawn as images) resampled to it, by vec_io's `ImagePolicy(dpi=…)`; not given, they are kept as they are |
+| `default_dpi` | images without `dpi`: the resolution, for this call (default the figure's `default_dpi`, `"4x"`: four image pixels per px); PDF, EPS and SVG never use it |
+| `background` | images: the color the figure is drawn on, in place of its `background` (`None`, `"none"`: transparent, white in JPEG); not given, the figure's |
+| `images` | PDF, EPS and SVG: a vec_io `ImagePolicy` or a dict of its fields: `quality`, `jxl`, and with `dpi` `dpi_mode` (`"down"`, default: images finer than `dpi` resampled down; `"match"`: every image to `dpi`), `dpi_threshold` (images within this factor kept, default 1.5), `dpi_average` (shrinking averages the stored values, `"srgb"`, default, or light, `"linear"`) |
+| `png`, `jpeg`, `jxl`, `avif` | that image output: a vec_io `PNG`, `JPEG`, `JXL` or `AVIF` or a dict of its fields (`quality`, `compression`, …) |
 
 EPS output (`.eps`) is vec_io's: one page of PostScript Level 3, its transparency (the
-`alpha` of bands, markers, …) flattened into opaque shapes, with an image where it cannot
-be (dense translucent scatters), and its fonts embedded (Type 42 or CFF). JPEG XL output
+opacity of bands, markers, …) flattened into opaque shapes, with an image where it cannot
+be (dense translucent scatters), and its fonts embedded (Type 42 or CFF). SVG output
+(`.svg`) is vec_io's SVG writer: paths, `<text>` naming the font families (fonts are not
+embedded: the reader needs them, or use `text_as_paths=True`), images as PNG or JPEG data;
+it keeps what the PDF keeps (`simplify`, rasterized series as their images, `quality`). 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
@@ -2669,9 +2917,9 @@ 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.
+colors cannot render well enough stays lossless. The 28 example PNGs total 2.0 MB this way.
+Notebook previews (`_repr_png_`) are lossless, at the figure's `default_dpi`, and shown at the
+figure's size in px.
 
 ### Large data
 
@@ -2688,6 +2936,9 @@ slower). Notebook previews are lossless.
   axes and text stay vectors. Image output draws the group as vectors at its own
   resolution.
 
+Statistics and rasterization run on vec_io's worker threads: `VEC_IO_THREADS` sets their
+number (default: the usable CPUs, at most 8; 1: none). Results never depend on it.
+
 Timings (`tools/bench.py`, 8 threads, PDF written):
 
 | Case | Time |
@@ -2761,8 +3012,9 @@ Details:
   `"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`
+  `Region` (`chr`, `start`, `end`). A region has no strand: a fourth element or a `strand`
+  key is a `ValueError`. A series reads its own `region`, else its x axis'.
+  Data are read when the figure is drawn, for the region drawn: `save`, `write`, `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
@@ -2856,11 +3108,12 @@ t.bigwig(pax7_reader, name="Pax7", color="rose")
 | `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`. |
+| `fill` | True | Fill (to `fill_to`): `True` (the line color), a color, or `False`. |
+| `fill_opacity` | 0.2 | Opacity of the fill, times `opacity`. |
 | `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. |
+| `opacity` | 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`. |
@@ -2889,13 +3142,15 @@ pl.Genes(reader, plot=None, **settings)    # Bed with kind="genes", rows expande
 (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`.
+A score that is not a number (`"."`) is missing (the map's `bad` color); an interval
+ending before it starts, or blocks not matching `blockCount`, are a `ValueError`.
 `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
+with `rows="expand"` packing leaves room for them (their measured width) (`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
+`fill` (`False` for outlines only) at `fill_opacity` (0.3), 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
@@ -2914,7 +3169,8 @@ every feature has the same lightness.
 | `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). |
+| `fill` | True | Fill of the features: `True` (their color), a color, or `False` (outlines only). |
+| `fill_opacity` | 0.3 | Opacity of the fill, times `opacity`. |
 | `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. |
@@ -2922,7 +3178,7 @@ every feature has the same lightness.
 | `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. |
+| `opacity` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `line_width` | inherited (0.5) | Line width. Length. |
 | `text_color` | inherited ('black') | Text color. |
@@ -2947,7 +3203,7 @@ Groups: `FillStyle`, `TextStyle` (`name_`), `Font`.
 | `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). |
+| `fill_opacity` | 1.0 | Opacity of the fill, times `opacity`. |
 
 Groups: `FillStyle`.
 <!-- /settings -->
@@ -2991,7 +3247,8 @@ the cells of a size (`bins="5kb"`) sit on the file's grid, those past the region
 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`.
+`nan_color`, transparent), through the figure's `color_map`. A region without a finite
+positive value draws no cells, its color axis at its default limits.
 
 <!-- settings:HiC -->
 | Setting | Default | Meaning |
@@ -3011,7 +3268,7 @@ to quantiles of the cells drawn (`color_limits="q:0.01/q:0.99"`), on a log scale
 | `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. |
+| `opacity` | 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`. |
@@ -3053,12 +3310,12 @@ 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.registry.styles.add("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)
+pl.registry.styles.names()             # registered names
+pl.registry.styles.get("house")        # every key of the chain, DEFAULTS included
 ```
 
 * **Keys.** Names of inherited settings (`"font_size"`, `"palette"`), `"Class.name"` for
@@ -3073,23 +3330,25 @@ pl.styles.settings("house")            # the resolved dict (base theme included)
   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.
+  `var(--accent)`; a style has no `"Figure.style"` (its bases are `"base"`) or `vars`
+  key. Values are checked when the style is registered or set.
+* **`"base"`.** A style name or a list of names (later ones win over earlier ones); the
+  style's own keys win over its bases. Registered styles use the same form.
+* **Chain.** A figure's style, then its bases (depth first, each once), then `"default"`
+  (`DEFAULTS`). The nearer style wins; within a style, the most specific key wins: a
+  style's `"Marker.size"` beats its base's `"Line.marker_size"`. The order against the
+  object's own values and the parent is the cascade of [conventions](#1-conventions);
+  `explain` names the style a value comes from.
 * **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`.
+  created (`use_style` innermost, else `set_style`), else `"default"`. `DEFAULTS` is
+  read-only and `"default"` cannot be re-registered: change defaults with a style
+  (`pl.set_style({"font_family": "Nimbus Sans Narrow"})`).
 * **`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
+Bundled styles (`pl.registry.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).
@@ -3097,6 +3356,7 @@ color map, default series looks). They never change plot sizes or the minus sign
 | Style | Follows | Variants |
 |---|---|---|
 | `default` | `DEFAULTS` | — |
+| `solid` | solid bars, bar histograms, areas and violins, black-outlined boxes, markers without outline; the base of the library styles | — |
 | `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` |
@@ -3121,14 +3381,13 @@ documented default properties. What cannot be expressed: legend titles naming a
 | 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 |
+| `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 (`background` for a PDF, `font_hinting` 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; dot grids of two shapes, or two rows for one dot cell |
 
 ## 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
+`pl.__all__` (47 names) is the API. These modules are public too:
+`plot_io.registry` (`Registry`, and the registries), `plot_io.genome` (`parse_region`, `Region`), `plot_io.markers`
+(`resolve`, `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`, `FigureColorbar`). The others are internal: their names
 may change in any release.
@@ -3145,7 +3404,7 @@ may change in any release.
 | `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`) |
+| `render.py` | drawing from the geometry; the page of a px document and its outputs (`write`: plot_io's options mapped, `vec_io.Document.write`) |
 | `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` |
@@ -3154,10 +3413,11 @@ may change in any release.
 | `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) |
+| `color/` | colors: `values.py` (the `color` validator, named color scales, palette references, alpha channels, 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`) |
+| `styles/` | styles and their expansion; bundled styles (point libraries in `pt`) |
+| `registry.py` | `pl.registry`: the color map, palette, marker, style and layer registries |
 | `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 |