forgegraph 0.7.0__tar.gz → 0.8.0__tar.gz

{forgegraph-0.7.0 → forgegraph-0.8.0}/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written.
 
+## 0.8.0 (2026-11-07)
+
+### New Features
+
+- **Controls on the HTML page.** Two new layers add controls to a graph's web page. A `choice` layer lists views, such as other columns for a series or a log axis, and readers switch between them with a dropdown or radio buttons. A `toggle` layer adds checkboxes that show or hide series and layers; a series named in a key gets its checkbox in the key. Every view is drawn ahead of time, so the page needs no server, and the graph keeps its size and position as you switch. The controls go to the right of the graph, or above or below it, and the theme sets their text. In a layout, controls of the same name in different panels work together. Saved images show the first view, without the items hidden at first.
+- **Axis limits that leave out outliers.** An axis's `min` or `max` can be `3IQR`, which ends the axis 3 interquartile ranges beyond the quartile, so a few extreme values don't squash the rest of the data.
+- **Geometric statistics.** `geom_mean`, `geom_stddev` and `geom_ci` work wherever the other statistics do: combining points, error bars and reference lines. They suit values that vary by a factor, such as concentrations, and their error bars are longer above the point than below it.
+- **Star and asterisk markers.**
+- **Long titles can wrap.** A theme's `title.max_wrap` lets a title run onto more lines. By default a title doesn't wrap, and one that's too long now gives an error that names it.
+- **Named parts in SVG files.** In an SVG, each series' and layer's parts have ids that start with its name, such as `fg-series-Voltage-1`, so a web page can find them.
+
+### Changes
+
+- **Fewer tick labels when they'd run together.** Automatic ticks on a number axis now space out until their labels fit.
+- **Ticks on an extended axis.** When an axis grows to make room for a key, note or label, its ticks carry on into the new part.
+- **Keys and notes keep clear of reference lines and bands.** Keys, notes and reference labels no longer sit on a reference line, a band, or the edge of a large marker. The axis grows to make room, or the error says what's in the way. Some graphs will place their key differently.
+- **Reference lines past a set limit.** A reference line or band beyond an axis limit you've set is now left out, and lint says so, rather than stopping the graph.
+- **Clearer label errors.** When a reference label at `position: auto` has no room, the error says what's in the way at each place it tried.
+- **The agent skill** knows about the new controls, and its examples are now the ones in the documentation.
+
+### Bug Fixes
+
+- Points and bars beyond a set axis limit still had a hover box on the HTML page. Only what's drawn inside the plot has one now.
+- Cross and plus markers were drawn in black instead of their series' color.
+- After an axis grew to fit a key, a new top tick label could run off the figure.
+
 ## 0.7.0 (2026-11-02)
 
 ### New Features

