coeftable 0.4.0__tar.gz → 0.6.0__tar.gz

{coeftable-0.4.0 → coeftable-0.6.0}/.gitignore

@@ -20,3 +20,4 @@ src/coeftable/_version.py
 docs/superpowers/
 # local feature worktrees
 /.worktrees/
+.superpowers/

coeftable-0.6.0/AGENTS.md

@@ -0,0 +1,7 @@
+# Agent guidelines
+
+## Changelog
+
+Never edit `CHANGELOG.md`. It is generated by release automation
+(`.github/release.yml`) from merged PR titles; Describe changes in the PR
+description instead.

{coeftable-0.4.0 → coeftable-0.6.0}/CHANGELOG.md

@@ -1,7 +1,34 @@
-## Unreleased
+<a id="v0.5.0"></a>
+# [v0.5.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.5.0) - 2026-08-19
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.5.0 -->
+
+## What's Changed
+### Maintenance
+* Update changelog for v0.4.0 by [@github-actions](https://github.com/github-actions)[bot] in [#32](https://github.com/kylejcaron/coeftable/pull/32)
+* feat: forest plot outlier handling. robust autoscale + margin-fade clipping by [@kylejcaron](https://github.com/kylejcaron) in [#33](https://github.com/kylejcaron/coeftable/pull/33)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.4.0...v0.5.0
+
+[Changes][v0.5.0]
+
+
+<a id="v0.4.0"></a>
+# [v0.4.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.4.0) - 2026-08-14
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.4.0 -->
+
+## What's Changed
+### Maintenance
+* build: align hatchling metadata floor by [@kylejcaron](https://github.com/kylejcaron) in [#30](https://github.com/kylejcaron/coeftable/pull/30)
+* feature: support plot annotations by [@kylejcaron](https://github.com/kylejcaron) in [#31](https://github.com/kylejcaron/coeftable/pull/31)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.3.1...v0.4.0
+
+[Changes][v0.4.0]
 
-### Features
-- Add typed rule and band annotations to forest plots and sparklines, including row-specific field binding and domain-aware layering.
 
 <a id="v0.3.1"></a>
 # [v0.3.1](https://github.com/kylejcaron/coeftable/releases/tag/v0.3.1) - 2026-08-14
@@ -97,6 +124,8 @@
 [Changes][v0.1.0]
 
 
+[v0.5.0]: https://github.com/kylejcaron/coeftable/compare/v0.4.0...v0.5.0
+[v0.4.0]: https://github.com/kylejcaron/coeftable/compare/v0.3.1...v0.4.0
 [v0.3.1]: https://github.com/kylejcaron/coeftable/compare/v0.3.0...v0.3.1
 [v0.3.0]: https://github.com/kylejcaron/coeftable/compare/v0.2.1...v0.3.0
 [v0.2.1]: https://github.com/kylejcaron/coeftable/compare/v0.2.0...v0.2.1

{coeftable-0.4.0 → coeftable-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.4.0
+Version: 0.6.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
@@ -414,6 +414,36 @@ trend = pl.DataFrame(
 )
 ```
 
+**Forest plots take `autoscale` too.** A single extreme interval (say a
++3000% lift among sub-1% metrics) otherwise stretches the shared domain
+and flattens every other bar:
+
+```python
+lifts = pl.DataFrame(
+    {
+        "metric": ["Checkout CVR", "Signup Rate", "Retention D7", "AOV", "Rare Event"],
+        "rel": [0.03, -0.05, 0.08, 0.02, 30.0],
+        "rel_lb": [0.01, -0.09, 0.04, -0.01, 22.0],
+        "rel_ub": [0.05, -0.01, 0.12, 0.05, 41.0],
+    }
+)
+
+(
+    ct.CoefTable(lifts, rows="metric")
+    .estimate("Lift %", "rel", ci=("rel_lb", "rel_ub"), fmt=ct.Percent(signed=True))
+    # "robust" fits an IQR/Tukey fence over the pooled values instead of
+    # the raw min/max, so the outlier stops dictating the axis. Composes
+    # with symmetric= (fence first, then mirror around ref); ylim= still
+    # overrides everything.
+    .forest("Lift Plot", of="Lift %", ref=0.0, autoscale="robust")
+)
+```
+
+A discounted interval is never hidden: bars in a clipping domain plot
+against a slightly inset region and the clipped interval continues into
+the reserved margin as a gradient fade, reading as "extends beyond the
+axis". Buckets with nothing clipped render exactly as before.
+
 **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):
@@ -440,6 +470,176 @@ absolute = pl.DataFrame(
 )
 ```
 
+## Standalone plots
+
+The inline SVG plots that power `.forest(...)` and `.sparkline(...)` columns
+are available directly from `coeftable.plots` — the same emitters, the same
+themes, no table required. Each function returns a complete `<svg>` string
+for embedding anywhere HTML goes:
+
+```python
+from coeftable.plots import forest_bar, sparkline_bar
+from coeftable.theme import DEFAULT
+import coeftable as ct
+
+bar = forest_bar(
+    1.2, 0.4, 2.0,            # estimate, lower, upper
+    domain=(-1.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    theme=DEFAULT,
+)
+
+line = sparkline_bar(
+    [0.0, 1.0, 2.0],          # x
+    [1.0, 1.5, 2.0],          # y
+    [0.5, 1.0, 1.6],          # lower
+    [1.5, 2.0, 2.4],          # upper
+    x_domain=(0.0, 2.0),
+    domain=(0.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    fmt=ct.Number(),
+    theme=DEFAULT,
+)
+```
+
+Also exported: `sparkline_multi` + `Trace` for overlaid series,
+`forest_axis` / `sparkline_axis` for the shared axis footer under a column
+of plots, and `ResolvedRule` / `ResolvedBand` for reference lines and
+shaded intervals via each function's `annotations=` parameter. Because a
+standalone plot and a table column share one `Theme`, a report that mixes
+both stays visually consistent.
+
+## Metric cards (experimental)
+
+`coeftable.cards` composes the standalone plots into measured, foldable
+metric cards — the same formatters, themes, and SVG primitives as the
+tables. The API is experimental and may change; it is deliberately not
+exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card, CardGrid
+from coeftable.cards.regions import Diagnostics, Event, Events, Metric, Trend
+
+events = Events([Event("launch", "#4C72B0", at=2.0)])
+revenue = Card(
+    "Revenue",
+    subtitle="weekly lift vs control",
+    content=[
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+        Trend(
+            x=(0, 1, 2, 3), y=(0.3, 0.8, 1.1, 1.5),
+            lower=(-0.1, 0.3, 0.6, 0.9), upper=(0.7, 1.3, 1.6, 2.1),
+            x_domain=(0, 3), domain=(-0.5, 2.5), ref=0.0,
+            annotations=events.rules(),
+        ),
+        Diagnostics("diagnostics", [("n", 412), ("sigma", 0.8)]),
+        events,
+    ],
+)
+grid = CardGrid([revenue, revenue.with_theme(ct.theme.BLUE)])
+```
+
+A `Card` (or `CardGrid`) left as the last notebook expression renders
+itself; `as_raw_html()` is the string entry point. Cards are fixed-width
+with exact measured heights and fold via a native `<details>` header (the
+headline value stays visible as a chip when it fits beside the header,
+and is omitted otherwise). A standalone card collapses to
+its header; inside a `CardGrid` each card's expanded footprint stays
+reserved, so folding never reflows neighbors.
+
+## Metric panels (experimental)
+
+`coeftable.cards` panels put named side-by-side panes in one bordered shell
+with a shared header and footer: the compositional step above cards. The API
+is experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Metric, Pane, Panel, Row, TextBlock
+
+summary = Pane(
+    "Summary",
+    content=(
+        TextBlock("Weekly revenue", variant="subtitle"),
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+    ),
+    width=220,
+)
+segments = Pane(
+    "Segments",
+    content=(
+        Row(
+            (
+                (TextBlock("Enterprise"), 85),
+                (Metric(8.1, ct.Percent(signed=True)), 105),
+            )
+        ),
+    ),
+    width=200,
+)
+header = Row(
+    (
+        (TextBlock("Revenue", variant="title"), 320),
+        (Metric(3.4, ct.Percent(signed=True)), 120),
+    ),
+    gap=16,
+)
+panel = Panel((summary, segments), header=(header,))
+html = panel.as_raw_html()
+```
+
+Panes declare usable content widths; cell widths are author inputs; the panel
+derives its own footprint with exact measurement, not responsive guessing.
+
+A `Panel` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` returns the same composition under another
+theme.
+
+## Metric trees (experimental)
+
+`coeftable.graph` turns metric cards wired into a driver DAG into a metric
+tree: the graph layer adds slotted layout, vertical wires, and zero-JS
+fold/downstream-hide behavior. The API is experimental and may change; it is
+deliberately not exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card
+from coeftable.graph import MetricTree
+
+tree = MetricTree(
+    nodes=(
+        ("revenue", Card("Revenue")),
+        ("price", Card("Price")),
+        ("volume", Card("Volume")),
+        ("retention", Card("Retention")),
+    ),
+    edges=(
+        ("revenue", "price", 1.2),
+        ("revenue", "volume", 2.1),
+        ("volume", "retention", -0.6),
+    ),
+    fmt=ct.Number(suffix=' pp', decimals=1, signed=True, thousands=False),
+    dom_prefix='drivers',
+)
+html = tree.as_raw_html()
+```
+
+Use a distinct `dom_prefix` for each tree when rendering multiple graphs in one
+document, so their generated control, card, and wire ids remain disjoint.
+
+Each card retains its native `<details>` fold control. The nub under a parent
+hides a node only when every root path to it is blocked: collapsing one parent
+of a shared child leaves that child visible via the other path, all with pure
+CSS and no JavaScript.
+
+A `MetricTree` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` follows the same conventions as cards.
+
 ## Plot annotations
 
 `ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or

{coeftable-0.4.0 → coeftable-0.6.0}/README.md

@@ -360,6 +360,36 @@ trend = pl.DataFrame(
 )
 ```
 
+**Forest plots take `autoscale` too.** A single extreme interval (say a
++3000% lift among sub-1% metrics) otherwise stretches the shared domain
+and flattens every other bar:
+
+```python
+lifts = pl.DataFrame(
+    {
+        "metric": ["Checkout CVR", "Signup Rate", "Retention D7", "AOV", "Rare Event"],
+        "rel": [0.03, -0.05, 0.08, 0.02, 30.0],
+        "rel_lb": [0.01, -0.09, 0.04, -0.01, 22.0],
+        "rel_ub": [0.05, -0.01, 0.12, 0.05, 41.0],
+    }
+)
+
+(
+    ct.CoefTable(lifts, rows="metric")
+    .estimate("Lift %", "rel", ci=("rel_lb", "rel_ub"), fmt=ct.Percent(signed=True))
+    # "robust" fits an IQR/Tukey fence over the pooled values instead of
+    # the raw min/max, so the outlier stops dictating the axis. Composes
+    # with symmetric= (fence first, then mirror around ref); ylim= still
+    # overrides everything.
+    .forest("Lift Plot", of="Lift %", ref=0.0, autoscale="robust")
+)
+```
+
+A discounted interval is never hidden: bars in a clipping domain plot
+against a slightly inset region and the clipped interval continues into
+the reserved margin as a gradient fade, reading as "extends beyond the
+axis". Buckets with nothing clipped render exactly as before.
+
 **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):
@@ -386,6 +416,176 @@ absolute = pl.DataFrame(
 )
 ```
 
+## Standalone plots
+
+The inline SVG plots that power `.forest(...)` and `.sparkline(...)` columns
+are available directly from `coeftable.plots` — the same emitters, the same
+themes, no table required. Each function returns a complete `<svg>` string
+for embedding anywhere HTML goes:
+
+```python
+from coeftable.plots import forest_bar, sparkline_bar
+from coeftable.theme import DEFAULT
+import coeftable as ct
+
+bar = forest_bar(
+    1.2, 0.4, 2.0,            # estimate, lower, upper
+    domain=(-1.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    theme=DEFAULT,
+)
+
+line = sparkline_bar(
+    [0.0, 1.0, 2.0],          # x
+    [1.0, 1.5, 2.0],          # y
+    [0.5, 1.0, 1.6],          # lower
+    [1.5, 2.0, 2.4],          # upper
+    x_domain=(0.0, 2.0),
+    domain=(0.0, 3.0),
+    ref=0.0,
+    color=DEFAULT.favorable,
+    fmt=ct.Number(),
+    theme=DEFAULT,
+)
+```
+
+Also exported: `sparkline_multi` + `Trace` for overlaid series,
+`forest_axis` / `sparkline_axis` for the shared axis footer under a column
+of plots, and `ResolvedRule` / `ResolvedBand` for reference lines and
+shaded intervals via each function's `annotations=` parameter. Because a
+standalone plot and a table column share one `Theme`, a report that mixes
+both stays visually consistent.
+
+## Metric cards (experimental)
+
+`coeftable.cards` composes the standalone plots into measured, foldable
+metric cards — the same formatters, themes, and SVG primitives as the
+tables. The API is experimental and may change; it is deliberately not
+exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card, CardGrid
+from coeftable.cards.regions import Diagnostics, Event, Events, Metric, Trend
+
+events = Events([Event("launch", "#4C72B0", at=2.0)])
+revenue = Card(
+    "Revenue",
+    subtitle="weekly lift vs control",
+    content=[
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+        Trend(
+            x=(0, 1, 2, 3), y=(0.3, 0.8, 1.1, 1.5),
+            lower=(-0.1, 0.3, 0.6, 0.9), upper=(0.7, 1.3, 1.6, 2.1),
+            x_domain=(0, 3), domain=(-0.5, 2.5), ref=0.0,
+            annotations=events.rules(),
+        ),
+        Diagnostics("diagnostics", [("n", 412), ("sigma", 0.8)]),
+        events,
+    ],
+)
+grid = CardGrid([revenue, revenue.with_theme(ct.theme.BLUE)])
+```
+
+A `Card` (or `CardGrid`) left as the last notebook expression renders
+itself; `as_raw_html()` is the string entry point. Cards are fixed-width
+with exact measured heights and fold via a native `<details>` header (the
+headline value stays visible as a chip when it fits beside the header,
+and is omitted otherwise). A standalone card collapses to
+its header; inside a `CardGrid` each card's expanded footprint stays
+reserved, so folding never reflows neighbors.
+
+## Metric panels (experimental)
+
+`coeftable.cards` panels put named side-by-side panes in one bordered shell
+with a shared header and footer: the compositional step above cards. The API
+is experimental and may change; it is deliberately not exported from the
+top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Metric, Pane, Panel, Row, TextBlock
+
+summary = Pane(
+    "Summary",
+    content=(
+        TextBlock("Weekly revenue", variant="subtitle"),
+        Metric(3.4, ct.Percent(signed=True), ci=(1.2, 5.7), ref=0.0),
+    ),
+    width=220,
+)
+segments = Pane(
+    "Segments",
+    content=(
+        Row(
+            (
+                (TextBlock("Enterprise"), 85),
+                (Metric(8.1, ct.Percent(signed=True)), 105),
+            )
+        ),
+    ),
+    width=200,
+)
+header = Row(
+    (
+        (TextBlock("Revenue", variant="title"), 320),
+        (Metric(3.4, ct.Percent(signed=True)), 120),
+    ),
+    gap=16,
+)
+panel = Panel((summary, segments), header=(header,))
+html = panel.as_raw_html()
+```
+
+Panes declare usable content widths; cell widths are author inputs; the panel
+derives its own footprint with exact measurement, not responsive guessing.
+
+A `Panel` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` returns the same composition under another
+theme.
+
+## Metric trees (experimental)
+
+`coeftable.graph` turns metric cards wired into a driver DAG into a metric
+tree: the graph layer adds slotted layout, vertical wires, and zero-JS
+fold/downstream-hide behavior. The API is experimental and may change; it is
+deliberately not exported from the top-level `coeftable` namespace yet.
+
+```python
+import coeftable as ct
+from coeftable.cards import Card
+from coeftable.graph import MetricTree
+
+tree = MetricTree(
+    nodes=(
+        ("revenue", Card("Revenue")),
+        ("price", Card("Price")),
+        ("volume", Card("Volume")),
+        ("retention", Card("Retention")),
+    ),
+    edges=(
+        ("revenue", "price", 1.2),
+        ("revenue", "volume", 2.1),
+        ("volume", "retention", -0.6),
+    ),
+    fmt=ct.Number(suffix=' pp', decimals=1, signed=True, thousands=False),
+    dom_prefix='drivers',
+)
+html = tree.as_raw_html()
+```
+
+Use a distinct `dom_prefix` for each tree when rendering multiple graphs in one
+document, so their generated control, card, and wire ids remain disjoint.
+
+Each card retains its native `<details>` fold control. The nub under a parent
+hides a node only when every root path to it is blocked: collapsing one parent
+of a shared child leaves that child visible via the other path, all with pure
+CSS and no JavaScript.
+
+A `MetricTree` left as the last notebook expression renders itself via
+`_repr_html_`; `with_theme()` follows the same conventions as cards.
+
 ## Plot annotations
 
 `ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or

{coeftable-0.4.0 → coeftable-0.6.0}/pyproject.toml

@@ -72,14 +72,26 @@ src = ["src", "tests"]
 docstring-code-format = true
 
 [tool.ruff.lint]
-select = ["B", "D", "E", "F", "I", "RUF", "S", "UP", "W"]
+select = ["B", "C90", "D", "E", "F", "I", "PLR0911", "PLR0912", "PLR0913", "PLR0915", "RUF", "S", "UP", "W"]
 ignore = ["RUF001", "RUF002", "RUF012"]
 
+[tool.ruff.lint.mccabe]
+# Anti-spaghetti gate: flag functions with cyclomatic complexity >= 25.
+max-complexity = 24
+
+[tool.ruff.lint.pylint]
+max-branches = 24
+max-statements = 100
+max-returns = 12
+# Wide keyword-only APIs (plot primitives, table builders) are deliberate;
+# only flag genuine monsters.
+max-args = 24
+
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"
 
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = ["D", "S101"]
+"tests/*" = ["D", "S101", "PLR0915"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{coeftable-0.4.0 → coeftable-0.6.0}/src/coeftable/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
 
 __commit_id__ = commit_id = None

coeftable-0.6.0/src/coeftable/cards/__init__.py

@@ -0,0 +1,67 @@
+"""Experimental card layer. Not part of the public coeftable API yet.
+
+The adornment vocabulary is the closed content contract card regions
+resolve into; `render_adornment` is its only serializer.
+"""
+
+from coeftable.cards.adornments import (
+    Adornment,
+    Badge,
+    CaptionRow,
+    InlineSvg,
+    KeyValuePopover,
+    Legend,
+    MetricValue,
+    RuleStrip,
+    SelectControl,
+    TextBlock,
+)
+from coeftable.cards.card import Card, CardGrid
+from coeftable.cards.chrome import DEFAULT_CHROME, CardChrome
+from coeftable.cards.fragments import render_adornment
+from coeftable.cards.measure import Anchor, MeasuredCard
+from coeftable.cards.panel import MeasuredPanel, Pane, Panel, Row
+from coeftable.cards.regions import (
+    Diagnostics,
+    Event,
+    Events,
+    Interval,
+    Metric,
+    Region,
+    Trend,
+    resolve_content,
+)
+from coeftable.cards.template import CardTemplate
+
+__all__ = [
+    "DEFAULT_CHROME",
+    "Adornment",
+    "Anchor",
+    "Badge",
+    "CaptionRow",
+    "Card",
+    "CardChrome",
+    "CardGrid",
+    "CardTemplate",
+    "Diagnostics",
+    "Event",
+    "Events",
+    "InlineSvg",
+    "Interval",
+    "KeyValuePopover",
+    "Legend",
+    "MeasuredCard",
+    "MeasuredPanel",
+    "Metric",
+    "MetricValue",
+    "Pane",
+    "Panel",
+    "Region",
+    "Row",
+    "RuleStrip",
+    "SelectControl",
+    "TextBlock",
+    "Trend",
+    "render_adornment",
+    "resolve_content",
+]