coeftable 0.1.0__py3-none-any.whl

coeftable/spec.py

@@ -0,0 +1,437 @@
+"""Column specifications and the table builder."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from coeftable.format import CIStyle, Format, Number
+from coeftable.theme import DEFAULT, ColorRule, Direction, Theme
+
+if TYPE_CHECKING:
+    from great_tables import GT
+
+type Scale = Literal["table", "row_group", "split_column", "row"]
+
+# Module-level singletons: frozen and shared, so they are safe as argument
+# defaults where ruff B008 forbids a constructor call.
+_DEFAULT_FMT = Number()
+_DEFAULT_CI_STYLE = CIStyle()
+
+
+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."""
+
+
+@dataclass(frozen=True)
+class Estimate:
+    """A column rendering a point estimate and its interval.
+
+    Parameters
+    ----------
+    label
+        Column header, and the name a `Forest` binds to.
+    value
+        Frame column holding the point estimate.
+    ci
+        Frame columns holding the lower and upper bounds, or None.
+    fmt
+        Callable applied to the estimate and both bounds.
+    ci_style
+        Assembly options for the rendered cell.
+    """
+
+    label: str
+    value: str
+    ci: tuple[str, str] | None = None
+    fmt: Format = _DEFAULT_FMT
+    ci_style: CIStyle = _DEFAULT_CI_STYLE
+
+
+@dataclass(frozen=True)
+class Forest:
+    """A column rendering an inline SVG interval bar.
+
+    Parameters
+    ----------
+    label
+        Column header.
+    of
+        Label of the `Estimate` this plot visualises.
+    ref
+        Reference value for the dashed line and for role resolution.
+    scale
+        Which set of bars share an x-domain.
+    domain
+        Explicit domain, overriding `scale`.
+    symmetric
+        When `domain` is not set, symmetrize the auto-computed domain
+        around `ref` instead of fitting tightly to the data.
+    width
+        Bar width in pixels.
+    height
+        Bar row height in pixels.  `None` (the default) picks a height
+        that fills the row based on the bound estimate's `ci_style.layout`
+        so the reference line spans the full cell instead of a short
+        segment centred in a taller row.
+    show_axis
+        Emit an axis row for each distinct domain.
+    axis_fmt
+        Callable labelling axis ticks; defaults to the bound estimate's `fmt`.
+    """
+
+    label: str
+    of: str
+    ref: float = 0.0
+    scale: Scale = "table"
+    domain: tuple[float, float] | None = None
+    symmetric: bool = False
+    width: int = 220
+    height: int | None = None
+    show_axis: bool = True
+    axis_fmt: Format | None = None
+
+
+@dataclass(frozen=True)
+class Passthrough:
+    """A column rendering a frame column verbatim.
+
+    Parameters
+    ----------
+    label
+        Column header.
+    column
+        Frame column to display.
+    """
+
+    label: str
+    column: str
+
+
+type Column = Estimate | Forest | Passthrough
+
+
+def validate_columns(columns: tuple[Column, ...]) -> None:
+    """Check a column specification for internal consistency.
+
+    Parameters
+    ----------
+    columns
+        Declared columns, in display order.
+
+    Raises
+    ------
+    SpecError
+        When no columns are declared, labels collide, a `Forest` names an
+        undeclared estimate, or a `Forest` is bound to a CI-less estimate.
+    """
+    if not columns:
+        raise SpecError("Table has no columns; declare at least one.")
+
+    seen: set[str] = set()
+    for column in columns:
+        if column.label in seen:
+            raise SpecError(f"Table has duplicate column label {column.label!r}.")
+        seen.add(column.label)
+
+    estimates = {c.label: c for c in columns if isinstance(c, Estimate)}
+    for column in columns:
+        if not isinstance(column, Forest):
+            continue
+        target = estimates.get(column.of)
+        if target is None:
+            raise SpecError(
+                f"Forest column {column.label!r} references estimate {column.of!r}, "
+                f"which is not declared. Declared estimates: {sorted(estimates)}."
+            )
+        if target.ci is None:
+            raise SpecError(
+                f"Forest column {column.label!r} references estimate {column.of!r}, "
+                "which has no confidence interval to plot."
+            )
+
+
+class CoefTable:
+    """A specification for a summary table over a frame of estimates.
+
+    Immutable by convention: every chain method returns a new instance.
+
+    Parameters
+    ----------
+    data
+        Any frame narwhals can read: pandas, polars or pyarrow. A plain dict is
+        not accepted; narwhals has no backend to build from.
+    rows
+        Frame column whose values become the leading row label.
+    nest
+        Frame column stacked beneath each row key.
+    groups
+        Frame column driving row-group section headers.
+    split_columns
+        Frame column whose values repeat the declared columns side by side.
+    columns
+        Declared columns, in display order.
+    estimate, ci
+        Sugar declaring a single `Estimate` labelled ``"Estimate"``, prepended
+        before any `columns` entries.
+    direction
+        Which side of a reference counts as favorable, table-wide or per row key.
+    color_rule
+        Callable overriding role resolution entirely.
+    theme
+        Colour and typography.
+    title, subtitle
+        Header text.
+    sort_rows
+        Sort row keys lexically instead of by first appearance.
+    """
+
+    def __init__(
+        self,
+        data: Any,
+        *,
+        rows: str | None = None,
+        nest: str | None = None,
+        groups: str | None = None,
+        split_columns: str | None = None,
+        columns: Iterable[Column] = (),
+        estimate: str | None = None,
+        ci: tuple[str, str] | None = None,
+        direction: Direction | Mapping[str, Direction] = "higher_is_better",
+        color_rule: ColorRule | None = None,
+        theme: Theme = DEFAULT,
+        title: str = "",
+        subtitle: str = "",
+        sort_rows: bool = False,
+    ) -> None:
+        declared = tuple(columns)
+        if estimate is not None:
+            declared = (Estimate("Estimate", estimate, ci=ci), *declared)
+        self.data = data
+        self.rows = rows
+        self.nest = nest
+        self.groups = groups
+        self.split_columns = split_columns
+        self.columns = declared
+        self.direction = direction
+        self.color_rule = color_rule
+        self.theme = theme
+        self.title = title
+        self.subtitle = subtitle
+        self.sort_rows = sort_rows
+        if declared:
+            validate_columns(declared)
+
+    def _with(self, **changes: Any) -> CoefTable:
+        settings: dict[str, Any] = {
+            "rows": self.rows,
+            "nest": self.nest,
+            "groups": self.groups,
+            "split_columns": self.split_columns,
+            "columns": self.columns,
+            "direction": self.direction,
+            "color_rule": self.color_rule,
+            "theme": self.theme,
+            "title": self.title,
+            "subtitle": self.subtitle,
+            "sort_rows": self.sort_rows,
+        }
+        settings.update(changes)
+        return CoefTable(self.data, **settings)
+
+    def _add(self, column: Column) -> CoefTable:
+        return self._with(columns=(*self.columns, column))
+
+    def estimate(
+        self,
+        label: str,
+        value: str,
+        *,
+        ci: tuple[str, str] | None = None,
+        fmt: Format = _DEFAULT_FMT,
+        ci_style: CIStyle = _DEFAULT_CI_STYLE,
+    ) -> CoefTable:
+        """Append an estimate column.
+
+        Parameters
+        ----------
+        label
+            Column header, and the name a `Forest` binds to.
+        value
+            Frame column holding the point estimate.
+        ci
+            Frame columns holding the lower and upper bounds.
+        fmt
+            Callable applied to the estimate and both bounds.
+        ci_style
+            Assembly options for the rendered cell.
+
+        Returns
+        -------
+        CoefTable
+            A new table with the column appended.
+        """
+        return self._add(Estimate(label, value, ci=ci, fmt=fmt, ci_style=ci_style))
+
+    def forest(
+        self,
+        label: str,
+        *,
+        of: str,
+        ref: float = 0.0,
+        scale: Scale = "table",
+        domain: tuple[float, float] | None = None,
+        symmetric: bool = False,
+        width: int = 220,
+        height: int | None = None,
+        show_axis: bool = True,
+        axis_fmt: Format | None = None,
+    ) -> CoefTable:
+        """Append a forest-plot column bound to an existing estimate.
+
+        Parameters
+        ----------
+        label
+            Column header.
+        of
+            Label of the `Estimate` to visualise.
+        ref
+            Reference value for the dashed line and role resolution.
+        scale
+            Which set of bars share an x-domain.
+        domain
+            Explicit domain, overriding `scale`.
+        symmetric
+            When `domain` is not set, symmetrize the auto-computed domain
+            around `ref` instead of fitting tightly to the data.
+        width
+            Bar width in pixels.
+        height
+            Bar row height in pixels. `None` (the default) picks a height
+            that fills the row based on the bound estimate's
+            `ci_style.layout`.
+        show_axis
+            Emit an axis row per distinct domain.
+        axis_fmt
+            Callable labelling axis ticks.
+
+        Returns
+        -------
+        CoefTable
+            A new table with the column appended.
+        """
+        return self._add(
+            Forest(
+                label,
+                of=of,
+                ref=ref,
+                scale=scale,
+                domain=domain,
+                symmetric=symmetric,
+                width=width,
+                height=height,
+                show_axis=show_axis,
+                axis_fmt=axis_fmt,
+            )
+        )
+
+    def passthrough(self, label: str, column: str) -> CoefTable:
+        """Append a column rendered verbatim from the frame.
+
+        Parameters
+        ----------
+        label
+            Column header.
+        column
+            Frame column to display.
+
+        Returns
+        -------
+        CoefTable
+            A new table with the column appended.
+        """
+        return self._add(Passthrough(label, column))
+
+    def header(self, title: str, subtitle: str = "") -> CoefTable:
+        """Set the header text.
+
+        Parameters
+        ----------
+        title
+            Title line.
+        subtitle
+            Subtitle line.
+
+        Returns
+        -------
+        CoefTable
+            A new table with the header set.
+        """
+        return self._with(title=title, subtitle=subtitle)
+
+    def with_theme(self, theme: Theme) -> CoefTable:
+        """Replace the theme.
+
+        Parameters
+        ----------
+        theme
+            Theme to use.
+
+        Returns
+        -------
+        CoefTable
+            A new table using `theme`.
+        """
+        return self._with(theme=theme)
+
+    def with_direction(self, direction: Direction | Mapping[str, Direction]) -> CoefTable:
+        """Replace the direction semantics.
+
+        Parameters
+        ----------
+        direction
+            Table-wide direction, or a mapping from row key to direction.
+
+        Returns
+        -------
+        CoefTable
+            A new table using `direction`.
+        """
+        return self._with(direction=direction)
+
+    def direction_for(self, row_key: str) -> Direction:
+        """Resolve the direction applying to a row key.
+
+        Parameters
+        ----------
+        row_key
+            Value of the `rows` column.
+
+        Returns
+        -------
+        Direction
+            The direction for that row, defaulting to ``"higher_is_better"``.
+        """
+        if isinstance(self.direction, Mapping):
+            return self.direction.get(row_key, "higher_is_better")
+        return self.direction
+
+    def gt(self) -> GT:
+        """Render to a `great_tables` object.
+
+        Returns
+        -------
+        GT
+            The rendered table.
+        """
+        from coeftable.render import to_gt
+
+        return to_gt(self)
+
+    def _repr_html_(self) -> str:
+        return self.gt()._repr_html_()

