forgegraph 0.6.1__tar.gz → 0.7.0__tar.gz

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

@@ -2,6 +2,28 @@
 
 ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written.
 
+## 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.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.6.1
+Version: 0.7.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/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.7.0}/docs/packs/forgegraph_default/graphspecs/graphspec_example.md

@@ -30,7 +30,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             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.*\
             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.*\
@@ -46,7 +46,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             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.*\
             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, 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.7.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.7.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.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.*

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

@@ -46,7 +46,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.*\

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

@@ -6,7 +6,9 @@ Layers are drawn over a graph: reference lines and bands, error bars, and notes.
 
 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 second line, `line_2`, makes the layer a band, filled between the two lines. 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:
+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"

{forgegraph-0.6.1 → forgegraph-0.7.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.
 
 **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.7.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,7 +41,7 @@ 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.
 
@@ -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.7.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
 

{forgegraph-0.6.1 → forgegraph-0.7.0}/docs/specifications/catalogs/layer_reference.md

@@ -9,7 +9,7 @@ extends: None          *# \[None, catalog\]; The catalog this one exte
 baseline: forgegraph_default/graphspec_example          *# \[graphspec\]; The GraphSpec every card changes, without its own layers.*\
 settings: None          *# The GraphSpec parameters every card sets so that the layer can be drawn. If there are none, this is None.*\
 layer:          *# The parameters of the layer every card draws, which is named after its type. If None, the layer's defaults are used.*\
-    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.45          *# \[None, float, date, column\]; A number, a date, or a column.*\
  \
@@ -32,4 +32,6 @@ baselines:          *# Generic scenarios, each the baseline with one o
         layers.reference.line_2: {value: "Cell Voltage (V)", aggregation: {function: percentile, percentile: 75}}\
     percentile_offsets:          *# \[parameters and their values, or non-standard\]; Lines at the median cell voltage, each offset by a fraction of a percentile, so each offset's percentile acts.*\
         layers.reference.line_1: {value: "Cell Voltage (V)", aggregation: {function: median}, offset: {function: percentile, percentile: 10, multiplier: 0.05}}\
-        layers.reference.line_2: {value: "Cell Voltage (V)", aggregation: {function: median}, offset: {function: percentile, percentile: 90, multiplier: -0.05}}
+        layers.reference.line_2: {value: "Cell Voltage (V)", aggregation: {function: median}, offset: {function: percentile, percentile: 90, multiplier: -0.05}}\
+    from_an_equation:          *# \[parameters and their values, or non-standard\]; A line from an equation, so that its label can follow it.*\
+        layers.reference.line_1: {value: None, equation: "1.35 + 0.02x"}

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

@@ -18,7 +18,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         file: None          *# \[None, text\]; A Parquet file holding the DataFrame to draw: an absolute path, a path starting with ~, or a path relative to the folder of the file that sets it. If None, the DataFrame is passed through the Python API.*\
         preprocessing: None          *# \[None, text\]; Where the code that made the data is: a path, a URL or a note. It's recorded in provenance and never read. If None, it's not given.*\
     axis:\
-        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.*\
         x:\
             data:\
                 column: "PLACEHOLDER"          *# \[None, column\]; The column on this axis when it's arrangement.base_axis, which a GraphSpec must then set. Otherwise, it must be None.*\
@@ -31,7 +31,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             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.*\
             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.*\
@@ -47,7 +47,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             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.*\
             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.*\
@@ -61,7 +61,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         "SERIES_1":\
             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.*\
@@ -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, 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, 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:\
@@ -94,7 +94,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         direct:\
             max_relative_distance: 0.8          *# \[0-1\]; The farthest a direct label may be from its series, ÷ its distance to the next nearest series.*\
         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.*\
@@ -119,11 +119,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.7.0}/docs/specifications/graphtype_xy.md

@@ -21,7 +21,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             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.*\
             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.*\
@@ -36,7 +36,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         a:\
             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: None          *# \[None, columns\]; Columns whose values split the series into separate lines, e.g. replicates.*\
+            split: None          *# \[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: series          *# \[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.*\
@@ -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, 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, 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.*\
@@ -63,7 +63,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.*\

{forgegraph-0.6.1 → forgegraph-0.7.0}/docs/specifications/layer_reference.md

