mlsurv 0.1.0__py3-none-any.whl

mlsurv/__init__.py

@@ -0,0 +1,215 @@
+"""
+mlsurv: Low-code survival machine learning package.
+"""
+
+import os
+import tempfile
+import warnings
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from pathlib import Path
+
+# Single source of truth: read the version from the installed package metadata
+# (pyproject.toml) so it can never drift from the distribution version.
+try:
+    __version__ = _pkg_version("mlsurv")
+except PackageNotFoundError:  # running from an uninstalled source checkout
+    __version__ = "0.0.0+unknown"
+
+
+def _configure_matplotlib_cache_dir() -> None:
+    """Set a writable MPLCONFIGDIR when HOME is not writable."""
+    if os.environ.get("MPLCONFIGDIR"):
+        return
+
+    home_dir = Path.home()
+    mpl_dir = home_dir / ".matplotlib"
+
+    # If an existing cache dir is writable, keep matplotlib defaults.
+    if mpl_dir.exists() and os.access(mpl_dir, os.W_OK):
+        return
+
+    # If HOME itself is writable, matplotlib can create ~/.matplotlib.
+    if os.access(home_dir, os.W_OK):
+        return
+
+    try:
+        fallback = Path(tempfile.gettempdir()) / "mlsurv-matplotlib"
+        fallback.mkdir(parents=True, exist_ok=True)
+        os.environ["MPLCONFIGDIR"] = str(fallback)
+    except OSError:
+        from mlsurv._warnings import InternalWarning
+        warnings.warn(
+            "mlsurv could not create a writable matplotlib cache directory. "
+            "Set the MPLCONFIGDIR environment variable to a writable path "
+            "to avoid potential plotting errors.",
+            InternalWarning,
+            stacklevel=1,
+        )
+
+
+# Register mlsurv's tiered warning filters — must be before any code
+# that may emit warnings (e.g., matplotlib cache setup).
+from mlsurv._warnings import configure_default_filters
+configure_default_filters()
+
+
+def _check_stdout_encoding() -> None:
+    """Warn if stdout encoding cannot represent Unicode used by mlsurv."""
+    import codecs
+    import sys
+    encoding = getattr(sys.stdout, "encoding", None)
+    if not encoding:
+        return
+    try:
+        canonical = codecs.lookup(encoding).name
+    except LookupError:
+        return
+    if canonical in ("cp1252", "ascii", "iso8859-1", "latin-1"):
+        from mlsurv._warnings import SuggestionWarning
+        warnings.warn(
+            f"stdout encoding is '{encoding}', which cannot represent all "
+            "characters used by mlsurv. Set the environment variable "
+            "PYTHONIOENCODING=utf-8 to avoid UnicodeEncodeError crashes.",
+            SuggestionWarning,
+            stacklevel=1,
+        )
+
+
+_check_stdout_encoding()
+_configure_matplotlib_cache_dir()
+
+# Suppress loky resource_tracker KeyError tracebacks on Windows.
+# Loky's tracker subprocess has a race condition where multiple workers
+# UNREGISTER the same temp folder. We swap the module-level `main`
+# reference so the subprocess imports our wrapper (mlsurv._loky_patch),
+# which installs a selective sys.excepthook before delegating to the
+# real main. Also disable memmapping globally since it provides
+# negligible benefit for typical survival analysis datasets.
+import joblib
+joblib.parallel_config(max_nbytes=None)
+from joblib.externals.loky.backend import resource_tracker as _rt_mod
+from mlsurv._loky_patch import main as _patched_rt_main
+_rt_mod.main = _patched_rt_main
+
+# Suppress NumPy 2.x deprecation warning from sksurv calling np.trapz.
+# Cannot fix upstream; narrow filter matches only sksurv.metrics subpackage.
+warnings.filterwarnings(
+    "ignore",
+    message=r"`trapz` is deprecated",
+    category=DeprecationWarning,
+    module=r"sksurv\.metrics",
+)
+
+# Suppress lifelines emitting pandas-4.0 keyword-only deprecation warnings
+# from internal Series.var/mean/std calls during fit.  On lifelines
+# v0.30.3 + pandas 3.0.2 this is ``pandas.errors.Pandas4Warning`` (a
+# ``DeprecationWarning`` subclass), but earlier versions of lifelines have
+# emitted equivalent messages as ``UserWarning``.  Use ``category=Warning``
+# (the common base) so the filter is robust across versions; the message +
+# module narrowing keeps legitimate lifelines warnings (convergence,
+# ill-conditioned design, etc.) flowing through.
+warnings.filterwarnings(
+    "ignore",
+    message=r"Starting with pandas version 4\.0",
+    category=Warning,
+    module=r"lifelines\..*",
+)
+
+from mlsurv.utils import (
+    to_structured_array, load_survival_data,
+    compute_survival_time, SurvivalArray,
+)
+
+# Model wrappers (imported after definition)
+from mlsurv.models import (
+    BaseSurvivalModel,
+    CoxPHModel,
+    CoxNetModel,
+    RSFModel,
+    GBSAModel,
+    FSSVMModel,
+    XGBCoxModel,
+    XGBAFTModel,
+    WeibullAFTModel,
+)
+
+# Result containers
+from mlsurv.results import (
+    EvaluationResult,
+    BootstrapResult,
+    ModelResult,
+    ValidationResult,
+    BenchmarkResult,
+)
+
+# Preprocessing
+from mlsurv.preprocessing import (
+    TopKCoxSelector,
+)
+
+# Guidance
+from mlsurv.guidance import recommend_models, RecommendedModels
+
+# Main API
+from mlsurv.learner import SurvivalLearner
+load_learner = SurvivalLearner.load_learner
+
+# Reports
+from mlsurv.reports import ReportGenerator
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main API
+    "SurvivalLearner",
+    "load_learner",
+    # Reports
+    "ReportGenerator",
+    # Utilities
+    "recommend_models",
+    "RecommendedModels",
+    "to_structured_array",
+    "load_survival_data",
+    "compute_survival_time",
+    "SurvivalArray",
+    # Models
+    "BaseSurvivalModel",
+    "CoxPHModel",
+    "CoxNetModel",
+    "RSFModel",
+    "GBSAModel",
+    "FSSVMModel",
+    "XGBCoxModel",
+    "XGBAFTModel",
+    "WeibullAFTModel",
+    # Results
+    "EvaluationResult",
+    "BootstrapResult",
+    "ModelResult",
+    "ValidationResult",
+    "BenchmarkResult",
+    # Preprocessing
+    "TopKCoxSelector",
+]
+
+# Lazy import for DeepSurv (requires torch)
+def __getattr__(name):
+    if name == "DeepSurvModel":
+        try:
+            from mlsurv.models.deepsurv import DeepSurvModel
+            return DeepSurvModel
+        except ImportError:
+            raise ImportError(
+                "DeepSurvModel requires torch and pycox. "
+                "Install with: pip install mlsurv[deep]"
+            )
+    if name == "DeepHitModel":
+        try:
+            from mlsurv.models.deephit import DeepHitModel
+            return DeepHitModel
+        except ImportError:
+            raise ImportError(
+                "DeepHitModel requires torch and pycox. "
+                "Install with: pip install mlsurv[deep]"
+            )
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mlsurv/_calibration_thresholds.py

