pycrr 0.1.0__py3-none-any.whl

pycrr/__init__.py

@@ -0,0 +1,19 @@
+from pycrr.surv import Surv
+from pycrr.model import FineGrayModel
+from pycrr.core import estimate_ipcw_weights
+from pycrr.estimator import AalenJohansen
+from pycrr.compare import gray_test, GrayTestResult
+from pycrr.metrics import brier_score, integrated_brier_score, concordance
+
+__all__ = [
+    "Surv",
+    "FineGrayModel",
+    "estimate_ipcw_weights",
+    "AalenJohansen",
+    "gray_test",
+    "GrayTestResult",
+    "brier_score",
+    "integrated_brier_score",
+    "concordance",
+]
+__version__ = "0.1.0"

pycrr/compare.py

@@ -0,0 +1,176 @@
+"""
+Gray's K-sample test for comparing cumulative incidence functions.
+"""
+
+import numpy as np
+from scipy import stats
+from pycrr.surv import Surv
+
+
+class GrayTestResult:
+    """Result of Gray's test."""
+
+    def __init__(self, statistic, pvalue, df, group_stats, groups):
+        self.statistic   = statistic
+        self.pvalue      = pvalue
+        self.df          = df
+        self.group_stats = group_stats   # {group_label: U_g}
+        self.groups      = groups
+
+    def __repr__(self):
+        return (
+            f"GrayTestResult(statistic={self.statistic:.4f}, "
+            f"pvalue={self.pvalue:.4f}, df={self.df})"
+        )
+
+    def summary(self):
+        print(f"Gray's test  —  chi-squared = {self.statistic:.4f}, "
+              f"df = {self.df}, p = {self.pvalue:.4f}")
+        print(f"{'Group':>12}  {'U statistic':>12}")
+        print("-" * 27)
+        for g, u in self.group_stats.items():
+            print(f"{str(g):>12}  {u:12.4f}")
+
+
+def gray_test(time, event, group=None, cause=1, rho=0):
+    """
+    Gray's K-sample test for equality of cumulative incidence functions.
+
+    Tests H0: F_k^(1)(t) = ... = F_k^(G)(t) for all t, where k is the
+    specified cause of interest and superscripts denote groups.
+
+    The test uses the subdistribution risk set (subjects who experienced
+    competing events remain at risk) and optionally applies CIF-based
+    weighting following Gray (1988).
+
+    Parameters
+    ----------
+    time : array-like of shape (n,)
+        Observed times.
+    event : array-like of shape (n,)
+        Event indicators: 0 = censored, 1 = cause of interest, 2+ = competing.
+    group : array-like of shape (n,)
+        Group labels.  Can be any comparable values (int, str, etc.).
+    cause : int
+        Which cause to test.  Default 1.
+    rho : float
+        Weight exponent for Fleming-Harrington-type weighting.
+        ``rho=0`` (default) gives equal weights (log-rank type).
+        ``rho=1`` downweights late differences.
+
+    Returns
+    -------
+    GrayTestResult
+        Attributes: ``statistic``, ``pvalue``, ``df``, ``group_stats``.
+
+    References
+    ----------
+    Gray, R. J. (1988). A class of K-sample tests for comparing the
+    cumulative incidence of a competing risk. Annals of Statistics,
+    16(3), 1141-1154.
+    """
+    if isinstance(time, Surv):
+        # gray_test(Surv(time, event), group, ...)
+        group = event
+        time, event = time
+    elif group is None:
+        raise ValueError("group is required when time is not a Surv object.")
+    time  = np.asarray(time,  dtype=float)
+    event = np.asarray(event, dtype=int)
+    group = np.asarray(group)
+    n     = len(time)
+
+    groups  = np.sort(np.unique(group))
+    G       = len(groups)
+
+    if G < 2:
+        raise ValueError("gray_test requires at least 2 groups.")
+
+    # Unique times where cause-k events occur (pooled across groups)
+    cause_mask  = event == cause
+    cause_times = np.sort(np.unique(time[cause_mask]))
+
+    if len(cause_times) == 0:
+        raise ValueError(f"No events of cause {cause} found in the data.")
+
+    # Pooled CIF for weight function (needed when rho > 0)
+    pooled_cif_at_t = np.zeros(len(cause_times))
+    if rho > 0:
+        from pycrr.estimator import AalenJohansen
+        aj = AalenJohansen().fit(time, event)
+        if cause in aj.causes_:
+            _, cif_vals = aj.predict(cause, times=cause_times)
+            # We need CIF(t^-): use value at the step just before t
+            # Step interp already gives left-continuous values at t via "previous"
+            # Shift to get F(t^-): use interp at t - epsilon
+            eps = np.finfo(float).eps * cause_times
+            _, cif_before = aj.predict(cause, times=np.maximum(cause_times - 1e-8, 0))
+            pooled_cif_at_t = cif_before
+
+    # U statistics for each group, covariance matrix
+    U     = np.zeros(G)
+    Sigma = np.zeros((G, G))
+
+    for j, t in enumerate(cause_times):
+        # Weight at time t
+        w = (max(1.0 - pooled_cif_at_t[j], 0.0)) ** rho if rho > 0 else 1.0
+
+        # Subdistribution risk set at t (pooled):
+        # subject i is at risk if T_i >= t OR (T_i < t AND cause_i is competing)
+        competing = (event != 0) & (event != cause)
+        in_risk   = (time >= t) | ((time < t) & competing)
+        Y_total   = int(in_risk.sum())
+
+        if Y_total == 0:
+            continue
+
+        # Total cause-k events at t
+        dN_total = int(np.sum((time == t) & cause_mask))
+
+        # Per-group at-risk counts and event counts
+        Y_g  = np.array([int((in_risk & (group == g)).sum()) for g in groups])
+        dN_g = np.array([int(np.sum((time == t) & cause_mask & (group == g)))
+                         for g in groups])
+
+        expected = Y_g / Y_total * dN_total
+        U += w * (dN_g - expected)
+
+        # Covariance update
+        for gi in range(G):
+            for hi in range(G):
+                if gi == hi:
+                    Sigma[gi, gi] += (
+                        w**2
+                        * Y_g[gi] * (Y_total - Y_g[gi])
+                        / Y_total**2
+                        * dN_total
+                    )
+                else:
+                    Sigma[gi, hi] -= (
+                        w**2
+                        * Y_g[gi] * Y_g[hi]
+                        / Y_total**2
+                        * dN_total
+                    )
+
+    # Drop last group (constraint: sum U_g = 0)
+    U_trunc   = U[:G - 1]
+    Sig_trunc = Sigma[:G - 1, :G - 1]
+
+    # Chi-squared statistic
+    try:
+        Sig_inv  = np.linalg.inv(Sig_trunc)
+        stat     = float(U_trunc @ Sig_inv @ U_trunc)
+        stat     = max(stat, 0.0)   # numerical guard
+    except np.linalg.LinAlgError:
+        stat = np.nan
+
+    pvalue = float(1.0 - stats.chi2.cdf(stat, df=G - 1)) if np.isfinite(stat) else np.nan
+
+    return GrayTestResult(
+        statistic=stat,
+        pvalue=pvalue,
+        df=G - 1,
+        group_stats={g: float(U[i]) for i, g in enumerate(groups)},
+        groups=groups.tolist(),
+    )

