forgegraph 0.6.1__tar.gz → 0.8.0__tar.gz

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

@@ -2,6 +2,54 @@
 
 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
+
+- **Heat maps.** `marker.shape: grid_cell` makes each point fill its place in a grid, so an xy graph colored by a column of numbers becomes a heat map. The cells fit at any format, and an HTML page shows a cell's values when you point at it. There's an example in the gallery and in the skill.
+- **Reference lines from an equation.** A reference line can now be an equation instead of a value, such as `equation: x` for a y = x line on a parity plot, or `2x^2 - 3x + 1` for a curve. Two equations, such as `x - 10` and `x + 10`, make a tolerance band.
+- **No tick labels.** `tick.algorithm: none` draws no ticks or tick labels on an axis, for when there are too many names to fit and readers can point at a point to see its name.
+- **Tab bars stay in view.** On a layout's HTML page, the tabs now stay at the top of the window as you scroll, and switching tabs keeps your place on the page.
+
+### Changes
+
+- **More in the hover box.** On a graph of more than one series, the hover box now always names the series. It also shows each column a series is split by, so splitting a scatter by its sample's name shows that name on each point.
+- **More room for keys.** A reference line's label at `position: auto` now goes after the keys and keeps clear of them, so keys and labels may sit in different places than before. A second key can go under or beside the first, and the y-axis can grow by up to `axis.max_extension` to make room for a key. Some graphs that couldn't fit a key now draw, with a longer y-axis.
+- **Clearer key errors.** When a key doesn't fit, the error now says what's in the way at each position.
+
+### Bug Fixes
+
+- Coloring by the column on a categorical axis gave every point the first color and labelled the groups 0.0, 1.0 and 2.0. Each category now gets its own color, and the same goes for marker shapes and line styles. The axis already names the groups, so with `legend.method: auto` they aren't named again.
+- A categorical axis with exactly two categories had no tick labels. It now has one for each category.
+- An aggregated series colored by a column of numbers crashed with a message from matplotlib. If the rows behind a point share one value, the point now takes that color. If they don't, it's an error that says which column to change.
+- The hover box on an integer axis showed `2.0` where it now shows `2`.
+
 ## 0.6.1 (2026-10-31)
 
 ### Changes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.6.1
+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.6.1/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.8.0/docs/examples/plate_spectra.yaml

@@ -0,0 +1,32 @@
+name: plate_spectra
+version: 0
+description: A heat map of a plate's spectra, one row for each sample, colored by absorbance.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: A plate of UV-Vis spectra
+    data:
+        file: plate_spectra.parquet
+        preprocessing: examples/sample-data/plate_spectra.csv
+    arrangement:
+        base_axis: y
+    axis:
+        x:
+            title: Wavelength (nm)
+        y:
+            data:
+                column: Sample
+                type: categorical
+            title: Sample
+    series:
+        Wavelength (nm):
+            color: Normalized absorbance
+            color_scale: continuous
+            marker:
+                shape: grid_cell
+            line:
+                show: false

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

@@ -27,10 +27,10 @@ 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\]; 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.*\
+                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.*\
                 label:\
                     format: auto          *# \[auto, format\]; The tick label format. auto chooses one from the values, and for dates, from the tick unit.*\
@@ -43,10 +43,10 @@ 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\]; 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.*\
+                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.*\
                 label:\
                     format: auto          *# \[auto, format\]; The tick label format. auto chooses one from the values, and for dates, from the tick unit.*\
@@ -60,7 +60,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         "Cell Voltage (V)":\
             column: name          *# \[name, column\]; The column of values the series draws along the axis that isn't arrangement.base_axis. name uses the column with the series' name.*\
             aggregation:          *# \[aggregation style\]; How rows at the same location are combined into one point. If its function is None, each row is drawn.*\
-            split: \[Cell, Run\]          *# \[None, columns\]; Columns whose values split the series into separate lines, e.g. replicates.*\
+            split: \[Cell, Run\]          *# \[None, columns\]; Columns whose values split the series into separate lines, e.g. replicates. An html page's readout shows each one.*\
             order: sorted          *# \[sorted, data\]; The order of the series' groups: sorted, or data for the order in which they first appear.*\
             color: Cell          *# \[series, hex color, column\]; The series' color. series takes the next palette color, and a column gives each of its values its own.*\
             color_scale: auto          *# \[auto, categorical, continuous\]; For a color column: categorical uses the palette, continuous a color scale and color bar, and auto continuous for numbers.*\
