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.
- ensurv-0.1.0/.readthedocs.yaml +21 -0
- ensurv-0.1.0/MANIFEST.in +7 -0
- ensurv-0.1.0/PKG-INFO +69 -0
- ensurv-0.1.0/README.md +43 -0
- ensurv-0.1.0/docs/_static/ensurv.css +128 -0
- ensurv-0.1.0/docs/_static/survival-curves.png +0 -0
- ensurv-0.1.0/docs/_templates/author-credit.html +1 -0
- ensurv-0.1.0/docs/api.rst +52 -0
- ensurv-0.1.0/docs/conf.py +30 -0
- ensurv-0.1.0/docs/examples.rst +38 -0
- ensurv-0.1.0/docs/index.rst +72 -0
- ensurv-0.1.0/docs/method.rst +56 -0
- ensurv-0.1.0/docs/quickstart.rst +62 -0
- ensurv-0.1.0/examples/EnSurv_SUPPORT_Example.ipynb +663 -0
- ensurv-0.1.0/pyproject.toml +42 -0
- ensurv-0.1.0/setup.cfg +4 -0
- ensurv-0.1.0/simulations/Asymptotic_Simulations.ipynb +1243 -0
- ensurv-0.1.0/simulations/Prediction_Simulations.ipynb +42908 -0
- ensurv-0.1.0/src/ensurv/__init__.py +6 -0
- ensurv-0.1.0/src/ensurv/_diagnostics.py +99 -0
- ensurv-0.1.0/src/ensurv/_random.py +39 -0
- ensurv-0.1.0/src/ensurv/cross_validation.py +229 -0
- ensurv-0.1.0/src/ensurv/diagnostics.py +336 -0
- ensurv-0.1.0/src/ensurv/evaluation.py +171 -0
- ensurv-0.1.0/src/ensurv/horizon.py +104 -0
- ensurv-0.1.0/src/ensurv/km.py +191 -0
- ensurv-0.1.0/src/ensurv/loss.py +95 -0
- ensurv-0.1.0/src/ensurv/model.py +1029 -0
- ensurv-0.1.0/src/ensurv/preprocessing.py +301 -0
- ensurv-0.1.0/src/ensurv/utils.py +441 -0
- ensurv-0.1.0/src/ensurv/workflows.py +280 -0
- ensurv-0.1.0/src/ensurv.egg-info/PKG-INFO +69 -0
- ensurv-0.1.0/src/ensurv.egg-info/SOURCES.txt +34 -0
- ensurv-0.1.0/src/ensurv.egg-info/dependency_links.txt +1 -0
- ensurv-0.1.0/src/ensurv.egg-info/requires.txt +18 -0
- 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
|
ensurv-0.1.0/MANIFEST.in
ADDED
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
|
+
}
|
|
Binary file
|
|
@@ -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.
|