ensurv 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. ensurv-0.1.0/.readthedocs.yaml +21 -0
  2. ensurv-0.1.0/MANIFEST.in +7 -0
  3. ensurv-0.1.0/PKG-INFO +69 -0
  4. ensurv-0.1.0/README.md +43 -0
  5. ensurv-0.1.0/docs/_static/ensurv.css +128 -0
  6. ensurv-0.1.0/docs/_static/survival-curves.png +0 -0
  7. ensurv-0.1.0/docs/_templates/author-credit.html +1 -0
  8. ensurv-0.1.0/docs/api.rst +52 -0
  9. ensurv-0.1.0/docs/conf.py +30 -0
  10. ensurv-0.1.0/docs/examples.rst +38 -0
  11. ensurv-0.1.0/docs/index.rst +72 -0
  12. ensurv-0.1.0/docs/method.rst +56 -0
  13. ensurv-0.1.0/docs/quickstart.rst +62 -0
  14. ensurv-0.1.0/examples/EnSurv_SUPPORT_Example.ipynb +663 -0
  15. ensurv-0.1.0/pyproject.toml +42 -0
  16. ensurv-0.1.0/setup.cfg +4 -0
  17. ensurv-0.1.0/simulations/Asymptotic_Simulations.ipynb +1243 -0
  18. ensurv-0.1.0/simulations/Prediction_Simulations.ipynb +42908 -0
  19. ensurv-0.1.0/src/ensurv/__init__.py +6 -0
  20. ensurv-0.1.0/src/ensurv/_diagnostics.py +99 -0
  21. ensurv-0.1.0/src/ensurv/_random.py +39 -0
  22. ensurv-0.1.0/src/ensurv/cross_validation.py +229 -0
  23. ensurv-0.1.0/src/ensurv/diagnostics.py +336 -0
  24. ensurv-0.1.0/src/ensurv/evaluation.py +171 -0
  25. ensurv-0.1.0/src/ensurv/horizon.py +104 -0
  26. ensurv-0.1.0/src/ensurv/km.py +191 -0
  27. ensurv-0.1.0/src/ensurv/loss.py +95 -0
  28. ensurv-0.1.0/src/ensurv/model.py +1029 -0
  29. ensurv-0.1.0/src/ensurv/preprocessing.py +301 -0
  30. ensurv-0.1.0/src/ensurv/utils.py +441 -0
  31. ensurv-0.1.0/src/ensurv/workflows.py +280 -0
  32. ensurv-0.1.0/src/ensurv.egg-info/PKG-INFO +69 -0
  33. ensurv-0.1.0/src/ensurv.egg-info/SOURCES.txt +34 -0
  34. ensurv-0.1.0/src/ensurv.egg-info/dependency_links.txt +1 -0
  35. ensurv-0.1.0/src/ensurv.egg-info/requires.txt +18 -0
  36. ensurv-0.1.0/src/ensurv.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ version: 2