@@ -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, 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.*\
+                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:\
@@ -91,7 +91,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
     legend:\
         method: auto          *# \[auto, direct, key, none\]; How this graph names its series: one of the theme's legend.methods.*\
         key:\
-            positions: \[top_right, top_left, bottom_right, bottom_left\]          *# \[top_left, top_center, top_right, bottom_left, bottom_center, bottom_right, right_top, right_center, right_bottom\]; The positions to try, in order. The key goes in the first one where it doesn't overlap the data.*\
+            positions: \[top_right, top_left, bottom_right, bottom_left\]          *# \[top_left, top_center, top_right, bottom_left, bottom_center, bottom_right, right_top, right_center, right_bottom\]; The positions to try, in order. The key goes in the first one where it doesn't overlap the data. If there's none inside the plot, it goes beside a key there, or the y-axis is extended.*\
             inside: true          *# \[true, false\]; Whether the key is inside the plot area. If false, top positions are above the plot area, bottom positions are below the x-axis title, and right positions are to its right.*\
             title:\
                 text: column_name          *# \[None, column_name, text\]; The title of every key. column_name uses the name of each key's column. Other text is allowed only when there is one key. If None, there is no title.*\
@@ -106,11 +106,11 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
     layers:          *# The layers drawn on the graph, in this order, each under a name the GraphSpec chooses. A layer may set the look its theme marks !var.*\
         target:\
             type: reference          *# \[layer type\]; The layer's type: one of the graph type's layer.types.*\
-            axis: y          *# \[x, y\]; The axis the values are on. y draws horizontal lines.*\
+            axis: y          *# \[x, y\]; The axis the values are on. y draws horizontal lines, and an equation then gives y in terms of x.*\
             line_1:\
                 value: 1.2          *# \[None, float, date, column\]; A number, a date, or a column.*\
                 label:\
-                    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. Other text is written as given.*\
+                    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.*

{forgegraph-0.6.1 → 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.6.1          *# \[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.6, <0.7"          *# \[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.6.1 → 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.*\
@@ -46,7 +47,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
                 count: 0          *# \[int ≥ 0\]; The number of minor ticks between major ticks. If 0, there are none.*\
                 length: 0.15          *# \[float ≥ 0\]; The minor tick length, × base size.*\
                 width: 0.05          *# \[float ≥ 0\]; The width, × base size. If 0, no line is drawn.*\
-        max_extension: 0.15          *# \[0-1\]; The most an axis may be extended to fit direct labels, notes and line labels inside the plot area, × its range. If 0, it's never extended.*\
+        max_extension: 0.15          *# \[0-1\]; The most an axis may be extended to fit direct labels, keys, notes and line labels inside the plot area, × its range. If 0, it's never extended.*\
     plot_area:\
         border:          *# \[line style\]; The plot area's border.*\
             width: 0.08          *# \[float ≥ 0\]; The width, × base size. If 0, no line is drawn.*\
@@ -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.6.1 → forgegraph-0.8.0}/docs/site/gallery.md

@@ -14,6 +14,18 @@ Polarization curves of three fuel cells, one line for each cell, named beside it
     --8<-- "docs/examples/polarization.yaml"
     ```
 
+## A heat map
+
+A plate of 60 UV-Vis spectra, one row for each sample, colored by absorbance. It's an xy graph whose markers fill the grid its points lie on, with `marker.shape: grid_cell`. Pointing at a cell on an HTML page shows its wavelength, sample and absorbance. Data: plate_spectra.csv.
+
+![A grid of colored cells, wavelength across and samples up, with four families of bands.](images/plate_spectra.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/plate_spectra.yaml"
+    ```
+
 ## Lines over time
 
 Each cell's voltage over a 200-hour durability test, as lines without markers. Data: cell_durability.csv.

