coeftable 0.1.0__py3-none-any.whl

coeftable/theme.py

@@ -0,0 +1,187 @@
+"""Colour roles, direction semantics and table chrome."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+type Role = Literal["favorable", "unfavorable", "inconclusive", "neutral"]
+type Direction = Literal["higher_is_better", "lower_is_better", "neutral"]
+type ColorRule = Callable[[float | None, float | None, float | None, float], Role]
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Colour, typography and chrome slots for a table.
+
+    Roles are named by meaning rather than by colour so that a palette can be
+    swapped without the calling code implying a value judgement.
+
+    Parameters
+    ----------
+    favorable, unfavorable, inconclusive, neutral
+        Colours for the four semantic roles.
+    header_bg, header_fg, column_label_bg
+        Title, subtitle and column-label chrome.
+    band
+        Fill for alternating row-key blocks.
+    surface
+        Table background; also the colour of the estimate tick inside a bar.
+    rule, axis, muted, text
+        Divider, axis, secondary-text and body-text colours.
+    value_size, ci_size, table_font_size
+        CSS font sizes.
+    na_text
+        Text substituted for a missing estimate.
+    border_style
+        ``"boxed"`` draws a solid rule on all four table sides (the
+        default). ``"minimal"`` drops the left and right rules for a more
+        textual, publication-style layout with only top and bottom rules.
+    border_color
+        Colour used for structural table chrome: the heading divider,
+        column-label rules, row-group borders, and the table frame
+        (including the table-body top rule).  If `None` (the default),
+        ``header_bg`` is reused so that these borders and the title
+        banner share a colour.  Set this independently to keep the title
+        banner light while still drawing visible chrome rules.  Does
+        *not* affect ``rule``, which styles lighter dividers within the
+        body-row region (nest-key separators, forest-plot axis lines).
+    """
+
+    favorable: str = "#55A868"
+    unfavorable: str = "#C44E52"
+    inconclusive: str = "#8C8C8C"
+    neutral: str = "#4C72B0"
+
+    header_bg: str = "#4C72B0"
+    header_fg: str = "#FFFFFF"
+    column_label_bg: str = "#8FA9CE"
+    band: str = "#F2F5FA"
+    surface: str = "#FFFFFF"
+    rule: str = "#C7C8CD"
+    axis: str = "#72767E"
+    muted: str = "#72767E"
+    text: str = "#343538"
+
+    value_size: str = "15px"
+    ci_size: str = "11px"
+    table_font_size: str = "16px"
+    na_text: str = "\u2014"
+    border_style: Literal["boxed", "minimal"] = "boxed"
+    border_color: str | None = None
+
+    def color(self, role: Role) -> str:
+        """Return the colour registered for `role`.
+
+        Parameters
+        ----------
+        role
+            Semantic role.
+
+        Returns
+        -------
+        str
+            Hex colour string.
+        """
+        match role:
+            case "favorable":
+                return self.favorable
+            case "unfavorable":
+                return self.unfavorable
+            case "inconclusive":
+                return self.inconclusive
+            case "neutral":
+                return self.neutral
+            case _:
+                raise ValueError(f"Unknown role: {role!r}")
+
+
+def role_for(
+    lower: float | None,
+    upper: float | None,
+    ref: float,
+    direction: Direction,
+) -> Role:
+    """Map an interval to a semantic role.
+
+    An interval lying entirely on one side of `ref` is favorable or unfavorable
+    according to `direction`; one that spans `ref`, or that is unbounded on the
+    deciding side, is inconclusive. A `direction` of ``"neutral"`` always yields
+    ``"neutral"``, so a table making no directional claim does not look like a
+    table full of null results.
+
+    Parameters
+    ----------
+    lower, upper
+        Interval bounds. `None` means unbounded on that side.
+    ref
+        Reference value the interval is compared against.
+    direction
+        Which side of `ref` counts as favorable.
+
+    Returns
+    -------
+    Role
+        The resolved role.
+    """
+    if direction == "neutral":
+        return "neutral"
+    if lower is not None and lower > ref:
+        return "favorable" if direction == "higher_is_better" else "unfavorable"
+    if upper is not None and upper < ref:
+        return "unfavorable" if direction == "higher_is_better" else "favorable"
+    return "inconclusive"
+
+
+BLUE = Theme()
+
+COLORBLIND = Theme(
+    favorable="#0072B2",
+    unfavorable="#D55E00",
+    inconclusive="#999999",
+    neutral="#0072B2",
+    header_bg="#0072B2",
+    column_label_bg="#7FB8DC",
+    band="#EEF5FA",
+)
+
+MONO = Theme(
+    # Grayscale-only: direction is never colour-coded (favorable and
+    # unfavorable share a shade), but significance is. A result whose
+    # interval clears the reference (favorable/unfavorable) renders in a
+    # dark, high-contrast gray; an inconclusive result is rendered in a
+    # light gray to visually recede; neutral (no directional claim) sits
+    # in between.
+    favorable="#2B2B2B",
+    unfavorable="#2B2B2B",
+    inconclusive="#B0B0B0",
+    neutral="#6E6E6E",
+    header_bg="#343538",
+    column_label_bg="#72767E",
+    band="#F4F4F4",
+)
+
+TEXTUAL = Theme(
+    # A quieter, publication-style theme: a muted palette, a light title
+    # banner, no row banding, and borders confined to the top and bottom
+    # rules -- closer to a printed table than a dashboard.
+    favorable="#2E7D32",
+    unfavorable="#C62828",
+    inconclusive="#9E9E9E",
+    neutral="#455A64",
+    header_bg="#F5F5F5",
+    header_fg="#1A1A1A",
+    column_label_bg="#FAFAFA",
+    band="#FFFFFF",
+    surface="#FFFFFF",
+    rule="#E0E0E0",
+    axis="#616161",
+    muted="#757575",
+    text="#212121",
+    border_style="minimal",
+    border_color="#A8A8A8",
+)
+
+
+DEFAULT = TEXTUAL

