coeftable 0.1.0__tar.gz → 0.2.1__tar.gz

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

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

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

@@ -0,0 +1,60 @@
+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
+    # 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.2.1/.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.2.1}/.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.2.1/CHANGELOG.md

@@ -0,0 +1,42 @@
+<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.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.1.0 → coeftable-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -45,6 +45,7 @@ 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'
@@ -91,6 +92,31 @@ leave it as the last expression in a cell, no extra call needed. Outside a noteb
 object: `table.gt().as_raw_html()` for an HTML string, `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.
+- `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
@@ -189,17 +215,161 @@ table = (
 )
 ```
 
-## Data shape
+## Trend over time
 
-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.
+![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)
 
-**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.
-- `split_columns` — an optional column whose values produce repeated column
-  groups side by side, useful for comparing methods.
+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))
+)
+```