pycrr/core.py

@@ -0,0 +1,78 @@
+import numpy as np
+from lifelines import KaplanMeierFitter
+
+
+def _censoring_survival(time, event, clip=1e-10):
+    """
+    KM estimate of the censoring survival function G(t) = P(C > t).
+
+    Returns a callable G_func(t) -> float that evaluates the left-continuous
+    step function at any time point.  Used internally by FineGrayModel for
+    time-varying IPCW weights.
+    """
+    time  = np.asarray(time, dtype=float)
+    event = np.asarray(event)
+    km    = KaplanMeierFitter()
+    km.fit(durations=time, event_observed=(event == 0).astype(int))
+
+    _times = km.event_table.index.values
+    _surv  = km.survival_function_["KM_estimate"].values
+
+    def G_func(t):
+        idx = int(np.clip(
+            np.searchsorted(_times, np.asarray(t) - 1e-8, side="right") - 1,
+            0, len(_surv) - 1,
+        ))
+        return float(max(_surv[idx], clip))
+
+    return G_func
+
+
+def estimate_ipcw_weights(time, event, clip=0.05):
+    """
+    Estimate inverse probability of censoring weights (IPCW) via Kaplan-Meier.
+
+    Fits a KM estimator on the censoring distribution G(t) and returns
+    subject-level weights 1/G(t_i-), normalized to mean 1.  Competing-event
+    subjects always receive weight 1.0 (they are not censored with respect to
+    the subdistribution).
+
+    Parameters
+    ----------
+    time : array-like of shape (n,)
+        Observed times (time to event or censoring).
+    event : array-like of shape (n,)
+        Event indicators: 0 = censored, 1 = event of interest, 2 = competing event.
+    clip : float
+        Floor applied to G(t) before inversion to prevent extreme weights.
+        Default 0.05.
+
+    Returns
+    -------
+    weights : ndarray of shape (n,)
+        Subject-level IPCW weights, normalized so that mean(weights) = 1.
+    ipcw_func : callable
+        A function ``ipcw_func(t) -> float`` that evaluates the weight at any
+        time point.  Useful for time-varying weight schemes.
+    """
+    time  = np.asarray(time,  dtype=float)
+    event = np.asarray(event)
+
+    censoring_indicator = (event == 0).astype(int)
+    km = KaplanMeierFitter()
+    km.fit(durations=time, event_observed=censoring_indicator)
+
+    event_times = km.event_table.index.values
+    surv_probs  = km.survival_function_["KM_estimate"].values
+
+    def ipcw_func(t):
+        idx = np.searchsorted(event_times, np.asarray(t) - 1e-8, side="right") - 1
+        idx = np.clip(idx, 0, len(surv_probs) - 1)
+        G   = surv_probs[idx]
+        return 1.0 / np.clip(G, clip, 1.0)
+
+    weights          = ipcw_func(time)
+    weights[event == 2] = 1.0
+    weights          = weights / np.mean(weights)
+
+    return weights, ipcw_func