@@ -0,0 +1,25 @@
+"""Shared calibration thresholds.
+
+Single source of truth for the slope/p-value cutoffs used by both the
+runtime ``MethodologicalWarning`` (``mlsurv.evaluation.evaluate``) and the
+HTML report's poor-calibration flag (``mlsurv.reports.sections.limitations``).
+Lives at the package root to avoid an upward dependency from ``evaluation``
+into ``reports``.
+"""
+
+from __future__ import annotations
+
+# Calibration slope is the sole drift trigger. The band is deliberately wide:
+# a slope inside [0.5, 1.5] (|slope-1| <= 0.5) is treated as adequately
+# calibrated for deployment, so the flag fires only on genuinely large
+# miscalibration that calibrating S(t|x) would meaningfully fix. Both
+# CAL_SLOPE_LOW/HIGH and SEVERE_DRIFT_THRESHOLD describe the same |slope-1| > 0.5
+# cutoff (kept as separate names for the two call sites that read them).
+CAL_SLOPE_LOW = 0.5
+CAL_SLOPE_HIGH = 1.5
+SEVERE_DRIFT_THRESHOLD = 0.5
+
+# GND (Greenwood-Nam-D'Agostino) p-value: reported as context in the drift
+# message text only. It is NOT a standalone trigger -- it over-rejects on
+# well-powered cohorts, so the slope band alone decides whether to flag.
+P_THRESHOLD_SIGNIFICANT = 0.05

