meds-algorithm-retain 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.
- meds_algorithm_retain-0.1.0/.gitignore +12 -0
- meds_algorithm_retain-0.1.0/CHANGELOG.md +11 -0
- meds_algorithm_retain-0.1.0/LICENSE +21 -0
- meds_algorithm_retain-0.1.0/PKG-INFO +218 -0
- meds_algorithm_retain-0.1.0/README.md +198 -0
- meds_algorithm_retain-0.1.0/RELEASING.md +101 -0
- meds_algorithm_retain-0.1.0/algorithms/supervised/model.yaml +24 -0
- meds_algorithm_retain-0.1.0/configs/runs/run.yaml +25 -0
- meds_algorithm_retain-0.1.0/docs/IMPLEMENTATION_GUIDE.md +219 -0
- meds_algorithm_retain-0.1.0/docs/TESTING.md +82 -0
- meds_algorithm_retain-0.1.0/pyproject.toml +56 -0
- meds_algorithm_retain-0.1.0/scripts/check_distribution.sh +20 -0
- meds_algorithm_retain-0.1.0/scripts/check_release.py +32 -0
- meds_algorithm_retain-0.1.0/scripts/github-sync.sh +29 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/__init__.py +6 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/__main__.py +65 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/_interpret.py +102 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/_model.py +171 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/_preprocess.py +270 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/_training.py +320 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/_windows.py +221 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/config.py +114 -0
- meds_algorithm_retain-0.1.0/src/retain_meds/retain_meds.py +252 -0
- meds_algorithm_retain-0.1.0/tests/__init__.py +1 -0
- meds_algorithm_retain-0.1.0/tests/conftest.py +31 -0
- meds_algorithm_retain-0.1.0/tests/e2e.py +140 -0
- meds_algorithm_retain-0.1.0/tests/test_conformance.py +7 -0
- meds_algorithm_retain-0.1.0/tests/test_data_path.py +477 -0
- meds_algorithm_retain-0.1.0/tests/test_model_fidelity.py +255 -0
- meds_algorithm_retain-0.1.0/tests/test_primary_behavior.py +183 -0
- meds_algorithm_retain-0.1.0/tests/wheel_smoke.py +55 -0
- meds_algorithm_retain-0.1.0/uv.lock +1279 -0
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Changes
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
- RETAIN (Choi et al., NeurIPS 2016) for MEDS behind the MEDS algorithm contract, `supervised` profile:
|
|
6
|
+
`preprocess_data`, `train_supervised`, `predict_supervised`.
|
|
7
|
+
- Converted from the earlier `meds-model-retain` layout to `MEDS_algorithm_template` @ `731e759` with
|
|
8
|
+
`meds-algorithm==0.4.0a5`. The model, its defaults and its scores are unchanged.
|
|
9
|
+
- Validation: model fidelity against a NumPy transcription of the official equations, data-path and
|
|
10
|
+
temporal-cutoff tests, a signal test with a shuffled-label control, the shared conformance suite, and the
|
|
11
|
+
temporal-leakage checks of `meds-algorithm` main (future-rewrite rerun and null world).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Florent Pollet
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: meds-algorithm-retain
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: RETAIN (Choi et al., NeurIPS 2016) reverse-time attention model for MEDS, a supervised classifier behind the MEDS algorithm contract.
|
|
5
|
+
Project-URL: Repository, https://github.com/florian6973/meds-algorithm-retain
|
|
6
|
+
Author-email: Florent Pollet <flo1.raymond@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Python: >=3.11
|
|
10
|
+
Requires-Dist: meds-algorithm[data]==0.4.0a5
|
|
11
|
+
Requires-Dist: numpy>=1.26
|
|
12
|
+
Requires-Dist: pyarrow>=15
|
|
13
|
+
Requires-Dist: pyyaml>=6
|
|
14
|
+
Requires-Dist: torch>=2.2
|
|
15
|
+
Provides-Extra: orchestration
|
|
16
|
+
Requires-Dist: meds-algorithm[orchestration]==0.4.0a5; extra == 'orchestration'
|
|
17
|
+
Provides-Extra: test
|
|
18
|
+
Requires-Dist: meds-algorithm[conformance]==0.4.0a5; extra == 'test'
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# RETAIN
|
|
22
|
+
|
|
23
|
+
RETAIN ([Choi et al., NeurIPS 2016](https://proceedings.neurips.cc/paper/2016/hash/231141b34c82aa95e48810a9d1b33a79-Abstract.html))
|
|
24
|
+
for datasets in the [Medical Event Data Standard](https://github.com/Medical-Event-Data-Standard/meds): a
|
|
25
|
+
reverse-time attention model that predicts a binary outcome from a subject's sequence of visits and
|
|
26
|
+
reports which codes drove each prediction.
|
|
27
|
+
|
|
28
|
+
- **What it runs:** `preprocess_data` (code vocabulary fitted on the training split), `train_supervised`
|
|
29
|
+
(the whole model, for one task) and `predict_supervised` (one probability per requested key).
|
|
30
|
+
- **Model:** a PyTorch reimplementation of the official Theano code
|
|
31
|
+
([`mp2893/retain`](https://github.com/mp2893/retain) @ `9fd39c46`), with the official defaults, checked
|
|
32
|
+
against a NumPy transcription of the official equations.
|
|
33
|
+
- **MEDS adaptation:** a visit is the set of codes in one time bucket (`visit_bucket_minutes`, default one
|
|
34
|
+
day), and each history is cut at its prediction time before visits are formed. No dataset predicates
|
|
35
|
+
are needed.
|
|
36
|
+
- **Status:** [IMPLEMENTATION_REPORT.md](IMPLEMENTATION_REPORT.md) lists what was verified, including the
|
|
37
|
+
temporal-leakage checks, and what was not.
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install meds-algorithm-retain
|
|
41
|
+
retain-meds preprocess_data external_meds_dir=$MEDS_DIR output_data_dir=$RUN/data
|
|
42
|
+
retain-meds train_supervised input_data_dir=$RUN/data external_labels_dir=$LABELS_DIR \
|
|
43
|
+
output_supervised_algorithm_dir=$RUN/algorithm
|
|
44
|
+
retain-meds predict_supervised input_data_dir=$RUN/data input_supervised_algorithm_dir=$RUN/algorithm \
|
|
45
|
+
external_index_dir=$LABELS_DIR splits=[held_out] output_predictions_dir=$RUN/predictions
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Settings are the fields of `RETAINConfig` (`src/retain_meds/config.py`); pass a YAML or JSON file of
|
|
49
|
+
overrides to every step with `config_file=<path>`.
|
|
50
|
+
|
|
51
|
+
## Python API and named command
|
|
52
|
+
|
|
53
|
+
The implementation is `src/retain_meds/retain_meds.py`, with configuration in `config.py`.
|
|
54
|
+
Both concrete classes are public package exports:
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from retain_meds import RETAIN, RETAINConfig
|
|
58
|
+
|
|
59
|
+
algorithm = RETAIN(RETAINConfig())
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Run typed requests through `meds_algorithm.StepRunner.run(...)` so validation, measurements and
|
|
63
|
+
publication apply. Calling an implementation method directly bypasses that execution contract.
|
|
64
|
+
After installation, the algorithm's own `retain-meds` command runs the CLI:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
retain-meds commands --profile supervised
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
RETAIN (Choi et al., NeurIPS 2016) reverse-time attention model for MEDS, a supervised classifier behind the MEDS algorithm contract.
|
|
71
|
+
|
|
72
|
+
This repository declares the **`supervised`** profiles under version 4 of the minimal MEDS algorithm
|
|
73
|
+
contract. The contract standardizes MEDS input, command meanings and arguments, artifact envelopes,
|
|
74
|
+
final predictions, measurements, MEDS-DEV packaging, and operational interfaces. The algorithm owns every
|
|
75
|
+
computational choice and every intermediate payload.
|
|
76
|
+
|
|
77
|
+
## Algorithm profile commands
|
|
78
|
+
|
|
79
|
+
- `supervised`: `preprocess_data → train_supervised → predict_supervised`
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
retain-meds profiles
|
|
83
|
+
retain-meds commands --profile supervised
|
|
84
|
+
retain-meds <step> --profile <profile> key=value ...
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Each profile has `algorithms/<profile>/model.yaml`. Multiple profiles share one Python package and one
|
|
88
|
+
registry; select one explicitly for each run. `STUB_PROFILES` tracks implementation status separately.
|
|
89
|
+
Read [Software contract](SPEC.md) for exact class responsibilities and step inputs.
|
|
90
|
+
|
|
91
|
+
Intermediate artifacts may be tensors, files, databases, external-system references, or any other
|
|
92
|
+
implementation-owned representation. Generic tests inspect only their `manifest.yaml` envelopes. They
|
|
93
|
+
must not assume batches, Lightning, PyTorch, Parquet intermediate data, or iteration order.
|
|
94
|
+
|
|
95
|
+
## Profile runner (prototype)
|
|
96
|
+
|
|
97
|
+
Install `uv sync --extra orchestration --extra test`, then fill the input paths and new output directory
|
|
98
|
+
in `configs/runs/run.yaml`. Algorithm settings belong under `algorithm`; core validates them using
|
|
99
|
+
this repository's concrete Config class.
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
uv run retain-meds run --dry-run
|
|
103
|
+
uv run retain-meds run execution=local
|
|
104
|
+
# Use a NEW output_dir and configure your cluster's resources before submission:
|
|
105
|
+
uv run retain-meds run execution=slurm output_dir=/runs/new-cluster-run
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
A dry run prints all resolved arguments, paths, configuration and resources without writing files or
|
|
109
|
+
submitting jobs. Local execution uses fresh subprocesses; Submitit submits separate dependent SLURM
|
|
110
|
+
jobs. See the [shared runner guide](https://meds-algorithm.readthedocs.io/en/latest/running/#profile-runner-prototype)
|
|
111
|
+
for stage subsets, artifact reuse, resource configuration and prototype limitations. The existing
|
|
112
|
+
per-step CLI and shell launcher remain available for comparison. This prototype does not implement
|
|
113
|
+
Hydra multirun, multi-node training or checkpoint/resume.
|
|
114
|
+
|
|
115
|
+
## Publishing this algorithm
|
|
116
|
+
|
|
117
|
+
Follow [the release guide](RELEASING.md) for package metadata, one-time PyPI Trusted Publisher setup,
|
|
118
|
+
installed-wheel checks, and version-tag publication. All profiles ship in the `meds-algorithm-retain`
|
|
119
|
+
distribution. Tests run in CI; publishing is an explicit workflow dispatch after implementation.
|
|
120
|
+
|
|
121
|
+
## Inputs and predicates
|
|
122
|
+
|
|
123
|
+
- `external_meds_dir` is the standard MEDS dataset boundary.
|
|
124
|
+
- `external_index_dir` supplies only `(subject_id, prediction_time)` to inference and scoring.
|
|
125
|
+
- `external_labels_dir` supplies permitted training targets or explicit in-context examples.
|
|
126
|
+
- `external_evaluation_labels_dir`, when supplied, is used only to attach truth after scores are fixed.
|
|
127
|
+
- `external_predicates_file` supplies dataset-specific predicates when useful. For MIMIC-IV, reuse the
|
|
128
|
+
predicates from MEDS-DEV. This repository decides whether and how to interpret them.
|
|
129
|
+
|
|
130
|
+
A command that consumes predicates records their absolute path and SHA-256 digest in its manifest.
|
|
131
|
+
Predicates do not imply a standard feature representation.
|
|
132
|
+
|
|
133
|
+
## Implementing the algorithm
|
|
134
|
+
|
|
135
|
+
Read [AGENTS.md](AGENTS.md), [SPEC.md](SPEC.md), and
|
|
136
|
+
[docs/IMPLEMENTATION_GUIDE.md](docs/IMPLEMENTATION_GUIDE.md) completely before changing implementation
|
|
137
|
+
files. The implementation source recorded when this repository was generated is:
|
|
138
|
+
|
|
139
|
+
```text
|
|
140
|
+
https://proceedings.neurips.cc/paper/2016/hash/231141b34c82aa95e48810a9d1b33a79-Abstract.html and https://github.com/mp2893/retain@9fd39c46e44b3fdae3a667a47fbdd5ffbd87bff5
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
The algorithm-owned surface is `src/retain_meds/retain_meds.py` (the typed algorithm), `src/retain_meds/config.py`
|
|
144
|
+
(its immutable configuration), `algorithms/<profile>/model.yaml`, and
|
|
145
|
+
`tests/e2e.py`. Implement the selected profile methods, define exact intermediate compatibility checks in
|
|
146
|
+
`validate_inputs`,
|
|
147
|
+
finalize MEDS-DEV command strings, and complete the report. Remove a profile from `STUB_PROFILES` only after it runs end to end. Complete every declared profile.
|
|
148
|
+
|
|
149
|
+
For each generated test and its purpose, read [the test guide](docs/TESTING.md).
|
|
150
|
+
|
|
151
|
+
## Configuration and execution ownership
|
|
152
|
+
|
|
153
|
+
Declare typed fields/defaults in `RETAINConfig`, with `validate()` for constraints. Pass
|
|
154
|
+
`config_file=/path/config.yaml` to a step for a JSON/YAML values mapping; unknown fields fail. Core saves
|
|
155
|
+
the complete resolved config and original typed request as `config.json` and `request.json` in each
|
|
156
|
+
published artifact. These JSON envelopes can be reloaded with the corresponding explicit classes.
|
|
157
|
+
|
|
158
|
+
Algorithm methods receive typed requests, write payloads into `request.output.directory` (staging), and
|
|
159
|
+
return `PayloadMetadata`. `create_repository().run(...)` constructs a fresh algorithm and delegates to
|
|
160
|
+
core's runner. It owns measurements, prediction validation, optional post-score truth attachment,
|
|
161
|
+
metadata and publication. Never publish from inside algorithm methods or write the reserved metadata files.
|
|
162
|
+
Reopen fitted artifacts on each step. Test config/request round trips and execution in a fresh process.
|
|
163
|
+
|
|
164
|
+
## Verification
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
uv run pytest -rs
|
|
168
|
+
uv run pytest -m meds_dev -rs
|
|
169
|
+
uv run pytest -m real_data -rs
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
- The default suite runs the local end-to-end adapter and contract tests.
|
|
173
|
+
- `meds_dev` registers `algorithms/<profile>/model.yaml`, installs this repository from `requirements.txt` in an isolated
|
|
174
|
+
environment, and executes MEDS-DEV's real command slots.
|
|
175
|
+
- `real_data` runs the full selected algorithm profile on the MEDS-DEV MIMIC-IV demo, the pinned
|
|
176
|
+
`mortality/in_icu/first_24h` task, and MEDS-DEV's
|
|
177
|
+
MIMIC predicates. Set `MEDS_DEMO_DIR` to reuse an existing demo and `MEDS_DEV_DIR` to reuse a checkout.
|
|
178
|
+
|
|
179
|
+
Automatic provisioning pins MEDS-DEV PR #330's tested commit, which has the `{predicates_path}`
|
|
180
|
+
passthrough (PR #325). Set `MEDS_DEV_REF` to use another
|
|
181
|
+
revision containing those capabilities. A checkout supplied through `MEDS_DEV_DIR` is checked and fails
|
|
182
|
+
clearly if it cannot populate them.
|
|
183
|
+
|
|
184
|
+
Both integration tiers explicitly `algorithm_stub`-skip until implementation is complete. A completed port
|
|
185
|
+
must have zero `algorithm_stub` skips and must account for every other skip using `-rs` output.
|
|
186
|
+
|
|
187
|
+
These commands are gates, not an unordered checklist. Follow the canonical staged workflow in
|
|
188
|
+
[docs/IMPLEMENTATION_GUIDE.md](docs/IMPLEMENTATION_GUIDE.md): local, MEDS-DEV, pre-demo report and human
|
|
189
|
+
review, MIMIC-IV demo, demo report and human review, authorized full-data run, then final report and GitHub
|
|
190
|
+
synchronization. Full-data cluster jobs run only from a clean, pushed commit and use the reviewed shared
|
|
191
|
+
task bundle for the selected dataset (for example, MIMIC-IV or NWICU in MEDS format), built upstream from
|
|
192
|
+
clinical ACES tasks or randomly sampled code-by-horizon tasks. The provided `real_data` test remains the MIMIC-IV demo regardless of that choice.
|
|
193
|
+
|
|
194
|
+
Final predictions must conform to MEDS evaluation, contain unique `(subject_id, prediction_time)` keys,
|
|
195
|
+
and exactly cover the requested evaluation index. Tests compare the actual key sets; self-reported manifest
|
|
196
|
+
counts are not accepted as evidence. Row order is never an association mechanism.
|
|
197
|
+
|
|
198
|
+
## Measurements
|
|
199
|
+
|
|
200
|
+
Every command manifest records monotonic wall time and sampled live process-tree memory. On Linux, peak
|
|
201
|
+
PSS from `/proc/*/smaps_rollup` is the primary comparison metric; aggregate RSS is retained as a
|
|
202
|
+
diagnostic. The measurement method and sampling interval are explicit. GPU measurements and SLURM
|
|
203
|
+
`MaxRSS`, when available, are separate metrics. Missing measurements are `null`; observed zero is `0`.
|
|
204
|
+
Time and memory are evidence, not portable test thresholds.
|
|
205
|
+
|
|
206
|
+
## Cluster execution and GitHub communication
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
$EDITOR slurm/config.sh
|
|
210
|
+
PROFILE=supervised ./slurm/submit.sh --dry-run
|
|
211
|
+
PROFILE=supervised ./slurm/submit.sh
|
|
212
|
+
scripts/github-sync.sh <run-id>
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
SLURM follows the selected algorithm profile and chains stages by successful dependencies. Structured evidence belongs
|
|
216
|
+
under `runs/<run-id>/`; raw logs, datasets, checkpoints, and credentials do not. GitHub synchronization
|
|
217
|
+
pushes a `runs/retain_meds/<run-id>` branch and optionally opens a draft PR. A failed push leaves the
|
|
218
|
+
result committed and recoverable locally.
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# RETAIN
|
|
2
|
+
|
|
3
|
+
RETAIN ([Choi et al., NeurIPS 2016](https://proceedings.neurips.cc/paper/2016/hash/231141b34c82aa95e48810a9d1b33a79-Abstract.html))
|
|
4
|
+
for datasets in the [Medical Event Data Standard](https://github.com/Medical-Event-Data-Standard/meds): a
|
|
5
|
+
reverse-time attention model that predicts a binary outcome from a subject's sequence of visits and
|
|
6
|
+
reports which codes drove each prediction.
|
|
7
|
+
|
|
8
|
+
- **What it runs:** `preprocess_data` (code vocabulary fitted on the training split), `train_supervised`
|
|
9
|
+
(the whole model, for one task) and `predict_supervised` (one probability per requested key).
|
|
10
|
+
- **Model:** a PyTorch reimplementation of the official Theano code
|
|
11
|
+
([`mp2893/retain`](https://github.com/mp2893/retain) @ `9fd39c46`), with the official defaults, checked
|
|
12
|
+
against a NumPy transcription of the official equations.
|
|
13
|
+
- **MEDS adaptation:** a visit is the set of codes in one time bucket (`visit_bucket_minutes`, default one
|
|
14
|
+
day), and each history is cut at its prediction time before visits are formed. No dataset predicates
|
|
15
|
+
are needed.
|
|
16
|
+
- **Status:** [IMPLEMENTATION_REPORT.md](IMPLEMENTATION_REPORT.md) lists what was verified, including the
|
|
17
|
+
temporal-leakage checks, and what was not.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install meds-algorithm-retain
|
|
21
|
+
retain-meds preprocess_data external_meds_dir=$MEDS_DIR output_data_dir=$RUN/data
|
|
22
|
+
retain-meds train_supervised input_data_dir=$RUN/data external_labels_dir=$LABELS_DIR \
|
|
23
|
+
output_supervised_algorithm_dir=$RUN/algorithm
|
|
24
|
+
retain-meds predict_supervised input_data_dir=$RUN/data input_supervised_algorithm_dir=$RUN/algorithm \
|
|
25
|
+
external_index_dir=$LABELS_DIR splits=[held_out] output_predictions_dir=$RUN/predictions
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Settings are the fields of `RETAINConfig` (`src/retain_meds/config.py`); pass a YAML or JSON file of
|
|
29
|
+
overrides to every step with `config_file=<path>`.
|
|
30
|
+
|
|
31
|
+
## Python API and named command
|
|
32
|
+
|
|
33
|
+
The implementation is `src/retain_meds/retain_meds.py`, with configuration in `config.py`.
|
|
34
|
+
Both concrete classes are public package exports:
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
from retain_meds import RETAIN, RETAINConfig
|
|
38
|
+
|
|
39
|
+
algorithm = RETAIN(RETAINConfig())
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Run typed requests through `meds_algorithm.StepRunner.run(...)` so validation, measurements and
|
|
43
|
+
publication apply. Calling an implementation method directly bypasses that execution contract.
|
|
44
|
+
After installation, the algorithm's own `retain-meds` command runs the CLI:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
retain-meds commands --profile supervised
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
RETAIN (Choi et al., NeurIPS 2016) reverse-time attention model for MEDS, a supervised classifier behind the MEDS algorithm contract.
|
|
51
|
+
|
|
52
|
+
This repository declares the **`supervised`** profiles under version 4 of the minimal MEDS algorithm
|
|
53
|
+
contract. The contract standardizes MEDS input, command meanings and arguments, artifact envelopes,
|
|
54
|
+
final predictions, measurements, MEDS-DEV packaging, and operational interfaces. The algorithm owns every
|
|
55
|
+
computational choice and every intermediate payload.
|
|
56
|
+
|
|
57
|
+
## Algorithm profile commands
|
|
58
|
+
|
|
59
|
+
- `supervised`: `preprocess_data → train_supervised → predict_supervised`
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
retain-meds profiles
|
|
63
|
+
retain-meds commands --profile supervised
|
|
64
|
+
retain-meds <step> --profile <profile> key=value ...
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Each profile has `algorithms/<profile>/model.yaml`. Multiple profiles share one Python package and one
|
|
68
|
+
registry; select one explicitly for each run. `STUB_PROFILES` tracks implementation status separately.
|
|
69
|
+
Read [Software contract](SPEC.md) for exact class responsibilities and step inputs.
|
|
70
|
+
|
|
71
|
+
Intermediate artifacts may be tensors, files, databases, external-system references, or any other
|
|
72
|
+
implementation-owned representation. Generic tests inspect only their `manifest.yaml` envelopes. They
|
|
73
|
+
must not assume batches, Lightning, PyTorch, Parquet intermediate data, or iteration order.
|
|
74
|
+
|
|
75
|
+
## Profile runner (prototype)
|
|
76
|
+
|
|
77
|
+
Install `uv sync --extra orchestration --extra test`, then fill the input paths and new output directory
|
|
78
|
+
in `configs/runs/run.yaml`. Algorithm settings belong under `algorithm`; core validates them using
|
|
79
|
+
this repository's concrete Config class.
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
uv run retain-meds run --dry-run
|
|
83
|
+
uv run retain-meds run execution=local
|
|
84
|
+
# Use a NEW output_dir and configure your cluster's resources before submission:
|
|
85
|
+
uv run retain-meds run execution=slurm output_dir=/runs/new-cluster-run
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
A dry run prints all resolved arguments, paths, configuration and resources without writing files or
|
|
89
|
+
submitting jobs. Local execution uses fresh subprocesses; Submitit submits separate dependent SLURM
|
|
90
|
+
jobs. See the [shared runner guide](https://meds-algorithm.readthedocs.io/en/latest/running/#profile-runner-prototype)
|
|
91
|
+
for stage subsets, artifact reuse, resource configuration and prototype limitations. The existing
|
|
92
|
+
per-step CLI and shell launcher remain available for comparison. This prototype does not implement
|
|
93
|
+
Hydra multirun, multi-node training or checkpoint/resume.
|
|
94
|
+
|
|
95
|
+
## Publishing this algorithm
|
|
96
|
+
|
|
97
|
+
Follow [the release guide](RELEASING.md) for package metadata, one-time PyPI Trusted Publisher setup,
|
|
98
|
+
installed-wheel checks, and version-tag publication. All profiles ship in the `meds-algorithm-retain`
|
|
99
|
+
distribution. Tests run in CI; publishing is an explicit workflow dispatch after implementation.
|
|
100
|
+
|
|
101
|
+
## Inputs and predicates
|
|
102
|
+
|
|
103
|
+
- `external_meds_dir` is the standard MEDS dataset boundary.
|
|
104
|
+
- `external_index_dir` supplies only `(subject_id, prediction_time)` to inference and scoring.
|
|
105
|
+
- `external_labels_dir` supplies permitted training targets or explicit in-context examples.
|
|
106
|
+
- `external_evaluation_labels_dir`, when supplied, is used only to attach truth after scores are fixed.
|
|
107
|
+
- `external_predicates_file` supplies dataset-specific predicates when useful. For MIMIC-IV, reuse the
|
|
108
|
+
predicates from MEDS-DEV. This repository decides whether and how to interpret them.
|
|
109
|
+
|
|
110
|
+
A command that consumes predicates records their absolute path and SHA-256 digest in its manifest.
|
|
111
|
+
Predicates do not imply a standard feature representation.
|
|
112
|
+
|
|
113
|
+
## Implementing the algorithm
|
|
114
|
+
|
|
115
|
+
Read [AGENTS.md](AGENTS.md), [SPEC.md](SPEC.md), and
|
|
116
|
+
[docs/IMPLEMENTATION_GUIDE.md](docs/IMPLEMENTATION_GUIDE.md) completely before changing implementation
|
|
117
|
+
files. The implementation source recorded when this repository was generated is:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
https://proceedings.neurips.cc/paper/2016/hash/231141b34c82aa95e48810a9d1b33a79-Abstract.html and https://github.com/mp2893/retain@9fd39c46e44b3fdae3a667a47fbdd5ffbd87bff5
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The algorithm-owned surface is `src/retain_meds/retain_meds.py` (the typed algorithm), `src/retain_meds/config.py`
|
|
124
|
+
(its immutable configuration), `algorithms/<profile>/model.yaml`, and
|
|
125
|
+
`tests/e2e.py`. Implement the selected profile methods, define exact intermediate compatibility checks in
|
|
126
|
+
`validate_inputs`,
|
|
127
|
+
finalize MEDS-DEV command strings, and complete the report. Remove a profile from `STUB_PROFILES` only after it runs end to end. Complete every declared profile.
|
|
128
|
+
|
|
129
|
+
For each generated test and its purpose, read [the test guide](docs/TESTING.md).
|
|
130
|
+
|
|
131
|
+
## Configuration and execution ownership
|
|
132
|
+
|
|
133
|
+
Declare typed fields/defaults in `RETAINConfig`, with `validate()` for constraints. Pass
|
|
134
|
+
`config_file=/path/config.yaml` to a step for a JSON/YAML values mapping; unknown fields fail. Core saves
|
|
135
|
+
the complete resolved config and original typed request as `config.json` and `request.json` in each
|
|
136
|
+
published artifact. These JSON envelopes can be reloaded with the corresponding explicit classes.
|
|
137
|
+
|
|
138
|
+
Algorithm methods receive typed requests, write payloads into `request.output.directory` (staging), and
|
|
139
|
+
return `PayloadMetadata`. `create_repository().run(...)` constructs a fresh algorithm and delegates to
|
|
140
|
+
core's runner. It owns measurements, prediction validation, optional post-score truth attachment,
|
|
141
|
+
metadata and publication. Never publish from inside algorithm methods or write the reserved metadata files.
|
|
142
|
+
Reopen fitted artifacts on each step. Test config/request round trips and execution in a fresh process.
|
|
143
|
+
|
|
144
|
+
## Verification
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
uv run pytest -rs
|
|
148
|
+
uv run pytest -m meds_dev -rs
|
|
149
|
+
uv run pytest -m real_data -rs
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
- The default suite runs the local end-to-end adapter and contract tests.
|
|
153
|
+
- `meds_dev` registers `algorithms/<profile>/model.yaml`, installs this repository from `requirements.txt` in an isolated
|
|
154
|
+
environment, and executes MEDS-DEV's real command slots.
|
|
155
|
+
- `real_data` runs the full selected algorithm profile on the MEDS-DEV MIMIC-IV demo, the pinned
|
|
156
|
+
`mortality/in_icu/first_24h` task, and MEDS-DEV's
|
|
157
|
+
MIMIC predicates. Set `MEDS_DEMO_DIR` to reuse an existing demo and `MEDS_DEV_DIR` to reuse a checkout.
|
|
158
|
+
|
|
159
|
+
Automatic provisioning pins MEDS-DEV PR #330's tested commit, which has the `{predicates_path}`
|
|
160
|
+
passthrough (PR #325). Set `MEDS_DEV_REF` to use another
|
|
161
|
+
revision containing those capabilities. A checkout supplied through `MEDS_DEV_DIR` is checked and fails
|
|
162
|
+
clearly if it cannot populate them.
|
|
163
|
+
|
|
164
|
+
Both integration tiers explicitly `algorithm_stub`-skip until implementation is complete. A completed port
|
|
165
|
+
must have zero `algorithm_stub` skips and must account for every other skip using `-rs` output.
|
|
166
|
+
|
|
167
|
+
These commands are gates, not an unordered checklist. Follow the canonical staged workflow in
|
|
168
|
+
[docs/IMPLEMENTATION_GUIDE.md](docs/IMPLEMENTATION_GUIDE.md): local, MEDS-DEV, pre-demo report and human
|
|
169
|
+
review, MIMIC-IV demo, demo report and human review, authorized full-data run, then final report and GitHub
|
|
170
|
+
synchronization. Full-data cluster jobs run only from a clean, pushed commit and use the reviewed shared
|
|
171
|
+
task bundle for the selected dataset (for example, MIMIC-IV or NWICU in MEDS format), built upstream from
|
|
172
|
+
clinical ACES tasks or randomly sampled code-by-horizon tasks. The provided `real_data` test remains the MIMIC-IV demo regardless of that choice.
|
|
173
|
+
|
|
174
|
+
Final predictions must conform to MEDS evaluation, contain unique `(subject_id, prediction_time)` keys,
|
|
175
|
+
and exactly cover the requested evaluation index. Tests compare the actual key sets; self-reported manifest
|
|
176
|
+
counts are not accepted as evidence. Row order is never an association mechanism.
|
|
177
|
+
|
|
178
|
+
## Measurements
|
|
179
|
+
|
|
180
|
+
Every command manifest records monotonic wall time and sampled live process-tree memory. On Linux, peak
|
|
181
|
+
PSS from `/proc/*/smaps_rollup` is the primary comparison metric; aggregate RSS is retained as a
|
|
182
|
+
diagnostic. The measurement method and sampling interval are explicit. GPU measurements and SLURM
|
|
183
|
+
`MaxRSS`, when available, are separate metrics. Missing measurements are `null`; observed zero is `0`.
|
|
184
|
+
Time and memory are evidence, not portable test thresholds.
|
|
185
|
+
|
|
186
|
+
## Cluster execution and GitHub communication
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
$EDITOR slurm/config.sh
|
|
190
|
+
PROFILE=supervised ./slurm/submit.sh --dry-run
|
|
191
|
+
PROFILE=supervised ./slurm/submit.sh
|
|
192
|
+
scripts/github-sync.sh <run-id>
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
SLURM follows the selected algorithm profile and chains stages by successful dependencies. Structured evidence belongs
|
|
196
|
+
under `runs/<run-id>/`; raw logs, datasets, checkpoints, and credentials do not. GitHub synchronization
|
|
197
|
+
pushes a `runs/retain_meds/<run-id>` branch and optionally opens a draft PR. A failed push leaves the
|
|
198
|
+
result committed and recoverable locally.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Publishing RETAIN
|
|
2
|
+
|
|
3
|
+
One PyPI distribution, `meds-algorithm-retain`, contains all declared profiles. Its Python import is
|
|
4
|
+
`retain_meds` and its executable is `retain-meds`. Publishing the
|
|
5
|
+
algorithm does not require another release of the shared core or template.
|
|
6
|
+
|
|
7
|
+
## Prepare once
|
|
8
|
+
|
|
9
|
+
1. Choose an available PyPI name; edit `[project].name` in `pyproject.toml` if needed. The import and CLI
|
|
10
|
+
names need not match it. Update this guide and the CLI installation hint if changing the name later.
|
|
11
|
+
2. Set `project.urls.Repository`, choose an SPDX `project.license` expression compatible with your
|
|
12
|
+
implementation and upstream sources, and add the actual `LICENSE` file. Review the authors,
|
|
13
|
+
description and README. The template deliberately does not choose a license for you.
|
|
14
|
+
3. Declare every runtime dependency in `pyproject.toml`; release dependencies must be installable
|
|
15
|
+
from the package index, without Git/direct URL requirements. Commit `uv.lock` after `uv lock`.
|
|
16
|
+
4. Complete every declared profile and its scientific tests; remove completed profiles from
|
|
17
|
+
`STUB_PROFILES`. Publication rejects remaining stubs. Passing packaging checks does not establish
|
|
18
|
+
scientific correctness. Extend `tests/wheel_smoke.py` for required algorithm resources/configuration.
|
|
19
|
+
5. Merge `.github/workflows/publish.yml` into `main`. Create GitHub environments `testpypi` and `pypi`;
|
|
20
|
+
configure release reviewers/tag restrictions as appropriate for your repository.
|
|
21
|
+
6. On [PyPI](https://pypi.org/manage/account/publishing/) and separately on
|
|
22
|
+
[TestPyPI](https://test.pypi.org/manage/account/publishing/), register a pending GitHub publisher:
|
|
23
|
+
|
|
24
|
+
| Field | Value |
|
|
25
|
+
|---|---|
|
|
26
|
+
| PyPI project name | `meds-algorithm-retain` |
|
|
27
|
+
| Owner | Your GitHub user or organization |
|
|
28
|
+
| Repository | This algorithm's GitHub repository name |
|
|
29
|
+
| Workflow filename | `publish.yml` |
|
|
30
|
+
| Environment | `pypi` on PyPI; `testpypi` on TestPyPI |
|
|
31
|
+
|
|
32
|
+
For an existing PyPI project, add the publisher in its Publishing settings instead. No API token
|
|
33
|
+
is needed. See the [official setup guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
|
|
34
|
+
|
|
35
|
+
## Check each release
|
|
36
|
+
|
|
37
|
+
Update `[project].version` and `CHANGELOG.md`, then run these commands from the repository root
|
|
38
|
+
(Bash, with Git and uv installed):
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
uv lock
|
|
42
|
+
uv sync --locked --extra test
|
|
43
|
+
uv run --no-sync pytest -rs
|
|
44
|
+
uv run --no-sync python scripts/check_release.py
|
|
45
|
+
bash scripts/check_distribution.sh
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The distribution check builds a wheel from the source archive, validates metadata, installs the base
|
|
49
|
+
wheel in a fresh environment, checks imports/commands/resources from a temporary working directory,
|
|
50
|
+
then installs orchestration and checks a preprocessing dry-run. It runs no training or SLURM jobs.
|
|
51
|
+
It leaves the checked files in `dist/`; move old `dist/` contents elsewhere before repeating it.
|
|
52
|
+
Commit the version, lockfile, changelog and implementation changes; merge passing CI into `main`.
|
|
53
|
+
|
|
54
|
+
## Tag, rehearse, publish
|
|
55
|
+
|
|
56
|
+
Replace `OWNER/REPOSITORY` below. Set `version` to the exact version in `pyproject.toml`:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
repository=OWNER/REPOSITORY
|
|
60
|
+
version=0.1.0
|
|
61
|
+
git switch main
|
|
62
|
+
git pull --ff-only
|
|
63
|
+
git tag -a "v$version" -m "Release $version"
|
|
64
|
+
git push origin "v$version"
|
|
65
|
+
gh workflow run publish.yml --repo "$repository" --ref "v$version" -f index=testpypi
|
|
66
|
+
gh run list --repo "$repository" --workflow publish.yml
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Wait for success and verify installation from TestPyPI. Install dependencies from PyPI first, then
|
|
70
|
+
replace only this package from TestPyPI, avoiding mixed-index dependency resolution:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
uv venv /tmp/algorithm-release-check
|
|
74
|
+
uv pip install --python /tmp/algorithm-release-check/bin/python dist/*.whl
|
|
75
|
+
uv pip install --python /tmp/algorithm-release-check/bin/python --reinstall --no-deps \
|
|
76
|
+
--index-url https://test.pypi.org/simple/ "meds-algorithm-retain==$version"
|
|
77
|
+
/tmp/algorithm-release-check/bin/python -I tests/wheel_smoke.py
|
|
78
|
+
gh workflow run publish.yml --repo "$repository" --ref "v$version" -f index=pypi
|
|
79
|
+
gh run list --repo "$repository" --workflow publish.yml
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The workflow requires the matching version tag on `main` history, a committed lockfile, complete
|
|
83
|
+
profiles, passing tests, and valid installed distributions. A separate job uploads those exact checked
|
|
84
|
+
files using Trusted Publishing. Rehearsal and production runs each build and check their own artifacts
|
|
85
|
+
from the same tag. After success, install `meds-algorithm-retain==$version` in a fresh environment and
|
|
86
|
+
repeat the smoke check. Never move a published tag or reuse a published version; increment it for fixes.
|
|
87
|
+
|
|
88
|
+
## What installation includes
|
|
89
|
+
|
|
90
|
+
`configs/runs/` and `algorithms/` are the single editable source for portable run defaults and MEDS-DEV
|
|
91
|
+
YAMLs. The wheel copies them to `retain_meds/resources/` during its build; the source archive
|
|
92
|
+
includes the originals. No second copy is maintained in Git.
|
|
93
|
+
|
|
94
|
+
The runner uses `./configs/runs` when present, otherwise its installed defaults. `--config-dir` explicitly
|
|
95
|
+
selects user configuration. Supply dataset paths and run settings as overrides or external configuration;
|
|
96
|
+
do not put dataset-specific paths, credentials, labels, datasets or fitted weights in bundled defaults.
|
|
97
|
+
The source archive uses an explicit file allowlist; review its contents before publishing.
|
|
98
|
+
|
|
99
|
+
Access installed profile YAMLs with `importlib.resources.files("retain_meds") / "resources" /
|
|
100
|
+
"algorithms"`. SLURM shell scripts and implementation reports remain checkout tooling. Large pretrained
|
|
101
|
+
weights should be retrieved as separately versioned artifacts, not silently embedded in a wheel.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
## MEDS-DEV descriptor for RETAIN. This retains the established command-slot interface.
|
|
7
|
+
## Each MEDS-DEV run directory {output_dir} holds this run's artifacts as sibling subdirectories (data/,
|
|
8
|
+
## pretrained/, algorithm/, embeddings/ or trajectories/, predictions/): MEDS-DEV keeps its own cmd.sh and .done marker in
|
|
9
|
+
## {output_dir}, and artifacts are published by publishing their own destination directory.
|
|
10
|
+
metadata:
|
|
11
|
+
description: "RETAIN (Choi et al., NeurIPS 2016) reverse-time attention model for MEDS, a supervised classifier behind the MEDS algorithm contract."
|
|
12
|
+
contacts:
|
|
13
|
+
- name: "Florent Pollet"
|
|
14
|
+
email: "flo1.raymond@gmail.com"
|
|
15
|
+
|
|
16
|
+
commands:
|
|
17
|
+
supervised:
|
|
18
|
+
train: |-
|
|
19
|
+
retain-meds preprocess_data --profile supervised external_meds_dir={dataset_dir} output_data_dir={output_dir}/data do_overwrite=true
|
|
20
|
+
retain-meds train_supervised --profile supervised input_data_dir={output_dir}/data external_labels_dir={labels_dir} output_supervised_algorithm_dir={output_dir}/algorithm
|
|
21
|
+
|
|
22
|
+
predict: |-
|
|
23
|
+
retain-meds predict_supervised --profile supervised input_data_dir="$(meds-algorithm-resolve-input {model_initialization_dir}/algorithm input_data_dir)" input_supervised_algorithm_dir={model_initialization_dir}/algorithm external_index_dir={labels_dir} splits=[{split}] output_predictions_dir={output_dir}/predictions do_overwrite=true external_evaluation_labels_dir={labels_dir}
|
|
24
|
+
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Prototype: one config for local subprocesses or dependent Submitit SLURM jobs.
|
|
2
|
+
# Shared field/resource defaults come from meds-algorithm, not a copied schema.
|
|
3
|
+
defaults:
|
|
4
|
+
- meds_run
|
|
5
|
+
- _self_
|
|
6
|
+
|
|
7
|
+
profile: supervised
|
|
8
|
+
execution: local
|
|
9
|
+
output_dir: ??? # New directory for this run; relative paths use the invocation's working directory.
|
|
10
|
+
|
|
11
|
+
inputs:
|
|
12
|
+
meds_dir: null # Required by preprocessing and materialized zero-shot prediction.
|
|
13
|
+
index_dir: null # Required by inference and prediction.
|
|
14
|
+
labels_dir: null # Required by supervised/finetune/probe training.
|
|
15
|
+
|
|
16
|
+
# Add only algorithm settings that differ from the concrete Config class's defaults.
|
|
17
|
+
algorithm: {}
|
|
18
|
+
|
|
19
|
+
# Optional overrides, e.g. resources.compute.gpus_per_node=1 and its partition/account.
|
|
20
|
+
# Both resource presets default to CPUs; choose resources appropriate for this algorithm.
|
|
21
|
+
# resources:
|
|
22
|
+
# compute:
|
|
23
|
+
# gpus_per_node: 1
|
|
24
|
+
# partition: gpu
|
|
25
|
+
# timeout_min: 240
|