pysofra 0.1.0a1__py3-none-any.whl

pysofra/plot/inline.py

@@ -0,0 +1,171 @@
+"""Cross-backend inline plot representation.
+
+When a plot is attached to a :class:`SofraTable`, we keep multiple
+serialised forms so each renderer can pick the one it needs:
+
+* ``svg`` — for the HTML renderer.
+* ``png_bytes`` — for DOCX and PPTX.
+* ``pdf_bytes`` — for LaTeX (written as a sidecar file at export time).
+
+All three are rendered once from the same matplotlib figure, ensuring
+the visual representation is consistent across formats.
+
+**Determinism.** matplotlib by default embeds the current wall-clock
+timestamp and a process-random hash salt into every SVG/PNG/PDF it
+writes. That makes binary renders unstable across processes and
+breaks PySofra's "byte-identical reproducibility" guarantee for
+plot-embedded tables. The helpers in this module strip those
+non-deterministic fields so the same figure always serialises to the
+same bytes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import re
+from dataclasses import dataclass
+from typing import Any
+
+# A fixed (project-stable) hash salt overrides matplotlib's random
+# default for inline SVG/PDF element IDs.
+_HASH_SALT = "pysofra-inline-plot"
+
+# Constant timestamp baked into PDF metadata so two renders of the
+# same figure are byte-identical. The literal predates the project
+# and has no operational meaning.
+_PDF_FIXED_DATE = b"D:20260101000000Z"
+
+
+def _configure_deterministic_matplotlib() -> None:
+    """Pin matplotlib's hash salt and metadata so output is reproducible.
+
+    Idempotent — safe to call repeatedly.
+    """
+    try:
+        import matplotlib as mpl
+    except ImportError:  # pragma: no cover — matplotlib is an optional extra
+        return
+    mpl.rcParams["svg.hashsalt"] = _HASH_SALT
+
+
+# Patterns used to strip the timestamp from SVG / PNG / PDF outputs.
+_SVG_DATE_RE = re.compile(
+    rb"<dc:date>[^<]*</dc:date>",
+    re.IGNORECASE,
+)
+_PDF_DATE_RE = re.compile(
+    rb"/(?:CreationDate|ModDate)\s*\(D:\d+(?:Z|[+\-]\d{2}'\d{2}')?\)",
+)
+_PDF_ID_RE = re.compile(
+    rb"/ID\s*\[\s*<[0-9A-Fa-f]+>\s*<[0-9A-Fa-f]+>\s*\]",
+)
+
+
+def _strip_svg_nondeterminism(svg_bytes: bytes) -> bytes:
+    """Remove timestamp metadata from an SVG byte stream."""
+    return _SVG_DATE_RE.sub(b"<dc:date>2026-01-01T00:00:00</dc:date>", svg_bytes)
+
+
+def _strip_pdf_nondeterminism(pdf_bytes: bytes) -> bytes:
+    """Pin /CreationDate, /ModDate, and /ID in a PDF byte stream."""
+    out = _PDF_DATE_RE.sub(b"/CreationDate (" + _PDF_FIXED_DATE + b")", pdf_bytes)
+    # We always emit a deterministic /ID derived from the file hash so the
+    # two-id PDF reference is stable across runs.
+    digest = hashlib.sha256(out).hexdigest()[:32].upper().encode()
+    out = _PDF_ID_RE.sub(b"/ID [<" + digest + b"><" + digest + b">]", out)
+    return out
+
+
+def _strip_png_nondeterminism(png_bytes: bytes) -> bytes:
+    """Strip the optional ``tIME`` and ``tEXt`` chunks from a PNG.
+
+    PNG's ``tIME`` chunk stores the modification time; ``tEXt``/``iTXt``
+    chunks added by matplotlib's `Software` key embed the matplotlib
+    version + Python build banner. Removing them gives byte-stable PNG
+    output across runs and across matplotlib patch releases.
+    """
+    # PNG layout: 8-byte signature, then a sequence of chunks
+    #   [length (4) | type (4) | data (length) | crc (4)]
+    if not png_bytes.startswith(b"\x89PNG\r\n\x1a\n"):
+        return png_bytes  # pragma: no cover — not a PNG
+    out = bytearray(png_bytes[:8])
+    pos = 8
+    drop_types = {b"tIME", b"tEXt", b"iTXt", b"zTXt"}
+    while pos < len(png_bytes):
+        if pos + 8 > len(png_bytes):  # pragma: no cover — malformed
+            break
+        length = int.from_bytes(png_bytes[pos : pos + 4], "big")
+        ctype = png_bytes[pos + 4 : pos + 8]
+        chunk_end = pos + 8 + length + 4  # data + crc
+        if ctype not in drop_types:
+            out.extend(png_bytes[pos:chunk_end])
+        pos = chunk_end
+    return bytes(out)
+
+
+def fig_to_svg(fig: Any) -> str:
+    """Serialise a matplotlib Figure to a deterministic inline SVG string.
+
+    Trims the ``<?xml ...?>`` / ``<!DOCTYPE ...>`` headers so the result
+    can be embedded directly into HTML, replaces the explicit
+    width / height attributes with a responsive ``max-width:100%``
+    style so the SVG scales inside its container, and strips the
+    ``<dc:date>`` timestamp so two consecutive renders are byte-equal.
+    """
+    _configure_deterministic_matplotlib()
+    buf = io.BytesIO()
+    fig.savefig(buf, format="svg", bbox_inches="tight")
+    raw = _strip_svg_nondeterminism(buf.getvalue())
+    svg = raw.decode("utf-8")
+    idx = svg.find("<svg")
+    if idx > 0:
+        svg = svg[idx:]
+    svg = svg.replace(
+        "<svg ", '<svg style="max-width:100%;height:auto;" ', 1,
+    )
+    return svg
+
+
+@dataclass(frozen=True)
+class InlinePlot:
+    """A plot serialised for every backend PySofra supports."""
+
+    svg: str
+    png_bytes: bytes
+    pdf_bytes: bytes
+    width_in: float
+    height_in: float
+
+
+def render_inline_plot(fig: Any, *, width_in: float, height_in: float,
+                       dpi: int = 200) -> InlinePlot:
+    """Serialise a matplotlib figure to SVG + PNG + PDF in one pass.
+
+    All three byte streams are post-processed to remove the
+    timestamps / process-randomised IDs matplotlib would otherwise
+    embed, so the output is byte-identical across runs of the same
+    PySofra version.
+    """
+    _configure_deterministic_matplotlib()
+    svg = fig_to_svg(fig)
+
+    # PNG bytes — for DOCX / PPTX.
+    png_buf = io.BytesIO()
+    fig.savefig(png_buf, format="png", bbox_inches="tight", dpi=dpi,
+                metadata={"Software": None})
+    png_bytes = _strip_png_nondeterminism(png_buf.getvalue())
+
+    # PDF bytes — for LaTeX sidecar.
+    pdf_buf = io.BytesIO()
+    fig.savefig(pdf_buf, format="pdf", bbox_inches="tight",
+                metadata={"CreationDate": None, "ModDate": None})
+    pdf_bytes = _strip_pdf_nondeterminism(pdf_buf.getvalue())
+
+    return InlinePlot(
+        svg=svg,
+        png_bytes=png_bytes,
+        pdf_bytes=pdf_bytes,
+        width_in=width_in,
+        height_in=height_in,
+    )

pysofra/plot/km.py

@@ -0,0 +1,249 @@
+"""Kaplan–Meier curve rendering for tbl_survival SofraTables.
+
+This function does *not* re-extract the KM fits from the table — those
+aren't preserved in the rendered structure. Instead it accepts the same
+data the user passed to ``tbl_survival`` and fits curves freshly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..core.frames import to_pandas
+from .inline import InlinePlot, fig_to_svg, render_inline_plot
+
+
+def km_curve(
+    data: Any,
+    *,
+    time: str,
+    event: str,
+    by: str | None = None,
+    width_in: float = 6.5,
+    height_in: float = 4.0,
+    ci: bool = True,
+    xlabel: str = "Time",
+    ylabel: str = "Survival probability",
+    palette: list[str] | None = None,
+    risk_times: list[float] | tuple[float, ...] | None = None,
+) -> InlinePlot:
+    """Render KM curves as an :class:`InlinePlot` (SVG + PNG + PDF).
+
+    ``risk_times`` adds a numbers-at-risk table below the curves at the
+    listed time points (no table is added when ``risk_times`` is None).
+    """
+    fig = _build_km_figure(
+        data, time=time, event=event, by=by,
+        width_in=width_in, height_in=height_in, ci=ci,
+        xlabel=xlabel, ylabel=ylabel, palette=palette,
+        risk_times=risk_times,
+    )
+    plot = render_inline_plot(fig, width_in=width_in, height_in=height_in)
+    try:
+        import matplotlib.pyplot as plt
+        plt.close(fig)
+    except ImportError:  # pragma: no cover
+        pass
+    return plot
+
+
+def km_curve_svg(
+    data: Any,
+    *,
+    time: str,
+    event: str,
+    by: str | None = None,
+    width_in: float = 6.5,
+    height_in: float = 4.0,
+    ci: bool = True,
+    xlabel: str = "Time",
+    ylabel: str = "Survival probability",
+    palette: list[str] | None = None,
+    risk_times: list[float] | tuple[float, ...] | None = None,
+) -> str:
+    """Render Kaplan–Meier curves to an inline SVG string."""
+    fig = _build_km_figure(
+        data, time=time, event=event, by=by,
+        width_in=width_in, height_in=height_in, ci=ci,
+        xlabel=xlabel, ylabel=ylabel, palette=palette,
+        risk_times=risk_times,
+    )
+    svg = fig_to_svg(fig)
+    try:
+        import matplotlib.pyplot as plt
+        plt.close(fig)
+    except ImportError:  # pragma: no cover
+        pass
+    return svg
+
+
+def _build_km_figure(
+    data: Any,
+    *,
+    time: str,
+    event: str,
+    by: str | None,
+    width_in: float,
+    height_in: float,
+    ci: bool,
+    xlabel: str,
+    ylabel: str,
+    palette: list[str] | None,
+    risk_times: list[float] | tuple[float, ...] | None = None,
+) -> Any:
+    try:
+        from ._backend import use_headless_backend
+        use_headless_backend()
+        import matplotlib.pyplot as plt
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "KM curves require matplotlib. Install with "
+            "`pip install matplotlib`."
+        ) from e
+    try:
+        from lifelines import KaplanMeierFitter
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("KM curves require lifelines.") from e
+
+    df = to_pandas(data)
+    df_groups = (
+        [("Overall", df)]
+        if by is None
+        else list(df.groupby(by, observed=True))
+    )
+
+    palette = palette or [
+        "#0b3d91", "#c1272d", "#198754", "#ffc107", "#6f42c1", "#fd7e14",
+    ]
+
+    # Risk-table augment: shrink the curve axes and add a small axes
+    # underneath listing N at risk per group at each requested time.
+    n_groups_pred = len(df_groups)
+
+    if risk_times:
+        from matplotlib.gridspec import GridSpec
+
+        # Each column needs roughly one digit's worth of breathing room
+        # so adjacent two-/three-digit at-risk counts never touch.
+        min_w = max(width_in, 1.5 + 0.55 * len(risk_times))
+        # Each group row in the risk table needs ~0.28 in plus a small
+        # cushion for the heading.
+        risk_h_in = 0.28 * n_groups_pred + 0.55
+        total_h = height_in + risk_h_in + 0.25
+        fig = plt.figure(figsize=(min_w, total_h))
+        gs = GridSpec(
+            2, 1, figure=fig,
+            height_ratios=[height_in, risk_h_in],
+            hspace=0.32,
+        )
+        ax = fig.add_subplot(gs[0])
+        ax_risk = fig.add_subplot(gs[1], sharex=ax)
+    else:
+        fig, ax = plt.subplots(figsize=(width_in, height_in))
+        ax_risk = None
+
+    fits: dict[str, Any] = {}
+    for i, (label, sub) in enumerate(df_groups):
+        sub = sub.dropna(subset=[time, event])
+        if sub.empty:
+            continue
+        kmf = KaplanMeierFitter()
+        kmf.fit(sub[time], sub[event], label=str(label))
+        fits[str(label)] = kmf
+        color = palette[i % len(palette)]
+        kmf.plot_survival_function(ax=ax, ci_show=ci, color=color)
+
+    ax.set_ylabel(ylabel)
+    ax.set_ylim(0, 1.02)
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    if by is None:
+        legend = ax.get_legend()
+        if legend is not None:
+            legend.set_visible(False)
+
+    if ax_risk is not None and risk_times:
+        # Clamp the x-window to the range the user asked about. Without
+        # this, a long-tailed survival curve (e.g. one censored case at
+        # t=110 when risk_times stop at 30) inflates xlim and crams every
+        # risk-table column into the leftmost slice of the figure.
+        rt_min = float(min(risk_times))
+        rt_max = float(max(risk_times))
+        span = max(rt_max - rt_min, 1e-9)
+        # Generous left pad so the first risk-table number sits *inside*
+        # the axes (otherwise a centered "165" at t=0 punches through the
+        # y-axis into the "Placebo"/"Treatment" label column).
+        ax.set_xlim(rt_min - 0.08 * span, rt_max + 0.04 * span)
+
+        # Clear the curve's bottom axis — the risk table owns the x-axis labels.
+        ax.set_xlabel("")
+        ax.tick_params(axis="x", labelbottom=False)
+
+        # Risk-table axis. We want a *grid of numbers*: rows = groups, cols
+        # = time points. Numbers sit at (t_pt, group_index) in data
+        # coordinates so they line up vertically with the curve.
+        n_groups = len(fits)
+        ax_risk.set_xlim(ax.get_xlim())
+        ax_risk.set_xticks(list(risk_times))
+        # Force the tick labels to render as integers / floats with no
+        # trailing zeroes so they don't collide.
+        ax_risk.set_xticklabels([
+            f"{int(t)}" if float(t).is_integer() else f"{t:g}"
+            for t in risk_times
+        ], fontsize=9)
+        ax_risk.tick_params(axis="x", length=4, pad=2)
+
+        # Group labels on y, ordered top-to-bottom to mirror the curve legend.
+        ax_risk.set_yticks(range(n_groups))
+        ax_risk.set_yticklabels(list(fits.keys()), fontsize=9)
+        ax_risk.set_ylim(-0.5, n_groups - 0.5)
+        ax_risk.invert_yaxis()
+        ax_risk.tick_params(axis="y", length=0, pad=4)
+        for spine in ("top", "right", "left"):
+            ax_risk.spines[spine].set_visible(False)
+
+        # Auto-scale font down for very dense risk tables.
+        font_size = 9 if len(risk_times) <= 6 else 8
+
+        # Render numbers at each (time, group) cell.
+        for i, (_name, kmf) in enumerate(fits.items()):
+            for t_pt in risk_times:
+                n_at_risk = _n_at_risk(kmf, float(t_pt))
+                ax_risk.text(
+                    t_pt, i, f"{n_at_risk}",
+                    ha="center", va="center", fontsize=font_size,
+                )
+
+        ax_risk.set_xlabel(xlabel)
+        # "Number at risk" heading sits above the *numbers* portion (centered
+        # over the columns), using axes coordinates so it never collides with
+        # the curve plot or the values themselves.
+        ax_risk.text(
+            0.5, 1.20,
+            "Number at risk",
+            transform=ax_risk.transAxes,
+            fontsize=9, fontweight="bold",
+            ha="center", va="bottom",
+        )
+    else:
+        ax.set_xlabel(xlabel)
+
+    return fig
+
+
+def _n_at_risk(kmf: Any, t: float) -> int:
+    """Number of individuals at risk *just before* time ``t``.
+
+    See :func:`pysofra.models.survival._n_at_risk` for the convention
+    rationale — this is the same implementation, duplicated to avoid
+    a cross-module import in the matplotlib hot path.
+    """
+    try:
+        tbl = kmf.event_table
+        idx = tbl.index[tbl.index >= t]
+        if len(idx) == 0:
+            return 0
+        first_t = idx.min()
+        return int(tbl.loc[first_t, "at_risk"])
+    except Exception:  # pragma: no cover
+        return 0

