coeftable 0.7.0__tar.gz → 0.9.0__tar.gz

{coeftable-0.7.0 → coeftable-0.9.0}/CHANGELOG.md

@@ -1,3 +1,40 @@
+<a id="v0.8.0"></a>
+# [v0.8.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.8.0) - 2026-08-27
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.8.0 -->
+
+## What's Changed
+### New Features
+* Label periods through one caller-supplied formatter by [@kylejcaron](https://github.com/kylejcaron) in [#49](https://github.com/kylejcaron/coeftable/pull/49)
+### Maintenance
+* Update changelog for v0.7.0 by [@github-actions](https://github.com/github-actions)[bot] in [#48](https://github.com/kylejcaron/coeftable/pull/48)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.7.0...v0.8.0
+
+[Changes][v0.8.0]
+
+
+<a id="v0.7.0"></a>
+# [v0.7.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.7.0) - 2026-08-27
+
+<!-- Release notes generated using configuration in .github/release.yml at v0.7.0 -->
+
+## What's Changed
+### New Features
+* Generalize the shared-position proof for nested breakout switchers by [@kylejcaron](https://github.com/kylejcaron) in [#43](https://github.com/kylejcaron/coeftable/pull/43)
+* Add DriverTree, a decomposition report with nested breakout switching by [@kylejcaron](https://github.com/kylejcaron) in [#44](https://github.com/kylejcaron/coeftable/pull/44)
+### Maintenance
+* Update changelog for v0.6.0 by [@github-actions](https://github.com/github-actions)[bot] in [#42](https://github.com/kylejcaron/coeftable/pull/42)
+* Run CI on pull requests to any base branch by [@kylejcaron](https://github.com/kylejcaron) in [#46](https://github.com/kylejcaron/coeftable/pull/46)
+* Judge additive decompositions at their endpoints too by [@kylejcaron](https://github.com/kylejcaron) in [#47](https://github.com/kylejcaron/coeftable/pull/47)
+
+
+**Full Changelog**: https://github.com/kylejcaron/coeftable/compare/v0.6.0...v0.7.0
+
+[Changes][v0.7.0]
+
+
 <a id="v0.6.0"></a>
 # [v0.6.0](https://github.com/kylejcaron/coeftable/releases/tag/v0.6.0) - 2026-08-27
 
@@ -147,6 +184,8 @@
 [Changes][v0.1.0]
 
 
+[v0.8.0]: https://github.com/kylejcaron/coeftable/compare/v0.7.0...v0.8.0
+[v0.7.0]: https://github.com/kylejcaron/coeftable/compare/v0.6.0...v0.7.0
 [v0.6.0]: https://github.com/kylejcaron/coeftable/compare/v0.5.0...v0.6.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

{coeftable-0.7.0 → coeftable-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.7.0
+Version: 0.9.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
@@ -692,6 +692,31 @@ with two or more breakouts (like `revenue` above) renders a native
 because the alternatives share one slotted position and pure CSS shows
 exactly one of them at a time.
 
+**Two different percentages appear, and they are not the same number.** Under
+each card's title sits that card's *own* change across the window. On each
+wire sits that child's *contribution* to its parent's change — a
+size-weighted delta for an additive slice, a log share for a factorization —
+and those contributions sum to the parent's own change. The two diverge
+whenever a child is small relative to its parent: a region that grew 90% on
+its own may have moved the total by only 6 points. The card's number answers
+"did this grow?", the wire's answers "how much of the parent's move came from
+here?". A card whose first level is zero or negative shows no own-change,
+since a percentage from that base misleads rather than informs.
+
+`op` is optional. Omit it and the operator is derived from the series: a
+genuine sum reconciles under `+` and is off by orders of magnitude under `x`,
+so the numbers already say which was meant. Supplying it asserts that intent
+and is still checked. If neither reading explains the parent, the build
+refuses and names the breakout rather than adopting one and blaming your
+arithmetic for the gap.
+
+A child may subtract from its parent. Growth accounting —
+`DAU = retained + new + resurrected − churned`, where churn is negative —
+decomposes correctly. The credibility statistics work in log space and so
+need positive levels; a signed child simply gets no uncertainty ribbon and
+claims no direction, exactly as an injected residual does, rather than
+refusing the whole tree.
+
 Each decomposition is checked against its own arithmetic: a parent that
 should equal the sum or product of its children but falls short gets an
 injected `"Unattributed"` residual card (additive shortfalls) or a reported
@@ -708,12 +733,12 @@ wraps to fit the card using an estimated character width, growing across
 as many lines as that estimate needs. Runs of whitespace collapse to a
 single space and line breaks are not preserved, and unusually wide text
 can still be clipped on a line, since the wrap is an estimate rather than
-a font measurement. A literal `{weeks}` placeholder is substituted for the
+a font measurement. A literal `{periods}` placeholder is substituted for the
 observed period count, and `caption` defaults to `None`, so nothing
 renders unless you ask for it.
 If you want a note that edge labels are accounting, not causal
 claims, that wording is yours to choose — for example
-`caption="Edge labels are an accounting of the realized {weeks}-week
+`caption="Edge labels are an accounting of the realized {periods}-week
 change, not causal impact."` `events` fan out to every card named in their
 `affects` tuple, both as sparkline markers and as captions, and the
 report's header is a timeline strip indexing them across the whole canvas.
@@ -723,6 +748,17 @@ experiments. With neither events nor a `strip_title` there is nothing to
 index and no heading to show, so the strip is omitted rather than reserving
 space for a bare axis; supplying either one brings it back.
 
+Tick labels on the strip, each event pin's trailing period text, and every
+card's own sparkline x axis all come from one callable, `period_label`: it
+maps a zero-based period index to display text and defaults to
+`coeftable.graph.timeline.default_period_label` (`W1`, `W2`, ...), which is
+why a report built with no `period_label` argument renders exactly the
+weekly labels used above. Pass your own, e.g.
+`period_label=lambda i: f"M{int(i) + 1}"`, and it reaches the strip's ticks,
+its event pins, and every card's axis together — the one parameter that
+makes a report period-neutral, so monthly, daily, or quarterly data renders
+its own correct labels instead of a hardcoded week count.
+
 **Switchers can nest.** Every level of the tree may carry its own switcher at
 the same time — revenue by drivers or region, and within drivers, active users
 by funnel or country, and within that, sessions by platform or channel.

{coeftable-0.7.0 → coeftable-0.9.0}/README.md

@@ -638,6 +638,31 @@ with two or more breakouts (like `revenue` above) renders a native
 because the alternatives share one slotted position and pure CSS shows
 exactly one of them at a time.
 
+**Two different percentages appear, and they are not the same number.** Under
+each card's title sits that card's *own* change across the window. On each
+wire sits that child's *contribution* to its parent's change — a
+size-weighted delta for an additive slice, a log share for a factorization —
+and those contributions sum to the parent's own change. The two diverge
+whenever a child is small relative to its parent: a region that grew 90% on
+its own may have moved the total by only 6 points. The card's number answers
+"did this grow?", the wire's answers "how much of the parent's move came from
+here?". A card whose first level is zero or negative shows no own-change,
+since a percentage from that base misleads rather than informs.
+
+`op` is optional. Omit it and the operator is derived from the series: a
+genuine sum reconciles under `+` and is off by orders of magnitude under `x`,
+so the numbers already say which was meant. Supplying it asserts that intent
+and is still checked. If neither reading explains the parent, the build
+refuses and names the breakout rather than adopting one and blaming your
+arithmetic for the gap.
+
+A child may subtract from its parent. Growth accounting —
+`DAU = retained + new + resurrected − churned`, where churn is negative —
+decomposes correctly. The credibility statistics work in log space and so
+need positive levels; a signed child simply gets no uncertainty ribbon and
+claims no direction, exactly as an injected residual does, rather than
+refusing the whole tree.
+
 Each decomposition is checked against its own arithmetic: a parent that
 should equal the sum or product of its children but falls short gets an
 injected `"Unattributed"` residual card (additive shortfalls) or a reported
@@ -654,12 +679,12 @@ wraps to fit the card using an estimated character width, growing across
 as many lines as that estimate needs. Runs of whitespace collapse to a
 single space and line breaks are not preserved, and unusually wide text
 can still be clipped on a line, since the wrap is an estimate rather than
-a font measurement. A literal `{weeks}` placeholder is substituted for the
+a font measurement. A literal `{periods}` placeholder is substituted for the
 observed period count, and `caption` defaults to `None`, so nothing
 renders unless you ask for it.
 If you want a note that edge labels are accounting, not causal
 claims, that wording is yours to choose — for example
-`caption="Edge labels are an accounting of the realized {weeks}-week
+`caption="Edge labels are an accounting of the realized {periods}-week
 change, not causal impact."` `events` fan out to every card named in their
 `affects` tuple, both as sparkline markers and as captions, and the
 report's header is a timeline strip indexing them across the whole canvas.
@@ -669,6 +694,17 @@ experiments. With neither events nor a `strip_title` there is nothing to
 index and no heading to show, so the strip is omitted rather than reserving
 space for a bare axis; supplying either one brings it back.
 
+Tick labels on the strip, each event pin's trailing period text, and every
+card's own sparkline x axis all come from one callable, `period_label`: it
+maps a zero-based period index to display text and defaults to
+`coeftable.graph.timeline.default_period_label` (`W1`, `W2`, ...), which is
+why a report built with no `period_label` argument renders exactly the
+weekly labels used above. Pass your own, e.g.
+`period_label=lambda i: f"M{int(i) + 1}"`, and it reaches the strip's ticks,
+its event pins, and every card's axis together — the one parameter that
+makes a report period-neutral, so monthly, daily, or quarterly data renders
+its own correct labels instead of a hardcoded week count.
+
 **Switchers can nest.** Every level of the tree may carry its own switcher at
 the same time — revenue by drivers or region, and within drivers, active users
 by funnel or country, and within that, sessions by platform or channel.

{coeftable-0.7.0 → coeftable-0.9.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.7.0'
-__version_tuple__ = version_tuple = (0, 7, 0)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)
 
 __commit_id__ = commit_id = None

{coeftable-0.7.0 → coeftable-0.9.0}/src/coeftable/frame.py

@@ -3,12 +3,13 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from functools import partial
 from itertools import combinations
 from typing import Any
 
 import narwhals as nw
 
-from coeftable.grid import assemble_rows, build_grid
+from coeftable.grid import AssembledRows, Grid, assemble_rows, build_grid
 from coeftable.spec import (
     Cell,
     CoefTable,
@@ -92,30 +93,11 @@ def _check_columns(frame: nw.DataFrame, table: CoefTable) -> None:
         )
 
 
-def resolve(table: CoefTable) -> Resolved:  # noqa: C901
-    """Resolve `table` against its frame.
-
-    Parameters
-    ----------
-    table
-        The specification to resolve.
+def _output_name(column: Column, split: Any) -> str:
+    return column.label if split is None else f"{split}{SPLIT_JOINER}{column.label}"
 
-    Returns
-    -------
-    Resolved
-        Rendered cells plus the layout metadata `render` needs.
-
-    Raises
-    ------
-    ColumnNotFoundError
-        When a named column is absent from the frame.
-    TypeError
-        When an estimate or bound column is not numeric.
-    SpecError
-        When the column specification is inconsistent.
-    """
-    validate_columns(table.columns)
 
+def _validate_layout_label_collisions(table: CoefTable) -> None:
     # A column label colliding with a layout key silently overwrites the
     # layout column in the output frame. Catch it here at spec-check time.
     layout_keys = {n for n in (table.rows, table.nest, table.groups) if n is not None}
@@ -126,6 +108,8 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
                 f"(rows/nest/groups key {column.label!r}); choose a different label."
             )
 
+
+def _validate_layout_key_uniqueness(table: CoefTable) -> None:
     # Two layout roles naming the same column collide in the output frame,
     # which `resolve()` builds keyed by column name -- the later write
     # silently discards the earlier role's values, so the table renders with
@@ -139,6 +123,8 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
                 f"{first_key!r}; each layout role needs its own column."
             )
 
+
+def _validate_sparkline_series_collisions(table: CoefTable) -> None:
     # The overlaid `series` dimension cannot also be a table axis: the
     # table's row structure already spends whichever of these an
     # identity maps to, so naming the same column both ways is
@@ -156,15 +142,32 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
                 "overlaid dimension cannot also be a table axis."
             )
 
-    frame = nw.from_native(table.data, eager_only=True)
-    _check_columns(frame, table)
 
-    n = len(frame)
+def _validate_spec(table: CoefTable) -> None:
+    validate_columns(table.columns)
+    _validate_layout_label_collisions(table)
+    _validate_layout_key_uniqueness(table)
+    _validate_sparkline_series_collisions(table)
+
+
+def _extract_layout_keys(
+    frame: nw.DataFrame, table: CoefTable, n: int
+) -> tuple[list[Any], list[Any], list[Any], list[Any]]:
     row_keys = frame[table.rows].to_list() if table.rows else [""] * n
     nest_keys = frame[table.nest].to_list() if table.nest else [None] * n
     group_keys = frame[table.groups].to_list() if table.groups else [None] * n
     split_keys = frame[table.split_columns].to_list() if table.split_columns else [None] * n
+    return row_keys, nest_keys, group_keys, split_keys
+
 
+def _prepare_columns(
+    table: CoefTable,
+    frame: nw.DataFrame,
+    row_keys: list[Any],
+    nest_keys: list[Any],
+    group_keys: list[Any],
+    split_keys: list[Any],
+) -> list[Prepared]:
     scan = Scan(
         frame=frame,
         columns=table.columns,
@@ -177,35 +180,35 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
         groups=table.groups,
         split_columns=table.split_columns,
     )
-    prepared: list[Prepared] = [column.prepare(scan) for column in table.columns]
+    return [column.prepare(scan) for column in table.columns]
 
-    grid = build_grid(
-        row_keys,
-        nest_keys,
-        group_keys,
-        split_keys,
-        sort_rows=table.sort_rows,
-        has_splits=table.split_columns is not None,
-    )
-
-    def output_name(column: Column, split: Any) -> str:
-        return column.label if split is None else f"{split}{SPLIT_JOINER}{column.label}"
 
+def _build_display_columns(
+    table: CoefTable, grid: Grid
+) -> tuple[list[str], dict[str, str], dict[str, list[str]], list[str]]:
     display_columns: list[str] = []
     labels: dict[str, str] = {}
     spanners: dict[str, list[str]] = {}
     plot_columns: list[str] = []
     for split in grid.splits:
         for column in table.columns:
-            name = output_name(column, split)
+            name = _output_name(column, split)
             display_columns.append(name)
             labels[name] = column.label
             if split is not None:
                 spanners.setdefault(str(split), []).append(name)
             if isinstance(column, (Forest, Sparkline)):
                 plot_columns.append(name)
+    return display_columns, labels, spanners, plot_columns
 
-    # Cell pass: one call to `column.cell` per (row, split, column).
+
+def _compute_cells(
+    table: CoefTable,
+    grid: Grid,
+    prepared: list[Prepared],
+    display_columns: list[str],
+) -> dict[str, list[str]]:
+    # One call to `column.cell` per (row, split, column).
     cell_values: dict[str, list[str]] = {name: [] for name in display_columns}
     for position, (row_key, nest_key, identity_group) in enumerate(grid.ordered):
         direction = table.direction_for(str(row_key))
@@ -213,7 +216,7 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
         for split in grid.splits:
             index = grid.source_index.get(((row_key, nest_key, identity_group), split))
             for column, prep in zip(table.columns, prepared, strict=True):
-                name = output_name(column, split)
+                name = _output_name(column, split)
                 if index is None:
                     cell_values[name].append("")
                     continue
@@ -228,8 +231,13 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
                     theme=table.theme,
                 )
                 cell_values[name].append(column.cell(ctx))
+    return cell_values
+
 
-    # Footer pass: interleave axis rows wherever a column's domain closes.
+def _build_footer_data(
+    table: CoefTable, grid: Grid, prepared: list[Prepared]
+) -> tuple[dict[str, Column], dict[str, Prepared], dict[str, list[list[Any]]], set[str]]:
+    # Interleave axis rows wherever a column's domain closes.
     column_by_label: dict[str, Column] = {}
     prepared_by_label: dict[str, Prepared] = {}
     footer_keys: dict[str, list[list[Any]]] = {}
@@ -250,23 +258,32 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
     shared_footer_labels = {
         label for label in footer_keys if prepared_by_label[label].shared_footer
     }
-
-    def render_footer(pending: dict[str, list[Any]]) -> dict[str, str]:
-        out: dict[str, str] = {}
-        for label, keys in pending.items():
-            column = column_by_label[label]
-            prep = prepared_by_label[label]
-            for split_idx, split in enumerate(grid.splits):
-                ctx = Footer(prepared=prep, key=keys[split_idx], theme=table.theme)
-                text = column.footer(ctx)
-                if text is not None:
-                    out[output_name(column, split)] = text
-        return out
-
-    assembled = assemble_rows(
-        grid, display_columns, cell_values, footer_keys, render_footer, shared_footer_labels
-    )
-
+    return column_by_label, prepared_by_label, footer_keys, shared_footer_labels
+
+
+def _render_footer(
+    pending: dict[str, list[Any]],
+    *,
+    column_by_label: dict[str, Column],
+    prepared_by_label: dict[str, Prepared],
+    grid: Grid,
+    theme: Any,
+) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for label, keys in pending.items():
+        column = column_by_label[label]
+        prep = prepared_by_label[label]
+        for split_idx, split in enumerate(grid.splits):
+            ctx = Footer(prepared=prep, key=keys[split_idx], theme=theme)
+            text = column.footer(ctx)
+            if text is not None:
+                out[_output_name(column, split)] = text
+    return out
+
+
+def _build_output_frame(
+    table: CoefTable, frame: nw.DataFrame, assembled: AssembledRows, display_columns: list[str]
+) -> Any:
     data: dict[str, list[Any]] = {}
     if table.groups:
         data[table.groups] = assembled.layout_group
@@ -276,13 +293,81 @@ def resolve(table: CoefTable) -> Resolved:  # noqa: C901
         data[table.nest] = assembled.layout_nest
     for name in display_columns:
         data[name] = assembled.cells[name]
+    return nw.from_dict(data, backend=nw.get_native_namespace(frame)).to_native()
 
+
+def _build_display_and_markdown_columns(
+    table: CoefTable, display_columns: list[str]
+) -> tuple[list[str], list[str]]:
     leading = [c for c in (table.groups, table.rows, table.nest) if c]
     markdown = [c for c in (table.rows, table.nest) if c] + display_columns
+    display = [*(leading[1:] if table.groups else leading), *display_columns]
+    return display, markdown
+
+
+def resolve(table: CoefTable) -> Resolved:
+    """Resolve `table` against its frame.
+
+    Parameters
+    ----------
+    table
+        The specification to resolve.
+
+    Returns
+    -------
+    Resolved
+        Rendered cells plus the layout metadata `render` needs.
+
+    Raises
+    ------
+    ColumnNotFoundError
+        When a named column is absent from the frame.
+    TypeError
+        When an estimate or bound column is not numeric.
+    SpecError
+        When the column specification is inconsistent.
+    """
+    _validate_spec(table)
+
+    frame = nw.from_native(table.data, eager_only=True)
+    _check_columns(frame, table)
+
+    n = len(frame)
+    row_keys, nest_keys, group_keys, split_keys = _extract_layout_keys(frame, table, n)
+    prepared = _prepare_columns(table, frame, row_keys, nest_keys, group_keys, split_keys)
+
+    grid = build_grid(
+        row_keys,
+        nest_keys,
+        group_keys,
+        split_keys,
+        sort_rows=table.sort_rows,
+        has_splits=table.split_columns is not None,
+    )
+
+    display_columns, labels, spanners, plot_columns = _build_display_columns(table, grid)
+    cell_values = _compute_cells(table, grid, prepared, display_columns)
+    column_by_label, prepared_by_label, footer_keys, shared_footer_labels = _build_footer_data(
+        table, grid, prepared
+    )
+    render_footer = partial(
+        _render_footer,
+        column_by_label=column_by_label,
+        prepared_by_label=prepared_by_label,
+        grid=grid,
+        theme=table.theme,
+    )
+
+    assembled = assemble_rows(
+        grid, display_columns, cell_values, footer_keys, render_footer, shared_footer_labels
+    )
+
+    native_frame = _build_output_frame(table, frame, assembled, display_columns)
+    display, markdown = _build_display_and_markdown_columns(table, display_columns)
 
     return Resolved(
-        frame=nw.from_dict(data, backend=nw.get_native_namespace(frame)).to_native(),
-        display_columns=[*(leading[1:] if table.groups else leading), *display_columns],
+        frame=native_frame,
+        display_columns=display,
         labels=labels,
         spanners=spanners,
         group_column=table.groups,

{coeftable-0.7.0 → coeftable-0.9.0}/src/coeftable/graph/breakout.py

@@ -59,19 +59,29 @@ def _canonical(value: object, *, name: str) -> tuple[object, ...]:
 
 @dataclass(frozen=True, slots=True)
 class Breakout:
-    """One alternative decomposition: a label, its operator, and its cards."""
+    """One alternative decomposition: a label, its cards, and optionally its operator.
+
+    ``op`` may be left as ``None``, in which case the builder derives it from
+    the series themselves -- a genuine sum reconciles under ``"+"`` and is off
+    by orders of magnitude under ``"x"``, so the data already says which one
+    the caller meant. Supplying it explicitly asserts that intent and is still
+    checked against the numbers.
+
+    ``children`` keeps its position, so both the fully positional form and the
+    keyword form continue to work unchanged.
+    """
 
     key: str
     label: str
-    op: Op
-    children: tuple[str, ...]
+    op: Op | None = None
+    children: tuple[str, ...] = ()
 
     def __post_init__(self) -> None:
         """Validate the breakout's identity, operator, and child cards."""
         _non_empty_str(self.key, name="Breakout.key")
         _non_empty_str(self.label, name="Breakout.label")
-        if self.op not in _OPS:
-            raise SpecError(f"Breakout.op must be one of {_OPS}, got {self.op!r}")
+        if self.op is not None and self.op not in _OPS:
+            raise SpecError(f"Breakout.op must be one of {_OPS} or None, got {self.op!r}")
         children = _canonical(self.children, name="Breakout.children")
         if not children:
             raise SpecError("Breakout.children must not be empty")