2
+
3
+ build:
4
+ os: ubuntu-24.04
5
+ tools:
6
+ python: "3.12"
7
+ jobs:
8
+ pre_install:
9
+ - '"$READTHEDOCS_VIRTUALENV_PATH/bin/python" -m pip install --index-url https://download.pytorch.org/whl/cpu "torch>=2.2"'
10
+
11
+ sphinx:
12
+ configuration: docs/conf.py
13
+ fail_on_warning: true
14
+
15
+ python:
16
+ install:
17
+ - method: pip
18
+ path: .
19
+ extra_requirements:
20
+ - docs
21
+ - workflow
@@ -0,0 +1,7 @@
1
+ include .readthedocs.yaml
2
+ include RELEASE.md
3
+ include docs/_templates/author-credit.html
4
+ recursive-include docs *.py *.rst *.css *.png
5
+ recursive-include examples *.ipynb
6
+ recursive-include simulations *.ipynb
7
+ prune docs/_build
ensurv-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,69 @@
1
+ Metadata-Version: 2.4
2
+ Name: ensurv
3
+ Version: 0.1.0
4
+ Summary: Generative survival modeling for right-censored time-to-event data
5
+ Classifier: Intended Audience :: Science/Research
6
+ Classifier: Programming Language :: Python :: 3
7
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
8
+ Requires-Python: >=3.11
9
+ Description-Content-Type: text/markdown
10
+ Requires-Dist: numpy>=1.26
11
+ Requires-Dist: pandas>=2.0
12
+ Requires-Dist: torch>=2.2
13
+ Requires-Dist: tqdm>=4.65
14
+ Provides-Extra: workflow
15
+ Requires-Dist: IPython>=8; extra == "workflow"
16
+ Requires-Dist: lifelines>=0.30; extra == "workflow"
17
+ Requires-Dist: matplotlib>=3.8; extra == "workflow"
18
+ Requires-Dist: scikit-learn>=1.5; extra == "workflow"
19
+ Requires-Dist: seaborn>=0.13; extra == "workflow"
20
+ Requires-Dist: SurvivalEVAL==0.8.2; extra == "workflow"
21
+ Provides-Extra: docs
22
+ Requires-Dist: Sphinx<10,>=8.2; extra == "docs"
23
+ Requires-Dist: pydata-sphinx-theme<0.17,>=0.16.1; extra == "docs"
24
+ Requires-Dist: sphinx-copybutton<0.6,>=0.5.2; extra == "docs"
25
+ Requires-Dist: sphinx-design<0.8,>=0.6; extra == "docs"
26
+
27
+ # EnSurv
28
+
29
+ EnSurv fits a generative model for right-censored time-to-event data. A PyTorch generator learns to draw event times conditional on covariates. These draws can be summarized as patient-level survival curves, medians, quantiles, or sample distributions.
30
+
31
+ ## Installation
32
+
33
+ After the first PyPI release, install EnSurv with Python 3.11 or newer.
34
+
35
+ ```bash
36
+ python -m pip install ensurv
37
+ ```
38
+
39
+ From a source checkout, use `python -m pip install .`. Add the `workflow` extra for data preprocessing, evaluation metrics, and diagnostic plots (`ensurv[workflow]` or `.[workflow]`).
40
+
41
+ ## Fit and predict
42
+
43
+ ```python
44
+ import numpy as np
45
+ from ensurv import EnSurv
46
+
47
+ rng = np.random.default_rng(7)
48
+ X = rng.normal(size=(128, 2))
49
+ event_time = rng.lognormal(4.0 + 0.5 * X[:, 0], 0.4)
50
+ censor_time = rng.uniform(25, 140, size=len(X))
51
+ Y = np.minimum(event_time, censor_time)
52
+ Delta = (event_time <= censor_time).astype(int)
53
+
54
+ model = EnSurv(device="cpu", random_state=7)
55
+ model.fit(X, Y, Delta, epochs=10, m=8, B=8)
56
+
57
+ times = np.linspace(0, model.tau_, 50, endpoint=False)
58
+ survival = model.predict_survival(X[:3], times, nsample=500, random_state=7)
59
+ print(survival.shape) # (3, 50)
60
+ ```
61
+
62
+ `Y` contains positive observed follow-up times. `Delta=1` marks an observed event and `Delta=0` marks right censoring. The default fitted horizon `model.tau_` is the largest observed event time in the training data. Keep raw survival queries below that horizon or pass `restricted=True` for the horizon-restricted distribution.
63
+
64
+ ## Examples and documentation
65
+
66
+ - `examples/EnSurv_SUPPORT_Example.ipynb` walks through three-fold cross-validation, metrics, and diagnostics on public SUPPORT data.
67
+ - `simulations/` contains the asymptotic and synthetic prediction experiments.
68
+ - `docs/` contains the Sphinx user guide and API reference. Build it with `python -m pip install ".[docs,workflow]"` followed by `python -m sphinx -W -b html docs docs/_build/html`.
69
+ - `RELEASE.md` covers building distributions, publishing to PyPI, and hosting the docs on Read the Docs.
ensurv-0.1.0/README.md ADDED
@@ -0,0 +1,43 @@
1
+ # EnSurv
2
+
3
+ EnSurv fits a generative model for right-censored time-to-event data. A PyTorch generator learns to draw event times conditional on covariates. These draws can be summarized as patient-level survival curves, medians, quantiles, or sample distributions.
4
+
5
+ ## Installation
6
+
7
+ After the first PyPI release, install EnSurv with Python 3.11 or newer.
8
+
9
+ ```bash
10
+ python -m pip install ensurv
11
+ ```
12
+
13
+ From a source checkout, use `python -m pip install .`. Add the `workflow` extra for data preprocessing, evaluation metrics, and diagnostic plots (`ensurv[workflow]` or `.[workflow]`).
14
+
15
+ ## Fit and predict
16
+
17
+ ```python
18
+ import numpy as np
19
+ from ensurv import EnSurv
20
+
21
+ rng = np.random.default_rng(7)
22
+ X = rng.normal(size=(128, 2))
23
+ event_time = rng.lognormal(4.0 + 0.5 * X[:, 0], 0.4)
24
+ censor_time = rng.uniform(25, 140, size=len(X))
25
+ Y = np.minimum(event_time, censor_time)
26
+ Delta = (event_time <= censor_time).astype(int)
27
+
28
+ model = EnSurv(device="cpu", random_state=7)
29
+ model.fit(X, Y, Delta, epochs=10, m=8, B=8)
30
+
31
+ times = np.linspace(0, model.tau_, 50, endpoint=False)
32
+ survival = model.predict_survival(X[:3], times, nsample=500, random_state=7)
33
+ print(survival.shape) # (3, 50)
34
+ ```
35
+
36
+ `Y` contains positive observed follow-up times. `Delta=1` marks an observed event and `Delta=0` marks right censoring. The default fitted horizon `model.tau_` is the largest observed event time in the training data. Keep raw survival queries below that horizon or pass `restricted=True` for the horizon-restricted distribution.
37
+
38
+ ## Examples and documentation
39
+
40
+ - `examples/EnSurv_SUPPORT_Example.ipynb` walks through three-fold cross-validation, metrics, and diagnostics on public SUPPORT data.
41
+ - `simulations/` contains the asymptotic and synthetic prediction experiments.
42
+ - `docs/` contains the Sphinx user guide and API reference. Build it with `python -m pip install ".[docs,workflow]"` followed by `python -m sphinx -W -b html docs docs/_build/html`.
43
+ - `RELEASE.md` covers building distributions, publishing to PyPI, and hosting the docs on Read the Docs.
@@ -0,0 +1,128 @@
1
+ html[data-theme="light"] {
2
+ --pst-color-primary: #126455;
3
+ --pst-color-secondary: #075375;
4
+ --ensurv-card-border: #cbded9;
5
+ --ensurv-card-tint: #f3faf7;
6
+ }
7
+
8
+ html[data-theme="dark"] {
9
+ --pst-color-primary: #82ead0;
10
+ --pst-color-secondary: #a6dcff;
11
+ --ensurv-card-border: #415a61;
12
+ --ensurv-card-tint: #202d35;
13
+ }
14
+
15
+ .navbar-brand .logo__title {
16
+ color: var(--pst-color-primary);
17
+ font-weight: 750;
18
+ letter-spacing: -0.04em;
19
+ }
20
+
21
+ .bd-main .bd-content .bd-article-container:has(.ensurv-hero) {
22
+ max-width: 74rem;
23
+ }
24
+
25
+ section:has(> .ensurv-hero) > h1 {
26
+ position: absolute;
27
+ width: 1px;
28
+ height: 1px;
29
+ overflow: hidden;
30
+ clip-path: inset(50%);
31
+ }
32
+
33
+ .ensurv-hero.docutils.container {
34
+ display: grid;
35
+ grid-template-columns: minmax(0, 1.12fr) minmax(0, 1fr);
36
+ align-items: center;
37
+ gap: clamp(1.25rem, 3vw, 3rem);
38
+ margin: 0.8rem 0 1.1rem;
39
+ padding: clamp(1.4rem, 4vw, 3.3rem);
40
+ border: 1px solid #23515c;
41
+ border-radius: 1.35rem;
42
+ background:
43
+ radial-gradient(ellipse at 94% 3%, #14605575, transparent 58%),
44
+ linear-gradient(130deg, #101f34, #102d36);
45
+ color: #e0f5f1;
46
+ }
47
+
48
+ .ensurv-intro > p {
49
+ max-width: 36ch;
50
+ color: #d7e5ee;
51
+ line-height: 1.62;
52
+ }
53
+
54
+ .ensurv-kicker p {
55
+ margin: 0 0 0.9rem;
56
+ color: #8cffe0;
57
+ font-size: 0.73rem;
58
+ font-weight: 700;
59
+ letter-spacing: 0.14em;
60
+ text-transform: uppercase;
61
+ }
62
+
63
+ .ensurv-headline p {
64
+ margin: 0 0 1rem;
65
+ color: #f6fffc;
66
+ font-size: clamp(2.25rem, 4.45vw, 3.85rem);
67
+ font-weight: 790;
68
+ letter-spacing: -0.06em;
69
+ line-height: 1.03;
70
+ text-wrap: balance;
71
+ }
72
+
73
+ .ensurv-hero a.ensurv-cta {
74
+ margin: 0.55rem 0 0;
75
+ padding: 0.58rem 0.85rem;
76
+ border: 1px solid transparent;
77
+ border-radius: 0.55rem;
78
+ background: #abf7db;
79
+ color: #0e2d2a;
80
+ font-weight: 700;
81
+ }
82
+
83
+ .ensurv-hero a.ensurv-cta:hover,
84
+ .ensurv-hero a.ensurv-cta:focus-visible {
85
+ background: #d3fcec;
86
+ color: #0e2d2a;
87
+ }
88
+
89
+ .ensurv-hero > figure {
90
+ min-width: 0;
91
+ margin: 0;
92
+ padding: clamp(0.6rem, 1.6vw, 1.05rem);
93
+ border: 1px solid #ffffff29;
94
+ border-radius: 0.9rem;
95
+ background: #071d2859;
96
+ }
97
+
98
+ .ensurv-hero > figure img {
99
+ width: 100%;
100
+ height: auto;
101
+ background: transparent;
102
+ }
103
+
104
+ .ensurv-hero > figure .caption-text {
105
+ color: #c7dce5;
106
+ font-size: 0.82rem;
107
+ font-style: normal;
108
+ }
109
+
110
+ .ensurv-install {
111
+ border-radius: 0.7rem;
112
+ }
113
+
114
+ .ensurv-guides .sd-card.sd-sphinx-override {
115
+ background: var(--ensurv-card-tint);
116
+ border: 1px solid var(--ensurv-card-border);
117
+ border-radius: 0.8rem;
118
+ }
119
+
120
+ .ensurv-guides .sd-card-title {
121
+ color: var(--pst-color-primary);
122
+ }
123
+
124
+ @media (max-width: 760px) {
125
+ .ensurv-hero.docutils.container {
126
+ grid-template-columns: minmax(0, 1fr);
127
+ }
128
+ }
@@ -0,0 +1 @@
1
+ <p>Rajdeep Pathak, Tanujit Chakraborty, et al.</p>
@@ -0,0 +1,52 @@
1
+ API reference
2
+ =============
3
+
4
+ Fit and predict
5
+ ---------------
6
+
7
+ .. autoclass:: ensurv.EnSurv
8
+ :members: fit, predict, predict_survival, explain
9
+
10
+ .. autoclass:: ensurv.EnSurvNet
11
+ :members: forward
12
+
13
+ Preprocessing and evaluation
14
+ ----------------------------
15
+
16
+ Install the ``workflow`` extra to use these functions.
17
+
18
+ .. autofunction:: ensurv.preprocessing.preprocess_df
19
+ .. autofunction:: ensurv.preprocessing.prepare_unos_dataset
20
+ .. autofunction:: ensurv.evaluation.compute_all_metrics
21
+ .. autofunction:: ensurv.evaluation.analyze_hierarchical_importance
22
+
23
+ Diagnostics
24
+ -----------
25
+
26
+ .. autoclass:: ensurv.diagnostics.EnSurvDiagnostics
27
+ :members:
28
+
29
+ .. automodule:: ensurv.utils
30
+ :members:
31
+
32
+ Horizon and training score
33
+ --------------------------
34
+
35
+ .. automodule:: ensurv.horizon
36
+ :members: resolve_tau, apply_tau_restriction
37
+
38
+ .. automodule:: ensurv.km
39
+ :members:
40
+
41
+ .. automodule:: ensurv.loss
42
+ :members:
43
+
44
+ Research workflows
45
+ ------------------
46
+
47
+ For the original kidney experiment, supply your own dataset path explicitly.
48
+
49
+ .. autofunction:: ensurv.cross_validation.run_cross_validation
50
+
51
+ .. automodule:: ensurv.workflows
52
+ :members:
@@ -0,0 +1,30 @@
1
+ from importlib.metadata import version as distribution_version
2
+
3
+ project = "EnSurv"
4
+ release = distribution_version("ensurv")
5
+
6
+ extensions = [
7
+ "sphinx.ext.autodoc",
8
+ "sphinx.ext.mathjax",
9
+ "sphinx_copybutton",
10
+ "sphinx_design",
11
+ ]
12
+
13
+ exclude_patterns = ["_build"]
14
+ autodoc_member_order = "bysource"
15
+ autodoc_typehints = "description"
16
+
17
+ html_theme = "pydata_sphinx_theme"
18
+ html_title = "EnSurv documentation"
19
+ templates_path = ["_templates"]
20
+ html_static_path = ["_static"]
21
+ html_css_files = ["ensurv.css"]
22
+ html_sidebars = {"index": []}
23
+ html_theme_options = {
24
+ "navbar_align": "left",
25
+ "logo": {"text": "EnSurv"},
26
+ "show_prev_next": True,
27
+ "footer_start": ["author-credit"],
28
+ "footer_end": [],
29
+ "secondary_sidebar_items": ["page-toc"],
30
+ }
@@ -0,0 +1,38 @@
1
+ Examples and simulations
2
+ ========================
3
+
4
+ SUPPORT cross-validation
5
+ ------------------------
6
+
7
+ :download:`Download the SUPPORT notebook <../examples/EnSurv_SUPPORT_Example.ipynb>`
8
+ for a three-fold workflow using public cohort data. It estimates time to death
9
+ in days from recorded covariates and shows metrics, training diagnostics,
10
+ and fitted feature summaries. The notebook includes data provenance and the
11
+ feature list.
12
+
13
+ After publication, install the workflow and notebook dependencies with:
14
+
15
+ .. code-block:: bash
16
+
17
+ python -m pip install "ensurv[workflow]" jupyterlab
18
+ python -m jupyterlab
19
+
20
+ From a checkout, replace ``ensurv[workflow]`` with ``.[workflow]`` in that
21
+ command. Open the notebook in JupyterLab and select the kernel from the same
22
+ environment. It downloads the public data on the first run and saves fold
23
+ artifacts under ``support_cv_outputs/``. For a smaller run, set
24
+ ``N_PATIENTS = 600`` and ``EPOCHS = 5`` in the configuration cell.
25
+
26
+ Each fold fits preprocessing statistics on its training rows and evaluates
27
+ on held-out rows. Keep each fold's model, time divisor, and feature order
28
+ together when interpreting predictions and diagnostic plots.
29
+
30
+ Simulation notebooks
31
+ --------------------
32
+
33
+ * :download:`Asymptotic simulations <../simulations/Asymptotic_Simulations.ipynb>`
34
+ exercise the Kaplan–Meier completion and energy-score routines. Install
35
+ ``ensurv`` with ``matplotlib``, ``scipy``, and ``jupyterlab``.
36
+ * :download:`Prediction simulations <../simulations/Prediction_Simulations.ipynb>`
37
+ fit EnSurv across synthetic data-generating scenarios and export a results
38
+ CSV. Install ``ensurv[workflow]`` with ``jupyterlab``.
@@ -0,0 +1,72 @@
1
+ :html_theme.sidebar_secondary.remove: true
2
+
3
+ EnSurv
4
+ ======
5
+
6
+ .. toctree::
7
+ :hidden:
8
+ :maxdepth: 2
9
+
10
+ quickstart
11
+ method
12
+ examples
13
+ api
14
+
15
+ .. container:: ensurv-hero
16
+
17
+ .. container:: ensurv-intro
18
+
19
+ .. container:: ensurv-kicker
20
+
21
+ Generative survival analysis
22
+
23
+ .. container:: ensurv-headline
24
+
25
+ Learn the distribution of event times
26
+
27
+ Fit EnSurv model to right-censored data. Draw possible event times, estimate
28
+ patient-specific survival curves, and inspect the fitted model.
29
+
30
+ .. button-ref:: quickstart
31
+ :class: ensurv-cta
32
+
33
+ Start with a CPU example →
34
+
35
+ .. figure:: _static/survival-curves.png
36
+ :class: dark-light
37
+ :alt: Two illustrative patient survival curves fall at different rates. A vertical line marks the fitted horizon tau.
38
+
39
+ Illustrative survival curves up to the fitted horizon.
40
+
41
+ .. code-block:: bash
42
+ :class: ensurv-install
43
+
44
+ python -m pip install ensurv
45
+
46
+ .. grid:: 1 2 2 2
47
+ :gutter: 3
48
+ :class-container: ensurv-guides
49
+
50
+ .. grid-item-card:: Fit your first model
51
+ :link: quickstart
52
+ :link-type: doc
53
+
54
+ Run a synthetic example and get survival probabilities, medians, and time draws.
55
+
56
+ .. grid-item-card:: Understand the horizon
57
+ :link: method
58
+ :link-type: doc
59
+
60
+ See how pooled Kaplan–Meier completion and horizon restriction enter the model.
61
+
62
+ .. grid-item-card:: Explore worked notebooks
63
+ :link: examples
64
+ :link-type: doc
65
+
66
+ Run the public SUPPORT workflow or reproduce the synthetic experiments.
67
+
68
+ .. grid-item-card:: Browse the API
69
+ :link: api
70
+ :link-type: doc
71
+
72
+ Look up model parameters, prediction shapes, metrics, and plotting helpers.
@@ -0,0 +1,56 @@
1
+ Model and horizon
2
+ =================
3
+
4
+ EnSurv models a conditional distribution of event times from features and
5
+ random noise. Its generator operates on the log-time scale. Log-time draws
6
+ can be converted to event times, summarized with quantiles, or compared with
7
+ a time grid to estimate a survival curve.
8
+
9
+ Horizon restriction and completion
10
+ ----------------------------------
11
+
12
+ A fit uses a horizon :math:`\tau`. Set it explicitly in the same units as
13
+ ``Y`` or use the default ``tau="max_event"``, which selects the largest
14
+ observed event time in the training data. Each outcome contributes to the
15
+ energy score according to its follow-up:
16
+
17
+ * An observed event before :math:`\tau` contributes its observed time.
18
+ * Follow-up reaching :math:`\tau` contributes the restricted time :math:`\tau`.
19
+ * A right-censored observation before :math:`\tau` is scored against the
20
+ part of a pooled Kaplan–Meier completion distribution strictly after its
21
+ censoring time. Bootstrap estimates average the contribution, with residual
22
+ probability mass assigned to :math:`\tau`.
23
+
24
+ The fitted generator targets the resulting completed working distribution.
25
+ Its agreement with the underlying conditional event-time distribution depends
26
+ on how well pooled completion represents the censored outcomes.
27
+
28
+ .. seealso::
29
+
30
+ :func:`ensurv.km.kaplan_meier_batched` documents the bootstrap curves.
31
+ :func:`ensurv.loss.survival_engression_loss` gives the empirical score.
32
+
33
+ Prediction at the horizon
34
+ -------------------------
35
+
36
+ By default, ``predict_survival`` accepts only times strictly below the fitted
37
+ horizon. With ``restricted=True``, it estimates the survival function of
38
+ :math:`\min(T,\tau)` and returns zero at and after :math:`\tau` by definition.
39
+ To query raw generator survival at or beyond the horizon, pass
40
+ ``allow_extrapolation=True`` and interpret those estimates as extrapolations of
41
+ the fitted working model. Raw time draws can also extend past the horizon.
42
+
43
+ Time scaling and evaluation
44
+ ---------------------------
45
+
46
+ The model's ``time_scale`` option divides durations internally before taking
47
+ logs. The fit and prediction APIs continue to accept times in the original
48
+ fit-input units. The :doc:`SUPPORT workflow <examples>` uses a different
49
+ convention for :func:`ensurv.evaluation.compute_all_metrics`: it divides the
50
+ training times externally by the training maximum ``y_max`` and provides
51
+ original, day-scale outcomes plus ``y_max`` to the evaluator. In that
52
+ workflow, leave the model's internal ``time_scale`` at its default of 1.
53
+
54
+ The evaluator uses fixed one- and five-year horizons in days. It enables raw
55
+ extrapolation over its evaluation grid, so check the fold's fitted horizon
56
+ when interpreting its metrics.
@@ -0,0 +1,62 @@
1
+ Quickstart
2
+ ==========
3
+
4
+ Install EnSurv
5
+ --------------
6
+
7
+ EnSurv requires Python 3.11 or newer. After the first PyPI release, install the
8
+ model with:
9
+
10
+ .. code-block:: bash
11
+
12
+ python -m pip install ensurv
13
+
14
+ For a source checkout, run ``python -m pip install .`` from the repository root.
15
+ Add ``[workflow]`` to the install target to enable preprocessing, metrics, and
16
+ diagnostic plotting. To use a specific CPU or accelerator build, install
17
+ `PyTorch <https://pytorch.org/get-started/locally/>`_ for your platform first.
18
+
19
+ Fit on synthetic data
20
+ ---------------------
21
+
22
+ Give :meth:`ensurv.EnSurv.fit` a finite numeric feature matrix ``X``, strictly
23
+ positive observed follow-up times ``Y``, and binary event indicators ``Delta``.
24
+ Use ``1`` for an observed event and ``0`` for right censoring. Preserve the
25
+ training feature order when predicting. Fit any imputation, encoding, or
26
+ scaling on training data before applying it to held-out data.
27
+
28
+ .. code-block:: python
29
+
30
+ import numpy as np
31
+ from ensurv import EnSurv
32
+
33
+ rng = np.random.default_rng(7)
34
+ X = rng.normal(size=(128, 2))
35
+ event_time = rng.lognormal(4.0 + 0.5 * X[:, 0], 0.4)
36
+ censor_time = rng.uniform(25, 140, size=len(X))
37
+ Y = np.minimum(event_time, censor_time)
38
+ Delta = (event_time <= censor_time).astype(int)
39
+
40
+ model = EnSurv(device="cpu", random_state=7)
41
+ model.fit(X, Y, Delta, epochs=10, m=8, B=8)
42
+
43
+ Generate predictions
44
+ --------------------
45
+
46
+ ``predict_survival`` returns one row per observation and one column per query
47
+ time. The default horizon ``model.tau_`` is the largest observed training
48
+ event time. ``endpoint=False`` keeps the query grid strictly below it.
49
+
50
+ .. code-block:: python
51
+
52
+ times = np.linspace(0, model.tau_, 50, endpoint=False)
53
+ survival = model.predict_survival(X[:3], times, nsample=500, random_state=7)
54
+ medians = model.predict(X[:3], target="median", restricted=True, random_state=7)
55
+ draws = model.predict(X[:3], target=None, nsample=500, restricted=True, random_state=7)
56
+
57
+ print(survival.shape, medians.shape, draws.shape)
58
+ # (3, 50) (3,) (3, 500)
59
+
60
+ Prediction times use the units supplied to ``fit``. ``restricted=True`` caps
61
+ time draws at the fitted horizon. The :doc:`method` guide explains how to
62
+ interpret predictions at that boundary.