coeftable 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -18,3 +18,5 @@ src/coeftable/_version.py
 /.roborev/
 # internal planning docs (not shipped, not for the public repo)
 docs/superpowers/
+# local feature worktrees
+/.worktrees/

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

@@ -1,3 +1,8 @@
+## Unreleased
+
+### 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
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coeftable
-Version: 0.3.1
+Version: 0.4.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
@@ -439,3 +439,59 @@ absolute = pl.DataFrame(
     .sparkline("Hidden reference", value="value", ref=0.0, show_ref=False)
 )
 ```
+
+## Plot annotations
+
+`ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or
+sparkline. A numeric, date, or datetime coordinate is a literal; a string is
+the name of a scalar column on the main table frame. A missing field value
+leaves that annotation out of that row, which makes row-specific marks
+possible:
+
+```python
+import polars as pl
+import coeftable as ct
+
+annotated = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "estimate": [1.2, -0.4],
+        "lower": [0.8, -0.8],
+        "upper": [1.6, 0.1],
+        # Only Revenue receives the second vertical rule.
+        "target": [1.5, None],
+        "trend": [[1.0, 1.2, 1.4], [-0.1, -0.3, -0.4]],
+        "guard_low": [0.9, -0.6],
+        "guard_high": [1.6, 0.0],
+    }
+)
+
+(
+    ct.CoefTable(annotated, rows="metric")
+    .estimate("Effect", "estimate", ci=("lower", "upper"))
+    .forest(
+        "Effect plot",
+        of="Effect",
+        annotations=(ct.Rule("target", axis="x"),),
+    )
+    .sparkline(
+        "Trend",
+        value="trend",
+        annotations=(ct.Band("guard_low", "guard_high", axis="y"),),
+    )
+)
+```
+
+Forest annotations use `axis="x"` only. Sparklines accept `axis="x"` and
+`axis="y"`; use the former for a shared time or sequence position and the
+latter for a value threshold or range. `layer="underlay"` (the default for
+bands) draws before the plot; `layer="overlay"` (the default for rules) draws
+after it. `affect_domain=True` by default expands an automatic axis domain to
+include the annotation; set it to `False` to keep the existing domain and
+allow the mark to be clipped. `ylim` overrides the Forest x-domain and the
+Sparkline y-domain, so annotations on those axes do not expand them. Sparkline
+x annotations still participate in their shared x-domain; `max_ylim` can cap
+the Sparkline y-domain and clip or omit distant marks. Annotations supplement
+rather than replace
+`ref`: `ref` remains the built-in semantic reference that controls colors and
+its optional dashed line.

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

