pystatsbio 1.0.0__py3-none-any.whl

pystatsbio/__init__.py

@@ -0,0 +1,24 @@
+"""
+PyStatsBio: Biotech and pharmaceutical statistical computing for Python.
+
+Built on top of pystatistics for the general statistical computing layer.
+PyStatsBio provides domain-specific methods for the drug development pipeline:
+dose-response modeling, sample size/power, diagnostic accuracy, and pharmacokinetics.
+
+Usage:
+    from pystatsbio import power, doseresponse, diagnostic, pk
+"""
+
+__version__ = "1.0.0"
+__author__ = "Hai-Shuo"
+__email__ = "contact@sgcx.org"
+
+from pystatsbio import diagnostic, doseresponse, pk, power
+
+__all__ = [
+    "__version__",
+    "power",
+    "doseresponse",
+    "diagnostic",
+    "pk",
+]

pystatsbio/diagnostic/__init__.py

@@ -0,0 +1,27 @@
+"""
+Diagnostic accuracy analysis for biomarker evaluation.
+
+ROC analysis, sensitivity/specificity, predictive values, likelihood ratios,
+and high-throughput batch AUC computation for biomarker panel screening.
+
+Validates against: R packages pROC, OptimalCutpoints, epiR.
+"""
+
+from pystatsbio.diagnostic._accuracy import diagnostic_accuracy
+from pystatsbio.diagnostic._batch import BatchAUCResult, batch_auc
+from pystatsbio.diagnostic._common import DiagnosticResult, ROCResult
+from pystatsbio.diagnostic._cutoff import CutoffResult, optimal_cutoff
+from pystatsbio.diagnostic._roc import ROCTestResult, roc, roc_test
+
+__all__ = [
+    "ROCResult",
+    "DiagnosticResult",
+    "ROCTestResult",
+    "CutoffResult",
+    "BatchAUCResult",
+    "roc",
+    "roc_test",
+    "diagnostic_accuracy",
+    "optimal_cutoff",
+    "batch_auc",
+]

pystatsbio/diagnostic/_accuracy.py