pycrr/estimator.py

@@ -0,0 +1,255 @@
+"""
+Non-parametric Aalen-Johansen estimator of the cumulative incidence function.
+"""
+
+import numpy as np
+from scipy import stats
+from scipy.interpolate import interp1d
+from pycrr.surv import Surv
+
+
+class AalenJohansen:
+    """
+    Non-parametric Aalen-Johansen estimator for competing risks.
+
+    Estimates F_k(t) = P(T <= t, cause = k) without any covariate adjustment,
+    the correct non-parametric analog of 1 - KM when competing events are present.
+
+    Parameters
+    ----------
+    confidence_level : float
+        Confidence level for pointwise CI. Default 0.95.
+
+    Examples
+    --------
+    >>> from pycrr.estimator import AalenJohansen
+    >>> aj = AalenJohansen().fit(time, event)
+    >>> aj.summary(cause=1)
+    >>> t, cif = aj.predict(cause=1)
+    >>> lo, hi  = aj.confidence_intervals(cause=1)
+    """
+
+    def __init__(self, confidence_level=0.95):
+        self.confidence_level = confidence_level
+        self.causes_   = None
+        self.n_        = None
+        self._tables   = {}   # cause -> dict(times, cif, var)
+
+    # ------------------------------------------------------------------
+    # Fit
+    # ------------------------------------------------------------------
+
+    def fit(self, time, event=None):
+        """
+        Fit the Aalen-Johansen estimator.
+
+        Parameters
+        ----------
+        time : array-like of shape (n,)
+            Observed times.
+        event : array-like of shape (n,)
+            Event indicators: 0 = censored, 1, 2, ... = cause codes.
+
+        Returns
+        -------
+        self
+        """
+        if isinstance(time, Surv):
+            if event is not None:
+                raise ValueError(
+                    "Pass either a Surv object or separate (time, event), not both."
+                )
+            time, event = time
+        elif event is None:
+            raise ValueError("event is required when time is not a Surv object.")
+
+        time  = np.asarray(time,  dtype=float)
+        event = np.asarray(event, dtype=int)
+        self.n_      = len(time)
+        self.causes_ = sorted(int(c) for c in np.unique(event) if c != 0)
+
+        if not self.causes_:
+            raise ValueError("No events observed (all event codes are 0).")
+
+        # Unique times where any event (any cause) occurs
+        event_times = np.sort(np.unique(time[event != 0]))
+
+        # Walk through event times, tracking overall KM survival S(t^-)
+        S            = 1.0          # overall KM, updated after each step
+        S_before     = []           # S(t^-) at each event time
+        Y_vec        = []           # at-risk count at each event time
+        dNk_vecs     = {k: [] for k in self.causes_}
+
+        for t in event_times:
+            Y  = int(np.sum(time >= t))                  # at risk just before t
+            dN = int(np.sum((time == t) & (event != 0))) # all-cause events at t
+
+            S_before.append(S)
+            Y_vec.append(Y)
+
+            for k in self.causes_:
+                dNk_vecs[k].append(int(np.sum((time == t) & (event == k))))
+
+            if Y > 0:
+                S = S * (1.0 - dN / Y)
+
+        S_before = np.array(S_before, dtype=float)
+        Y_arr    = np.array(Y_vec,    dtype=float)
+
+        # Build per-cause CIF and variance
+        for k in self.causes_:
+            dNk = np.array(dNk_vecs[k], dtype=float)
+
+            # CIF increment: dF_k(t) = S(t^-) * dN_k(t) / Y(t)
+            safe_Y = np.where(Y_arr > 0, Y_arr, np.inf)
+            dF     = S_before * dNk / safe_Y
+
+            times_full = np.concatenate([[0.0], event_times])
+            cif_full   = np.concatenate([[0.0], np.cumsum(dF)])
+
+            # Variance (Greenwood-style approximation):
+            # Var[F_k(t)] ≈ sum_{s<=t} S(s^-)^2 * dN_k(s) / Y(s)^2
+            var_inc  = np.where(Y_arr > 0, S_before**2 * dNk / Y_arr**2, 0.0)
+            var_full = np.concatenate([[0.0], np.cumsum(var_inc)])
+
+            self._tables[k] = dict(times=times_full, cif=cif_full, var=var_full)
+
+        return self
+
+    # ------------------------------------------------------------------
+    # Predict
+    # ------------------------------------------------------------------
+
+    def predict(self, cause, times=None):
+        """
+        Return CIF values for a given cause.
+
+        Parameters
+        ----------
+        cause : int
+        times : array-like or None
+            Evaluation time points. If None, returns values at all observed
+            event times (plus t=0).
+
+        Returns
+        -------
+        times : ndarray
+        cif   : ndarray
+        """
+        self._check_fitted(cause)
+        tbl = self._tables[cause]
+
+        if times is None:
+            return tbl["times"].copy(), tbl["cif"].copy()
+
+        times = np.asarray(times, dtype=float)
+        f     = self._step_interp(tbl["times"], tbl["cif"])
+        return times, f(times)
+
+    def confidence_intervals(self, cause, times=None):
+        """
+        Pointwise confidence intervals via the log-log transform.
+
+        Parameters
+        ----------
+        cause : int
+        times : array-like or None
+
+        Returns
+        -------
+        lower, upper : ndarray  (same length as times or full time grid)
+        """
+        self._check_fitted(cause)
+        tbl = self._tables[cause]
+
+        if times is not None:
+            times = np.asarray(times, dtype=float)
+            cif   = self._step_interp(tbl["times"], tbl["cif"])(times)
+            var   = self._step_interp(tbl["times"], tbl["var"])(times)
+        else:
+            times = tbl["times"]
+            cif   = tbl["cif"]
+            var   = tbl["var"]
+
+        z  = stats.norm.ppf(1.0 - (1.0 - self.confidence_level) / 2.0)
+        se = np.sqrt(np.clip(var, 0.0, np.inf))
+
+        # log-log transform: theta = log(-log F_k)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            log_cif = np.where(cif > 0, np.log(cif), -700.0)
+            theta   = np.where(cif > 0, np.log(-log_cif), np.inf)
+            se_ll   = np.where(
+                (cif > 0) & (np.abs(log_cif) > 1e-10),
+                se / (cif * np.abs(log_cif)),
+                np.inf,
+            )
+
+        lower = np.exp(-np.exp(theta + z * se_ll))
+        upper = np.exp(-np.exp(theta - z * se_ll))
+
+        return np.clip(lower, 0.0, 1.0), np.clip(upper, 0.0, 1.0)
+
+    # ------------------------------------------------------------------
+    # Summary
+    # ------------------------------------------------------------------
+
+    def summary(self, cause, times=None, max_rows=20):
+        """
+        Print a table of CIF estimates with confidence intervals.
+
+        Parameters
+        ----------
+        cause : int
+        times : array-like or None
+            Specific evaluation time points.  If None, evenly spaced rows
+            from the observed event time grid are shown.
+        max_rows : int
+            Maximum table rows when times is None.
+        """
+        self._check_fitted(cause)
+        tbl = self._tables[cause]
+
+        if times is None:
+            full_t = tbl["times"]
+            idx    = np.unique(
+                np.linspace(0, len(full_t) - 1, min(len(full_t), max_rows), dtype=int)
+            )
+            t_out = full_t[idx]
+        else:
+            t_out = np.asarray(times, dtype=float)
+
+        _, cif_out = self.predict(cause, times=t_out)
+        lo, hi     = self.confidence_intervals(cause, times=t_out)
+
+        n_cause = int(np.sum(
+            [1 for v in self._tables.values()
+             for _ in [None]] ))  # just a placeholder, see below
+
+        print(f"Aalen-Johansen CIF  —  cause {cause}  (n={self.n_})")
+        print(f"{'Time':>10}  {'CIF':>8}  {'Lower':>8}  {'Upper':>8}")
+        print("-" * 44)
+        for t, c, l, u in zip(t_out, cif_out, lo, hi):
+            if t == 0.0:
+                continue
+            print(f"{t:10.4f}  {c:8.4f}  {l:8.4f}  {u:8.4f}")
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _step_interp(x, y):
+        return interp1d(
+            x, y,
+            kind="previous",
+            bounds_error=False,
+            fill_value=(y[0], y[-1]),
+        )
+
+    def _check_fitted(self, cause):
+        if not self._tables:
+            raise RuntimeError("Model not fitted. Call fit() first.")
+        if cause not in self._tables:
+            raise ValueError(
+                f"Cause {cause} not in fitted causes {self.causes_}."
+            )