coeftable-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: coeftable
+Version: 0.1.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
+Project-URL: Issues, https://github.com/kylejcaron/coeftable/issues
+Author-email: Kyle Caron <kyle.j.caron@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Kyle Caron
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: confidence-interval,forest-plot,great-tables,statistics,tables
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Requires-Dist: great-tables>=0.22
+Requires-Dist: narwhals>=2.24
+Provides-Extra: dev
+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: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Requires-Dist: ty>=0.0.49; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# coeftable
+
+Lightweight, report-ready summary tables for estimates with uncertainty. Renders
+inline forest plots, builds on great_tables HTML output, and works with pandas,
+polars, or pyarrow frames.
+
+![Rendered experiment results table with grouped sections, nested variants, and an inline forest plot](docs/images/example.png)
+
+## Installation
+
+```bash
+uv add coeftable
+```
+
+## Quick start
+
+The one-line form declares a table with a single estimate column:
+
+```python
+import polars as pl
+import coeftable as ct
+
+df = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Latency"],
+        "est": [3.4, 0.5],
+        "lb": [1.2, -1.0],
+        "ub": [5.7, 2.0],
+    }
+)
+
+ct.CoefTable(df, rows="metric", estimate="est", ci=("lb", "ub"))
+```
+
+A `CoefTable` renders itself in marimo, Jupyter, and any other `_repr_html_`-aware viewer —
+leave it as the last expression in a cell, no extra call needed. Outside a notebook, use
+`.gt()` to reach the underlying [great_tables](https://posit-dev.github.io/great-tables/)
+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.
+
+## Experiment table
+
+Build a complete experiment results table with multiple estimates, a forest
+plot column, grouped row sections, nested variants, and direction hints:
+
+```python
+import polars as pl
+import coeftable as ct
+
+experiment = pl.DataFrame(
+    {
+        "area": ["Core", "Core", "Ops", "Ops"],
+        "metric": ["Revenue", "Revenue", "Latency", "Latency"],
+        "variant": ["B", "C", "B", "C"],
+        "att": [12400.0, -3100.0, 40.0, 120.0],
+        "att_lb": [4200.0, -9800.0, -80.0, 45.0],
+        "att_ub": [20600.0, 3600.0, 160.0, 195.0],
+        "rel": [3.4, -1.2, 0.5, 2.0],
+        "rel_lb": [1.2, -4.0, -1.0, 0.8],
+        "rel_ub": [5.7, 1.6, 2.0, 3.2],
+    }
+)
+
+(
+    ct.CoefTable(experiment, rows="metric", nest="variant", groups="area")
+    .estimate("Lift Amount", "att", ci=("att_lb", "att_ub"), fmt=ct.Number(compact=True))
+    .estimate("Lift %", "rel", ci=("rel_lb", "rel_ub"), fmt=ct.Percent(signed=True))
+    .forest("Lift Plot", of="Lift %", ref=0.0, symmetric=True)
+    .header("Experiment Results", "Example Experiment")
+    .with_direction({"Latency": "lower_is_better"})
+)
+```
+
+## Comparing methods
+
+Use `split_columns` to compare multiple methods side by side. Each value in the
+split column produces its own set of estimate / forest columns:
+
+```python
+import polars as pl
+import coeftable as ct
+
+methods = pl.DataFrame(
+    {
+        "metric": ["Revenue", "Revenue", "Latency", "Latency"],
+        "method": ["A", "B", "A", "B"],
+        "est": [3.4, 3.1, 0.5, 0.6],
+        "lb": [1.2, 1.0, -1.0, -0.8],
+        "ub": [5.7, 5.2, 2.0, 2.1],
+    }
+)
+
+(
+    ct.CoefTable(
+        methods, rows="metric", split_columns="method", estimate="est", ci=("lb", "ub")
+    )
+    .header("Cohort Revenue by Method")
+)
+```
+
+## Theming
+
+Four built-in themes are available from `coeftable.theme`:
+
+```python
+from coeftable.theme import BLUE, COLORBLIND, DEFAULT, MONO, TEXTUAL
+
+DEFAULT       # Alias for TEXTUAL -- what CoefTable uses if you don't set a theme
+TEXTUAL       # Minimal, publication-style: muted colours, light chrome
+BLUE          # The original blue-grey palette
+COLORBLIND    # Colourblind-safe palette
+MONO          # Grayscale for mono journals
+```
+
+Apply one with `.with_theme(...)`:
+
+```python
+table.with_theme(BLUE)
+```
+
+Customise a theme with `dataclasses.replace`:
+
+```python
+from dataclasses import replace
+
+my_theme = replace(BLUE, favorable="#0072B2")
+```
+
+Use `with_direction` to mark rows where lower values are favourable (reusing
+the `df` frame from [Quick start](#quick-start)):
+
+```python
+table = (
+    ct.CoefTable(df, rows="metric", estimate="est", ci=("lb", "ub"))
+    .with_direction({"Latency": "lower_is_better"})
+)
+```
+
+## 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.

coeftable-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+coeftable/__init__.py,sha256=Te3yTkSGN6qw21tEIDUSgrRFIQOqgAhjm_EiMPqxHyQ,2101
+coeftable/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+coeftable/format.py,sha256=dVB0ZS4jSVPzSeUqAHU14xnzdkbCRoQOLO5TUNAwYjM,6402
+coeftable/frame.py,sha256=CLomTQYWx39PqnQZkOjN-w9wrxyvwQzlNTOPef-Aygk,16798
+coeftable/render.py,sha256=dQghm3DNZaqlrx_zmrXSBbkxoPzHysDaB821kpsVBgk,5781
+coeftable/spec.py,sha256=sTa4qZsiD5g8XlJGPAfWPewBBSbIos_qQ_KuFFJn7qI,12407
+coeftable/svg.py,sha256=nQOSzRzYLT2fQ6V0aRy-SJqpePhDPXle9RbbrEF0m_I,6375
+coeftable/theme.py,sha256=h865hbxC37LPnzuOs0Ss7OOc8pkddSYavSViu-l1U5w,5846
+coeftable-0.1.0.dist-info/METADATA,sha256=WoVh8mvBviU5DZwC6jdNGGnPMpHzw70SYvNBKo5aqEQ,7174
+coeftable-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+coeftable-0.1.0.dist-info/licenses/LICENSE,sha256=KWGy7AY1cdpA9QiaSSaJXX0qWHpMwQtkkIcw5hw_nts,1067
+coeftable-0.1.0.dist-info/RECORD,,

coeftable-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

coeftable-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Caron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.