{forgegraph-0.6.1 → 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.8.0/docs/site/guides/layers.md

@@ -0,0 +1,92 @@
+# Layers
+
+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
+
+A `reference` layer draws a line across the plot at a value: horizontal with `axis: y`, vertical with `axis: x`. `line_1.value` is a number, a date, or a column, and a column's rows are combined by `line_1.aggregation`, so a line can sit at the data's mean, median, a percentile and so on. `offset` adds a distance to that, such as three standard deviations.
+
+A line can also be an equation, in place of a value, such as `equation: x` for a line of y = x on a parity plot. With `axis: y`, an equation gives y in terms of x, and with `axis: x`, x in terms of y. It may use numbers, that letter, `+`, `-`, `*`, `/`, `^` and parentheses, as in `2x^2 - 3x + 1`, and it may be a curve. The line runs across the plot without widening an axis, and its label lies along it. `label.text: value` writes the equation, as in y = 2x. A label that can't find a clear place beside the data can go beyond the plot, with `label.inside: false`.
+
+A second line, `line_2`, makes the layer a band, filled between the two lines, which can be equations: `x - 10` and `x + 10` make a tolerance band around y = x. The savings rate has a band one standard deviation either side of its mean, drawn without its lines, and a second layer with a line at the mean:
+
+```yaml
+--8<-- "docs/examples/savings.yaml"
+```
+
+![The savings rate by month, with a grey band one standard deviation either side of the mean and a dashed line at the mean, labelled Mean: 14.9.](../images/savings.png){ width="480" }
+
+- **label.text** writes the line's label: `aggregation` writes, for example, Mean, `value` writes 14.9, `aggregation_value` writes Mean: 14.9, and other text is written as it's given. `label.position` and `label.inside` place it; here it's outside the plot, at the line's end.
+- **per_series: true** draws the layer for every series with matching color, marker shape, marker fill and line style, in its color and from its rows, instead of once for all the data.
+- **scope: each** makes a line that follows the data, instead of a straight line over all the rows.
+
+## Error bars
+
+An `error_bar` layer draws a bar on each point or bar, along `axis` (y by default). Its distances below and above each value come from `value.lower` and `value.upper`:
+
+- **data_column**, the default, takes them from the rows each point stands for, as `value.aggregation` says: their standard deviation by default, or their standard error, confidence interval and so on. The series must then be aggregated, so each point stands for several rows.
+- **A number** is the same distance for every point.
+- **A column** gives each point its own, with `value.aggregation.function: None` to use the column's values as they are.
+
+The mean tip on each day, with the 95 % confidence interval of each mean:
+
+```yaml
+--8<-- "docs/examples/tips_side_by_side.yaml"
+```
+
+![Bars of the mean tip on each day, for women and men side by side, each with an error bar.](../images/tips_side_by_side.png){ width="480" }
+
+When the data already holds the spread, the error bars read it from its column:
+
+```yaml
+--8<-- "docs/examples/assay_summary.yaml"
+```
+
+![Each compound's mean response at each dose, with error bars from the data's standard deviations.](../images/assay_summary.png){ width="480" }
+
+## Notes
+
+A `note` layer writes a block of text in or around the plot. Its `text` is written in label markup, and a line break starts a new line. `position: auto` puts it at the first clear place inside the plot area; `inside: false` puts it outside, at the `position` given.
+
+```yaml
+--8<-- "docs/examples/dose_response.yaml"
+```
+
+![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 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.6.1 → forgegraph-0.8.0}/docs/site/guides/layouts.md

@@ -56,11 +56,13 @@ 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`.
+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:
 
 - each axis's title and the point's value, with its error bar and the error bar's aggregation where it has one, as in `8.0 ± 0.4 (95%CI)`;
-- then the series' color, marker shape and line style, each where it varies, as the key's title and the point's group.
+- then the series' color, marker shape and line style, each where it varies, as the key's title and the point's group;
+- then, with more than one series, the series' name;
+- then each column the series is split by, with the point's value. To name each point of a scatter, split the series by the column that holds its name, as in `split: measurement_id`.
 
-Markers, a line's points and bars respond; empty space, reference lines and notes don't. A number with an error bar is rounded to the error's last digit; one without has a decimal more than the tick labels. The page carries each figure's points and the font the readouts are written in, so it's larger than the image alone.
+Markers, a line's points and bars respond; empty space, reference lines and notes don't. A number with an error bar is rounded to the error's last digit; one without has a decimal more than the tick labels, except on an integer base axis, whose values are whole. The page carries each figure's points and the font the readouts are written in, so it's larger than the image alone.

{forgegraph-0.6.1 → 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.6.1 → forgegraph-0.8.0}/docs/site/guides/series.md

@@ -20,7 +20,7 @@ Each series chooses its marks: `line.show`, `marker.show` and `bar.show`. By def
 
 - **Lines** join the points in order of x, or in the order of the rows with `line.connect_order: data`. `line.interpolate` draws them straight, in steps, or as a smooth curve.
 - **Missing values:** with `line.missing_values: drop`, a line joins across a row missing its x or y; with `gap`, the line breaks there. Either way, the lint counts the rows left out.
-- **Markers** take the theme's shapes and fills, and `marker.size` sets their size.
+- **Markers** take the theme's shapes and fills, and `marker.size` sets their size. `marker.shape: grid_cell` instead fills the grid the points lie on, which makes a heat map: see the [gallery](../gallery.md#a-heat-map).
 - **Bars** stand on the x-axis, from 0, or from 1 on a log axis, and `bar.width` sets how much of the space between neighboring bars they fill.
 
 The durability test draws lines without markers:
@@ -41,13 +41,13 @@ A series' rows can be split into groups by a column. Each of `color`, `line.styl
 
 ![Bill depth against bill length, a color and a marker shape for each penguin species.](../images/penguins.png){ width="480" }
 
-- **split** specifies how rows should be grouped for aggregation or line paths. This can be used to, for example, prevent averaging of data from replicates or draw independent lines for multiple runs under the same conditions.
+- **split** specifies how rows should be grouped for aggregation or line paths. This can be used to, for example, prevent averaging of data from replicates or draw independent lines for multiple runs under the same conditions. On an HTML page, a point's readout shows its value of each column it's split by.
 - **order** puts the groups in sorted order, or with `data`, in the order they first appear.
 - **A numeric color column** draws on a color scale, with a color bar beside the plot. `color_scale: categorical` gives each number a palette color instead.
 
 ## 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:
@@ -85,7 +85,7 @@ A categorical axis keeps the order of its categories in the data, or sorts them
 `legend.method` chooses how a graph names its series, from the methods its theme allows:
 
 - **direct:** each name beside its own series, touching no line, marker or other name.
-- **key:** a key at the first of `legend.key.positions` that covers no data. With `legend.key.inside: false`, the key is outside the plot area.
+- **key:** a key at the first of `legend.key.positions` that covers no data. If there's none, a second key goes under or beside the first, and otherwise the y-axis is extended by up to `axis.max_extension` to make room. With `legend.key.inside: false`, the key is outside the plot area.
 - **none:** no names, where the theme allows it. The built-in theme doesn't.
 - **auto**, the default, tries the theme's methods in order and uses the first that fits.
 

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

@@ -10,7 +10,7 @@ Every render lints the graph it drew and lists any issues, each under the name o
 
 Two texts' letters overlap, such as neighboring tick labels or a title and a key.
 
-Make room: fewer ticks (`tick.algorithm: manual` with a larger `tick.step`), a shorter label or tick label format, a wider format (`figure.width`), or rotated x tick labels, where the theme lets a GraphSpec set `axis.tick.label.x_rotation`.
+Make room: fewer ticks (`tick.algorithm: manual` with a larger `tick.step`), no tick labels at all (`tick.algorithm: none`, where readers identify a point from its readout on an HTML page), a shorter label or tick label format, a wider format (`figure.width`), or rotated x tick labels, where the theme lets a GraphSpec set `axis.tick.label.x_rotation`.
 
 ### clipped-text
 
@@ -22,7 +22,7 @@ Shorten the text, place it inside the plot, or widen the format.
 
 A key covers a line or marker.
 
-List other positions in `legend.key.positions`, put the key outside the plot with `legend.key.inside: false`, or name the series directly with `legend.method: direct`.
+The error says what's in the way at each position. List other positions in `legend.key.positions`, let the axis extend further with a larger `axis.max_extension`, move a reference line's label by leaving its `position` at `auto`, put the key outside the plot with `legend.key.inside: false`, or name the series directly with `legend.method: direct`.
 
 ### too-many-groups
 
@@ -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.6.1 → 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.*