coeftable/svg.py

@@ -0,0 +1,210 @@
+"""Inline SVG emitters for forest bars and their shared axis."""
+
+from __future__ import annotations
+
+import math
+
+from coeftable.format import Format, is_missing
+from coeftable.theme import Theme
+
+_TICK_STEPS = (1.0, 2.0, 2.5, 5.0, 10.0)
+
+
+def nice_ticks(low: float, high: float, target: int = 4) -> list[float]:
+    """Return round tick positions spanning ``[low, high]``.
+
+    Parameters
+    ----------
+    low, high
+        Domain bounds.
+    target
+        Approximate number of ticks wanted.
+
+    Returns
+    -------
+    list of float
+        Tick positions, empty when the domain is invalid.
+    """
+    if not (math.isfinite(low) and math.isfinite(high)) or high < low:
+        return []
+    if high == low:
+        return [low]
+    raw = (high - low) / max(target, 1)
+    magnitude = 10.0 ** math.floor(math.log10(raw))
+    step = next((m * magnitude for m in _TICK_STEPS if raw <= m * magnitude), 10.0 * magnitude)
+    start = math.ceil(low / step) * step
+    count = math.floor((high - start) / step) + 1
+    return [round(start + i * step, 10) for i in range(max(count, 0))]
+
+
+def _projector(domain: tuple[float, float], width: int, pad: int):
+    low, high = domain
+    span = high - low
+    if span <= 0:
+        span = 1.0
+    inner = width - 2 * pad
+
+    def project(value: float) -> float:
+        return pad + (value - low) / span * inner
+
+    return project
+
+
+def _svg(width: int, height: int, body: str) -> str:
+    return (
+        f'<svg width="{width}" height="{height}" viewBox="0 0 {width} {height}" '
+        f'xmlns="http://www.w3.org/2000/svg" style="display:block;margin:0 auto">'
+        f"{body}</svg>"
+    )
+
+
+def forest_bar(
+    estimate: float | None,
+    lower: float | None,
+    upper: float | None,
+    *,
+    domain: tuple[float, float],
+    ref: float,
+    color: str,
+    theme: Theme,
+    width: int = 220,
+    height: int = 18,
+    bar_height: int = 9,
+    pad: int = 3,
+) -> str:
+    """Render one interval as an inline SVG bar.
+
+    The bar spans the interval, a light tick marks the point estimate, and a
+    dashed line marks `ref` when it falls inside `domain`.  A bound outside the
+    domain, including an unbounded one, draws to the edge with a triangular cap
+    so that clipping is visible rather than silently misleading.
+
+    Parameters
+    ----------
+    estimate
+        Point estimate; the tick is omitted when missing or outside `domain`.
+    lower, upper
+        Interval bounds.  ``None`` means unbounded on that side.
+    domain
+        Shared x-domain the bar is drawn against.
+    ref
+        Reference value for the dashed line.
+    color
+        Bar colour, resolved from a semantic role by the caller.
+    theme
+        Supplies axis and surface colours.
+    width, height, bar_height, pad
+        Geometry in pixels.
+
+    Returns
+    -------
+    str
+        A complete ``<svg>`` element.
+    """
+    low, high = domain
+    project = _projector(domain, width, pad)
+    low_value = low if lower is None or is_missing(lower) else lower
+    high_value = high if upper is None or is_missing(upper) else upper
+    clipped_low = is_missing(lower) or low_value < low
+    clipped_high = is_missing(upper) or high_value > high
+
+    x0 = project(max(low_value, low))
+    x1 = project(min(high_value, high))
+    top = (height - bar_height) / 2
+    middle = height / 2
+    parts: list[str] = []
+
+    if low <= ref <= high:
+        ref_x = project(ref)
+        parts.append(
+            f'<line x1="{ref_x:.2f}" y1="0" x2="{ref_x:.2f}" y2="{height}" '
+            f'stroke="{theme.axis}" stroke-width="1" stroke-dasharray="2,2"/>'
+        )
+
+    parts.append(
+        f'<rect x="{x0:.2f}" y="{top:.2f}" width="{max(x1 - x0, 0.75):.2f}" '
+        f'height="{bar_height}" fill="{color}" fill-opacity="0.75" '
+        f'stroke="{color}" stroke-width="0.75"/>'
+    )
+
+    if estimate is not None and not is_missing(estimate) and low <= estimate <= high:
+        tick_x = project(estimate)
+        parts.append(
+            f'<line x1="{tick_x:.2f}" y1="{top:.2f}" x2="{tick_x:.2f}" '
+            f'y2="{top + bar_height:.2f}" stroke="{theme.surface}" stroke-width="1.5"/>'
+        )
+
+    cap = bar_height * 0.6
+    if clipped_high:
+        tip = width - pad / 2
+        parts.append(
+            f'<polygon points="{tip:.2f},{middle:.2f} {tip - cap:.2f},{middle - cap:.2f} '
+            f'{tip - cap:.2f},{middle + cap:.2f}" fill="{color}"/>'
+        )
+    if clipped_low:
+        tip = pad / 2
+        parts.append(
+            f'<polygon points="{tip:.2f},{middle:.2f} {tip + cap:.2f},{middle - cap:.2f} '
+            f'{tip + cap:.2f},{middle + cap:.2f}" fill="{color}"/>'
+        )
+
+    return _svg(width, height, "".join(parts))
+
+
+def forest_axis(
+    *,
+    domain: tuple[float, float],
+    ref: float,
+    fmt: Format,
+    theme: Theme,
+    width: int = 220,
+    height: int = 22,
+    pad: int = 3,
+    target_ticks: int = 4,
+) -> str:
+    """Render the shared x-axis for a set of forest bars.
+
+    Parameters
+    ----------
+    domain
+        Shared x-domain.
+    ref
+        Reference value for the dashed line.
+    fmt
+        Callable used to label each tick.
+    theme
+        Supplies the axis colour and label size.
+    width, height, pad
+        Geometry in pixels.
+    target_ticks
+        Approximate number of ticks wanted.
+
+    Returns
+    -------
+    str
+        A complete ``<svg>`` element.
+    """
+    low, high = domain
+    project = _projector(domain, width, pad)
+    baseline = 4.0
+    parts = [
+        f'<line x1="{pad}" y1="{baseline:.2f}" x2="{width - pad}" y2="{baseline:.2f}" '
+        f'stroke="{theme.axis}" stroke-width="0.75"/>'
+    ]
+    if low <= ref <= high:
+        ref_x = project(ref)
+        parts.append(
+            f'<line x1="{ref_x:.2f}" y1="0" x2="{ref_x:.2f}" y2="{baseline:.2f}" '
+            f'stroke="{theme.axis}" stroke-width="1" stroke-dasharray="2,2"/>'
+        )
+    for tick in nice_ticks(low, high, target_ticks):
+        tick_x = project(tick)
+        parts.append(
+            f'<line x1="{tick_x:.2f}" y1="{baseline:.2f}" x2="{tick_x:.2f}" '
+            f'y2="{baseline + 3:.2f}" stroke="{theme.axis}" stroke-width="0.75"/>'
+        )
+        parts.append(
+            f'<text x="{tick_x:.2f}" y="{height - 2:.2f}" fill="{theme.axis}" '
+            f'font-size="9" text-anchor="middle">{fmt(tick)}</text>'
+        )
+    return _svg(width, height, "".join(parts))