pysofra/render/__init__.py

@@ -0,0 +1,28 @@
+"""Renderers — backend-agnostic output of :class:`~pysofra.core.SofraTable`."""
+
+from .docx import DocxRenderer
+from .html import HtmlRenderer
+from .latex import LatexRenderer
+from .markdown import MarkdownRenderer
+
+# PPTX and XLSX renderers are optional — gated on their backends.
+PptxRenderer: type | None
+XlsxRenderer: type | None
+try:
+    from .pptx import PptxRenderer
+except ImportError:  # pragma: no cover
+    PptxRenderer = None
+
+try:
+    from .xlsx import XlsxRenderer
+except ImportError:  # pragma: no cover
+    XlsxRenderer = None
+
+__all__ = [
+    "DocxRenderer",
+    "HtmlRenderer",
+    "LatexRenderer",
+    "MarkdownRenderer",
+    "PptxRenderer",
+    "XlsxRenderer",
+]

pysofra/render/_zip_determinism.py

@@ -0,0 +1,57 @@
+"""Make ZIP-based document outputs (.docx, .pptx) byte-deterministic
+across processes.
+
+Both ``python-docx`` and ``python-pptx`` save their documents as OOXML
+ZIP archives. The XML *contents* are deterministic given a deterministic
+input, but the underlying ``zipfile.ZipFile.writestr`` stamps each entry
+with ``time.localtime()`` by default, so two saves at different wall
+times produce different bytes even though every file inside is
+identical.
+
+PySofra's published claim is that every renderer produces
+byte-deterministic output. To honour that for the OOXML formats, after
+``python-docx`` / ``python-pptx`` finishes writing the archive we
+rewrite it in-place with every entry's ``date_time`` pinned to a fixed
+epoch and the compression level fixed.
+"""
+
+from __future__ import annotations
+
+import io
+import zipfile
+from pathlib import Path
+
+# Fixed wall-clock used for every ZIP entry's ``date_time`` field. The
+# ZIP format only stores DOS time (2-second granularity from 1980); we
+# use a deterministic constant well clear of that lower bound.
+_FIXED_DATE_TIME: tuple[int, int, int, int, int, int] = (2000, 1, 1, 0, 0, 0)
+
+
+def make_zip_deterministic(path: Path) -> None:
+    """Rewrite ``path`` (an OOXML zip) so its bytes are reproducible.
+
+    Reads every entry, pins ``date_time`` to ``_FIXED_DATE_TIME``, and
+    writes the archive back with the same compression mode and preserved
+    entry order. Idempotent — applying twice produces the same bytes.
+
+    Parameters
+    ----------
+    path
+        Path to a ZIP-format file (``.docx``, ``.pptx``, ``.xlsx``).
+    """
+    p = Path(path)
+    raw = p.read_bytes()
+    buf = io.BytesIO()
+    with zipfile.ZipFile(io.BytesIO(raw), mode="r") as src, \
+            zipfile.ZipFile(buf, mode="w") as dst:
+        for info in src.infolist():
+            new_info = zipfile.ZipInfo(
+                filename=info.filename,
+                date_time=_FIXED_DATE_TIME,
+            )
+            new_info.compress_type = info.compress_type
+            new_info.external_attr = info.external_attr
+            new_info.create_system = info.create_system
+            new_info.internal_attr = info.internal_attr
+            dst.writestr(new_info, src.read(info.filename))
+    p.write_bytes(buf.getvalue())

pysofra/render/base.py

@@ -0,0 +1,22 @@
+"""Base renderer interface.
+
+All renderers consume a :class:`~pysofra.core.SofraTable` and produce output
+in their target format. Concrete renderers live in sibling modules.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from ..core.table import SofraTable
+
+T = TypeVar("T")
+
+
+class Renderer(ABC, Generic[T]):
+    """Abstract base for all renderers."""
+
+    @abstractmethod
+    def render(self, table: SofraTable) -> T:  # pragma: no cover — interface
+        ...