mlsurv/_iter_warn.py

@@ -0,0 +1,396 @@
+"""Coalescer for repeated IterativeWarnings.
+
+Per-iteration loops emit warnings whose text varies per iteration (e.g.,
+``seed=...`` for failed bootstrap iterations, or ``label='X'`` for
+small-subpopulation notices). Python's ``simplefilter("once", ...)`` cannot
+deduplicate when message text differs, so stderr fills with hundreds of
+near-identical lines.
+
+Two modes are supported:
+
+* ``mode="failures"`` (default): each record carries a caught
+  exception. Examples are formatted as
+  ``"{summary_label} iteration failed{prefix}: {message}"``; the aggregate
+  summary describes count + error-type diversity.
+
+* ``mode="notices"``: each record carries a pre-rendered message
+  (no exception). Examples are emitted verbatim; the aggregate summary
+  reads ``"{n}/{n_total} ({pct}%) {summary_label}s {notice_phrase}: {keys}.{tail}"``,
+  where each ``key`` is the notice's ``display`` text (or ``group_key`` as
+  a fallback). ``group_key`` is reserved as a true identifier for future
+  grouping/dedup logic; ``display`` is the short summary-list text.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Iterable, Literal, Optional, Type
+
+from ._warnings import IterativeWarning
+
+
+@dataclass(frozen=True)
+class IterativeFailure:
+    """A single per-iteration failure to be reported by the coalescer."""
+
+    exc_type_name: str
+    message: str
+    context_prefix: str = ""
+
+    @classmethod
+    def from_exception(
+        cls, exc: BaseException, *, prefix: str = ""
+    ) -> "IterativeFailure":
+        """Build a failure record from a caught exception."""
+        return cls(
+            exc_type_name=type(exc).__name__,
+            message=str(exc),
+            context_prefix=prefix,
+        )
+
+
+@dataclass(frozen=True)
+class IterativeNotice:
+    """A single per-iteration notice (non-failure) to be coalesced.
+
+    Fields:
+
+    * ``message`` — full per-iteration text, emitted verbatim when
+      ``max_emit > 0``.
+    * ``group_key`` — true identifier for the iteration (e.g. a label,
+      seed, or bucket name). Reserved for future grouping/dedup logic
+      inside the coalescer.
+    * ``display`` — short text used in the aggregate summary's
+      "affected items" list. Falls back to ``group_key`` when empty,
+      so callers that only need an identifier can keep passing
+      ``group_key=`` alone.
+    """
+
+    message: str
+    group_key: str = ""
+    display: str = ""
+
+
+def coalesce_failures(
+    failures: Iterable[IterativeFailure],
+    *,
+    n_total: int,
+    summary_label: str,
+    max_emit: int = 3,
+    category: Type[Warning] = IterativeWarning,
+    stacklevel: int = 3,
+    tail_msg: str = "",
+) -> int:
+    """Emit warnings for ``failures`` according to the coalescer policy.
+
+    Policy:
+      1. Group by ``exc_type_name`` (encounter order).
+      2. Emit up to ``max_emit`` distinct error-type examples verbatim.
+      3. Emit one aggregate summary describing total count and type diversity.
+
+    Empty ``failures`` emits nothing.
+
+    Parameters
+    ----------
+    failures : iterable of IterativeFailure
+        Per-iteration failure records to coalesce.
+    n_total : int
+        Total number of iterations attempted (denominator for the summary).
+    summary_label : str
+        Human-readable label for the iteration kind (e.g. ``"bootstrap"``).
+    max_emit : int, default=3
+        Maximum number of distinct error-type examples emitted verbatim
+        before the aggregate summary.
+    category : type of Warning, default=IterativeWarning
+        Warning class to emit.
+    stacklevel : int, default=3
+        ``stacklevel`` forwarded to :func:`warnings.warn`.
+    tail_msg : str, default=""
+        Optional text appended to the aggregate summary message.
+
+    Returns
+    -------
+    int
+        Number of failures, for caller convenience.
+
+    Raises
+    ------
+    ValueError
+        If ``n_total`` is less than 1, if ``max_emit`` is negative, or if
+        the number of failures exceeds ``n_total``.
+    """
+    if n_total < 1:
+        raise ValueError(f"n_total must be >= 1; got {n_total}")
+    if max_emit < 0:
+        raise ValueError(f"max_emit must be >= 0; got {max_emit}")
+    failures = list(failures)
+    n_failed = len(failures)
+    if n_failed == 0:
+        return 0
+    if n_failed > n_total:
+        raise ValueError(
+            f"len(failures)={n_failed} exceeds n_total={n_total}"
+        )
+
+    grouped: "OrderedDict[str, list[IterativeFailure]]" = OrderedDict()
+    for f in failures:
+        grouped.setdefault(f.exc_type_name, []).append(f)
+
+    for exc_type_name, group in list(grouped.items())[:max_emit]:
+        example = group[0]
+        prefix = f" ({example.context_prefix})" if example.context_prefix else ""
+        warnings.warn(
+            f"{summary_label} iteration failed{prefix}: {example.message}",
+            category,
+            stacklevel=stacklevel,
+        )
+
+    pct = n_failed / n_total * 100
+    tail = f" {tail_msg}" if tail_msg else ""
+    if len(grouped) == 1:
+        only_type = next(iter(grouped))
+        summary = (
+            f"{n_failed}/{n_total} ({pct:.0f}%) {summary_label} iterations failed; "
+            f"all shared the same error type ({only_type}).{tail}"
+        )
+    else:
+        breakdown = ", ".join(
+            f"{name} (n={len(group)})" for name, group in grouped.items()
+        )
+        summary = (
+            f"{n_failed}/{n_total} ({pct:.0f}%) {summary_label} iterations failed "
+            f"across {len(grouped)} distinct error types: {breakdown}.{tail}"
+        )
+    warnings.warn(summary, category, stacklevel=stacklevel)
+    return n_failed
+
+
+def coalesce_notices(
+    notices: Iterable[IterativeNotice],
+    *,
+    n_total: int,
+    summary_label: str,
+    notice_phrase: str,
+    max_emit: int = 3,
+    category: Type[Warning] = IterativeWarning,
+    stacklevel: int = 3,
+    tail_msg: str = "",
+) -> int:
+    """Emit warnings for ``notices`` (non-failure repeated warnings).
+
+    Policy:
+      1. Emit up to ``max_emit`` notice messages verbatim (encounter order).
+      2. Emit one aggregate summary listing the affected ``group_key`` values.
+
+    Empty ``notices`` emits nothing.
+
+    Parameters
+    ----------
+    notices : iterable of IterativeNotice
+        Per-iteration notice records to coalesce.
+    n_total : int
+        Total number of iterations attempted (denominator for the summary).
+    summary_label : str
+        Human-readable label for the iteration kind (e.g. ``"bootstrap"``).
+    notice_phrase : str
+        Phrase describing the notice condition, used in the aggregate summary.
+    max_emit : int, default=3
+        Maximum number of notice messages emitted verbatim before the
+        aggregate summary.
+    category : type of Warning, default=IterativeWarning
+        Warning class to emit.
+    stacklevel : int, default=3
+        ``stacklevel`` forwarded to :func:`warnings.warn`.
+    tail_msg : str, default=""
+        Optional text appended to the aggregate summary message.
+
+    Returns
+    -------
+    int
+        Number of notices, for caller convenience.
+
+    Raises
+    ------
+    ValueError
+        If ``n_total`` is less than 1, if ``max_emit`` is negative, or if
+        the number of notices exceeds ``n_total``.
+    """
+    if n_total < 1:
+        raise ValueError(f"n_total must be >= 1; got {n_total}")
+    if max_emit < 0:
+        raise ValueError(f"max_emit must be >= 0; got {max_emit}")
+    notices = list(notices)
+    n = len(notices)
+    if n == 0:
+        return 0
+    if n > n_total:
+        raise ValueError(f"len(notices)={n} exceeds n_total={n_total}")
+
+    for notice in notices[:max_emit]:
+        warnings.warn(notice.message, category, stacklevel=stacklevel)
+
+    pct = n / n_total * 100
+    tail = f" {tail_msg}" if tail_msg else ""
+    keys = ", ".join(
+        (nt.display or nt.group_key)
+        for nt in notices
+        if (nt.display or nt.group_key)
+    )
+    keys_part = f": {keys}" if keys else ""
+    summary = (
+        f"{n}/{n_total} ({pct:.0f}%) {summary_label}s {notice_phrase}"
+        f"{keys_part}.{tail}"
+    )
+    warnings.warn(summary, category, stacklevel=stacklevel)
+    return n
+
+
+class IterativeWarningCoalescer:
+    """Context-manager form of the coalescer functions.
+
+    Two modes:
+
+    * ``mode="failures"`` (default): call ``.record(exc, prefix=...)`` for
+      each caught exception. Dispatches to :func:`coalesce_failures`.
+    * ``mode="notices"``: call ``.record_notice(message, group_key=...)``
+      for each pre-rendered notice. Requires ``notice_phrase``. Dispatches
+      to :func:`coalesce_notices`.
+
+    Calling the wrong ``record*`` method for the active mode raises
+    ``RuntimeError``.
+
+    Example (failures)::
+
+        with IterativeWarningCoalescer(summary_label="bootstrap",
+                                       n_total=n_bootstrap) as cz:
+            for seed in seeds:
+                try:
+                    ...
+                except (ValueError, RuntimeError) as exc:
+                    cz.record(exc, prefix=f"seed={seed}")
+
+    Example (notices)::
+
+        with IterativeWarningCoalescer(
+            mode="notices",
+            summary_label="'stage' subpopulation",
+            notice_phrase="have insufficient events (< 30)",
+            n_total=len(labels),
+            category=SmallSubpopulationWarning,
+        ) as cz:
+            for label in labels:
+                if n_events < min_events:
+                    cz.record_notice(msg, group_key=str(label))
+    """
+
+    def __init__(
+        self,
+        *,
+        summary_label: str,
+        n_total: int,
+        max_emit: int = 3,
+        category: Type[Warning] = IterativeWarning,
+        stacklevel: int = 3,
+        tail_msg: str = "",
+        mode: Literal["failures", "notices"] = "failures",
+        notice_phrase: str = "",
+    ):
+        if n_total < 1:
+            raise ValueError(f"n_total must be >= 1; got {n_total}")
+        if max_emit < 0:
+            raise ValueError(f"max_emit must be >= 0; got {max_emit}")
+        if mode not in ("failures", "notices"):
+            raise ValueError(
+                f"mode must be 'failures' or 'notices'; got {mode!r}"
+            )
+        if mode == "notices" and not notice_phrase:
+            raise ValueError("notice_phrase is required when mode='notices'")
+        self.summary_label = summary_label
+        self.n_total = n_total
+        self.max_emit = max_emit
+        self.category = category
+        self.stacklevel = stacklevel
+        self.tail_msg = tail_msg
+        self.mode = mode
+        self.notice_phrase = notice_phrase
+        self._failures: list[IterativeFailure] = []
+        self._notices: list[IterativeNotice] = []
+        self._summarized = False
+
+    def record(self, exc: Exception, *, prefix: str = "") -> None:
+        if self.mode != "failures":
+            raise RuntimeError(
+                f"record() requires mode='failures'; coalescer is in "
+                f"mode={self.mode!r}. Use record_notice() instead."
+            )
+        self._failures.append(IterativeFailure.from_exception(exc, prefix=prefix))
+
+    def record_failure(self, failure: IterativeFailure) -> None:
+        if self.mode != "failures":
+            raise RuntimeError(
+                f"record_failure() requires mode='failures'; coalescer is in "
+                f"mode={self.mode!r}. Use record_notice() instead."
+            )
+        self._failures.append(failure)
+
+    def record_notice(
+        self, message: str, *, group_key: str = "", display: str = ""
+    ) -> None:
+        if self.mode != "notices":
+            raise RuntimeError(
+                f"record_notice() requires mode='notices'; coalescer is in "
+                f"mode={self.mode!r}. Use record() instead."
+            )
+        self._notices.append(
+            IterativeNotice(message=message, group_key=group_key, display=display)
+        )
+
+    def summarize(self) -> int:
+        if self._summarized:
+            return len(self._failures) + len(self._notices)
+        self._summarized = True
+        # Bump stacklevel by +2 to account for the summarize() and __exit__()
+        # frames the coalesce_* function will see above its own warnings.warn
+        # call. This way callers pass the same stacklevel they would use for a
+        # direct coalesce_*() call, and the warning still attributes to the
+        # caller of compute_subpopulation_metrics() (or whichever site uses
+        # the context-manager form).
+        bumped_stacklevel = self.stacklevel + 2
+        if self.mode == "failures":
+            return coalesce_failures(
+                self._failures,
+                n_total=self.n_total,
+                summary_label=self.summary_label,
+                max_emit=self.max_emit,
+                category=self.category,
+                stacklevel=bumped_stacklevel,
+                tail_msg=self.tail_msg,
+            )
+        return coalesce_notices(
+            self._notices,
+            n_total=self.n_total,
+            summary_label=self.summary_label,
+            notice_phrase=self.notice_phrase,
+            max_emit=self.max_emit,
+            category=self.category,
+            stacklevel=bumped_stacklevel,
+            tail_msg=self.tail_msg,
+        )
+
+    def __enter__(self) -> "IterativeWarningCoalescer":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> Optional[bool]:
+        # Always attempt to summarize so a propagating exception in the
+        # with-block does not silently discard previously recorded
+        # records. If summarize() itself raises while a user exception
+        # is propagating, prefer the user exception — masking it with
+        # our own bookkeeping failure is the worse outcome.
+        try:
+            self.summarize()
+        except Exception:
+            if exc_type is None:
+                raise
+        return None

mlsurv/_loky_patch.py

@@ -0,0 +1,34 @@
+"""Wrapper for loky resource_tracker.main that suppresses KeyError tracebacks.
+
+The loky resource tracker has a race condition on Windows where multiple
+workers try to UNREGISTER the same temp folder, causing noisy KeyError
+tracebacks on stderr. This wrapper installs a selective sys.excepthook
+that suppresses only those specific errors.
+
+Used by monkeypatching loky's resource_tracker.main reference at mlsurv
+import time, so the tracker subprocess imports this wrapper instead of
+the original.
+"""
+
+import sys
+
+# Save the ORIGINAL main before mlsurv.__init__ replaces it.
+# This module is imported by __init__.py *before* the replacement happens,
+# so _original_main always points to loky's real main function.
+from joblib.externals.loky.backend.resource_tracker import (
+    main as _original_main,
+)
+
+
+def main(fd, verbose=False):
+    _orig_excepthook = sys.excepthook
+
+    def _quiet_excepthook(exc_type, exc_value, exc_tb):
+        if exc_type is KeyError and exc_tb is not None:
+            filename = getattr(exc_tb.tb_frame.f_code, "co_filename", "")
+            if "resource_tracker" in filename:
+                return
+        _orig_excepthook(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _quiet_excepthook
+    _original_main(fd, verbose)