pysofra 0.1.0a1__py3-none-any.whl

pysofra/summary/smd.py

@@ -0,0 +1,133 @@
+"""Standardized mean differences (SMDs) across groups.
+
+For two groups, the SMD is computed as |mean_1 - mean_2| / sd_pool for
+continuous variables and as the multivariate categorical SMD for factors.
+
+For three or more groups we report the *maximum pairwise* SMD, which is
+the convention used by ``tableone``. Users who want a different summary
+(mean pairwise, single-reference) can post-process the metadata.
+
+References
+----------
+Yang, D., & Dalton, J. E. (2012). A unified approach to measuring the
+effect size between two groups using SAS. SAS Global Forum.
+"""
+
+from __future__ import annotations
+
+from itertools import combinations
+
+import numpy as np
+import pandas as pd
+
+
+def continuous_smd_pair(a: np.ndarray, b: np.ndarray) -> float | None:
+    """SMD between two continuous samples using pooled SD."""
+    a = a[~np.isnan(a)]
+    b = b[~np.isnan(b)]
+    na, nb = a.size, b.size
+    if na < 2 or nb < 2:
+        return None
+    # Same ``inf``-safety wrap as ``continuous_stats``: numpy's mean / var
+    # emit ``RuntimeWarning`` on inf-bearing inputs which escalates to
+    # an exception under the project's ``filterwarnings = error`` gate.
+    # The resulting ``mean = inf`` / ``var = nan`` are handled by the
+    # explicit ``sd_pool == 0.0`` and ``ma == mb`` checks below.
+    import warnings as _w
+    with np.errstate(invalid="ignore", over="ignore"), _w.catch_warnings():
+        _w.simplefilter("ignore", RuntimeWarning)
+        ma, mb = float(np.mean(a)), float(np.mean(b))
+        va, vb = float(np.var(a, ddof=1)), float(np.var(b, ddof=1))
+        sd_pool = float(np.sqrt((va + vb) / 2.0))
+    if sd_pool == 0.0:
+        return 0.0 if ma == mb else float("inf")
+    return abs(ma - mb) / sd_pool
+
+
+def categorical_smd_pair(p1: np.ndarray, p2: np.ndarray) -> float | None:
+    """Multivariate categorical SMD between two proportion vectors.
+
+    ``p1`` and ``p2`` are proportion vectors over the same K levels.
+    Uses the Yang & Dalton (2012) formulation with K-1 dimensions.
+
+    Edge cases. When the (K-1) average covariance ``S`` is the zero
+    matrix the multivariate quadratic form is undefined; this happens
+    when both groups have all mass on a single (possibly different)
+    category, including the *complete-separation* case
+    (e.g. group 1 = "A", group 2 = "B" only). Returning the
+    Mahalanobis distance via the pseudo-inverse silently yields zero
+    in that case, which would report perfect balance — the opposite
+    of the truth. We therefore return ``inf`` when the contrast is
+    nonzero and the covariance is degenerate, and ``0`` when both
+    are zero (groups truly identical).
+    """
+    if p1.size != p2.size or p1.size < 2:
+        return None
+    # Use K-1 categories to avoid singular covariance.
+    p1 = p1[:-1]
+    p2 = p2[:-1]
+    diff = p1 - p2
+    # Mean covariance matrix S = (S1 + S2) / 2
+    s1 = np.diag(p1) - np.outer(p1, p1)
+    s2 = np.diag(p2) - np.outer(p2, p2)
+    s = (s1 + s2) / 2.0
+    # Degenerate covariance: either no variability within either group
+    # (each group concentrates on one category) or the K-1 contrast
+    # space is empty. ``pinv`` returns a near-zero matrix here, which
+    # would falsely report a zero SMD even under complete separation.
+    if np.allclose(s, 0.0):
+        return 0.0 if np.allclose(diff, 0.0) else float("inf")
+    try:
+        s_inv = np.linalg.pinv(s)
+    except np.linalg.LinAlgError:
+        return None
+    val = float(diff @ s_inv @ diff)
+    if val < 0:  # numerical
+        val = 0.0
+    return float(np.sqrt(val))
+
+
+def continuous_smd(values: pd.Series, groups: pd.Series) -> float | None:
+    """Maximum pairwise continuous SMD across groups."""
+    df = pd.DataFrame({"v": pd.to_numeric(values, errors="coerce"), "g": groups}).dropna()
+    if df.empty:
+        return None
+    by_group = {g: x["v"].to_numpy() for g, x in df.groupby("g", observed=True)}
+    keys = list(by_group)
+    if len(keys) < 2:
+        return None
+    if len(keys) == 2:
+        return continuous_smd_pair(by_group[keys[0]], by_group[keys[1]])
+    pair_results = [
+        continuous_smd_pair(by_group[a], by_group[b])
+        for a, b in combinations(keys, 2)
+    ]
+    pairs_cont: list[float] = [p for p in pair_results if p is not None]
+    return max(pairs_cont) if pairs_cont else None
+
+
+def categorical_smd(
+    values: pd.Series,
+    groups: pd.Series,
+    levels: list[object] | tuple[object, ...] | None = None,
+) -> float | None:
+    """Maximum pairwise categorical SMD across groups."""
+    df = pd.DataFrame({"v": values, "g": groups}).dropna()
+    if df.empty:
+        return None
+    ctab = pd.crosstab(df["v"], df["g"])
+    if levels is not None:
+        ctab = ctab.reindex(index=list(levels), fill_value=0)
+    if ctab.shape[0] < 2 or ctab.shape[1] < 2:
+        return None
+    col_totals = ctab.sum(axis=0).replace(0, np.nan)
+    props = (ctab / col_totals).fillna(0.0)
+    keys = list(props.columns)
+    if len(keys) == 2:
+        return categorical_smd_pair(props[keys[0]].to_numpy(), props[keys[1]].to_numpy())
+    cat_pair_results = [
+        categorical_smd_pair(props[a].to_numpy(), props[b].to_numpy())
+        for a, b in combinations(keys, 2)
+    ]
+    pairs_cat: list[float] = [p for p in cat_pair_results if p is not None]
+    return max(pairs_cat) if pairs_cat else None