@@ -0,0 +1,193 @@
+"""Sensitivity, specificity, predictive values, and likelihood ratios.
+
+Computes a comprehensive set of diagnostic accuracy metrics at a fixed
+cutoff: sensitivity/specificity with exact (Clopper-Pearson) or Wilson
+CIs, PPV/NPV with optional prevalence adjustment, likelihood ratios
+(LR+/LR−), and diagnostic odds ratio (DOR) with log-scale CI.
+
+Validates against: R ``epiR::epi.tests()``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy import stats
+
+from pystatsbio.diagnostic._common import DiagnosticResult
+
+# ---------------------------------------------------------------------------
+# CI helpers for binomial proportions
+# ---------------------------------------------------------------------------
+
+def _clopper_pearson_ci(
+    k: int, n: int, conf_level: float,
+) -> tuple[float, float]:
+    """Exact Clopper-Pearson CI for binomial proportion k/n."""
+    alpha = 1 - conf_level
+    if k == 0:
+        lo = 0.0
+        hi = 1.0 - (alpha / 2) ** (1.0 / n)
+    elif k == n:
+        lo = (alpha / 2) ** (1.0 / n)
+        hi = 1.0
+    else:
+        lo = float(stats.beta.ppf(alpha / 2, k, n - k + 1))
+        hi = float(stats.beta.ppf(1 - alpha / 2, k + 1, n - k))
+    return lo, hi
+
+
+def _wilson_ci(
+    k: int, n: int, conf_level: float,
+) -> tuple[float, float]:
+    """Wilson score CI for binomial proportion k/n."""
+    p_hat = k / n
+    z = stats.norm.ppf((1 + conf_level) / 2)
+    z2 = z ** 2
+    denom = 1 + z2 / n
+    centre = (p_hat + z2 / (2 * n)) / denom
+    margin = z / denom * np.sqrt(p_hat * (1 - p_hat) / n + z2 / (4 * n ** 2))
+    return float(centre - margin), float(centre + margin)
+
+
+def _binomial_ci(
+    k: int, n: int, conf_level: float, method: str,
+) -> tuple[float, float]:
+    """Dispatch to the requested CI method."""
+    if method == "clopper-pearson":
+        return _clopper_pearson_ci(k, n, conf_level)
+    elif method == "wilson":
+        return _wilson_ci(k, n, conf_level)
+    else:
+        raise ValueError(
+            f"ci_method must be 'clopper-pearson' or 'wilson', got {method!r}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def diagnostic_accuracy(
+    response: NDArray[np.integer],
+    predictor: NDArray[np.floating],
+    *,
+    cutoff: float,
+    direction: str = "<",
+    prevalence: float | None = None,
+    conf_level: float = 0.95,
+    ci_method: str = "clopper-pearson",
+) -> DiagnosticResult:
+    """Compute diagnostic accuracy metrics at a fixed cutoff.
+
+    Parameters
+    ----------
+    response : array of int
+        Binary outcome (0/1).
+    predictor : array of float
+        Continuous predictor.
+    cutoff : float
+        Classification threshold.
+    direction : str
+        ``'<'`` means predictor ≥ cutoff is classified positive
+        (controls < cases, higher values = disease).
+        ``'>'`` means predictor ≤ cutoff is classified positive
+        (controls > cases, lower values = disease).
+    prevalence : float or None
+        Disease prevalence for PPV/NPV adjustment via Bayes' theorem.
+        If ``None``, uses sample prevalence.
+    conf_level : float
+        Confidence level.
+    ci_method : str
+        ``'clopper-pearson'`` (exact) or ``'wilson'``.
+
+    Returns
+    -------
+    DiagnosticResult
+
+    Validates against: R ``epiR::epi.tests()``
+    """
+    response = np.asarray(response, dtype=np.intp)
+    predictor = np.asarray(predictor, dtype=np.float64)
+
+    if response.ndim != 1 or predictor.ndim != 1:
+        raise ValueError("response and predictor must be 1-D")
+    if len(response) != len(predictor):
+        raise ValueError("response and predictor must have equal length")
+    if direction not in ("<", ">"):
+        raise ValueError(f"direction must be '<' or '>', got {direction!r}")
+    if not 0 < conf_level < 1:
+        raise ValueError(f"conf_level must be in (0, 1), got {conf_level}")
+
+    # Classify
+    predicted_pos = predictor >= cutoff if direction == "<" else predictor <= cutoff
+
+    actual_pos = response == 1
+
+    TP = int(np.sum(predicted_pos & actual_pos))
+    FP = int(np.sum(predicted_pos & ~actual_pos))
+    FN = int(np.sum(~predicted_pos & actual_pos))
+    TN = int(np.sum(~predicted_pos & ~actual_pos))
+
+    n1 = TP + FN  # total positives
+    n0 = TN + FP  # total negatives
+
+    if n1 == 0 or n0 == 0:
+        raise ValueError("Need at least one case and one control")
+
+    # Sensitivity and specificity
+    sens = TP / n1
+    spec = TN / n0
+
+    sens_ci = _binomial_ci(TP, n1, conf_level, ci_method)
+    spec_ci = _binomial_ci(TN, n0, conf_level, ci_method)
+
+    # Prevalence
+    if prevalence is None:
+        prev = n1 / (n1 + n0)
+    else:
+        if not 0 < prevalence < 1:
+            raise ValueError(f"prevalence must be in (0, 1), got {prevalence}")
+        prev = prevalence
+
+    # PPV / NPV (with optional prevalence adjustment via Bayes)
+    ppv_denom = sens * prev + (1 - spec) * (1 - prev)
+    npv_denom = (1 - sens) * prev + spec * (1 - prev)
+    ppv = (sens * prev / ppv_denom) if ppv_denom > 0 else float("nan")
+    npv = (spec * (1 - prev) / npv_denom) if npv_denom > 0 else float("nan")
+
+    # Likelihood ratios
+    lr_pos = sens / (1 - spec) if (1 - spec) > 0 else float("inf")
+    lr_neg = (1 - sens) / spec if spec > 0 else float("inf")
+
+    # Diagnostic odds ratio (with 0.5 Haldane correction if any cell is 0)
+    z = stats.norm.ppf((1 + conf_level) / 2)
+    if TP == 0 or FP == 0 or FN == 0 or TN == 0:
+        TPc = TP + 0.5
+        FPc = FP + 0.5
+        FNc = FN + 0.5
+        TNc = TN + 0.5
+    else:
+        TPc, FPc, FNc, TNc = float(TP), float(FP), float(FN), float(TN)
+
+    dor = (TPc * TNc) / (FPc * FNc)
+    log_dor_se = np.sqrt(1 / TPc + 1 / FPc + 1 / FNc + 1 / TNc)
+    dor_lo = np.exp(np.log(dor) - z * log_dor_se)
+    dor_hi = np.exp(np.log(dor) + z * log_dor_se)
+
+    return DiagnosticResult(
+        cutoff=float(cutoff),
+        sensitivity=float(sens),
+        sensitivity_ci=sens_ci,
+        specificity=float(spec),
+        specificity_ci=spec_ci,
+        ppv=float(ppv),
+        npv=float(npv),
+        lr_positive=float(lr_pos),
+        lr_negative=float(lr_neg),
+        dor=float(dor),
+        dor_ci=(float(dor_lo), float(dor_hi)),
+        prevalence=float(prev),
+        conf_level=conf_level,
+        method=ci_method,
+    )

pystatsbio/diagnostic/_batch.py

@@ -0,0 +1,291 @@
+"""Batch AUC computation for high-throughput biomarker panels.
+
+Computes AUC (Mann-Whitney U / (n1*n0)) and DeLong standard errors for
+many biomarker candidates simultaneously.  The CPU path uses
+``scipy.stats.rankdata`` column-wise.  The GPU path uses PyTorch's
+batched ``argsort`` for ranking and a vectorised masked sum.
+
+GPU is beneficial when ``n_markers > 100``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    import torch
+
+
+@dataclass(frozen=True)
+class BatchAUCResult:
+    """Result of batch AUC computation across multiple biomarkers."""
+
+    auc: NDArray[np.floating]  # shape (n_markers,)
+    se: NDArray[np.floating]  # DeLong SE for each
+    n_markers: int
+
+
+# ---------------------------------------------------------------------------
+# CPU path
+# ---------------------------------------------------------------------------
+
+def _batch_auc_cpu(
+    response: NDArray, predictors: NDArray,
+) -> BatchAUCResult:
+    """Column-wise AUC + DeLong SE on CPU."""
+    from scipy import stats as sp_stats
+
+    N, M = predictors.shape
+    case_mask = response == 1
+    n1 = int(case_mask.sum())
+    n0 = N - n1
+
+    auc_arr = np.empty(M)
+    se_arr = np.empty(M)
+
+    for m in range(M):
+        col = predictors[:, m]
+
+        # Pooled ranks (midranks for ties)
+        pooled_ranks = sp_stats.rankdata(col, method="average")
+
+        # AUC via Mann-Whitney
+        sum_case_ranks = pooled_ranks[case_mask].sum()
+        auc_m = (sum_case_ranks - n1 * (n1 + 1) / 2) / (n1 * n0)
+
+        # DeLong placement values
+        case_ranks_within = sp_stats.rankdata(col[case_mask], method="average")
+        ctrl_ranks_within = sp_stats.rankdata(col[~case_mask], method="average")
+
+        V10 = (pooled_ranks[case_mask] - case_ranks_within) / n0
+        V01 = 1.0 - (pooled_ranks[~case_mask] - ctrl_ranks_within) / n1
+
+        S10 = np.var(V10, ddof=1) if n1 > 1 else 0.0
+        S01 = np.var(V01, ddof=1) if n0 > 1 else 0.0
+        var_auc = S10 / n1 + S01 / n0
+
+        auc_arr[m] = auc_m
+        se_arr[m] = np.sqrt(var_auc)
+
+    return BatchAUCResult(auc=auc_arr, se=se_arr, n_markers=M)
+
+
+# ---------------------------------------------------------------------------
+# GPU path
+# ---------------------------------------------------------------------------
+
+def _batch_auc_gpu(
+    response: NDArray, predictors: NDArray,
+) -> BatchAUCResult:
+    """Batched AUC + DeLong SE on GPU via PyTorch.
+
+    Uses batched argsort for column-wise ranking, then a single
+    matrix-vector product for the Mann-Whitney sum across all markers.
+    """
+    import torch
+
+    # Select device
+    if torch.cuda.is_available():
+        device = torch.device("cuda")
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        device = torch.device("mps")
+    else:
+        device = torch.device("cpu")
+
+    # MPS uses float32, others float64
+    dtype = torch.float32 if device.type == "mps" else torch.float64
+
+    N, M = predictors.shape
+    case_mask_np = response == 1
+    n1 = int(case_mask_np.sum())
+    n0 = N - n1
+
+    pred_t = torch.from_numpy(predictors).to(device=device, dtype=dtype)
+
+    # Column-wise ranking via argsort-of-argsort (handles ties with average)
+    # For GPU efficiency, use the argsort approach:
+    # rank[i] = position of element i in sorted order
+    # For ties, we need midranks which requires more work.
+    # Use argsort twice: argsort gives sorted indices, inverting gives ranks.
+    sorted_indices = pred_t.argsort(dim=0)           # (N, M)
+    ranks = torch.empty_like(pred_t)
+    base_ranks = torch.arange(1, N + 1, device=device, dtype=dtype).unsqueeze(1).expand(N, M)
+    ranks.scatter_(0, sorted_indices, base_ranks)
+
+    # Midrank correction for ties
+    # Group equal values and assign their mean rank (per-column loop)
+    sorted_vals = pred_t.gather(0, sorted_indices)  # (N, M) sorted
+    sorted_ranks = (
+        torch.arange(1, N + 1, device=device, dtype=dtype).unsqueeze(1).expand(N, M).clone()
+    )
+
+    # Group boundaries in sorted order
+    for m_idx in range(M):
+        col_sorted = sorted_vals[:, m_idx]
+        col_ranks = sorted_ranks[:, m_idx]
+        # Find runs of equal values
+        i = 0
+        while i < N:
+            j = i + 1
+            while j < N and col_sorted[j] == col_sorted[i]:
+                j += 1
+            if j > i + 1:
+                # Tied block [i, j): assign midrank
+                midrank = (i + 1 + j) / 2.0
+                col_ranks[i:j] = midrank
+            i = j
+
+    # Scatter midranks back to original positions
+    pooled_ranks_gpu = torch.empty_like(pred_t)
+    pooled_ranks_gpu.scatter_(0, sorted_indices, sorted_ranks)
+
+    # AUC: sum of case ranks - n1*(n1+1)/2, divided by n1*n0
+    case_mask_t = torch.from_numpy(case_mask_np).to(device=device)
+    case_ranks_pooled = pooled_ranks_gpu[case_mask_t]  # (n1, M)
+    sum_case_ranks = case_ranks_pooled.sum(dim=0)  # (M,)
+    auc_t = (sum_case_ranks - n1 * (n1 + 1) / 2) / (n1 * n0)
+
+    # DeLong SE: need within-group ranks for cases and controls separately
+    # Rank cases among cases only
+    case_pred = pred_t[case_mask_t]      # (n1, M)
+    ctrl_pred = pred_t[~case_mask_t]     # (n0, M)
+
+    case_within_ranks = _midranks_gpu(case_pred, device, dtype)  # (n1, M)
+    ctrl_within_ranks = _midranks_gpu(ctrl_pred, device, dtype)  # (n0, M)
+
+    # Placement values
+    V10 = (pooled_ranks_gpu[case_mask_t] - case_within_ranks) / n0  # (n1, M)
+    V01 = 1.0 - (pooled_ranks_gpu[~case_mask_t] - ctrl_within_ranks) / n1  # (n0, M)
+
+    # Variance per marker
+    auc_expanded = auc_t.unsqueeze(0)  # (1, M)
+    if n1 > 1:
+        S10 = ((V10 - auc_expanded) ** 2).sum(dim=0) / (n1 - 1)  # (M,)
+    else:
+        S10 = torch.zeros(M, device=device, dtype=dtype)
+    if n0 > 1:
+        S01 = ((V01 - auc_expanded) ** 2).sum(dim=0) / (n0 - 1)  # (M,)
+    else:
+        S01 = torch.zeros(M, device=device, dtype=dtype)
+
+    var_auc = S10 / n1 + S01 / n0
+    se_t = torch.sqrt(var_auc)
+
+    return BatchAUCResult(
+        auc=auc_t.cpu().numpy().astype(np.float64),
+        se=se_t.cpu().numpy().astype(np.float64),
+        n_markers=M,
+    )
+
+
+def _midranks_gpu(
+    data: torch.Tensor,
+    device: torch.device,
+    dtype: torch.dtype,
+) -> torch.Tensor:
+    """Compute midranks column-wise for a (N, M) tensor on GPU."""
+    import torch
+
+    N, M = data.shape
+    sorted_indices = data.argsort(dim=0)
+    sorted_vals = data.gather(0, sorted_indices)
+    ranks = torch.arange(1, N + 1, device=device, dtype=dtype).unsqueeze(1).expand(N, M).clone()
+
+    # Fix ties to midranks
+    for m_idx in range(M):
+        col_sorted = sorted_vals[:, m_idx]
+        col_ranks = ranks[:, m_idx]
+        i = 0
+        while i < N:
+            j = i + 1
+            while j < N and col_sorted[j] == col_sorted[i]:
+                j += 1
+            if j > i + 1:
+                col_ranks[i:j] = (i + 1 + j) / 2.0
+            i = j
+
+    result = torch.empty_like(data)
+    result.scatter_(0, sorted_indices, ranks)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def batch_auc(
+    response: NDArray[np.integer],
+    predictors: NDArray[np.floating],
+    *,
+    backend: str = "auto",
+) -> BatchAUCResult:
+    """Compute AUC for many biomarker candidates simultaneously.
+
+    Parameters
+    ----------
+    response : array of int, shape ``(n_samples,)``
+        Shared binary outcome (0/1).
+    predictors : array of float, shape ``(n_samples, n_markers)``
+        Matrix of biomarker values (one column per candidate marker).
+    backend : str
+        ``'cpu'``, ``'gpu'``, or ``'auto'``.
+
+    Returns
+    -------
+    BatchAUCResult
+
+    Notes
+    -----
+    GPU backend is beneficial when ``n_markers > 100``.  Uses rank-based
+    AUC computation which is embarrassingly parallel across markers.
+    DeLong standard errors are computed for each marker.
+    """
+    response = np.asarray(response, dtype=np.intp)
+    predictors = np.asarray(predictors, dtype=np.float64)
+
+    if response.ndim != 1:
+        raise ValueError(f"response must be 1-D, got shape {response.shape}")
+    if predictors.ndim != 2:
+        raise ValueError(
+            f"predictors must be 2-D (n_samples, n_markers), got shape {predictors.shape}"
+        )
+    if response.shape[0] != predictors.shape[0]:
+        raise ValueError(
+            f"response length {response.shape[0]} != predictors rows {predictors.shape[0]}"
+        )
+
+    unique_labels = np.unique(response)
+    if not np.array_equal(unique_labels, np.array([0, 1])):
+        raise ValueError(
+            f"response must be binary (0/1), got unique values {unique_labels}"
+        )
+
+    if not np.all(np.isfinite(predictors)):
+        raise ValueError(
+            "predictors contains NaN or infinite values. "
+            "Remove or impute missing values before calling batch_auc."
+        )
+
+    if backend == "cpu":
+        return _batch_auc_cpu(response, predictors)
+
+    if backend == "gpu":
+        return _batch_auc_gpu(response, predictors)
+
+    # auto — try GPU, fall back to CPU
+    try:
+        import torch
+
+        has_gpu = torch.cuda.is_available() or (
+            hasattr(torch.backends, "mps") and torch.backends.mps.is_available()
+        )
+        if has_gpu:
+            return _batch_auc_gpu(response, predictors)
+    except ImportError:
+        pass
+
+    return _batch_auc_cpu(response, predictors)