{forgegraph-0.7.0 → forgegraph-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.7.0
+Version: 0.8.0
 Summary: Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents.
 Project-URL: Repository, https://github.com/sskaye/forgegraph
 Project-URL: Issues, https://github.com/sskaye/forgegraph/issues

forgegraph-0.7.0/src/forgegraph/skill/forgegraph/examples/figure.schedule.yaml → forgegraph-0.8.0/docs/examples/cells.schedule.yaml

@@ -1,11 +1,11 @@
-name: figure
+name: cells
 version: 0
-description: The example layout, rendered every weekday at 06:00.
+description: The cells layout, rendered every weekday at 06:00.
 extends: forgegraph_default/schedule
 
 parameters:          # !var: a schedule that extends it may change it; !fix: it may not; on a category, all in it. Each parameter is tagged here or in the schedule it extends.
     targets:
-        files: [figure.layout.yaml]
+        files: [cells.layout.yaml]
     cadence:
         interval:
             unit: week

forgegraph-0.8.0/docs/examples/passenger_toggles.yaml

@@ -0,0 +1,48 @@
+name: passenger_toggles
+version: 0
+description: Airline passengers in March, July and November of each year, each month and July's mean shown or hidden on the HTML page.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Airline passengers by month
+    data:
+        file: air_passengers_by_month.parquet
+        preprocessing: examples/sample-data/air_passengers_by_month.csv, unchanged
+    axis:
+        x:
+            data:
+                column: Year
+            title: None
+        y:
+            title: Passengers (thousands)
+    series:
+        July:
+            column: Jul
+        March:
+            column: Mar
+        November:
+            column: Nov
+    legend:
+        method: direct
+        key:
+            title:
+                text: None
+    layers:
+        mean:
+            type: reference
+            axis: y
+            line_1:
+                value: Jul
+                aggregation:
+                    function: mean
+                label:
+                    text: aggregation_value
+        show:
+            type: toggle
+            label: Show
+            items: [series, mean]
+            hidden: [mean]

forgegraph-0.8.0/docs/examples/penguin_measures.yaml

@@ -0,0 +1,38 @@
+name: penguin_measures
+version: 0
+description: A penguin measurement against bill length for three species, the measurement chosen on the HTML page.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Penguin measurements
+    data:
+        file: penguins.parquet
+        preprocessing: examples/sample-data/penguins.csv, unchanged
+    axis:
+        x:
+            data:
+                column: bill_length_mm
+            title: Bill length (mm)
+        y:
+            title: Bill depth (mm)
+    series:
+        measure:
+            column: bill_depth_mm
+            color: species
+            line:
+                show: false
+            marker:
+                shape: species
+                size: 0.3
+    layers:
+        measure:
+            type: choice
+            label: Measurement
+            views:
+                Bill depth: {}
+                Flipper length: {series.measure.column: flipper_length_mm, axis.y.title: Flipper length (mm)}
+                Body mass: {series.measure.column: body_mass_g, axis.y.title: Body mass (g)}

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/packs/forgegraph_default/graphspecs/graphspec_example.md

@@ -27,8 +27,8 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                     direction: ascending          *# \[ascending, descending\]; The direction of the category order.*\
             title: column_name          *# \[None, column_name, text\]; The axis title. column_name uses the name of data.column if it's the base_axis or the series' column if it's not. With several series, use text or None.*\
             scale: linear          *# \[linear, log\]; The axis scale.*\
-            min: None          *# \[None, float, date\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range.*\
-            max: None          *# \[None, float, date\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range.*\
+            min: None          *# \[None, float, date, IQR rule\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range. 3IQR moves it in to the lower quartile minus 3 × the interquartile range.*\
+            max: None          *# \[None, float, date, IQR rule\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range. 3IQR moves it in to the upper quartile plus 3 × the interquartile range.*\
             tick:\
                 algorithm: auto          *# \[auto, all, manual, none\]; How the ticks are placed. auto uses the theme's algorithm, or on dates, the boundaries of one calendar unit. all places a tick at every value. manual places one every tick.step. none draws no ticks or tick labels.*\
                 step: None          *# \[None, float > 0, text\]; The distance between ticks when algorithm is manual, e.g. 5 or "2 week". On a log axis, it's a factor.*\
@@ -43,8 +43,8 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                     direction: ascending          *# \[ascending, descending\]; The direction of the category order.*\
             title: column_name          *# \[None, column_name, text\]; The axis title. column_name uses the name of data.column if it's the base_axis or the series' column if it's not. With several series, use text or None.*\
             scale: linear          *# \[linear, log\]; The axis scale.*\
-            min: None          *# \[None, float, date\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range.*\
-            max: None          *# \[None, float, date\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range.*\
+            min: None          *# \[None, float, date, IQR rule\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range. 3IQR moves it in to the lower quartile minus 3 × the interquartile range.*\
+            max: None          *# \[None, float, date, IQR rule\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range. 3IQR moves it in to the upper quartile plus 3 × the interquartile range.*\
             tick:\
                 algorithm: auto          *# \[auto, all, manual, none\]; How the ticks are placed. auto uses the theme's algorithm, or on dates, the boundaries of one calendar unit. all places a tick at every value. manual places one every tick.step. none draws no ticks or tick labels.*\
                 step: None          *# \[None, float > 0, text\]; The distance between ticks when algorithm is manual, e.g. 5 or "2 week". On a log axis, it's a factor.*\
@@ -73,7 +73,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                 missing_values: drop          *# \[drop, gap\]; What happens to rows missing x or y. drop joins the line across them, and gap breaks the line. Lint counts both in dropped-rows.*\
             marker:\
                 show: true          *# \[true, false\]; Whether to draw markers.*\
-                shape: first          *# \[first, series, circle, square, triangle_up, triangle_down, diamond, cross, plus, grid_cell, column\]; The marker shape. first is the theme's first marker shape, series takes the next one, and a column gives each of its values its own. grid_cell fills the grid the points lie on, for a heat map.*\
+                shape: first          *# \[first, series, circle, square, triangle_up, triangle_down, diamond, cross, plus, star, asterisk, grid_cell, column\]; The marker shape. first is the theme's first marker shape, series takes the next one, and a column gives each of its values its own. grid_cell fills the grid the points lie on, for a heat map.*\
                 fill: first          *# \[first, series, filled, open, column\]; The marker fill. first is the theme's first marker fill, series takes the next one, and a column gives each of its values its own.*\
                 size: 0.5          *# \[float > 0\]; The marker size, × base size.*\
             bar:\

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/packs/forgegraph_default/pack.md

@@ -3,7 +3,7 @@
 This page mirrors src/forgegraph/packs/forgegraph_default/pack.yaml, which is the specification. A test fails if they ever differ.
 
 name: forgegraph_default          *# \[text\]; The pack's name, which its specs' names start with (pack/name); a pip pack's must match its entry point.*\
-version: 0.7.0          *# \[text\]; The pack's release version.*\
+version: 0.8.0          *# \[text\]; The pack's release version.*\
 description: ForgeGraph's built-in default pack. So it’s always possible to create a graph.          *# \[text\]; One line, describing what the pack is.*\
 issues: https://github.com/sskaye/forgegraph/issues          *# \[text\]; Where to file feature requests and bug reports about the pack.*\
-requires: ">=0.7, <0.8"          *# \[None, version specifier\]; The ForgeGraph version required for the pack. pip format, e.g. ">=0.6, <1". If None, it works with any version.*
+requires: ">=0.8, <0.9"          *# \[None, version specifier\]; The ForgeGraph version required for the pack. pip format, e.g. ">=0.6, <1". If None, it works with any version.*

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/packs/forgegraph_default/themes/light_theme.md

@@ -27,6 +27,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         size: 1.05          *# \[float > 0\]; The size, × base size.*\
         weight: semibold          *# \[light, regular, medium, semibold, bold\]; The weight.*\
         gap: 0.41          *# \[float ≥ 0\]; The gap between the text and whatever is around it, × base size.*\
+        max_wrap: 0          *# \[int ≥ 0\]; The number of times the title may wrap onto a new line to fit above the plot. If 0, it never wraps.*\
     axis:\
         title:          *# \[text style\]; The axis titles.*\
             size: 1.05          *# \[float > 0\]; The size, × base size.*\
@@ -67,7 +68,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             width: 0.15          *# \[float ≥ 0\]; The width, × base size. If 0, no line is drawn.*\
             styles: !fix \[solid, dashed, dotted, dashdot\]          *# \[solid, dashed, dotted, dashdot\]; The line styles given to the series, or to the values of a series' line.style column.*\
         marker:\
-            shapes: !fix \[circle, square, triangle_up, diamond, triangle_down, cross\]          *# \[circle, square, triangle_up, triangle_down, diamond, cross, plus\]; The marker shapes given to the series, or to the values of a series' marker.shape column.*\
+            shapes: !fix \[circle, square, triangle_up, diamond, triangle_down, cross\]          *# \[circle, square, triangle_up, triangle_down, diamond, cross, plus, star, asterisk\]; The marker shapes given to the series, or to the values of a series' marker.shape column.*\
             fills: !fix \[filled, open\]          *# \[filled, open\]; The marker fills given to the series, or to the values of a series' marker.fill column. open draws only the outline.*\
             size: 0.5          *# \[float > 0\]; The marker size, × base size.*\
             edge:          *# \[line style\]; The outline of filled markers. Open markers are outlined at its width, in their series' color.*\
@@ -139,6 +140,10 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             size: 0.8          *# \[float > 0\]; The size, × base size.*\
             color: "#404040"          *# \[hex color\]; The color.*\
             gap: 0.5          *# \[float ≥ 0\]; The gap between the text and whatever is around it, × base size.*\
+        choice:          *# \[text style\]; A choice layer's label and its views' names on an HTML page. Its gap is between the label and the control.*\
+            alignment: left          *# \[left, center, right\]; The text alignment.*\
+        toggle:          *# \[text style\]; A toggle layer's label and its items' names on an HTML page. Its gap is between the label and the checkboxes.*\
+            alignment: left          *# \[left, center, right\]; The text alignment.*\
     watermark:          *# \[text style\]; The watermark drawn on non-standard graphs.*\
         weight: bold          *# \[light, regular, medium, semibold, bold\]; The weight.*\
         color: "#CC0000"          *# \[hex color\]; The color.*\

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/site/guides/graphs.md

@@ -16,7 +16,7 @@ These are the polarization curves of three fuel cells, from `cell_polarization.c
 - **extends** is the GraphSpec this one builds on. With `None`, the file lists every parameter it sets, and `!var` on `parameters` lets a GraphSpec that extends it change any of them (see [Building on a GraphSpec](#building-on-a-graphspec)).
 - **specifications** names the graph type, the theme and the format. The theme sets the look and the format sets the size and the file types. Both come from a [pack](themes-formats-packs.md), and are named `pack/name`.
 - **data.file** is the Parquet file holding the DataFrame, as a path from the GraphSpec's folder. `data.preprocessing` says where the code that made it is; it's recorded in the saved files and never read.
-- **axis.x.data.column** is the column along the x-axis. Each axis can also set its `title`, `scale` (`linear` or `log`), `min` and `max`, its ticks and their label format.
+- **axis.x.data.column** is the column along the x-axis. Each axis can also set its `title`, `scale` (`linear` or `log`), `min` and `max`, its ticks and their label format. `max: 3IQR` keeps a few far outliers from squashing the data: the axis stops at the upper quartile plus 3 × the interquartile range, where that's nearer than it would be, and lint counts the points beyond it.
 - **series** lists what's drawn against it, each under its name. A series draws the column with its name unless it sets `column`, and `color: cell` gives each cell its own color. The [Series guide](series.md) covers the rest.
 
 Titles are written in label markup: `^2` or `^{...}` makes a superscript and `_{...}` a subscript, so `A/cm^2` draws as A/cm². A column's name is always drawn as it's written.
@@ -29,7 +29,7 @@ Every parameter, with its default, the values it allows and its description, is
 forgegraph render polarization.yaml
 ```
 
-`render` saves the graph in each file type its format lists, beside the GraphSpec, and reports the lint. `--out` saves it elsewhere, and a suffix there picks one file type: `--out curves.svg`.
+`render` saves the graph in each file type its format lists, beside the GraphSpec, and reports the lint. `--out` saves it elsewhere, and a suffix there picks one file type: `--out curves.svg`. In an SVG, each part of a series or a layer has an id that names it, such as `fg-series-Cell_A-1` for a series' line or `fg-layer-target-1` for a reference line, so a page can style or hide a whole series by the start of its ids.
 
 The format's file types, size and resolution can be set in the GraphSpec too, where the format allows it. The built-in formats allow all of them:
 

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/site/guides/layers.md

@@ -1,6 +1,6 @@
 # Layers
 
-Layers are drawn over a graph: reference lines and bands, error bars, and notes. A GraphSpec lists its layers under `layers`, each under a name it chooses, with its `type`. They're drawn in the order they're listed. The [layer specifications](../reference/specifications/layer_reference.md) list every parameter.
+Layers are drawn over a graph: reference lines and bands, error bars, and notes. Choice and toggle layers add controls to the graph's HTML page instead. A GraphSpec lists its layers under `layers`, each under a name it chooses, with its `type`. They're drawn in the order they're listed. The [layer specifications](../reference/specifications/layer_reference.md) list every parameter.
 
 ## Reference lines and bands
 
@@ -54,6 +54,39 @@ A `note` layer writes a block of text in or around the plot. Its `text` is writt
 
 ![The mean response of three compounds at each dose, with error bars and the note Mean ± SD of 3 replicates in the lower right.](../images/dose_response.png){ width="480" }
 
+## Views
+
+A `choice` layer draws nothing on the graph. It lists views, and the graph's HTML page gets a control that switches between them. Each view is a set of the GraphSpec's parameters and their values, under the name the control shows, such as another column for a series and its axis title; `{}` changes nothing. ForgeGraph draws every view ahead of time, so the page needs no server. A png, pdf or svg file shows the first view. Every view has the same figure size and plot box, so the graph stays put as the views switch.
+
+```yaml
+--8<-- "docs/examples/penguin_measures.yaml"
+```
+
+[Open its HTML page](../pages/penguin_measures.html) to choose the measurement.
+
+- **control** shows the views' names as a `dropdown`, or as `radio` buttons, and **label** is the text before it.
+- **position** puts the control to the figure's `right` (the default), with the label above it, or at its `top` or `bottom`, with the label before it. On a narrow window, the right side moves below the figure.
+- A view can't change the data, the specifications, output or provenance. Each view is checked as the GraphSpec it makes, so a view can set a parameter only where the GraphSpec could.
+- Two choice layers, such as one for each axis, draw every combination of their views: four views each make 16 images. The page's size, and the time it takes to draw, grow with the number of images. Two choice layers can't set the same parameter.
+- In a layout, choice layers of the same name in several tiles share one control, which switches every tile that has it. Their views need the same names, in the same order, and the same position.
+
+## Toggles
+
+A `toggle` layer adds a checkbox to the graph's HTML page for each of its `items`, which shows the item when it's checked: `series` for every series, `layers` for every layer, or series and layers by name. `hidden` lists those hidden when the page opens, and png, pdf and svg files leave them out too.
+
+```yaml
+--8<-- "docs/examples/passenger_toggles.yaml"
+```
+
+[Open its HTML page](../pages/passenger_toggles.html) to show July's mean, or hide a month.
+
+- **label** is the text before the checkboxes, and **position** puts them to the figure's `right`, one under another, or in a row at its `top` or `bottom`.
+- A series named in a key gets its checkbox in the key, before its sample, on the page only: png, pdf and svg files are drawn without the room for it.
+- The graph is drawn once, with everything shown, so the axes don't change when an item is hidden, and the key keeps its entries.
+- A hidden series loses its lines, markers, bars, error bars, value labels, direct label and readouts. A hidden layer loses its lines, fill and label.
+- The page cuts the figure into images laid over each other, in the order the figure draws them, so it grows with the number of items. With choice layers, each view has its own.
+- A GraphSpec has at most one toggle layer. In a layout, the items of the same name in tiles with toggle layers share one checkbox, so they start hidden in every tile or in none, and the toggle layers share one list, so they need the same position.
+
 ## The layers' look
 
-Each layer's lines, labels, fill and text take their look from the theme's `layer` category. A layer may set the parts its theme marks `!var`, such as `line_1.line.style: None` above, which draws a band without its edges.
+Each layer's lines, labels, fill and text take their look from the theme's `layer` category: a choice or toggle layer's text from `layer.choice` and `layer.toggle`. A layer may set the parts its theme marks `!var`, such as `line_1.line.style: None` above, which draws a band without its edges.

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/site/guides/layouts.md

@@ -56,7 +56,7 @@ Tabs that hold tabs look like this, with a tab bar for each level on the HTML pa
 
 ## The HTML page
 
-A layout's HTML page, or a GraphSpec's, shows each figure as an image that shrinks to fit a narrow window. On a layout of several tabs, the tab names sit above the figures, in `tab_bar.label`'s look, with `tab_bar.line` under them; by default, they follow the first tile's theme. The tabs work where the page's scripts don't run. Where they run, each tab also has its own link, such as `#by-instrument`. The tab names stay at the top of the window as the page scrolls, and switching tabs leaves the page where it is, so the same tile stays in view.
+A layout's HTML page, or a GraphSpec's, shows each figure as an image that shrinks to fit a narrow window. On a layout of several tabs, the tab names sit above the figures, in `tab_bar.label`'s look, with `tab_bar.line` under them; by default, they follow the first tile's theme. The tabs work where the page's scripts don't run. Where they run, each tab also has its own link, such as `#by-instrument`. The tab names stay at the top of the window as the page scrolls, and switching tabs leaves the page where it is, so the same tile stays in view. A tile's [choice](layers.md#views) and [toggle](layers.md#toggles) layers add their controls under the tab names, and a control shows only on the tabs that use it.
 
 **Readouts.** Pointing at a data point on the page, or tapping it, shows its values in a box above it, with a ring around the point:
 

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/site/guides/schedules.md

@@ -4,10 +4,10 @@ A **schedule** re-renders GraphSpecs and layouts on a cadence, so a dashboard ke
 
 ## A schedule file
 
-This one, from the agent skill's examples, renders a layout every weekday at 06:00:
+This one, which the agent skill also uses as its example, renders a layout every weekday at 06:00:
 
 ```yaml
---8<-- "src/forgegraph/skill/forgegraph/examples/figure.schedule.yaml"
+--8<-- "docs/examples/cells.schedule.yaml"
 ```
 
 - **targets.files** are the GraphSpec and layout files rendered on each run, as paths from the schedule's folder. `targets.output_folder` saves their outputs elsewhere; by default, each is saved beside its file.
@@ -20,7 +20,7 @@ A schedule usually extends the built-in pack's `schedule`, or a pack's own, such
 ## Running it
 
 ```bash
-forgegraph job run figure.schedule.yaml
+forgegraph job run cells.schedule.yaml
 ```
 
 `job run` runs the schedule once: it renders every target, writes the status file, and runs on_failure or on_success. A target that fails is recorded, and the others still render; the command exits with 1 if any failed.
@@ -28,7 +28,7 @@ forgegraph job run figure.schedule.yaml
 ForgeGraph doesn't schedule the command itself. Whatever schedules commands where you work runs it at the schedule's times: cron, launchd, systemd, Task Scheduler, a GitHub Actions workflow, or an agent's scheduled task. For the schedule above, a cron line is:
 
 ```text
-0 6 * * 1-5 forgegraph job run /path/to/figure.schedule.yaml
+0 6 * * 1-5 forgegraph job run /path/to/cells.schedule.yaml
 ```
 
 Each run renders the data files as they are; keeping them current is up to you. On macOS, a background job that writes into a cloud-synced folder needs Full Disk Access.

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/site/guides/series.md

@@ -47,7 +47,7 @@ A series' rows can be split into groups by a column. Each of `color`, `line.styl
 
 ## Combining rows
 
-`aggregation` combines the rows at each x into one point: their mean, median, sum, minimum, maximum, a percentile, standard deviation, standard error, or half the 95 % confidence interval of the mean (`ci`). `multiplier` scales the result, and `percentile` sets which percentile.
+`aggregation` combines the rows at each x into one point: their mean, median, sum, minimum, maximum, a percentile, standard deviation, standard error, or half the 95 % confidence interval of the mean (`ci`). `multiplier` scales the result, and `percentile` sets which percentile. For positive values that vary by a factor, such as ratios or concentrations, `geom_mean` is the geometric mean, worked on the values' logs. `geom_stddev` and `geom_ci` are the geometric standard deviation and the 95 % confidence interval of the geometric mean: as a reference line's offset or an error bar, they multiply and divide, so an error bar's two sides differ.
 
 ```yaml
             aggregation:

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/site/help/troubleshooting.md

@@ -38,7 +38,7 @@ Use a linear scale, or leave those values out.
 
 ### outside-limits
 
-Points lie beyond an axis's fixed `min` or `max`, so they aren't drawn.
+Points, or a reference line or part of a band, lie beyond an axis's fixed `min` or `max`, so they aren't drawn.
 
 Widen the limits, or set them to None so the axis fits the data.
 
@@ -116,6 +116,14 @@ titel: unknown category; did you mean 'title'?
 
 A misspelled or misplaced parameter, with the nearest one ForgeGraph knows. The [specifications](../reference/specifications/index.md) list every parameter in its place.
 
+### A title too long for the figure
+
+```text
+text.title: too long for the figure: the title is 631 pt wide, and the figure 419 pt; ...
+```
+
+Shorten the title, put line breaks in it, or let a theme wrap it: `title.max_wrap` is how many more lines a title may take. It's 0, no wrapping, in the built-in theme.
+
 ### No way to name the series
 
 ```text

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/specifications/catalogs/graphtype_xy.md

@@ -11,7 +11,6 @@ baseline: forgegraph_default/graphspec_example          *# \[graphspec
 baselines:          *# Generic scenarios, each the baseline with one or more changes, numbered in the order they're first used. Every parameter gets one card, chosen by a rule: the first candidate value that changes the drawing, on the baseline or on the first of these scenarios where it does. The page shows the cards of the variable parameters. If there are no scenarios, this is None.*\
     key_shown: {legend.method: key}          *# \[parameters and their values, or non-standard\]; Series named in a key, so the key's parameters act.*\
     colored_by_temperature: {series.color: "Temperature (°C)"}          *# \[parameters and their values, or non-standard\]; A numeric color column, so a color bar is drawn.*\
-    colored_by_run: {series.color: Run}          *# \[parameters and their values, or non-standard\]; Colored by run, a column of numbers, so auto draws a color scale.*\
     temperatures:          *# \[parameters and their values, or non-standard\]; Each cell's peak power density at each temperature it ran at.*\
         axis.x.data.column: "Temperature (°C)"\
         series: {"Power Density (mW/cm²)": {color: Cell, split: None, aggregation: {function: max}}}\
@@ -52,4 +51,5 @@ baselines:          *# Generic scenarios, each the baseline with one o
         axis.y.data.column: Cell\
         axis.x.data.column: None\
         series: {"Temperature (°C)": {color: series, split: None, aggregation: {function: max}, line: {show: false}}}\
-    dated: {data.file: dated.parquet, axis.x.data.column: Date}          *# \[parameters and their values, or non-standard\]; Daily dates on x.*
+    dated: {data.file: dated.parquet, axis.x.data.column: Date}          *# \[parameters and their values, or non-standard\]; Daily dates on x.*\
+    temperature_key_outside: {series.color: "Temperature (°C)", legend.key.inside: false}          *# \[parameters and their values, or non-standard\]; A numeric color column with any key outside the plot area, so a key of each temperature fits.*

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/specifications/graphspec_example.md

@@ -28,8 +28,8 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                     direction: ascending          *# \[ascending, descending\]; The direction of the category order.*\
             title: column_name          *# \[None, column_name, text\]; The axis title. column_name uses the name of data.column if it's the base_axis or the series' column if it's not. With several series, use text or None.*\
             scale: linear          *# \[linear, log\]; The axis scale.*\
-            min: None          *# \[None, float, date\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range.*\
-            max: None          *# \[None, float, date\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range.*\
+            min: None          *# \[None, float, date, IQR rule\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range. 3IQR moves it in to the lower quartile minus 3 × the interquartile range.*\
+            max: None          *# \[None, float, date, IQR rule\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range. 3IQR moves it in to the upper quartile plus 3 × the interquartile range.*\
             tick:\
                 algorithm: auto          *# \[auto, all, manual, none\]; How the ticks are placed. auto uses the theme's algorithm, or on dates, the boundaries of one calendar unit. all places a tick at every value. manual places one every tick.step. none draws no ticks or tick labels.*\
                 step: None          *# \[None, float > 0, text\]; The distance between ticks when algorithm is manual, e.g. 5 or "2 week". On a log axis, it's a factor.*\
@@ -44,8 +44,8 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                     direction: ascending          *# \[ascending, descending\]; The direction of the category order.*\
             title: column_name          *# \[None, column_name, text\]; The axis title. column_name uses the name of data.column if it's the base_axis or the series' column if it's not. With several series, use text or None.*\
             scale: linear          *# \[linear, log\]; The axis scale.*\
-            min: None          *# \[None, float, date\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range.*\
-            max: None          *# \[None, float, date\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range.*\
+            min: None          *# \[None, float, date, IQR rule\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range. 3IQR moves it in to the lower quartile minus 3 × the interquartile range.*\
+            max: None          *# \[None, float, date, IQR rule\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range. 3IQR moves it in to the upper quartile plus 3 × the interquartile range.*\
             tick:\
                 algorithm: auto          *# \[auto, all, manual, none\]; How the ticks are placed. auto uses the theme's algorithm, or on dates, the boundaries of one calendar unit. all places a tick at every value. manual places one every tick.step. none draws no ticks or tick labels.*\
                 step: None          *# \[None, float > 0, text\]; The distance between ticks when algorithm is manual, e.g. 5 or "2 week". On a log axis, it's a factor.*\
@@ -74,7 +74,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                 missing_values: drop          *# \[drop, gap\]; What happens to rows missing x or y. drop joins the line across them, and gap breaks the line. Lint counts both in dropped-rows.*\
             marker:\
                 show: true          *# \[true, false\]; Whether to draw markers.*\
-                shape: first          *# \[first, series, circle, square, triangle_up, triangle_down, diamond, cross, plus, grid_cell, column\]; The marker shape. first is the theme's first marker shape, series takes the next one, and a column gives each of its values its own. grid_cell fills the grid the points lie on, for a heat map.*\
+                shape: first          *# \[first, series, circle, square, triangle_up, triangle_down, diamond, cross, plus, star, asterisk, grid_cell, column\]; The marker shape. first is the theme's first marker shape, series takes the next one, and a column gives each of its values its own. grid_cell fills the grid the points lie on, for a heat map.*\
                 fill: first          *# \[first, series, filled, open, column\]; The marker fill. first is the theme's first marker fill, series takes the next one, and a column gives each of its values its own.*\
                 size: 0.5          *# \[float > 0\]; The marker size, × base size.*\
             bar:\
@@ -126,4 +126,16 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                     text: Target 1.2 V          *# \[None, aggregation, value, aggregation_value, text\]; aggregation writes e.g. Mean, value e.g. 14.9, and aggregation_value e.g. Mean: 14.9. With an equation, value writes e.g. y = 2x. Other text is written as given.*\
         conditions:\
             type: note          *# \[layer type\]; The layer's type: one of the graph type's layer.types.*\
-            text: "60 °C, 1 atm, H₂/air"          *# \[text\]; The note's text, in label markup. A line break starts a new line.*
+            text: "60 °C, 1 atm, H₂/air"          *# \[text\]; The note's text, in label markup. A line break starts a new line.*\
+        metric:\
+            type: choice          *# \[layer type\]; The layer's type: one of the graph type's layer.types.*\
+            label: Metric          *# \[None, text\]; The text before the control, e.g. Metric. If None, there is none.*\
+            position: right          *# \[top, bottom, right\]; Where the control is on the HTML page: above the figure, below it, or to its right, with the label above it.*\
+            views:          *# The views, each under the name the control shows. A GraphSpec lists two or more, and the page opens on the first.*\
+                Voltage: {}          *# \[parameters and their values\]; What the view changes, e.g. a series' column and the y-axis title. {} changes nothing.*\
+                Power: {series.SERIES_1.column: Power Density (mW/cm²), axis.y.title: Power density (mW/cm²)}          *# \[parameters and their values\]; A series' column and the y-axis title.*\
+        hide:\
+            type: toggle          *# \[layer type\]; The layer's type: one of the graph type's layer.types.*\
+            label: Show          *# \[None, text\]; The text before the checkboxes, e.g. Show. If None, there is none.*\
+            position: right          *# \[top, bottom, right\]; Where the checkboxes are on the HTML page: above the figure, below it, or to its right, under the label.*\
+            items: \[series, target\]          *# \[series, layers, text\]; What can be hidden: series for all series, layers for all layers, or those named.*

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/specifications/graphtype_xy.md

@@ -18,8 +18,8 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                     direction: ascending          *# \[ascending, descending\]; The direction of the category order.*\
             title: column_name          *# \[None, column_name, text\]; The axis title. column_name uses the name of data.column if it's the base_axis or the series' column if it's not. With several series, use text or None.*\
             scale: linear          *# \[linear, log\]; The axis scale.*\
-            min: None          *# \[None, float, date\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range.*\
-            max: None          *# \[None, float, date\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range.*\
+            min: None          *# \[None, float, date, IQR rule\]; The axis minimum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the lowest value minus plot_area.gap × the data's range. 3IQR moves it in to the lower quartile minus 3 × the interquartile range.*\
+            max: None          *# \[None, float, date, IQR rule\]; The axis maximum. On a datetime axis, it's a date, e.g. 2025-08-25 or "2025-08-25T06:00". If None, it's the highest value plus plot_area.gap × the data's range. 3IQR moves it in to the upper quartile plus 3 × the interquartile range.*\
             tick:\
                 algorithm: auto          *# \[auto, all, manual, none\]; How the ticks are placed. auto uses the theme's algorithm, or on dates, the boundaries of one calendar unit. all places a tick at every value. manual places one every tick.step. none draws no ticks or tick labels.*\
                 step: None          *# \[None, float > 0, text\]; The distance between ticks when algorithm is manual, e.g. 5 or "2 week". On a log axis, it's a factor.*\
@@ -48,7 +48,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                 missing_values: drop          *# \[drop, gap\]; What happens to rows missing x or y. drop joins the line across them, and gap breaks the line. Lint counts both in dropped-rows.*\
             marker:\
                 show: true          *# \[true, false\]; Whether to draw markers.*\
-                shape: first          *# \[first, series, circle, square, triangle_up, triangle_down, diamond, cross, plus, grid_cell, column\]; The marker shape. first is the theme's first marker shape, series takes the next one, and a column gives each of its values its own. grid_cell fills the grid the points lie on, for a heat map.*\
+                shape: first          *# \[first, series, circle, square, triangle_up, triangle_down, diamond, cross, plus, star, asterisk, grid_cell, column\]; The marker shape. first is the theme's first marker shape, series takes the next one, and a column gives each of its values its own. grid_cell fills the grid the points lie on, for a heat map.*\
                 fill: first          *# \[first, series, filled, open, column\]; The marker fill. first is the theme's first marker fill, series takes the next one, and a column gives each of its values its own.*\
             bar:\
                 show: false          *# \[true, false\]; Whether to draw bars. Bars start at 0, or at 1 on a log axis, and the value axis then always includes that value.*\
@@ -71,4 +71,5 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             title:\
                 text: column_name          *# \[None, column_name, text\]; The color bar's title. column_name uses the name of the series' color column. If None, there is no title.*\
     layer:\
-        types: !fix \[reference, note, error_bar\]          *# \[layer types\]; The layer types that a GraphSpec of this graph type may use.*
+        types: !fix \[reference, note, error_bar, choice, toggle\]          *# \[layer types\]; The layer types that a GraphSpec of this graph type may use.*
+

forgegraph-0.8.0/docs/specifications/layer_choice.md

@@ -0,0 +1,15 @@
+# Layer specification: choice
+
+This page mirrors src/forgegraph/specifications/layer_choice.yaml, which is the specification. A test fails if they ever differ.
+
+name: choice          *# \[text\]; The name of the layer type.*\
+version: 0          *# \[int ≥ 0\]; The version number of the specification.*\
+description: A control on an HTML page that switches between views, each drawn ahead of time.          *# \[text\]; The description of the layer type.*\
+ \
+parameters:          *# \[text style, look from layer.choice\]; The control.*\
+    label: None          *# \[None, text\]; The text before the control, e.g. Metric. If None, there is none.*\
+    control: dropdown          *# \[dropdown, radio\]; How the page shows the views' names: as a dropdown, or as a row of radio buttons.*\
+    position: right          *# \[top, bottom, right\]; Where the control is on the HTML page: above the figure, below it, or to its right, with the label above it.*\
+    views:          *# The views, each under the name the control shows. A GraphSpec lists two or more, and the page opens on the first.*\
+        VIEW_1: {}          *# \[parameters and their values\]; What the view changes, e.g. a series' column and the y-axis title. {} changes nothing.*
+

forgegraph-0.8.0/docs/specifications/layer_toggle.md

@@ -0,0 +1,14 @@
+# Layer specification: toggle
+
+This page mirrors src/forgegraph/specifications/layer_toggle.yaml, which is the specification. A test fails if they ever differ.
+
+name: toggle          *# \[text\]; The name of the layer type.*\
+version: 0          *# \[int ≥ 0\]; The version number of the specification.*\
+description: Checkboxes on an HTML page that show or hide series and layers, each drawn ahead of time.          *# \[text\]; The description of the layer type.*\
+ \
+parameters:          *# \[text style, look from layer.toggle\]; The checkboxes.*\
+    label: None          *# \[None, text\]; The text before the checkboxes, e.g. Show. If None, there is none.*\
+    position: right          *# \[top, bottom, right\]; Where the checkboxes are on the HTML page: above the figure, below it, or to its right, under the label.*\
+    items: \[series\]          *# \[series, layers, text\]; What can be hidden: series for all series, layers for all layers, or those named.*\
+    hidden: None          *# \[None, texts\]; The series and layers hidden when the page opens. If None, everything is shown.*
+

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/specifications/pack.md

@@ -3,7 +3,7 @@
 This page mirrors src/forgegraph/specifications/pack.yaml, which is the specification. A test fails if they ever differ.
 
 name: forgegraph_specifications          *# \[text\]; The pack's name, which its specs' names start with (pack/name); a pip pack's must match its entry point.*\
-version: 0.7.0          *# \[text\]; The pack's release version.*\
+version: 0.8.0          *# \[text\]; The pack's release version.*\
 description: ForgeGraph's base specs, to define the specifications.          *# \[text\]; One line, describing what the pack is.*\
 issues: https://github.com/sskaye/forgegraph/issues          *# \[text\]; Where to file feature requests and bug reports about the pack's specs.*\
-requires: ">=0.7, <0.8"          *# \[None, version specifier\]; The ForgeGraph versions the pack works with, as pip writes them, e.g. ">=0.6, <1". If None, it works with any version.*
+requires: ">=0.8, <0.9"          *# \[None, version specifier\]; The ForgeGraph versions the pack works with, as pip writes them, e.g. ">=0.6, <1". If None, it works with any version.*

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/specifications/styles.md

@@ -7,6 +7,6 @@ version: 0          *# \[int ≥ 0\]; The version number of the specif
 description: Styles that graph types and layers share. A category marked with a style has its parameters, with these defaults, and lists only those it changes.          *# \[text\]; The description of the specification.*\
  \
 aggregation_style:          *# How a column's rows are combined into one number. Marked \[aggregation style\].*\
-    function: None          *# \[None, mean, median, sum, min, max, percentile, stddev, stderr, ci\]; The aggregate. ci is half the 95 % confidence interval of the mean. If None, each row's value is used.*\
+    function: None          *# \[None, mean, median, sum, min, max, percentile, stddev, stderr, ci, geom_mean, geom_stddev, geom_ci\]; The aggregate. ci is half the 95 % confidence interval of the mean. geom\_ functions work on the logs of values above 0; geom_stddev and geom_ci are factors, which multiply as an offset or error bar. If None, each row's value is used.*\
     multiplier: 1          *# \[float\]; The number the aggregate is multiplied by, e.g. 2 for twice the standard deviation.*\
     percentile: 50          *# \[0-100\]; The percentile when function is percentile.*

{forgegraph-0.7.0 → forgegraph-0.8.0}/docs/specifications/theme.md

@@ -24,6 +24,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
     background:\
         color: "#FFFFFF"          *# \[None, hex color\]; The background color of the figure and the plot area. If None, the background is transparent.*\
     title:          *# \[text style\]; The graph's title. Its gap is measured from the line its letters sit on.*\
+        max_wrap: 0          *# \[int ≥ 0\]; The number of times the title may wrap onto a new line to fit above the plot. If 0, it never wraps.*\
     axis:\
         title:          *# \[text style\]; The axis titles.*\
         tick:          *# \[line style\]; The tick marks.*\
@@ -62,7 +63,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         line:          *# \[line style\]; The series lines.*\
             styles: \[solid, dashed, dotted, dashdot\]          *# \[solid, dashed, dotted, dashdot\]; The line styles given to the series, or to the values of a series' line.style column.*\
         marker:\
-            shapes: \[circle, square, triangle_up, diamond, triangle_down, cross\]          *# \[circle, square, triangle_up, triangle_down, diamond, cross, plus\]; The marker shapes given to the series, or to the values of a series' marker.shape column.*\
+            shapes: \[circle, square, triangle_up, diamond, triangle_down, cross\]          *# \[circle, square, triangle_up, triangle_down, diamond, cross, plus, star, asterisk\]; The marker shapes given to the series, or to the values of a series' marker.shape column.*\
             fills: \[filled, open\]          *# \[filled, open\]; The marker fills given to the series, or to the values of a series' marker.fill column. open draws only the outline.*\
             size: 0.5          *# \[float > 0\]; The marker size, × base size.*\
             edge:          *# \[line style\]; The outline of filled markers. Open markers are outlined at its width, in their series' color.*\
@@ -107,9 +108,12 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                 color: "#808080"          *# \[None, series, hex color\]; The fill color. series uses the series' color. If None, there is no fill.*\
                 opacity: 0.15          *# \[0-1\]; The fill opacity.*\
         note:          *# \[text style\]; The notes.*\
+        choice:          *# \[text style\]; A choice layer's label and its views' names on an HTML page. Its gap is between the label and the control.*\
+        toggle:          *# \[text style\]; A toggle layer's label and its items' names on an HTML page. Its gap is between the label and the checkboxes.*\
     watermark:          *# \[text style\]; The watermark drawn on non-standard graphs.*\
         text: NON-STANDARD          *# \[text\]; The watermark's text.*\
         opacity: 0.18          *# \[0-1\]; The watermark's opacity.*\
         angle: 30          *# \[-90-90\]; The watermark's angle, in degrees counterclockwise.*\
         span: 0.8          *# \[0-1\]; The fraction of the plot area's width or height that the watermark spans, whichever it reaches first.*\
     footnote:          *# \[text style\]; The footnotes below the figure.*
+

{forgegraph-0.7.0 → forgegraph-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forgegraph"
-version = "0.7.0"
+version = "0.8.0"
 description = "Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents."
 readme = "README.md"
 license = "MIT AND OFL-1.1"