@@ -385,3 +385,59 @@ absolute = pl.DataFrame(
     .sparkline("Hidden reference", value="value", ref=0.0, show_ref=False)
 )
 ```
+
+## Plot annotations
+
+`ct.Rule` draws a line and `ct.Band` shades an interval in a forest plot or
+sparkline. A numeric, date, or datetime coordinate is a literal; a string is
+the name of a scalar column on the main table frame. A missing field value
+leaves that annotation out of that row, which makes row-specific marks
+possible:
+
+```python
+import polars as pl
+import coeftable as ct
+
+annotated = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "estimate": [1.2, -0.4],
+        "lower": [0.8, -0.8],
+        "upper": [1.6, 0.1],
+        # Only Revenue receives the second vertical rule.
+        "target": [1.5, None],
+        "trend": [[1.0, 1.2, 1.4], [-0.1, -0.3, -0.4]],
+        "guard_low": [0.9, -0.6],
+        "guard_high": [1.6, 0.0],
+    }
+)
+
+(
+    ct.CoefTable(annotated, rows="metric")
+    .estimate("Effect", "estimate", ci=("lower", "upper"))
+    .forest(
+        "Effect plot",
+        of="Effect",
+        annotations=(ct.Rule("target", axis="x"),),
+    )
+    .sparkline(
+        "Trend",
+        value="trend",
+        annotations=(ct.Band("guard_low", "guard_high", axis="y"),),
+    )
+)
+```
+
+Forest annotations use `axis="x"` only. Sparklines accept `axis="x"` and
+`axis="y"`; use the former for a shared time or sequence position and the
+latter for a value threshold or range. `layer="underlay"` (the default for
+bands) draws before the plot; `layer="overlay"` (the default for rules) draws
+after it. `affect_domain=True` by default expands an automatic axis domain to
+include the annotation; set it to `False` to keep the existing domain and
+allow the mark to be clipped. `ylim` overrides the Forest x-domain and the
+Sparkline y-domain, so annotations on those axes do not expand them. Sparkline
+x annotations still participate in their shared x-domain; `max_ylim` can cap
+the Sparkline y-domain and clip or omit distant marks. Annotations supplement
+rather than replace
+`ref`: `ref` remains the built-in semantic reference that controls colors and
+its optional dashed line.

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

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling>=1.25", "hatch-vcs>=0.4"]
+requires = ["hatchling>=1.27", "hatch-vcs>=0.4"]
 build-backend = "hatchling.build"
 
 [project]

{coeftable-0.3.1 → coeftable-0.4.0}/src/coeftable/__init__.py

@@ -2,6 +2,8 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
+from coeftable.annotations import Band, Rule
+from coeftable.errors import ColumnNotFoundError, SpecError
 from coeftable.format import (
     CalendarStep,
     CIStyle,
@@ -11,15 +13,7 @@ from coeftable.format import (
     Percent,
     TimeFormat,
 )
-from coeftable.spec import (
-    CoefTable,
-    ColumnNotFoundError,
-    Estimate,
-    Forest,
-    Passthrough,
-    Sparkline,
-    SpecError,
-)
+from coeftable.spec import CoefTable, Estimate, Forest, Passthrough, Sparkline
 from coeftable.theme import Theme, role_for
 
 try:
@@ -28,6 +22,7 @@ except PackageNotFoundError:  # pragma: no cover
     __version__ = "0.0.0.dev0"
 
 __all__ = [
+    "Band",
     "CIStyle",
     "CalendarStep",
     "CoefTable",
@@ -39,6 +34,7 @@ __all__ = [
     "Number",
     "Passthrough",
     "Percent",
+    "Rule",
     "Sparkline",
     "SpecError",
     "Theme",

coeftable-0.4.0/src/coeftable/_axis.py

@@ -0,0 +1,55 @@
+"""Shared axis coercion helpers."""
+
+from __future__ import annotations
+
+import datetime
+import math
+from collections.abc import Iterable
+from typing import Any
+
+# Deliberately naive: paired with elapsed-time subtraction in _epoch_seconds
+# so relative spacing never depends on the host machine's local timezone.
+_EPOCH = datetime.datetime(1970, 1, 1)
+
+
+def _epoch_seconds(value: datetime.date) -> float:
+    """Convert a date/datetime to seconds since the Unix epoch.
+
+    A timezone-aware `datetime` is converted to UTC first; a naive
+    `datetime` (or a plain `date`, read as midnight) is measured as an
+    elapsed-time delta from a naive epoch, never through
+    `datetime.timestamp()` -- which reads a naive value against the host's
+    *local* timezone and would make relative spacing depend on where the
+    code runs.
+    """
+    if isinstance(value, datetime.datetime):
+        if value.tzinfo is not None:
+            value = value.astimezone(datetime.UTC).replace(tzinfo=None)
+        return (value - _EPOCH).total_seconds()
+    return (datetime.datetime(value.year, value.month, value.day) - _EPOCH).total_seconds()
+
+
+def _detect_temporal(values: Iterable[Any]) -> bool:
+    """Return True when the first non-missing value is a date or datetime."""
+    for value in values:
+        if value is not None:
+            return isinstance(value, datetime.date)
+    return False
+
+
+def _coerce_temporal(values: Iterable[Any]) -> list[float | None]:
+    """Coerce raw date/datetime values to epoch seconds, `None` for missing.
+
+    A bare `None` is missing directly; pandas' `NaT` is not `None` but is
+    still an `isinstance(..., datetime.datetime)` whose epoch delta
+    degenerates to NaN rather than raising, so the result is checked for
+    NaN too -- mirroring `coerce_numeric`'s own missing-value handling.
+    """
+    out: list[float | None] = []
+    for value in values:
+        if value is None:
+            out.append(None)
+            continue
+        seconds = _epoch_seconds(value)
+        out.append(None if math.isnan(seconds) else seconds)
+    return out

{coeftable-0.3.1 → coeftable-0.4.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.3.1'
-__version_tuple__ = version_tuple = (0, 3, 1)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
 __commit_id__ = commit_id = None

coeftable-0.4.0/src/coeftable/annotations.py

@@ -0,0 +1,266 @@
+"""Typed plot-annotation declarations and frame-aware resolution."""
+
+from __future__ import annotations
+
+import datetime as dt
+import math
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import narwhals as nw
+
+from coeftable._axis import _coerce_temporal
+from coeftable.errors import SpecError
+from coeftable.format import coerce_numeric
+
+type Axis = Literal["x", "y"]
+type AxisKind = Literal["numeric", "temporal"]
+type Layer = Literal["underlay", "overlay"]
+type Dash = Literal["solid", "dashed", "dotted"]
+type AnnotationSource = int | float | dt.date | dt.datetime | str
+
+
+def _validate_coordinate(value: AnnotationSource, *, name: str) -> None:
+    """Validate a declaration's literal-or-field coordinate."""
+    if isinstance(value, bool) or not isinstance(value, (int, float, dt.date, str)):
+        raise SpecError(f"Annotation {name} must be a numeric/temporal literal or field name.")
+    if isinstance(value, float) and not math.isfinite(value):
+        raise SpecError(f"Annotation {name} must be finite.")
+
+
+def _validate_unit_interval(value: float, *, name: str) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise SpecError(f"Annotation {name} must be a finite number between 0 and 1.")
+    if not 0.0 <= value <= 1.0:
+        raise SpecError(f"Annotation {name} must be between 0 and 1.")
+
+
+@dataclass(frozen=True)
+class Rule:
+    """A line annotation at one axis coordinate."""
+
+    at: AnnotationSource
+    axis: Axis
+    layer: Layer = "overlay"
+    affect_domain: bool = True
+    color: str | None = None
+    opacity: float = 1.0
+    width: float = 1.0
+    dash: Dash = "dashed"
+
+    def __post_init__(self) -> None:
+        """Validate declaration-only rule styling and coordinates."""
+        _validate_coordinate(self.at, name="coordinate")
+        if self.layer not in ("underlay", "overlay"):
+            raise SpecError(
+                f"Annotation layer must be 'underlay' or 'overlay'; got {self.layer!r}."
+            )
+        _validate_unit_interval(self.opacity, name="opacity")
+        if isinstance(self.width, bool) or not isinstance(self.width, (int, float)):
+            raise SpecError("Annotation width must be a finite positive number.")
+        if not math.isfinite(self.width) or self.width <= 0:
+            raise SpecError("Annotation width must be a finite positive number.")
+        if self.dash not in ("solid", "dashed", "dotted"):
+            raise SpecError(
+                f"Annotation dash must be 'solid', 'dashed', or 'dotted'; got {self.dash!r}."
+            )
+
+
+@dataclass(frozen=True)
+class Band:
+    """A shaded interval annotation between two axis coordinates."""
+
+    start: AnnotationSource
+    end: AnnotationSource
+    axis: Axis
+    layer: Layer = "underlay"
+    affect_domain: bool = True
+    color: str | None = None
+    opacity: float = 0.12
+
+    def __post_init__(self) -> None:
+        """Validate declaration-only band styling and coordinates."""
+        _validate_coordinate(self.start, name="start")
+        _validate_coordinate(self.end, name="end")
+        if self.layer not in ("underlay", "overlay"):
+            raise SpecError(
+                f"Annotation layer must be 'underlay' or 'overlay'; got {self.layer!r}."
+            )
+        _validate_unit_interval(self.opacity, name="opacity")
+
+
+type Annotation = Rule | Band
+
+
+@dataclass(frozen=True)
+class ResolvedRule:
+    """A fully resolved line annotation."""
+
+    at: float
+    axis: Axis
+    layer: Layer
+    affect_domain: bool
+    color: str | None
+    opacity: float
+    width: float
+    dash: Dash
+
+
+@dataclass(frozen=True)
+class ResolvedBand:
+    """A fully resolved interval annotation."""
+
+    start: float
+    end: float
+    axis: Axis
+    layer: Layer
+    affect_domain: bool
+    color: str | None
+    opacity: float
+
+
+type ResolvedAnnotation = ResolvedRule | ResolvedBand
+
+
+@dataclass(frozen=True)
+class PreparedAnnotations:
+    """Resolved annotations grouped in frame-row order."""
+
+    by_row: tuple[tuple[ResolvedAnnotation, ...], ...]
+
+
+def annotation_sources(annotations: Sequence[Annotation]) -> tuple[str, ...]:
+    """Return source-field names once, in declaration order."""
+    sources: dict[str, None] = {}
+    for annotation in annotations:
+        coordinates = (
+            (annotation.at,)
+            if isinstance(annotation, Rule)
+            else (annotation.start, annotation.end)
+        )
+        for coordinate in coordinates:
+            if isinstance(coordinate, str):
+                sources.setdefault(coordinate, None)
+    return tuple(sources)
+
+
+def _coerce_values(
+    values: Sequence[Any],
+    *,
+    kind: AxisKind,
+    context: str,
+) -> list[float | None]:
+    present = [value for value in values if value is not None]
+    if kind == "numeric":
+        if any(isinstance(value, (bool, dt.date)) for value in present):
+            raise SpecError(f"{context} must be numeric for a numeric axis.")
+        try:
+            resolved = coerce_numeric(values, subject=context)
+        except TypeError as error:
+            raise SpecError(str(error)) from None
+    elif kind == "temporal":
+        if any(not isinstance(value, dt.date) for value in present):
+            raise SpecError(f"{context} must be temporal for a temporal axis.")
+        resolved = _coerce_temporal(values)
+    else:
+        raise SpecError(f"{context} has unsupported axis kind {kind!r}.")
+
+    if any(value is not None and not math.isfinite(value) for value in resolved):
+        raise SpecError(f"{context} must be finite.")
+    return resolved
+
+
+def prepare_annotations(
+    annotations: Sequence[Annotation],
+    frame: nw.DataFrame,
+    *,
+    axis_kinds: Mapping[Axis, AxisKind],
+    plot_label: str,
+    row_identities: Sequence[Any],
+) -> PreparedAnnotations:
+    """Resolve annotation literals and fields into one ordered tuple per row."""
+    row_count = len(frame)
+    if len(row_identities) != row_count:
+        raise SpecError(
+            f"{plot_label} annotation rows do not match the frame: "
+            f"{len(row_identities)} identities for {row_count} rows."
+        )
+
+    source_cache: dict[str, list[Any]] = {}
+
+    def values_for(
+        source: AnnotationSource, *, kind: AxisKind, context: str
+    ) -> list[float | None]:
+        if isinstance(source, str):
+            if source not in frame.columns:
+                raise SpecError(f"{context} names missing column {source!r}.")
+            if source not in source_cache:
+                source_cache[source] = frame[source].to_list()
+            raw = source_cache[source]
+        else:
+            raw = [source] * row_count
+        return _coerce_values(raw, kind=kind, context=context)
+
+    resolved_rows: list[list[ResolvedAnnotation]] = [[] for _ in range(row_count)]
+    for index, annotation in enumerate(annotations):
+        if annotation.axis not in axis_kinds:
+            raise SpecError(
+                f"{plot_label} annotation {index} uses unsupported axis {annotation.axis!r}."
+            )
+        kind = axis_kinds[annotation.axis]
+        prefix = f"{plot_label} annotation {index}"
+        if isinstance(annotation, Rule):
+            positions = values_for(annotation.at, kind=kind, context=f"{prefix} at")
+            for row, position in enumerate(positions):
+                if position is not None:
+                    resolved_rows[row].append(
+                        ResolvedRule(
+                            at=position,
+                            axis=annotation.axis,
+                            layer=annotation.layer,
+                            affect_domain=annotation.affect_domain,
+                            color=annotation.color,
+                            opacity=annotation.opacity,
+                            width=annotation.width,
+                            dash=annotation.dash,
+                        )
+                    )
+            continue
+
+        starts = values_for(annotation.start, kind=kind, context=f"{prefix} start")
+        ends = values_for(annotation.end, kind=kind, context=f"{prefix} end")
+        for row, (start, end) in enumerate(zip(starts, ends, strict=True)):
+            if start is None or end is None:
+                continue
+            if start > end:
+                raise SpecError(
+                    f"{prefix} row {row_identities[row]!r}: "
+                    f"band start {start!r} must not exceed end {end!r}."
+                )
+            resolved_rows[row].append(
+                ResolvedBand(
+                    start=start,
+                    end=end,
+                    axis=annotation.axis,
+                    layer=annotation.layer,
+                    affect_domain=annotation.affect_domain,
+                    color=annotation.color,
+                    opacity=annotation.opacity,
+                )
+            )
+
+    return PreparedAnnotations(by_row=tuple(tuple(marks) for marks in resolved_rows))
+
+
+def domain_values(marks: Sequence[ResolvedAnnotation], *, axis: Axis) -> list[float]:
+    """Return domain-affecting positions for one axis, preserving mark order."""
+    values: list[float] = []
+    for mark in marks:
+        if mark.axis != axis or not mark.affect_domain:
+            continue
+        if isinstance(mark, ResolvedRule):
+            values.append(mark.at)
+        else:
+            values.extend((mark.start, mark.end))
+    return values

coeftable-0.4.0/src/coeftable/errors.py

@@ -0,0 +1,9 @@
+"""Shared exceptions for invalid table specifications."""
+
+
+class SpecError(ValueError):
+    """Raised when a table specification is internally inconsistent."""
+
+
+class ColumnNotFoundError(KeyError):
+    """Raised when a specification names a column absent from the frame."""

{coeftable-0.3.1 → coeftable-0.4.0}/src/coeftable/series.py

@@ -10,16 +10,15 @@ coerces values and detects a temporal x -- callers only ever see a `Series`.
 
 from __future__ import annotations
 
-import datetime
 import math
-from collections.abc import Iterable
 from dataclasses import dataclass
 from typing import Any, overload
 
 import narwhals as nw
 
+from coeftable._axis import _coerce_temporal, _detect_temporal
+from coeftable.errors import SpecError
 from coeftable.format import coerce_numeric
-from coeftable.spec import SpecError
 
 
 @dataclass(frozen=True)
@@ -73,54 +72,6 @@ def _nan_to_none(values: list[Any]) -> list[Any]:
     return [None if isinstance(v, float) and math.isnan(v) else v for v in values]
 
 
-# Deliberately naive: paired with elapsed-time subtraction in _epoch_seconds
-# so relative spacing never depends on the host machine's local timezone.
-_EPOCH = datetime.datetime(1970, 1, 1)
-
-
-def _epoch_seconds(value: datetime.date) -> float:
-    """Convert a date/datetime to seconds since the Unix epoch.
-
-    A timezone-aware `datetime` is converted to UTC first; a naive
-    `datetime` (or a plain `date`, read as midnight) is measured as an
-    elapsed-time delta from a naive epoch, never through
-    `datetime.timestamp()` -- which reads a naive value against the host's
-    *local* timezone and would make relative spacing depend on where the
-    code runs.
-    """
-    if isinstance(value, datetime.datetime):
-        if value.tzinfo is not None:
-            value = value.astimezone(datetime.UTC).replace(tzinfo=None)
-        return (value - _EPOCH).total_seconds()
-    return (datetime.datetime(value.year, value.month, value.day) - _EPOCH).total_seconds()
-
-
-def _detect_temporal(values: Iterable[Any]) -> bool:
-    """Return True when the first non-missing value is a date or datetime."""
-    for value in values:
-        if value is not None:
-            return isinstance(value, datetime.date)
-    return False
-
-
-def _coerce_temporal(values: Iterable[Any]) -> list[float | None]:
-    """Coerce raw date/datetime values to epoch seconds, `None` for missing.
-
-    A bare `None` is missing directly; pandas' `NaT` is not `None` but is
-    still an `isinstance(..., datetime.datetime)` whose epoch delta
-    degenerates to NaN rather than raising, so the result is checked for
-    NaN too -- mirroring `coerce_numeric`'s own missing-value handling.
-    """
-    out: list[float | None] = []
-    for value in values:
-        if value is None:
-            out.append(None)
-            continue
-        seconds = _epoch_seconds(value)
-        out.append(None if math.isnan(seconds) else seconds)
-    return out
-
-
 def _build_series(
     y_raw: list[Any],
     lower_raw: list[Any] | None,