@@ -4,20 +4,21 @@ This page mirrors src/forgegraph/specifications/layer_reference.yaml, which is t
 
 name: reference          *# \[text\]; The name of the layer type.*\
 version: 0          *# \[int ≥ 0\]; The version number of the specification.*\
-description: A horizontal or vertical line, or a shaded band between two lines, at a value or drawn from the data.          *# \[text\]; The description of the layer type.*\
+description: A horizontal or vertical line, or a shaded band between two lines, at a value, drawn from the data, or from an equation.          *# \[text\]; The description of the layer type.*\
  \
 parameters:\
-    axis: None          *# \[x, y\]; The axis the values are on. y draws horizontal lines. A GraphSpec must set it.*\
+    axis: None          *# \[x, y\]; The axis the values are on. y draws horizontal lines, and an equation then gives y in terms of x. A GraphSpec must set it.*\
     per_series: false          *# \[true, false\]; If true, the layer is drawn for every series with matching color, marker shape, marker fill and line style. If false, it's drawn for all data combined.*\
     line_1:          *# The first line.*\
         value: None          *# \[None, float, date, column\]; A number, a date, or a column.*\
+        equation: None          *# \[None, text\]; The line as an equation in the other axis's letter, e.g. 2x or x^2, instead of a value. It may use numbers, the letter, +, -, \*, /, ^ and parentheses.*\
         aggregation:          *# \[aggregation style\]; How the column's rows are combined into the line's value. If its function is None, the values are used as-is.*\
         offset:          *# \[aggregation style\]; A distance added to the aggregate, e.g. 3 × stddev for three standard deviations above the aggregated value.*\
         scope: all          *# \[all, each\]; Which rows the aggregates are taken over: all for a straight line, or each, for a line that follows the data.*\
         line:          *# \[line style, look from layer.reference.line\]; The appearance of the line.*\
         label:          *# \[text style, look from layer.reference.label\]; The line's label.*\
-            text: None          *# \[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.*\
-            position: auto          *# \[auto, start_above, start_below, center_above, center_below, end_above, end_below\]; auto selects the first option that doesn't overlap the data and is invalid if inside is false.*\
+            text: None          *# \[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.*\
+            position: auto          *# \[auto, start_above, start_below, center_above, center_below, end_above, end_below\]; auto selects the first option that doesn't overlap the data, or with an equation, the first place along the line, and is invalid if inside is false.*\
             inside: true          *# \[true, false\]; Whether the label is inside the plot area. If false, it's beyond the plot area at the line's start or end, and a center position is invalid.*\
             format: auto          *# \[auto, format\]; The format of the value. auto uses the axis's tick label format if it's set, and otherwise one more decimal than the tick labels show. On a date axis, it uses the tick label format, which must then be set.*\
     line_2:          *# \[same as line_1\]; The second line.*\

{forgegraph-0.6.1 → forgegraph-0.7.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.6.1          *# \[text\]; The pack's release version.*\
+version: 0.7.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.6, <0.7"          *# \[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.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.*

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

@@ -45,7 +45,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
         y:\
             tick:\
                 label:          *# \[text style, look from axis.tick.label\]; The y-axis tick labels. Each parameter not set here is axis.tick.label's.*\
-        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.*\
             sides: \[left, bottom, top, right\]          *# \[left, right, top, bottom, None\]; The sides that have a border. If None, there is no border.*\

{forgegraph-0.6.1 → forgegraph-0.7.0}/examples/sample-data/README.md

@@ -32,6 +32,7 @@ cp -R examples/sample-data ~/forgegraph-trial
 | tips.csv | seaborn's tips | Mostly categories: day, time, sex, smoker, party size |
 | growth.csv | ChickWeight | 50 animals on 4 diets; some series end early; **diet is a number** (1–4) |
 | seaice.csv | seaborn's seaice | Daily dates; a month of missing values |
+| plate_spectra.csv | UV-Vis spectra of a plate | 60 samples at 76 wavelengths, in four families, for a heat map |
 | economics.csv | ggplot2's economics | Several monthly series in different units |
 | lab_export.xlsx | an instrument export | Summary sheet first; title rows above the header; a units row; `-` and `n/a` for missing; an Average row and "End of report" under the data |
 | lab_runs.xlsx | a LIMS run log | One row per instrument run over 15 weeks; title rows above the header; statuses typed inconsistently; runs still in progress; a total under the data; an Instruments sheet |