coeftable 0.1.0__tar.gz → 0.3.0__tar.gz

{coeftable-0.1.0 → coeftable-0.3.0}/.github/workflows/post-release.yml

@@ -4,6 +4,7 @@ on:
   release:
     types: [published]
   workflow_dispatch:
+  workflow_call:
 
 jobs:
   changelog:

coeftable-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish library
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v*"
+  workflow_call:
+    inputs:
+      ref:
+        description: "Git ref to build. Defaults to the triggering ref."
+        required: false
+        type: string
+      publish:
+        description: "Upload the built package to PyPI."
+        required: false
+        default: false
+        type: boolean
+  workflow_dispatch:
+
+jobs:
+  build-package:
+    runs-on: ubuntu-latest
+    permissions:
+      attestations: write
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # The version is derived from the tag by hatch-vcs, so the build
+          # must happen on the tag itself -- building the branch head would
+          # produce a development version instead of the release version.
+          ref: ${{ inputs.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: hynek/build-and-inspect-python-package@v2
+        with:
+          attest-build-provenance-github: true
+
+  publish:
+    runs-on: ubuntu-latest
+    # PyPI must have a trusted publisher registered for BOTH entry points,
+    # each with environment "publish": this workflow, for a manual run or a
+    # hand-pushed tag, and release.yml, for an automated release. Upload
+    # authentication matches on the reusable workflow, but the build
+    # provenance attestation carries the TOP-LEVEL workflow, so an automated
+    # release presents release.yml and is rejected with "does not match
+    # expected Trusted Publisher" unless that entry point is registered too.
+    #
+    # A tag pushed by a workflow using the default token does not raise a
+    # push event, so a release cut by automation asks for the upload
+    # explicitly. Any other run sitting on a tag -- a hand-pushed tag, or a
+    # manual run selecting one, which is how a stranded release gets
+    # published -- is also a release build. A run on a branch never is.
+    if: inputs.publish || startsWith(github.ref, 'refs/tags')
+    environment:
+      name: publish
+      url: https://pypi.org/p/coeftable
+    needs: build-package
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

coeftable-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,116 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump"
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+        default: patch
+      version:
+        description: "Explicit version override (e.g. 1.2.3) -- takes precedence over bump"
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.version.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Compute next version
+        id: version
+        env:
+          BUMP: ${{ inputs.bump }}
+          VERSION_OVERRIDE: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+
+          latest=$(git tag -l 'v*' --sort=-v:refname | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -n1 || true)
+          latest="${latest:-0.0.0}"
+
+          if [ -n "$VERSION_OVERRIDE" ]; then
+            next="${VERSION_OVERRIDE#v}"
+            if ! [[ "$next" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              echo "::error::Invalid version '$next' -- must be MAJOR.MINOR.PATCH"
+              exit 1
+            fi
+
+            IFS='.' read -r next_major next_minor next_patch <<< "$next"
+            IFS='.' read -r latest_major latest_minor latest_patch <<< "$latest"
+            if [ "$((next_major * 1000000 + next_minor * 1000 + next_patch))" -le \
+                 "$((latest_major * 1000000 + latest_minor * 1000 + latest_patch))" ]; then
+              echo "::error::Explicit version '$next' is not greater than the latest release 'v$latest'"
+              exit 1
+            fi
+          else
+            IFS='.' read -r major minor patch <<< "$latest"
+            case "$BUMP" in
+              major) next="$((major + 1)).0.0" ;;
+              minor) next="${major}.$((minor + 1)).0" ;;
+              patch) next="${major}.${minor}.$((patch + 1))" ;;
+              *) echo "::error::Unknown bump type '$BUMP'"; exit 1 ;;
+            esac
+          fi
+
+          tag="v${next}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "::error::Tag $tag already exists"
+            exit 1
+          fi
+
+          echo "Latest: v$latest -> Next: $tag"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ steps.version.outputs.tag }}" -m "Release ${{ steps.version.outputs.tag }}"
+          git push origin "${{ steps.version.outputs.tag }}"
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "${{ steps.version.outputs.tag }}" --generate-notes
+
+  publish:
+    # Called directly rather than left to the tag-push trigger on the publish
+    # workflow: the tag above is pushed with the workflow token, and GitHub
+    # does not raise workflow-triggering events for it.
+    needs: tag
+    uses: ./.github/workflows/publish.yml
+    permissions:
+      attestations: write
+      contents: read
+      id-token: write
+    with:
+      ref: ${{ needs.tag.outputs.tag }}
+      publish: true
+
+  changelog:
+    # Same reason as the publish job above: the release is created with the
+    # workflow token, so its published event never reaches the changelog
+    # workflow. Runs after the release exists, since the changelog is built
+    # from the published release notes.
+    needs: tag
+    uses: ./.github/workflows/post-release.yml
+    permissions:
+      contents: write
+      pull-requests: write

