forgegraph 0.6.0__tar.gz → 0.6.1__tar.gz

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

@@ -2,6 +2,17 @@
 
 ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written.
 
+## 0.6.1 (2026-10-31)
+
+### Changes
+
+- **A reference line for each look.** With `per_series`, a reference layer now draws a line for each look its series are drawn in: each color, marker shape, marker fill and line style. Before, groups that differed only in marker shape, fill or line style shared one line. Lines that `split` draws, such as replicates, still share one.
+- **Guides on the documentation site.** The site now has a guide to each part of ForgeGraph, a gallery of worked examples, help with every lint issue and common error, and the release notes.
+
+### Bug Fixes
+
+- `per_series` with series colored on a scale is now an error. Before, it drew a single line over all the rows in the palette's first color.
+
 ## 0.6.0 (2026-10-30)
 
 ### New Features

{forgegraph-0.6.0 → forgegraph-0.6.1}/CONTRIBUTING.md

@@ -33,7 +33,7 @@ uv run python scripts/build_recreations.py --baselines
 
 ## The documentation site
 
-The site is built with MkDocs from docs/site. Its Reference pages are generated as it's built: the commands from the CLI, the specifications and the built-in pack from their files, and the Python API from the docstrings (scripts/docs_site.py). To build it and read it while you work:
+The site is built with MkDocs from docs/site. Its Reference pages are generated as it's built: the commands from the CLI, the specifications and the built-in pack from their files, and the Python API from the docstrings (scripts/docs_site.py). The guides' and gallery's graphs are drawn as it's built, from the GraphSpecs, layouts and pack in docs/examples and the layouts in examples/layouts, with data from examples/sample-data, so an example that can't be drawn standard and lint-clean fails the build. To build it and read it while you work:
 
 ```bash
 uv run --group docs mkdocs serve

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.6.0
+Version: 0.6.1
 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
@@ -172,6 +172,7 @@ ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICE
 
 ## Documentation
 
+- [Documentation site](https://sskaye.github.io/forgegraph/): getting started, and a reference for every specification, command and Python function.
 - [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specifications): the file that defines each kind of spec, every parameter with its default, range and description.
 - [Built-in pack](https://github.com/sskaye/forgegraph/blob/main/docs/packs/forgegraph_default): forgegraph_default's specs.
 - [Changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md).

{forgegraph-0.6.0 → forgegraph-0.6.1}/README.md

@@ -142,6 +142,7 @@ ForgeGraph is [MIT-licensed](https://github.com/sskaye/forgegraph/blob/main/LICE
 
 ## Documentation
 
+- [Documentation site](https://sskaye.github.io/forgegraph/): getting started, and a reference for every specification, command and Python function.
 - [Specifications](https://github.com/sskaye/forgegraph/blob/main/docs/specifications): the file that defines each kind of spec, every parameter with its default, range and description.
 - [Built-in pack](https://github.com/sskaye/forgegraph/blob/main/docs/packs/forgegraph_default): forgegraph_default's specs.
 - [Changelog](https://github.com/sskaye/forgegraph/blob/main/CHANGELOG.md).

forgegraph-0.6.1/docs/examples/acme_polarization.yaml

@@ -0,0 +1,24 @@
+name: acme_polarization
+version: 0
+description: The polarization curves in the example acme pack's theme and slide format.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: acme/acme
+        format: acme/slide
+    text:
+        title: Polarization curves
+    data:
+        file: cell_polarization.parquet
+        preprocessing: examples/sample-data/cell_polarization.csv, unchanged
+    axis:
+        x:
+            data:
+                column: current_density_a_cm2
+            title: Current density (A/cm^2)
+        y:
+            title: Voltage (V)
+    series:
+        voltage_v:
+            color: cell

forgegraph-0.6.1/docs/examples/assay_summary.yaml

@@ -0,0 +1,33 @@
+name: assay_summary
+version: 0
+description: Each compound's mean response at each dose, with error bars from the standard deviations in the data.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Dose response
+    data:
+        file: assay_summary.parquet
+        preprocessing: examples/sample-data/assay_summary.csv, unchanged
+    axis:
+        x:
+            data:
+                column: dose_uM
+                type: categorical
+            title: Dose (µM)
+        y:
+            title: Response (%)
+    series:
+        mean_response_pct:
+            color: compound
+    layers:
+        spread:
+            type: error_bar
+            value:
+                lower: sd_pct
+                upper: sd_pct
+                aggregation:
+                    function: None

forgegraph-0.6.1/docs/examples/cells.layout.yaml

@@ -0,0 +1,26 @@
+name: cells
+version: 0
+description: The fuel cells' graphs under one tab, beside a tab of the CO₂ record.
+extends: forgegraph_default/layout
+
+parameters:
+    specifications:
+        format: forgegraph_default/compact_format
+    tabs:
+        Cells:
+            tabs:
+                Polarization:
+                    grid:
+                        areas: [[curves]]
+                    tiles:
+                        curves: polarization.yaml
+                Durability:
+                    grid:
+                        areas: [[voltage]]
+                    tiles:
+                        voltage: durability.yaml
+        CO2:
+            grid:
+                areas: [[record]]
+            tiles:
+                record: co2.yaml

forgegraph-0.6.1/docs/examples/co2.yaml

@@ -0,0 +1,28 @@
+name: co2
+version: 0
+description: Monthly CO₂ at Mauna Loa, on a date axis, with the line broken where a month is missing.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Atmospheric CO_{2}
+    data:
+        file: co2_monthly.parquet
+        preprocessing: examples/sample-data/co2_monthly.csv, with its dates read as dates and -99.99 as missing
+    axis:
+        x:
+            data:
+                column: date
+            title: None
+        y:
+            title: CO_{2} (ppm)
+    series:
+        Monthly mean:
+            column: co2_ppm
+            marker:
+                show: false
+            line:
+                missing_values: gap

forgegraph-0.6.1/docs/examples/dose_response.yaml

@@ -0,0 +1,33 @@
+name: dose_response
+version: 0
+description: The mean response of three compounds at each dose, with error bars of one standard deviation and a note.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Dose response
+    data:
+        file: dose_response.parquet
+        preprocessing: examples/sample-data/dose_response.csv, unchanged
+    axis:
+        x:
+            data:
+                column: dose_uM
+                type: categorical
+            title: Dose (µM)
+        y:
+            title: Response (%)
+    series:
+        response_pct:
+            aggregation:
+                function: mean
+            color: compound
+    layers:
+        spread:
+            type: error_bar
+        replicates:
+            type: note
+            text: Mean ± SD of 3 replicates

forgegraph-0.6.1/docs/examples/durability.yaml

@@ -0,0 +1,26 @@
+name: durability
+version: 0
+description: Each cell's voltage over a 200-hour durability test, as lines without markers.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Durability test
+    data:
+        file: cell_durability.parquet
+        preprocessing: examples/sample-data/cell_durability.csv, unchanged
+    axis:
+        x:
+            data:
+                column: hours
+            title: Time (h)
+        y:
+            title: Voltage (V)
+    series:
+        voltage_v:
+            color: cell
+            marker:
+                show: false

forgegraph-0.6.1/docs/examples/lab_polarization.yaml

@@ -0,0 +1,24 @@
+name: lab_polarization
+version: 0
+description: The polarization curves in the lab pack's theme and poster format.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: lab/lab_theme
+        format: lab/poster
+    text:
+        title: Polarization curves
+    data:
+        file: cell_polarization.parquet
+        preprocessing: examples/sample-data/cell_polarization.csv, unchanged
+    axis:
+        x:
+            data:
+                column: current_density_a_cm2
+            title: Current density (A/cm^2)
+        y:
+            title: Voltage (V)
+    series:
+        voltage_v:
+            color: cell

forgegraph-0.6.1/docs/examples/packs/lab/formats/poster.yaml

@@ -0,0 +1,11 @@
+name: poster
+version: 0
+description: A graph for a poster, wider than the built-in compact format and with larger text.
+extends: forgegraph_default/compact_format
+
+parameters:
+    figure:
+        width: 200
+        base_size: 22
+    output:
+        file_types: [png, pdf]

forgegraph-0.6.1/docs/examples/packs/lab/pack.yaml

@@ -0,0 +1,5 @@
+name: lab
+version: 1.0.0
+description: A lab's house style, for the guide to themes, formats and packs.
+issues: https://github.com/sskaye/forgegraph/issues
+requires: ">=0.6, <1"

forgegraph-0.6.1/docs/examples/packs/lab/themes/lab_theme.yaml

@@ -0,0 +1,13 @@
+name: lab_theme
+version: 0
+description: The lab's look, the built-in theme with Paul Tol's bright colors and horizontal grid lines.
+extends: forgegraph_default/light_theme
+
+parameters:
+    series:
+        colors: tol_bright
+    grid:
+        y:
+            show: true
+    title:
+        weight: bold

forgegraph-0.6.1/docs/examples/penguins.yaml

@@ -0,0 +1,29 @@
+name: penguins
+version: 0
+description: Bill depth against bill length for three penguin species, as markers colored and shaped by species.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Penguin bills
+    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:
+        bill_depth_mm:
+            color: species
+            line:
+                show: false
+            marker:
+                shape: species
+                size: 0.3

forgegraph-0.6.1/docs/examples/polarization.yaml

@@ -0,0 +1,24 @@
+name: polarization
+version: 0
+description: Polarization curves of three fuel cells, voltage against current density.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Polarization curves
+    data:
+        file: cell_polarization.parquet
+        preprocessing: examples/sample-data/cell_polarization.csv, unchanged
+    axis:
+        x:
+            data:
+                column: current_density_a_cm2
+            title: Current density (A/cm^2)
+        y:
+            title: Voltage (V)
+    series:
+        voltage_v:
+            color: cell

forgegraph-0.6.1/docs/examples/savings.yaml

@@ -0,0 +1,58 @@
+name: savings
+version: 0
+description: The personal savings rate by month, with a line at its mean and a band one standard deviation either side.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Personal savings rate
+    data:
+        file: economics.parquet
+        preprocessing: examples/sample-data/economics.csv, with its dates read as dates
+    axis:
+        x:
+            data:
+                column: date
+            title: None
+        y:
+            title: Savings rate (%)
+    series:
+        Savings rate:
+            column: psavert
+            marker:
+                show: false
+    layers:
+        spread:
+            type: reference
+            axis: y
+            line_1:
+                value: psavert
+                aggregation:
+                    function: mean
+                offset:
+                    function: stddev
+                    multiplier: -1
+                line:
+                    style: None
+            line_2:
+                value: psavert
+                aggregation:
+                    function: mean
+                offset:
+                    function: stddev
+                line:
+                    style: None
+        mean:
+            type: reference
+            axis: y
+            line_1:
+                value: psavert
+                aggregation:
+                    function: mean
+                label:
+                    text: aggregation_value
+                    position: end_above
+                    inside: false

forgegraph-0.6.1/docs/examples/tips_side_by_side.yaml

@@ -0,0 +1,46 @@
+name: tips_side_by_side
+version: 0
+description: The mean tip on each day, for women and men side by side, with the 95 % confidence interval of each mean.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Tips by day
+    data:
+        file: tips.parquet
+        preprocessing: examples/sample-data/tips.csv, unchanged
+    axis:
+        x:
+            data:
+                column: day
+                order:
+                    method: value
+                    direction: descending
+            title: None
+        y:
+            title: Mean tip ($)
+    arrangement:
+        offset: side_by_side
+    legend:
+        key:
+            inside: false
+    series:
+        tip:
+            aggregation:
+                function: mean
+            color: sex
+            line:
+                show: false
+            marker:
+                show: false
+            bar:
+                show: true
+    layers:
+        spread:
+            type: error_bar
+            value:
+                aggregation:
+                    function: ci

forgegraph-0.6.1/docs/examples/tips_stacked.yaml

@@ -0,0 +1,42 @@
+name: tips_stacked
+version: 0
+description: The total of the bills on each day, stacked by lunch and dinner, with each day's total written above.
+extends: None
+parameters: !var
+    specifications:
+        graph_type: xy
+        theme: forgegraph_default/light_theme
+        format: forgegraph_default/compact_format
+    text:
+        title: Bills by day
+    data:
+        file: tips.parquet
+        preprocessing: examples/sample-data/tips.csv, unchanged
+    axis:
+        x:
+            data:
+                column: day
+                order:
+                    method: value
+                    direction: descending
+            title: None
+        y:
+            title: Total of the bills ($)
+    arrangement:
+        stacking: sum
+        total:
+            show: true
+    legend:
+        key:
+            inside: false
+    series:
+        total_bill:
+            aggregation:
+                function: sum
+            color: time
+            line:
+                show: false
+            marker:
+                show: false
+            bar:
+                show: true

{forgegraph-0.6.0 → forgegraph-0.6.1}/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.0          *# \[text\]; The pack's release version.*\
+version: 0.6.1          *# \[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.*

forgegraph-0.6.1/docs/site/gallery.md

@@ -0,0 +1,123 @@
+# Gallery
+
+Worked examples, each drawn from its GraphSpec as this site is built. The data is the [sample data](https://github.com/sskaye/forgegraph/tree/main/examples/sample-data) in the repository: synthetic look-alikes of the datasets data-visualization tutorials use, saved as Parquet. Open a GraphSpec to see how the graph is made; the [guides](guides/graphs.md) explain each part.
+
+## Lines and markers
+
+Polarization curves of three fuel cells, one line for each cell, named beside it. Data: cell_polarization.csv.
+
+![Voltage against current density for cells A, B and C.](images/polarization.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/polarization.yaml"
+    ```
+
+## Lines over time
+
+Each cell's voltage over a 200-hour durability test, as lines without markers. Data: cell_durability.csv.
+
+![Each cell's voltage over 200 hours.](images/durability.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/durability.yaml"
+    ```
+
+## Dates
+
+Monthly CO₂ at Mauna Loa on a date axis, with the line broken where a month is missing. Data: co2_monthly.csv, with its dates read as dates and −99.99, which marks a missing month, read as missing.
+
+![Monthly CO2 from 1958, rising with a yearly cycle.](images/co2.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/co2.yaml"
+    ```
+
+## Groups by color and shape
+
+Bill depth against bill length for three penguin species, as markers with a color and a shape for each species. Data: penguins.csv.
+
+![Bill depth against bill length, a color and shape for each species.](images/penguins.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/penguins.yaml"
+    ```
+
+## Stacked bars
+
+The total of the bills on each day, stacked by lunch and dinner, with each day's total, and the days in order of their totals. Data: tips.csv.
+
+![Bars of the total bills on each day, dinner and lunch stacked.](images/tips_stacked.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/tips_stacked.yaml"
+    ```
+
+## Bars side by side, with error bars
+
+The mean tip on each day, for women and men side by side, each with the 95 % confidence interval of its mean. Data: tips.csv.
+
+![Bars of the mean tip on each day, women and men side by side, with error bars.](images/tips_side_by_side.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/tips_side_by_side.yaml"
+    ```
+
+## Error bars and a note
+
+Three compounds' mean response at each dose, with error bars of one standard deviation of the replicates, and a note saying so. Data: dose_response.csv.
+
+![The mean response of three compounds at each dose, with error bars and a note.](images/dose_response.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/dose_response.yaml"
+    ```
+
+## A reference line and band
+
+The personal savings rate by month, with a line at its mean, labelled outside the plot, and a band one standard deviation either side. Data: economics.csv, with its dates read as dates.
+
+![The savings rate by month, with a band around the mean and a dashed line at it.](images/savings.png){ width="480" }
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/savings.yaml"
+    ```
+
+## A dashboard
+
+The Overview tab of a lab's throughput dashboard, from [examples/layouts/dashboard](https://github.com/sskaye/forgegraph/tree/main/examples/layouts/dashboard). Its other tab shows the runs on each instrument.
+
+![Completed runs per week across the top, with failed runs, samples per week and run time below.](images/lab_throughput-overview.png)
+
+??? example "Layout"
+
+    ```yaml
+    --8<-- "examples/layouts/dashboard/lab_throughput.layout.yaml"
+    ```
+
+## A house style
+
+The polarization curves in the example acme pack's theme, a serif look with a light grid and no box, and its 16:9 slide format. Its parameters differ from the first example's only in the theme and format. The pack is in [examples/packs/acme](https://github.com/sskaye/forgegraph/tree/main/examples/packs/acme).
+
+![The polarization curves in a serif font with a light grid, on a wide slide.](images/acme_polarization.png)
+
+??? example "GraphSpec"
+
+    ```yaml
+    --8<-- "docs/examples/acme_polarization.yaml"
+    ```

forgegraph-0.6.1/docs/site/guides/configs.md

@@ -0,0 +1,38 @@
+# Configs
+
+A **config** lists the packs that may be used: their themes, formats, GraphSpecs, layouts and schedules. It's how a person or an organization requires its house style, and how a graph made outside it is marked.
+
+```toml
+packs = ["forgegraph_default", "./lab"]
+```
+
+Built-in and pip packs are listed by name, and folder packs by their path from the config file. `forgegraph schema config` lists the settings.
+
+## The main config and folder configs
+
+- **The main config**, `~/.config/forgegraph/config.toml` on every platform, or the file the `FORGEGRAPH_CONFIG` environment variable names, applies to all work. ForgeGraph writes it, listing the built-in pack, the first time a command reads the configs, such as `catalog` or `render`, and never overwrites it.
+- **A folder config**, `forgegraph.toml`, applies to the files in its folder and in every folder below it. A file uses the nearest one: in its own folder, or else in the closest folder above it.
+
+When both apply, a file may use only the packs the folder config lists. The configs are found from the file being drawn, not from the folder a command is run in, so a scheduled run is checked the same way as one by hand. `forgegraph catalog` and `forgegraph pack-notes` take `--folder` to show what may be used in another folder.
+
+The example paper figure's folder has a config listing the built-in pack and its own journal pack:
+
+```toml
+--8<-- "examples/layouts/paper/forgegraph.toml"
+```
+
+## Non-standard graphs
+
+A pack that a folder config lists but the main config doesn't still works, but it's **non-standard**: whatever is drawn with it is watermarked, the record saved in the file names the pack, and ForgeGraph's commands say so:
+
+```text
+Non-standard: pack 'acme' isn't in the main config (~/.config/forgegraph/config.toml), so whatever is drawn with it is watermarked
+```
+
+That way you can make and try a pack without changing an organization's main config, and nothing drawn with it passes as standard. List the pack in the main config to draw it as standard. A folder config can't give a pack the name of one the main config lists or a built-in pack's, so a folder can't swap an organization's pack for its own copy.
+
+What's drawn on `fg.blank`, a themed canvas for drawing with matplotlib what no graph type can, is always non-standard, and watermarked the same way.
+
+## Building on other packs
+
+A config limits what a drawn file may name, not what a pack may build on. A pack's specs may extend specs in any pack a config that applies lists, or in an installed pip pack, even one a GraphSpec may not use. A spec made by extending is usable only if its own pack is allowed.