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.
Files changed (32) hide show
  1. meds_algorithm_retain-0.1.0/.gitignore +12 -0
  2. meds_algorithm_retain-0.1.0/CHANGELOG.md +11 -0
  3. meds_algorithm_retain-0.1.0/LICENSE +21 -0
  4. meds_algorithm_retain-0.1.0/PKG-INFO +218 -0
  5. meds_algorithm_retain-0.1.0/README.md +198 -0
  6. meds_algorithm_retain-0.1.0/RELEASING.md +101 -0
  7. meds_algorithm_retain-0.1.0/algorithms/supervised/model.yaml +24 -0
  8. meds_algorithm_retain-0.1.0/configs/runs/run.yaml +25 -0
  9. meds_algorithm_retain-0.1.0/docs/IMPLEMENTATION_GUIDE.md +219 -0
  10. meds_algorithm_retain-0.1.0/docs/TESTING.md +82 -0
  11. meds_algorithm_retain-0.1.0/pyproject.toml +56 -0
  12. meds_algorithm_retain-0.1.0/scripts/check_distribution.sh +20 -0
  13. meds_algorithm_retain-0.1.0/scripts/check_release.py +32 -0
  14. meds_algorithm_retain-0.1.0/scripts/github-sync.sh +29 -0
  15. meds_algorithm_retain-0.1.0/src/retain_meds/__init__.py +6 -0
  16. meds_algorithm_retain-0.1.0/src/retain_meds/__main__.py +65 -0
  17. meds_algorithm_retain-0.1.0/src/retain_meds/_interpret.py +102 -0
  18. meds_algorithm_retain-0.1.0/src/retain_meds/_model.py +171 -0
  19. meds_algorithm_retain-0.1.0/src/retain_meds/_preprocess.py +270 -0
  20. meds_algorithm_retain-0.1.0/src/retain_meds/_training.py +320 -0
  21. meds_algorithm_retain-0.1.0/src/retain_meds/_windows.py +221 -0
  22. meds_algorithm_retain-0.1.0/src/retain_meds/config.py +114 -0
  23. meds_algorithm_retain-0.1.0/src/retain_meds/retain_meds.py +252 -0
  24. meds_algorithm_retain-0.1.0/tests/__init__.py +1 -0
  25. meds_algorithm_retain-0.1.0/tests/conftest.py +31 -0
  26. meds_algorithm_retain-0.1.0/tests/e2e.py +140 -0
  27. meds_algorithm_retain-0.1.0/tests/test_conformance.py +7 -0
  28. meds_algorithm_retain-0.1.0/tests/test_data_path.py +477 -0
  29. meds_algorithm_retain-0.1.0/tests/test_model_fidelity.py +255 -0
  30. meds_algorithm_retain-0.1.0/tests/test_primary_behavior.py +183 -0
  31. meds_algorithm_retain-0.1.0/tests/wheel_smoke.py +55 -0
  32. meds_algorithm_retain-0.1.0/uv.lock +1279 -0
@@ -0,0 +1,12 @@
1
+ __pycache__/
2
+ .pytest_cache/
3
+ .venv/
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ runs/**/logs/
8
+ runs/**/artifacts/
9
+ runs/**/checkpoints/
10
+
11
+ # Arguments and scheduler outputs are local run products.
12
+ runs/**/command-args/
@@ -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