{coeftable-0.1.0 → coeftable-0.3.0}/.gitignore

@@ -16,3 +16,5 @@ src/coeftable/_version.py
 .kata.local.toml
 # roborev snapshots
 /.roborev/
+# internal planning docs (not shipped, not for the public repo)
+docs/superpowers/

coeftable-0.3.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+<a id="v0.2.1"></a>
+# [v0.2.1](https://github.com/kylejcaron/coeftable/releases/tag/v0.2.1) - 2026-08-05
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.2.1 -->
+
+## What's Changed
+### Maintenance
+* Update changelog for v0.2.0 by [@github-actions](https://github.com/github-actions)[bot] in [#11](https://github.com/kylejcaron/coeftable/pull/11)
+* Publish releases to PyPI automatically by [@kylejcaron](https://github.com/kylejcaron) in [#12](https://github.com/kylejcaron/coeftable/pull/12)
+
+## New Contributors
+* [@github-actions](https://github.com/github-actions)[bot] made their first contribution in [#11](https://github.com/kylejcaron/coeftable/pull/11)
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.2.0...v0.2.1
+
+[Changes][v0.2.1]
+
+
+<a id="v0.2.0"></a>
+# [v0.2.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.2.0) - 2026-08-04
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.2.0 -->
+
+## What's Changed
+### Maintenance
+* ci: add workflow_dispatch release workflow with semver bump by [@kylejcaron](https://github.com/kylejcaron) in [#7](https://github.com/kylejcaron/coeftable/pull/7)
+* Sparkline column: inline line plots with uncertainty by [@kylejcaron](https://github.com/kylejcaron) in [#10](https://github.com/kylejcaron/coeftable/pull/10)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.1.0...v0.2.0
+
+[Changes][v0.2.0]
+
+
+<a id="v0.1.0"></a>
+# [v0.1.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.1.0) - 2026-07-28
+
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+## What's Changed
+### Maintenance
+* chore: install pre-commit hooks during setup by [@kylejcaron](https://github.com/kylejcaron) in [#1](https://github.com/kylejcaron/coeftable/pull/1)
+* ci: drop redundant lint and typecheck jobs by [@kylejcaron](https://github.com/kylejcaron) in [#2](https://github.com/kylejcaron/coeftable/pull/2)
+* Theming by [@kylejcaron](https://github.com/kylejcaron) in [#3](https://github.com/kylejcaron/coeftable/pull/3)
+* docs patch: restore Parameters section header on Forest docstring by [@kylejcaron](https://github.com/kylejcaron) in [#4](https://github.com/kylejcaron/coeftable/pull/4)
+* chore: complete package metadata for PyPI publishing by [@kylejcaron](https://github.com/kylejcaron) in [#5](https://github.com/kylejcaron/coeftable/pull/5)
+* docs: add hero image, fix stale theming section in README by [@kylejcaron](https://github.com/kylejcaron) in [#6](https://github.com/kylejcaron/coeftable/pull/6)
+
+## New Contributors
+* [@kylejcaron](https://github.com/kylejcaron) made their first contribution in [#1](https://github.com/kylejcaron/coeftable/pull/1)
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/commits/v0.1.0
+
+[Changes][v0.1.0]
+
+
+[v0.2.1]: https://github.com/kylejcaron/coeftable/compare/v0.2.0...v0.2.1
+[v0.2.0]: https://github.com/kylejcaron/coeftable/compare/v0.1.0...v0.2.0
+[v0.1.0]: https://github.com/kylejcaron/coeftable/tree/v0.1.0
+
+<!-- Generated by https://github.com/rhysd/changelog-from-release v3.9.1 -->

coeftable-0.3.0/PKG-INFO

@@ -0,0 +1,405 @@
+Metadata-Version: 2.4
+Name: coeftable
+Version: 0.3.0
+Summary: Publication-quality summary tables for estimates with uncertainty.
+Project-URL: Homepage, https://github.com/kylejcaron/coeftable
+Project-URL: Repository, https://github.com/kylejcaron/coeftable
+Project-URL: Issues, https://github.com/kylejcaron/coeftable/issues
+Author-email: Kyle Caron <kyle.j.caron@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Kyle Caron
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: confidence-interval,forest-plot,great-tables,statistics,tables
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Requires-Dist: great-tables>=0.22
+Requires-Dist: narwhals>=2.24
+Provides-Extra: dev
+Requires-Dist: nox>=2025.5; extra == 'dev'
+Requires-Dist: pandas>=2.2; extra == 'dev'
+Requires-Dist: polars>=1.0; extra == 'dev'
+Requires-Dist: prek>=0.4.5; extra == 'dev'
+Requires-Dist: pyarrow>=25.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Requires-Dist: ty>=0.0.49; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# coeftable
+
+Lightweight, report-ready summary tables for estimates with uncertainty. Renders
+inline forest plots, builds on great_tables HTML output, and works with pandas,
+polars, or pyarrow frames.
+
+![Rendered experiment results table with grouped sections, nested variants, and an inline forest plot](docs/images/example.png)
+
+## Installation
+
+```bash
+uv add coeftable
+```
+
+## Quick start
+
+The one-line form declares a table with a single estimate column:
+
+```python
+import polars as pl
+import coeftable as ct
+
+df = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "est": [3.4, 0.5],
+        "lb": [1.2, -1.0],
+        "ub": [5.7, 2.0],
+    }
+)
+
+ct.CoefTable(df, rows="metric", estimate="est", ci=("lb", "ub"))
+```
+
+A `CoefTable` renders itself in marimo, Jupyter, and any other `_repr_html_`-aware viewer —
+leave it as the last expression in a cell, no extra call needed. Outside a notebook,
+`table.as_raw_html()` is the HTML string entry point. `.gt()` remains the escape hatch to the
+underlying [great_tables](https://posit-dev.github.io/great-tables/) object itself:
+`table.gt().save("t.png")` for an image, `table.gt().tab_options(...)` to keep styling with
+great_tables' own API.
+
+## Data shape
+
+coeftable expects a dataframe where every row is a single comparison. The
+resolution logic maps pairs of upper / lower bound columns to each estimate, so
+your data should be **wide in triples** — one point-estimate column and (when
+applicable) its lower and upper bound columns — rather than in long format with
+a `parameter` column.
+
+**Dimensions:**
+- `rows` — the label for each row in the table (e.g. a metric name).
+- `nest` — an optional secondary label stacked below each row.
+- `groups` — an optional column whose values produce section headers. Pass
+  `collapsible_groups=True` to make those sections collapsible in the rendered
+  HTML — a pure CSS toggle (relies on `:has()`, Baseline since late 2023; on an
+  older browser without it the toggle no-ops and sections stay expanded), no
+  JavaScript, sections start expanded. Applies to `as_raw_html()`/`_repr_html_`;
+  `.gt()` is unaffected.
+- `split_columns` — an optional column whose values produce repeated column
+  groups side by side, useful for comparing methods.
+
+**Series columns bend this rule.** A point estimate is one number (plus
+bounds), so a triple of scalar columns holds it. A `.sparkline(...)` series
+is N points, not one -- most naturally via the companion-frame door, a
+separate long frame with one row per point, joined by the table's row/nest/
+split keys. Or, when the series is already collapsed onto its row, its
+`value` / `ci` columns can instead hold a *list* per row directly. Either
+way a row of the table is still one row; the series column just carries
+more data per row than an estimate column does. See
+[Trend over time](#trend-over-time) for both shapes.
+
+## Experiment table
+
+Build a complete experiment results table with multiple estimates, a forest
+plot column, grouped row sections, nested variants, and direction hints:
+
+```python
+import polars as pl
+import coeftable as ct
+
+experiment = pl.DataFrame(
+    {
+        "area": ["Core", "Core", "Ops", "Ops"],
+        "metric": ["Revenue", "Revenue", "Latency", "Latency"],
+        "variant": ["B", "C", "B", "C"],
+        "att": [12400.0, -3100.0, 40.0, 120.0],
+        "att_lb": [4200.0, -9800.0, -80.0, 45.0],
+        "att_ub": [20600.0, 3600.0, 160.0, 195.0],
+        "rel": [3.4, -1.2, 0.5, 2.0],
+        "rel_lb": [1.2, -4.0, -1.0, 0.8],
+        "rel_ub": [5.7, 1.6, 2.0, 3.2],
+    }
+)
+
+(
+    ct.CoefTable(experiment, rows="metric", nest="variant", groups="area")
+    .estimate("Lift Amount", "att", ci=("att_lb", "att_ub"), fmt=ct.Number(compact=True))
+    .estimate("Lift %", "rel", ci=("rel_lb", "rel_ub"), fmt=ct.Percent(signed=True))
+    .forest("Lift Plot", of="Lift %", ref=0.0, symmetric=True)
+    .header("Experiment Results", "Example Experiment")
+    .with_direction({"Latency": "lower_is_better"})
+)
+```
+
+## Comparing methods
+
+Use `split_columns` to compare multiple methods side by side. Each value in the
+split column produces its own set of estimate / forest columns:
+
+```python
+import polars as pl
+import coeftable as ct
+
+methods = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Revenue", "Latency", "Latency"],
+        "method": ["A", "B", "A", "B"],
+        "est": [3.4, 3.1, 0.5, 0.6],
+        "lb": [1.2, 1.0, -1.0, -0.8],
+        "ub": [5.7, 5.2, 2.0, 2.1],
+    }
+)
+
+(
+    ct.CoefTable(
+        methods, rows="metric", split_columns="method", estimate="est", ci=("lb", "ub")
+    ).header("Cohort Revenue by Method")
+)
+```
+
+## Theming
+
+Four built-in themes are available from `coeftable.theme`:
+
+```python
+from coeftable.theme import BLUE, COLORBLIND, DEFAULT, MONO, TEXTUAL
+
+DEFAULT  # Alias for TEXTUAL -- what CoefTable uses if you don't set a theme
+TEXTUAL  # Minimal, publication-style: muted colours, light chrome
+BLUE  # The original blue-grey palette
+COLORBLIND  # Colourblind-safe palette
+MONO  # Grayscale for mono journals
+```
+
+Apply one with `.with_theme(...)`:
+
+```python
+table.with_theme(BLUE)
+```
+
+Customise a theme with `dataclasses.replace`:
+
+```python
+from dataclasses import replace
+
+my_theme = replace(BLUE, favorable="#0072B2")
+```
+
+Use `with_direction` to mark rows where lower values are favourable (reusing
+the `df` frame from [Quick start](#quick-start)):
+
+```python
+table = ct.CoefTable(df, rows="metric", estimate="est", ci=("lb", "ub")).with_direction(
+    {"Latency": "lower_is_better"}
+)
+```
+
+## Trend over time
+
+![Rendered experiment results table with a 30-day trend column showing favorable, unfavorable, and inconclusive series with narrowing uncertainty bands](docs/images/trend-example.png)
+
+Add a `.sparkline(...)` column to plot a metric's trajectory next to its
+point estimate: an inline SVG line with a shaded credible interval and a
+dashed reference line (pass `show_endpoint=True` to also label the last
+value). Below, `ref=0.0` draws the reference line that Latency's series
+crosses as its credible interval narrows over three weeks of data:
+
+There are two front doors for the series data, the same list-columns vs.
+companion-frame choice used elsewhere in coeftable:
+
+**A long companion frame** — the shape most real series data already
+arrives in: a SQL export, a dbt model, an experimentation platform's daily
+metrics table. Pass `data=` a separate frame with one row per point, and
+`value` / `ci` / `x` name *scalar* columns on it. coeftable groups the
+companion frame by the table's `rows` (+ `nest`, + `split_columns`) keys
+and collapses each group into a series internally:
+
+```python
+import datetime as dt
+import pandas as pd
+import polars as pl
+import coeftable as ct
+
+dates = [dt.date(2024, 1, 1), dt.date(2024, 1, 8), dt.date(2024, 1, 15)]
+
+trend = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "lift": [3.4, 0.5],
+        "lift_lb": [1.2, -1.0],
+        "lift_ub": [5.7, 2.0],
+    }
+)
+
+history = pd.DataFrame(
+    {
+        "metric": ["Revenue", "Revenue", "Revenue", "Latency", "Latency", "Latency"],
+        "date": dates + dates,
+        "lift": [1.5, 2.4, 3.4, -1.0, 0.2, 1.5],
+        "lift_lb": [0.3, 1.4, 2.6, -2.5, -0.6, 1.0],
+        "lift_ub": [2.7, 3.4, 4.2, 0.5, 1.0, 2.0],
+    }
+)
+
+(
+    ct.CoefTable(trend, rows="metric")
+    .estimate("Lift %", "lift", ci=("lift_lb", "lift_ub"), fmt=ct.Percent(signed=True))
+    .sparkline(
+        "Trend",
+        value="lift",
+        ci=("lift_lb", "lift_ub"),
+        x="date",
+        data=history,
+        ref=0.0,
+        axis_fmt=ct.DateAxis(),
+    )
+)
+```
+
+**List columns on the main frame** — if the series is already collapsed
+onto its row (e.g. from a prior `.group_by(...).agg(...)`, or a source that
+natively stores arrays), `value` / `ci` / `x` can instead name columns
+whose cells each hold one list of points per row:
+
+```python
+import datetime as dt
+import polars as pl
+import coeftable as ct
+
+dates = [dt.date(2024, 1, 1), dt.date(2024, 1, 8), dt.date(2024, 1, 15)]
+
+trend = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "lift": [3.4, 0.5],
+        "lift_lb": [1.2, -1.0],
+        "lift_ub": [5.7, 2.0],
+        "history": [
+            [1.5, 2.4, 3.4],
+            [-1.0, 0.2, 1.5],
+        ],
+        "history_lb": [
+            [0.3, 1.4, 2.6],
+            [-2.5, -0.6, 1.0],
+        ],
+        "history_ub": [
+            [2.7, 3.4, 4.2],
+            [0.5, 1.0, 2.0],
+        ],
+        "date": [dates, dates],
+    }
+)
+
+(
+    ct.CoefTable(trend, rows="metric")
+    .estimate("Lift %", "lift", ci=("lift_lb", "lift_ub"), fmt=ct.Percent(signed=True))
+    .sparkline(
+        "Trend",
+        value="history",
+        ci=("history_lb", "history_ub"),
+        x="date",
+        ref=0.0,
+        axis_fmt=ct.DateAxis(),
+    )
+)
+```
+
+Both render the same column. Reach for the companion frame first — it
+matches how most series data actually arrives, one row per observation.
+Reach for list columns only when the series is already collapsed onto its
+row.
+
+Since `x` is always shared table-wide (dates must line up across rows), a
+series with fewer points than its neighbours visibly occupies only part of
+its cell's width rather than stretching to fill it — this is intentional,
+not a bug: `x` position reflects where a point falls in the shared domain,
+never the row's own extent.
+
+Want a plain trend line with no uncertainty band — no `ci`, no ribbon?
+great_tables' own `.gt().fmt_nanoplot(...)` covers that directly.
+`.sparkline(...)` exists specifically for the estimate-with-interval case.
+
+**Shaping the y-axis.** Each row's domain fits tightly to its own data by
+default (`scale="row"`, `autoscale="tight"`). Four ways to change that,
+shown together against the same noisy series:
+
+```python
+import polars as pl
+import coeftable as ct
+
+trend = pl.DataFrame(
+    {
+        "metric": ["Revenue"],
+        "lift": [[1.0, 1.05, 0.95, 1.02, 0.98, 300.0]],
+    }
+)
+
+(
+    ct.CoefTable(trend, rows="metric")
+    # Default: fits tightly to this row's own min/max. A single outlier
+    # like the 300.0 here dominates and flattens the rest of the series.
+    .sparkline("Tight (default)", value="lift", ref=1.0)
+    # autoscale="robust" fits an IQR/Tukey fence instead of raw min/max,
+    # so the outlier doesn't flatten the rest. It still draws -- clipped
+    # to the domain edge and flagged with a clip-cap marker, never hidden.
+    .sparkline("Robust", value="lift", ref=1.0, autoscale="robust")
+    # max_ylim=N narrows whatever domain scale/autoscale would have
+    # produced -- clamping to `ref +/- N`, only if the natural domain
+    # would have exceeded that ceiling. Composes with autoscale.
+    .sparkline("Ceiling", value="lift", ref=1.0, max_ylim=0.5)
+    # ylim=(lo, hi) is an absolute override, replacing scale/autoscale/
+    # max_ylim entirely.
+    .sparkline("Override", value="lift", ref=1.0, ylim=(0.9, 1.1))
+)
+```
+
+**No reference, or a hidden one.** `ref` also drives the dashed line and
+colour resolution; two ways to opt out, for data with no meaningful
+zero (revenue, durations, absolute counts):
+
+```python
+absolute = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "value": [[282.3, 300.1, 320.0], [900.0, 910.0, 920.0]],
+    }
+)
+
+(
+    ct.CoefTable(absolute, rows="metric")
+    # ref=None: no reference at all. No dashed line, no forced domain
+    # inclusion of 0, and every cell colours neutral -- "favorable" has
+    # no meaning without something to compare against.
+    .sparkline("No reference", value="value", ref=None)
+    # ref=0.0, show_ref=False: the reference is real and still drives
+    # colour (favorable/unfavorable against 0), it just isn't drawn or
+    # forced into the domain. Opt in deliberately: a mark can then claim
+    # "above the reference" while the reference sits off-canvas.
+    .sparkline("Hidden reference", value="value", ref=0.0, show_ref=False)
+)
+```