pystatsbio/diagnostic/_common.py

@@ -0,0 +1,110 @@
+"""Shared result types for diagnostic accuracy analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+@dataclass(frozen=True)
+class ROCResult:
+    """Result of ROC analysis.
+
+    Attributes
+    ----------
+    thresholds : array
+        Thresholds at which TPR/FPR are evaluated.  Includes ``-inf``
+        and ``+inf`` so the curve always passes through (0,0) and (1,1).
+    tpr : array
+        True positive rate (sensitivity) at each threshold.
+    fpr : array
+        False positive rate (1 − specificity) at each threshold.
+    auc : float
+        Area under the ROC curve (Mann-Whitney U / (n1*n0)).
+    auc_se : float
+        DeLong standard error of the AUC.
+    auc_ci_lower, auc_ci_upper : float
+        Confidence interval for AUC (logit-transformed DeLong).
+    conf_level : float
+        Confidence level used for CI.
+    n_positive, n_negative : int
+        Number of positive (case) and negative (control) observations.
+    direction : str
+        ``'<'`` (controls < cases) or ``'>'`` (controls > cases).
+    """
+
+    thresholds: NDArray[np.floating]
+    tpr: NDArray[np.floating]  # sensitivity / true positive rate
+    fpr: NDArray[np.floating]  # 1 - specificity / false positive rate
+    auc: float
+    auc_se: float  # DeLong standard error
+    auc_ci_lower: float
+    auc_ci_upper: float
+    conf_level: float
+    n_positive: int
+    n_negative: int
+    direction: str  # '<' or '>'
+
+    def summary(self) -> str:
+        """Human-readable summary."""
+        lines = [
+            "ROC Analysis",
+            "=" * 40,
+            f"Direction   : controls {self.direction} cases",
+            f"AUC         : {self.auc:.4f}",
+            f"DeLong SE   : {self.auc_se:.4f}",
+            f"{self.conf_level:.0%} CI      : [{self.auc_ci_lower:.4f}, {self.auc_ci_upper:.4f}]",
+            f"n positive  : {self.n_positive}",
+            f"n negative  : {self.n_negative}",
+            f"n thresholds: {len(self.thresholds)}",
+        ]
+        return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class DiagnosticResult:
+    """Result of diagnostic accuracy evaluation at a fixed cutoff.
+
+    All CIs use the method specified in ``method`` (e.g.
+    ``'clopper-pearson'`` for exact binomial CIs).
+    """
+
+    cutoff: float
+    sensitivity: float
+    sensitivity_ci: tuple[float, float]
+    specificity: float
+    specificity_ci: tuple[float, float]
+    ppv: float
+    npv: float
+    lr_positive: float
+    lr_negative: float
+    dor: float  # diagnostic odds ratio
+    dor_ci: tuple[float, float]
+    prevalence: float
+    conf_level: float
+    method: str  # CI method, e.g. 'clopper-pearson'
+
+    def summary(self) -> str:
+        """Human-readable summary."""
+        lines = [
+            "Diagnostic Accuracy",
+            "=" * 40,
+            f"Cutoff        : {self.cutoff:.4g}",
+            f"Sensitivity   : {self.sensitivity:.4f}  "
+            f"({self.conf_level:.0%} CI: "
+            f"{self.sensitivity_ci[0]:.4f}–{self.sensitivity_ci[1]:.4f})",
+            f"Specificity   : {self.specificity:.4f}  "
+            f"({self.conf_level:.0%} CI: "
+            f"{self.specificity_ci[0]:.4f}–{self.specificity_ci[1]:.4f})",
+            f"PPV           : {self.ppv:.4f}",
+            f"NPV           : {self.npv:.4f}",
+            f"LR+           : {self.lr_positive:.4f}",
+            f"LR−           : {self.lr_negative:.4f}",
+            f"DOR           : {self.dor:.4f}  "
+            f"({self.conf_level:.0%} CI: {self.dor_ci[0]:.4f}–{self.dor_ci[1]:.4f})",
+            f"Prevalence    : {self.prevalence:.4f}",
+            f"CI method     : {self.method}",
+        ]
+        return "\n".join(lines)