pysofra/summary/stats.py

@@ -0,0 +1,135 @@
+"""Summary statistic computations for continuous and categorical variables.
+
+Pure functions that take a pandas Series (or groupby slice) and return a
+small dataclass of statistics. Format-free — formatting belongs to
+:mod:`pysofra.core.format`.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class ContinuousStats:
+    n: int
+    n_missing: int
+    mean: float
+    sd: float
+    median: float
+    q1: float
+    q3: float
+    min: float
+    max: float
+
+
+def continuous_stats(series: pd.Series) -> ContinuousStats:
+    """Compute continuous summary statistics. Tolerates all-NaN slices."""
+    s = pd.to_numeric(series, errors="coerce")
+    n_total = len(s)
+    valid = s.dropna()
+    n = int(valid.size)
+    n_missing = int(n_total - n)
+
+    if n == 0:
+        nan = float("nan")
+        return ContinuousStats(0, n_missing, nan, nan, nan, nan, nan, nan, nan)
+
+    arr = valid.to_numpy(dtype=float)
+    # When the array contains ``inf``/``-inf``, numpy's ``mean`` / ``std``
+    # / ``quantile`` emit ``RuntimeWarning: invalid value encountered in
+    # subtract`` (and similar). Under ``filterwarnings = error`` — which
+    # this project's own pyproject.toml sets and which is a common
+    # user-side ``-W error`` posture — those warnings escalate to
+    # exceptions and crash ``tbl_one`` on perfectly legal data. The R6
+    # audit fixed the ``int(np.inf) → OverflowError`` path in
+    # ``infer_kind`` but didn't reach this downstream stats site.
+    # Wrap arithmetic in ``np.errstate`` + ``catch_warnings`` so the
+    # stats compute cleanly to ``nan`` / ``inf`` (which the formatters
+    # then render as em-dash).
+    with np.errstate(invalid="ignore", over="ignore"), warnings.catch_warnings():
+        warnings.simplefilter("ignore", RuntimeWarning)
+        mean = float(np.mean(arr))
+        # Sample SD (ddof=1) is undefined for n=1; we report NaN so renderers
+        # can show ``—`` rather than a misleading "0.00".
+        sd = float(np.std(arr, ddof=1)) if n > 1 else float("nan")
+        median = float(np.median(arr))
+        q1, q3 = (float(x) for x in np.quantile(arr, [0.25, 0.75]))
+        arr_min = float(np.min(arr))
+        arr_max = float(np.max(arr))
+    return ContinuousStats(
+        n=n,
+        n_missing=n_missing,
+        mean=mean,
+        sd=sd,
+        median=median,
+        q1=q1,
+        q3=q3,
+        min=arr_min,
+        max=arr_max,
+    )
+
+
+@dataclass(frozen=True)
+class CategoricalStats:
+    n: int
+    n_missing: int
+    counts: dict[object, int]  # ordered by level
+    levels: tuple[object, ...]
+
+
+def categorical_stats(
+    series: pd.Series,
+    levels: list[object] | tuple[object, ...] | None = None,
+) -> CategoricalStats:
+    """Compute counts per level.
+
+    If ``levels`` is provided, levels missing from the series are included
+    with count 0 (so that grouped tables align across strata).
+    """
+    s = series
+    n_missing = int(s.isna().sum())
+    valid = s.dropna()
+
+    if levels is None:
+        if isinstance(s.dtype, pd.CategoricalDtype):
+            level_list: list[object] = list(s.cat.categories)
+        else:
+            level_list = sorted(valid.unique(), key=_safe_sort_key)
+    else:
+        level_list = list(levels)
+
+    counts: dict[object, int] = {lvl: 0 for lvl in level_list}
+    vc = valid.value_counts(dropna=False)
+    for lvl, c in vc.items():
+        if lvl in counts:
+            counts[lvl] = int(c)
+        else:
+            # Out-of-spec level (only when caller passed explicit levels).
+            counts[lvl] = int(c)
+            level_list.append(lvl)
+
+    return CategoricalStats(
+        n=int(valid.size),
+        n_missing=n_missing,
+        counts=counts,
+        levels=tuple(level_list),
+    )
+
+
+def _safe_sort_key(x: object) -> tuple[int, object]:
+    """Sort key that puts numerics first, then strings, then everything else.
+
+    Avoids ``TypeError`` from mixed-type uniques (e.g. ``[1, "a"]``).
+    """
+    if isinstance(x, bool):
+        return (0, int(x))
+    if isinstance(x, (int, float, np.integer, np.floating)):
+        return (0, float(x))
+    if isinstance(x, str):
+        return (1, x)
+    return (2, repr(x))

pysofra/summary/tbl_cross.py

@@ -0,0 +1,339 @@
+"""Cross-tabulation tables — equivalent to ``gtsummary::tbl_cross``.
+
+``tbl_cross`` builds a two-way contingency table with selectable cell
+content:
+
+* ``n``         — raw count (default)
+* ``row_pct``   — row-percent
+* ``col_pct``   — column-percent
+* ``total_pct`` — overall percent
+* ``n_row_pct`` — n with row-% in parens (the "n (row %)" style)
+* ``n_col_pct`` — n with col-% in parens
+* ``n_total_pct`` — n with total-% in parens
+
+Margins (row totals / column totals / grand total) are added by default
+and can be turned off with ``margins=False``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from ..core.format import fmt_n_pct, fmt_p_value
+from ..core.frames import to_pandas
+from ..core.schema import HeaderCell, HeaderRow, Row, make_cell
+from ..core.table import SofraTable, TableSpec
+
+_CELL_STYLES = (
+    "n", "row_pct", "col_pct", "total_pct",
+    "n_row_pct", "n_col_pct", "n_total_pct",
+)
+
+
+def tbl_cross(
+    data: Any,
+    *,
+    row: str,
+    column: str,
+    cell: str = "n_col_pct",
+    margins: bool = True,
+    digits: int = 1,
+    labels: dict[str, str] | None = None,
+) -> SofraTable:
+    """Cross-tabulate ``row`` against ``column``.
+
+    Parameters
+    ----------
+    data
+        Source dataframe.
+    row
+        Variable name for the rows.
+    column
+        Variable name for the columns.
+    cell
+        How to display each interior cell. See module docstring.
+    margins
+        Include row / column / grand totals.
+    digits
+        Decimal places for the percent.
+    labels
+        Optional mapping of level → display label, applied to both row
+        and column labels.
+
+    Notes
+    -----
+    The returned :class:`SofraTable` carries a rebuild closure over the
+    source ``data`` so the statistical modifiers ``.add_p()`` and
+    ``.add_overall()`` work directly:
+
+    * ``.add_p()`` re-runs the cross-tab and appends a *p*-value
+      footnote based on the auto-selected categorical test (Fisher's
+      exact for 2x2, Pearson χ² otherwise).
+    * ``.add_overall()`` toggles ``margins=True`` so the row, column,
+      and grand totals are rendered (no-op when margins are already on,
+      which is the default).
+    * ``.add_smd()`` raises :class:`NotImplementedError` — SMD is a
+      between-group effect-size on a single distribution and is
+      undefined on a contingency table. Use :func:`tbl_one` for SMD
+      between two arms.
+    """
+    if cell not in _CELL_STYLES:
+        raise ValueError(
+            f"cell must be one of {_CELL_STYLES}; got {cell!r}."
+        )
+    df = to_pandas(data)
+    if row not in df.columns:
+        raise KeyError(f"row column {row!r} not in data")
+    if column not in df.columns:
+        raise KeyError(f"column column {column!r} not in data")
+
+    spec = TableSpec(
+        builder="tbl_cross",
+        options={
+            "row": row,
+            "column": column,
+            "cell": cell,
+            "margins": margins,
+            "digits": digits,
+            "labels": dict(labels or {}),
+            # Modifier flags — toggled by .add_p() / .add_overall() /
+            # .add_smd() via SofraTable._with_option().
+            "p_value": False,
+            "overall": False,
+            "smd": False,
+        },
+    )
+    return _build_cross(df, spec)
+
+
+def _build_cross(df: pd.DataFrame, spec: TableSpec) -> SofraTable:
+    """Build a tbl_cross SofraTable from a frozen source df and spec."""
+    row: str = spec.options["row"]
+    column: str = spec.options["column"]
+    cell: str = spec.options["cell"]
+    # add_overall() forces margins on; the user-passed margins= remains
+    # otherwise.
+    margins: bool = bool(spec.options["margins"] or spec.options.get("overall"))
+    digits: int = int(spec.options["digits"])
+    labels: dict[str, str] = dict(spec.options.get("labels") or {})
+
+    # add_smd() is meaningless on a cross-tab. Surface that explicitly
+    # rather than emitting a spurious "SMD" column or silently dropping
+    # the flag.
+    if spec.options.get("smd"):
+        raise NotImplementedError(
+            "add_smd() is not defined for tbl_cross — SMD measures the "
+            "standardised difference between two distributions of a "
+            "single variable. For SMD between two arms on the same "
+            "variable, use tbl_one(df, by=...).add_smd().",
+        )
+
+    # Drop rows missing either dimension.
+    sub = df[[row, column]].dropna()
+    if sub.empty:
+        # Emit a minimal placeholder table. Carry the spec + rebuild so
+        # the table can still respond to modifiers (no-ops in practice,
+        # but the contract is "rebuild always works").
+        def _empty_rebuild(new_spec: TableSpec) -> SofraTable:  # pragma: no cover — modifier on empty cross-tab
+            return _build_cross(df, new_spec)
+        return SofraTable(
+            rows=(Row(cells=(make_cell(row, align="left", bold=True),
+                             make_cell("—", value=None,
+                                       kind="numeric", align="right"))),),
+            headers=(HeaderRow(cells=(
+                HeaderCell(text=labels.get(row, row), align="left"),
+                HeaderCell(text=labels.get(column, column)),
+            )),),
+            footnotes=("No non-missing rows for the requested cross-tabulation.",),
+            metadata={"builder": "tbl_cross"},
+            _spec=spec,
+            _rebuild=_empty_rebuild,
+        )
+
+    # Preserve categorical ordering where present.
+    if isinstance(df[row].dtype, pd.CategoricalDtype):
+        row_levels = [lvl for lvl in df[row].cat.categories if lvl in set(sub[row])]
+    else:
+        row_levels = sorted(sub[row].unique(), key=_sort_key)
+    if isinstance(df[column].dtype, pd.CategoricalDtype):
+        col_levels = [lvl for lvl in df[column].cat.categories if lvl in set(sub[column])]
+    else:
+        col_levels = sorted(sub[column].unique(), key=_sort_key)
+
+    ctab = pd.crosstab(sub[row], sub[column])
+    ctab = ctab.reindex(index=row_levels, columns=col_levels, fill_value=0)
+
+    row_totals = ctab.sum(axis=1)
+    col_totals = ctab.sum(axis=0)
+    grand_total = float(ctab.values.sum())
+
+    # ------------------------------------------------------------------
+    # Headers
+    # ------------------------------------------------------------------
+    header_cells = [HeaderCell(text=labels.get(row, row), align="left")]
+    for lvl in col_levels:
+        header_cells.append(HeaderCell(text=labels.get(lvl, str(lvl))))
+    if margins:
+        header_cells.append(HeaderCell(text="Total"))
+    headers = (HeaderRow(cells=tuple(header_cells)),)
+
+    # spanning header naming the column variable
+    from ..core.schema import SpanningHeader
+    spanning: tuple[SpanningHeader, ...]
+    if len(col_levels) > 0:
+        spanning = (SpanningHeader(
+            label=labels.get(column, column),
+            start=1,
+            end=len(col_levels) + (1 if margins else 0),
+        ),)
+    else:  # pragma: no cover — guarded by the empty-sub short-circuit above
+        spanning = ()
+
+    # ------------------------------------------------------------------
+    # Body rows
+    # ------------------------------------------------------------------
+    rows: list[Row] = []
+    for r_lvl in row_levels:
+        body = [make_cell(labels.get(r_lvl, str(r_lvl)), align="left")]
+        for c_lvl in col_levels:
+            n = int(ctab.loc[r_lvl, c_lvl])
+            body.append(_fmt_cross_cell(
+                n=n,
+                row_total=int(row_totals.loc[r_lvl]),
+                col_total=int(col_totals.loc[c_lvl]),
+                grand_total=grand_total,
+                style=cell,
+                digits=digits,
+            ))
+        if margins:
+            rt = int(row_totals.loc[r_lvl])
+            body.append(make_cell(
+                _fmt_margin(rt, grand_total, style=cell, digits=digits),
+                value=rt, kind="numeric", align="right",
+            ))
+        rows.append(Row(cells=tuple(body)))
+
+    # Margin row
+    if margins:
+        body = [make_cell("Total", align="left", bold=True)]
+        for c_lvl in col_levels:
+            ct = int(col_totals.loc[c_lvl])
+            body.append(make_cell(
+                _fmt_margin(ct, grand_total, style=cell, digits=digits),
+                value=ct, kind="numeric", align="right",
+            ))
+        body.append(make_cell(
+            f"{int(grand_total):,}",
+            value=int(grand_total),
+            kind="numeric", align="right", bold=True,
+        ))
+        rows.append(Row(cells=tuple(body), is_group_header=True))
+
+    footnotes = [_footnote_for(cell)]
+
+    # ------------------------------------------------------------------
+    # add_p() — auto-selected categorical test on the full contingency.
+    # Reported as a footnote so the table body stays a clean grid.
+    # ------------------------------------------------------------------
+    metadata: dict[str, Any] = {"builder": "tbl_cross"}
+    if spec.options.get("p_value"):
+        from .tests import categorical_test
+        res = categorical_test(sub[row], sub[column])
+        if res.p_value is not None:
+            footnotes.append(
+                f"{res.test}: p = {fmt_p_value(res.p_value)}",
+            )
+            # Surface the raw p-value + test name in metadata for
+            # programmatic consumers (e.g. golden tests, downstream
+            # reports that want the numeric value).
+            metadata["p_value"] = float(res.p_value)
+            metadata["p_test"] = res.test
+
+    def _rebuild(new_spec: TableSpec) -> SofraTable:
+        return _build_cross(df, new_spec)
+
+    return SofraTable(
+        rows=tuple(rows),
+        headers=headers,
+        spanning_headers=spanning,
+        footnotes=tuple(footnotes),
+        metadata=metadata,
+        _spec=spec,
+        _rebuild=_rebuild,
+    )
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+def _fmt_cross_cell(
+    *, n: int, row_total: int, col_total: int, grand_total: float,
+    style: str, digits: int,
+) -> Any:
+    """Format one body cell of the cross-tab according to ``style``."""
+    if style == "n":
+        return make_cell(f"{n:,}", value=n, kind="numeric", align="right")
+    if style == "row_pct":
+        pct = 100.0 * n / row_total if row_total else float("nan")
+        return make_cell(_pct(pct, digits), value=pct,
+                         kind="numeric", align="right")
+    if style == "col_pct":
+        pct = 100.0 * n / col_total if col_total else float("nan")
+        return make_cell(_pct(pct, digits), value=pct,
+                         kind="numeric", align="right")
+    if style == "total_pct":
+        pct = 100.0 * n / grand_total if grand_total else float("nan")
+        return make_cell(_pct(pct, digits), value=pct,
+                         kind="numeric", align="right")
+    if style == "n_row_pct":
+        return make_cell(fmt_n_pct(n, row_total, digits=digits),
+                         value=n, kind="numeric", align="right")
+    if style == "n_col_pct":
+        return make_cell(fmt_n_pct(n, col_total, digits=digits),
+                         value=n, kind="numeric", align="right")
+    if style == "n_total_pct":
+        return make_cell(fmt_n_pct(n, int(grand_total), digits=digits),
+                         value=n, kind="numeric", align="right")
+    raise ValueError(f"unknown cell style {style!r}")  # pragma: no cover — guarded by top-level cell-style validation
+
+
+def _fmt_margin(n: int, grand_total: float, *, style: str, digits: int) -> str:
+    """Margin cell formatting — always 'n (overall %)' for n-style cells."""
+    if style.startswith("n_"):
+        return fmt_n_pct(n, int(grand_total), digits=digits)
+    if style in ("row_pct", "col_pct", "total_pct"):
+        return _pct(100.0 * n / grand_total if grand_total else float("nan"),
+                    digits)
+    return f"{n:,}"
+
+
+def _pct(p: float, digits: int) -> str:
+    import math
+    if p is None or (isinstance(p, float) and math.isnan(p)):
+        return "—"
+    return f"{p:.{digits}f}%"
+
+
+def _footnote_for(style: str) -> str:
+    return {
+        "n":            "Cells: raw counts.",
+        "row_pct":      "Cells: row-percent.",
+        "col_pct":      "Cells: column-percent.",
+        "total_pct":    "Cells: overall percent.",
+        "n_row_pct":    "Cells: n (row-%).",
+        "n_col_pct":    "Cells: n (column-%).",
+        "n_total_pct":  "Cells: n (overall-%).",
+    }[style]
+
+
+def _sort_key(x: Any) -> tuple[int, Any]:
+    if isinstance(x, bool):
+        return (0, int(x))
+    if isinstance(x, (int, float)):
+        return (0, float(x))
+    if isinstance(x, str):
+        return (1, x)
+    return (2, repr(x))