meds-algorithm-template 0.4.0a1__py3-none-any.whl
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_template/__init__.py +1 -0
- meds_algorithm_template/cli.py +39 -0
- meds_algorithm_template-0.4.0a1.dist-info/METADATA +351 -0
- meds_algorithm_template-0.4.0a1.dist-info/RECORD +7 -0
- meds_algorithm_template-0.4.0a1.dist-info/WHEEL +4 -0
- meds_algorithm_template-0.4.0a1.dist-info/entry_points.txt +2 -0
- meds_algorithm_template-0.4.0a1.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Generate MEDS algorithm repositories from the matching canonical template release."""
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Small version-bound frontend to Copier's public API."""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
from importlib.metadata import version
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
import yaml
|
|
8
|
+
from copier import run_copy
|
|
9
|
+
|
|
10
|
+
TEMPLATE_REPOSITORY = "https://github.com/McDermottHealthAI/MEDS_algorithm_template.git"
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def main(argv: list[str] | None = None) -> None:
|
|
14
|
+
release = version("meds-algorithm-template")
|
|
15
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
16
|
+
parser.add_argument("--version", action="version", version=release)
|
|
17
|
+
parser.add_argument("destination", type=Path, help="Directory for the generated repository")
|
|
18
|
+
parser.add_argument(
|
|
19
|
+
"--defaults", action="store_true", help="Use defaults instead of interactive questions"
|
|
20
|
+
)
|
|
21
|
+
parser.add_argument("--data-file", type=Path, help="YAML mapping of Copier answers")
|
|
22
|
+
parser.add_argument("--trust", action="store_true", help="Trust the reviewed template's Copier features")
|
|
23
|
+
args = parser.parse_args(argv)
|
|
24
|
+
answers = None
|
|
25
|
+
if args.data_file is not None:
|
|
26
|
+
try:
|
|
27
|
+
answers = yaml.safe_load(args.data_file.read_text(encoding="utf-8"))
|
|
28
|
+
except (OSError, yaml.YAMLError) as error:
|
|
29
|
+
parser.error(f"Cannot read answers: {error}")
|
|
30
|
+
if not isinstance(answers, dict) or any(not isinstance(key, str) for key in answers):
|
|
31
|
+
parser.error("The answers file must contain a mapping with string keys")
|
|
32
|
+
run_copy(
|
|
33
|
+
TEMPLATE_REPOSITORY,
|
|
34
|
+
args.destination,
|
|
35
|
+
vcs_ref=f"v{release}",
|
|
36
|
+
data=answers,
|
|
37
|
+
defaults=args.defaults,
|
|
38
|
+
unsafe=args.trust,
|
|
39
|
+
)
|
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: meds-algorithm-template
|
|
3
|
+
Version: 0.4.0a1
|
|
4
|
+
Summary: A minimal, contract-first Copier template for MEDS algorithm repositories.
|
|
5
|
+
Project-URL: Repository, https://github.com/McDermottHealthAI/MEDS_algorithm_template
|
|
6
|
+
Project-URL: Documentation, https://McDermottHealthAI.github.io/MEDS_algorithm_template/
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Python: >=3.11
|
|
10
|
+
Requires-Dist: copier<10,>=9.17.1
|
|
11
|
+
Requires-Dist: pyyaml>=6
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
|
|
14
|
+
# Minimal MEDS algorithm template
|
|
15
|
+
|
|
16
|
+
[](https://www.python.org/downloads/)
|
|
17
|
+
[](https://pypi.org/project/meds-algorithm-template/)
|
|
18
|
+
[](https://github.com/McDermottHealthAI/MEDS_algorithm_template/actions/workflows/ci.yml)
|
|
19
|
+
[](https://McDermottHealthAI.github.io/MEDS_algorithm_template/)
|
|
20
|
+
[](https://github.com/McDermottHealthAI/MEDS_algorithm_template/graphs/contributors)
|
|
21
|
+
[](https://github.com/McDermottHealthAI/MEDS_algorithm_template/pulls)
|
|
22
|
+
[](https://github.com/McDermottHealthAI/MEDS_algorithm_template/blob/main/LICENSE)
|
|
23
|
+
|
|
24
|
+
This repository is a self-contained [Copier](https://copier.readthedocs.io) template for minimal,
|
|
25
|
+
contract-first MEDS algorithm repositories.
|
|
26
|
+
|
|
27
|
+
Shared contracts and the canonical specification live in
|
|
28
|
+
[`meds-algorithm`](https://github.com/McDermottHealthAI/meds-algorithm). This template and generated projects pin
|
|
29
|
+
`meds-algorithm==0.4.0a4` from PyPI.
|
|
30
|
+
The core owns the reusable infrastructure and conformance helpers; generated repositories import it directly.
|
|
31
|
+
|
|
32
|
+
The template fixes the external contract—MEDS input, six algorithm profiles and standard arguments, typed
|
|
33
|
+
artifact manifests, final MEDS predictions, measurements, MEDS-DEV, SLURM, and GitHub result exchange—while
|
|
34
|
+
leaving preprocessing, featurization, intermediate formats, frameworks, batching, and algorithm execution to
|
|
35
|
+
the generated repository.
|
|
36
|
+
|
|
37
|
+
## Documentation
|
|
38
|
+
|
|
39
|
+
For setup and every command in execution order, see the [fully manual example](https://github.com/McDermottHealthAI/MEDS_algorithm_template/blob/main/docs/manual-example.md).
|
|
40
|
+
It includes a complete tutorial implementation and synthetic data, so it runs without an agent or cluster.
|
|
41
|
+
|
|
42
|
+
This README is written for coding agents that port algorithms. For a human-oriented explanation of the
|
|
43
|
+
contract (concepts, choosing a profile, zero-shot algorithms, the gate workflow, running, and reference), read
|
|
44
|
+
the documentation site: https://McDermottHealthAI.github.io/MEDS_algorithm_template/ (built from `docs/` by
|
|
45
|
+
`.github/workflows/docs.yml`). Preview it locally with:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
uv run --group docs mkdocs serve
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Render a repository
|
|
52
|
+
|
|
53
|
+
The installable `meds-algorithm-template` command uses the matching `v<package-version>` tag from this
|
|
54
|
+
GitHub repository. It needs Git and network access; it does not bundle a second copy of the template.
|
|
55
|
+
Install and run the generator with:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
uvx --from 'meds-algorithm-template==0.4.0a1' meds-algorithm-template ../my-meds-algorithm --trust
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Use `--defaults --data-file answers.yaml` for unattended generation. The answers file records the
|
|
62
|
+
canonical GitHub source and release tag, so subsequent `copier update --trust` uses the same source.
|
|
63
|
+
The package itself uses Copier and PyYAML; generated projects depend on `meds-algorithm`.
|
|
64
|
+
See [publishing both packages in order](https://github.com/McDermottHealthAI/MEDS_algorithm_template/blob/main/RELEASING.md) for the release process and dependency updates.
|
|
65
|
+
|
|
66
|
+
From the root of this checkout:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
uv tool install copier
|
|
70
|
+
copier copy . ../my-meds-algorithm
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The rendered repository commits `.copier-answers.yml`, which records its template source, revision, and
|
|
74
|
+
answers. To bring later template changes into that repository, review its working tree and run:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
cd ../my-meds-algorithm
|
|
78
|
+
copier update --trust
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
For portable updates across machines, copy from the Git repository URL rather than from a local checkout;
|
|
82
|
+
Copier records that source in the answers file.
|
|
83
|
+
|
|
84
|
+
For a reproducible non-interactive render, first create `profiles.yml` containing
|
|
85
|
+
`profiles: [probe]` (or several profile names), then run:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
copier copy --defaults --trust \
|
|
89
|
+
--data algorithm_name="My MEDS Algorithm" \
|
|
90
|
+
--data algorithm_slug=my_meds_algorithm \
|
|
91
|
+
--data-file profiles.yml \
|
|
92
|
+
--data uses_predicates=true \
|
|
93
|
+
--data implementation_source=https://github.com/example/source-model \
|
|
94
|
+
. ../my-meds-algorithm
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`--trust` is safe but currently unnecessary because the template defines no post-copy tasks. It is included
|
|
98
|
+
so the command remains usable if formatting/bootstrap tasks are added later.
|
|
99
|
+
|
|
100
|
+
### Copier questions
|
|
101
|
+
|
|
102
|
+
| Question | Meaning |
|
|
103
|
+
|---|---|
|
|
104
|
+
| `algorithm_name` | Human-readable algorithm name. |
|
|
105
|
+
| `algorithm_slug` | Importable Python package and MEDS-DEV algorithm identifier. |
|
|
106
|
+
| `algorithm_class` | Public class name; defaults to CamelCase from the slug. Set `RETAIN` explicitly to preserve that spelling. |
|
|
107
|
+
| `profiles` | Nonempty list of supported profiles; each gets its own MEDS-DEV YAML. |
|
|
108
|
+
| `algorithm_description` | Short description rendered into README and `algorithms/<profile>/model.yaml`. |
|
|
109
|
+
| `author_name`, `author_email` | MEDS-DEV contact metadata. |
|
|
110
|
+
| `uses_predicates` | Whether generated MEDS-DEV commands pass `external_predicates_file`. The algorithm still owns interpretation. |
|
|
111
|
+
| `implementation_source` | Paper path/URL, source repository path/URL, or both; prefilled into generated guidance and the report. |
|
|
112
|
+
|
|
113
|
+
For example, `algorithm_slug=retain algorithm_class=RETAIN` generates `retain/retain.py` containing
|
|
114
|
+
`RETAIN`, plus `retain/config.py` containing `RETAINConfig`. Import them with
|
|
115
|
+
`from retain import RETAIN, RETAINConfig` (or `from retain.retain import RETAIN`). The installed
|
|
116
|
+
`retain` and `meds-algorithm` commands share the same dispatcher. Use the core runner for Python
|
|
117
|
+
execution so direct imports retain the same validation/publication path as the CLI.
|
|
118
|
+
|
|
119
|
+
Profiles are `supervised`, `finetune`, `probe`, `zero_shot_direct`, `zero_shot_materialized`, and
|
|
120
|
+
`predict_only`. A algorithm profile selects required commands, not an architecture or execution backend.
|
|
121
|
+
|
|
122
|
+
The two zero-shot profiles also receive the task itself: an ACES criteria file passed as
|
|
123
|
+
`external_task_criteria_file` (`{task_criteria_path}` in `algorithms/<profile>/model.yaml`). They must publish a
|
|
124
|
+
`relaxations.yaml` ledger stating how the answered task differs from the requested one. They differ in how
|
|
125
|
+
the algorithm answers. `zero_shot_direct` algorithms answer task-derived queries directly (MOTOR, EveryQuery),
|
|
126
|
+
recommended as an `aces-to-<algorithm>` adapter on aces-relaxations. `zero_shot_materialized` algorithms generate
|
|
127
|
+
futures in a task-independent `infer_trajectories`, and `predict_zero_shot_materialized` evaluates the task on them. See [Zero-shot in practice](https://github.com/McDermottHealthAI/MEDS_algorithm_template/blob/main/docs/zero-shot.md) for the design, algorithm examples, and the MEDS-DEV
|
|
128
|
+
passthrough this needs.
|
|
129
|
+
|
|
130
|
+
## Work in the generated repository
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
cd ../my-meds-algorithm
|
|
134
|
+
uv sync --extra test
|
|
135
|
+
uv run meds-algorithm commands
|
|
136
|
+
uv run pytest -rs
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
The generated commands are intentional stubs. Before implementation, the local, MEDS-DEV, and MIMIC
|
|
140
|
+
end-to-end tests report explicit `algorithm_stub` skips. Start with these rendered files:
|
|
141
|
+
|
|
142
|
+
1. `AGENTS.md`
|
|
143
|
+
2. `SPEC.md`
|
|
144
|
+
3. `README.md`
|
|
145
|
+
4. `docs/IMPLEMENTATION_GUIDE.md`
|
|
146
|
+
5. `src/<algorithm_slug>/<algorithm_slug>.py` and `src/<algorithm_slug>/config.py`
|
|
147
|
+
6. `tests/e2e.py`
|
|
148
|
+
7. `IMPLEMENTATION_REPORT.md`
|
|
149
|
+
|
|
150
|
+
A completed implementation removes each profile from `STUB_PROFILES` only after that profile works.
|
|
151
|
+
|
|
152
|
+
<!-- --8<-- [start:implementation-prompt] -->
|
|
153
|
+
## Copyable algorithm-implementation prompt
|
|
154
|
+
|
|
155
|
+
Use this after rendering a repository. Replace all placeholders before sending it to a coding agent.
|
|
156
|
+
The full-data evaluation may target any suitable MEDS dataset (for example, MIMIC-IV or NWICU); the
|
|
157
|
+
provided `real_data` test remains the MIMIC-IV demo smoke test.
|
|
158
|
+
|
|
159
|
+
The prompt adapts [Ponytail's implementation principles](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md)
|
|
160
|
+
to scientific algorithm development. It works with Claude and other coding agents without installing a plugin.
|
|
161
|
+
|
|
162
|
+
```text
|
|
163
|
+
Based on the following source:
|
|
164
|
+
|
|
165
|
+
<PAPER_PATH_OR_URL_AND_OR_REPOSITORY_PATH_OR_URL>
|
|
166
|
+
|
|
167
|
+
implement the algorithm in the generated MEDS algorithm repository at:
|
|
168
|
+
|
|
169
|
+
<GENERATED_REPOSITORY_PATH>
|
|
170
|
+
|
|
171
|
+
For the full-data run, target this dataset in MEDS format (name, revision, and location):
|
|
172
|
+
|
|
173
|
+
<TARGET_DATASET_NAME_REVISION_AND_MEDS_PATH>
|
|
174
|
+
|
|
175
|
+
Use this dataset-specific shared task bundle if already available:
|
|
176
|
+
|
|
177
|
+
<FULL_DATA_WORK_DIR_OR_NOT_YET_AVAILABLE>
|
|
178
|
+
|
|
179
|
+
Read AGENTS.md, SPEC.md, README.md, and docs/IMPLEMENTATION_GUIDE.md in the generated repository
|
|
180
|
+
completely before writing code. Inspect the paper, supplementary material, source repository,
|
|
181
|
+
configuration files, checkpoints, preprocessing code, and evaluation code available from the supplied
|
|
182
|
+
source.
|
|
183
|
+
|
|
184
|
+
Apply the Ponytail principle of the smallest complete change: implement the complete source-defined
|
|
185
|
+
algorithm with the least additional infrastructure. Check meds-algorithm, existing algorithm-family code,
|
|
186
|
+
standard libraries and installed dependencies before creating helpers. Keep shared fixes in their
|
|
187
|
+
owning package; do not copy core utilities into the algorithm repository. Avoid speculative wrappers,
|
|
188
|
+
configuration options and compatibility layers. Trace affected commands, callers, fixtures and
|
|
189
|
+
documentation, and finish all required changes. Simplicity must preserve scientific fidelity, temporal
|
|
190
|
+
and label isolation, artifact validation, reproducibility, required evaluation evidence and human
|
|
191
|
+
review gates. Write focused tests for new behavior and failure cases. Report deviations and checks
|
|
192
|
+
that were not run.
|
|
193
|
+
|
|
194
|
+
Write minimalist, auditable, object-oriented algorithm code. Put source-defined hyperparameters and defaults
|
|
195
|
+
in the algorithm-owned frozen <AlgorithmClass>Config class in config.py; validate values and prove
|
|
196
|
+
serialization round trips. Keep the implementation in <algorithm_slug>.py and expose the named algorithm
|
|
197
|
+
and configuration classes from the package, so callers can import them meaningfully.
|
|
198
|
+
For neural algorithms with matching semantics, extend core NNConfig rather than
|
|
199
|
+
duplicating shared capacity, learning_rate, batch_size, weight_decay and dropout settings. Define
|
|
200
|
+
source-backed defaults and the capacity-multiplier mapping (reference architecture, dimensions, rounding
|
|
201
|
+
and minimums); call super().validate() for inherited
|
|
202
|
+
constraints. Test that the settings actually control construction/training. See the installed architecture
|
|
203
|
+
guide for units, extension examples and scaling ownership. Keep cohort selection upstream; record actual
|
|
204
|
+
parameter counts and consumed data separately rather than inferring them from capacity or a data fraction.
|
|
205
|
+
Use inherited additional_predicates_file for dataset-specific feature additions when needed. Read the
|
|
206
|
+
runner-resolved request.predicates_file in preprocessing; do not override base definitions, merge again,
|
|
207
|
+
or change task predicates. Preserve temporal isolation and use the same configuration across steps.
|
|
208
|
+
Implement the selected Algorithm profile methods with their typed request classes. Prefer small cohesive
|
|
209
|
+
components and explicit constructor dependencies; use inheritance for the profile contract and composition
|
|
210
|
+
for algorithm internals. Do not add unnecessary classes, wrappers, mutable module-level runtime state, hidden
|
|
211
|
+
singletons, import-time work, broad exception swallowing, or duplicated contract tables. Declarative
|
|
212
|
+
constants and the profile-to-implementation association are appropriate; fitted state belongs in artifacts.
|
|
213
|
+
Use core's runner for both CLI execution and tests. Algorithm methods write only to its staging destination
|
|
214
|
+
and return PayloadMetadata; do not reimplement publication, measurements or manifest/config/request writing.
|
|
215
|
+
Implement explicit payload compatibility checks. Prediction outputs contain keys and probabilities;
|
|
216
|
+
only the runner attaches evaluation truth after scoring. Demonstrate that saved configuration and requests
|
|
217
|
+
can be reloaded in a fresh process and executed without an earlier call on the same algorithm instance.
|
|
218
|
+
|
|
219
|
+
Preserve the selected algorithm profile and standardized command arguments, MEDS input boundary, artifact
|
|
220
|
+
manifest envelopes, MEDS-DEV model.yaml interface, and final MEDS prediction output. Intermediate payload
|
|
221
|
+
formats and execution mechanisms are algorithm-owned: choose whatever preprocessing, featurization, framework,
|
|
222
|
+
batching or non-batching strategy, external executable, storage format, and algorithm architecture most
|
|
223
|
+
faithfully reproduce the source.
|
|
224
|
+
|
|
225
|
+
When predicates are needed, reuse MEDS-DEV predicates for the selected dataset if available; otherwise,
|
|
226
|
+
use reviewed external predicates for that dataset and record their provenance. Decide within the algorithm
|
|
227
|
+
how those predicates become inputs. Validate dataset-specific codes, units, task definitions, and label mappings;
|
|
228
|
+
do not assume MIMIC mappings apply to another dataset. Keep such mappings in dataset-specific
|
|
229
|
+
configuration or algorithm-owned code. Do not introduce a generic predicate-derived feature representation
|
|
230
|
+
into the contract package. Keep the provided MIMIC-IV demo code, task, and MEDS-DEV predicates as the
|
|
231
|
+
canonical smoke test, regardless of the full-data target.
|
|
232
|
+
|
|
233
|
+
For a zero_shot_direct algorithm (answers queries directly, e.g. MOTOR, EveryQuery) or a zero_shot_materialized
|
|
234
|
+
algorithm (generates futures and evaluates the task on them; infer is task-independent and only predict
|
|
235
|
+
receives the task): the algorithm receives the original ACES task through
|
|
236
|
+
external_task_criteria_file (with the dataset predicates) and the upstream-built index through
|
|
237
|
+
external_index_dir. Never build, filter, or extend the cohort, and read the index only through
|
|
238
|
+
meds_algorithm.read_index. Reuse an existing aces-to-<algorithm> adapter for this algorithm if one exists;
|
|
239
|
+
otherwise write one on aces-relaxations, pinned to an exact version: reject tasks that are not future-only
|
|
240
|
+
or are degenerate, normalize, then apply only the approximations and assumptions the algorithm's query
|
|
241
|
+
language forces. Publish relaxations.yaml with every step, and report per task whether the answer is exact.
|
|
242
|
+
A materialized algorithm evaluates the task on generated futures instead and needs no relaxation beyond
|
|
243
|
+
sampling. Follow the shape for the selected profile in docs/IMPLEMENTATION_GUIDE.md.
|
|
244
|
+
Do not omit source behavior because it is inconvenient for a fixture; adapt the implementation or fixture
|
|
245
|
+
instead.
|
|
246
|
+
|
|
247
|
+
Record every material source element as ported, adapted, or omitted, with evidence and justification, in
|
|
248
|
+
IMPLEMENTATION_REPORT.md. Implement every selected typed algorithm method, finalize the implementation-specific
|
|
249
|
+
command strings in model.yaml, and implement tests/e2e.py. Keep STUB_PROFILES = set(PROFILES) until the actual selected
|
|
250
|
+
algorithm profile completes and produces standards-conformant predictions.
|
|
251
|
+
|
|
252
|
+
Then run:
|
|
253
|
+
|
|
254
|
+
uv run pytest -rs
|
|
255
|
+
uv run pytest -m meds_dev -rs
|
|
256
|
+
|
|
257
|
+
Complete the pre-demo sections of IMPLEMENTATION_REPORT.md and ask for human review of source fidelity,
|
|
258
|
+
predicate interpretation, and the proposed MIMIC-IV demo execution. Only after approval, run:
|
|
259
|
+
|
|
260
|
+
uv run pytest -m real_data -rs
|
|
261
|
+
|
|
262
|
+
There must be zero algorithm_stub skips. Report exact pass/skip counts and account for every remaining skip.
|
|
263
|
+
Update IMPLEMENTATION_REPORT.md with the demo cohort, final-output coverage, predicate provenance,
|
|
264
|
+
environment, wall time, peak process-tree PSS/RSS, GPU measurements when available, failures, and fixes.
|
|
265
|
+
Ask for a second human review before launching the selected full dataset through the repository's SLURM
|
|
266
|
+
interface. Review target-dataset compatibility, access, and resources separately from the MIMIC-IV demo.
|
|
267
|
+
Use a shared, reviewed task bundle for the target dataset, built once upstream: clinical tasks defined in
|
|
268
|
+
ACES and extracted with the ACES package, or randomly sampled code-by-horizon tasks (generated with
|
|
269
|
+
https://github.com/florian6973/meds-random-task-sampler and selected with https://github.com/florian6973/meds-task-selection).
|
|
270
|
+
It must contain each task's definition and its generated index/labels; zero-shot algorithms also need each
|
|
271
|
+
task's ACES criteria. If a compatible bundle is not yet available, report that blocker before the
|
|
272
|
+
full-data run. Record the dataset name/revision, predicate provenance, bundle location, the commit of the
|
|
273
|
+
tool that built it, and a digest of its task definitions. Keep the bundle external to Git. Commit and push the implementation,
|
|
274
|
+
configuration, and report-so-far; run the cluster job from that exact clean commit. After the authorized
|
|
275
|
+
run, complete the report with full-data evidence, scientific deviations, and known limitations, then
|
|
276
|
+
synchronize structured results through the GitHub workflow. Treat
|
|
277
|
+
docs/IMPLEMENTATION_GUIDE.md as the authority for the ordered gates and their evidence.
|
|
278
|
+
```
|
|
279
|
+
<!-- --8<-- [end:implementation-prompt] -->
|
|
280
|
+
|
|
281
|
+
## Test tiers in a generated repository
|
|
282
|
+
|
|
283
|
+
```bash
|
|
284
|
+
uv run pytest -rs
|
|
285
|
+
uv run pytest -m meds_dev -rs
|
|
286
|
+
uv run pytest -m real_data -rs
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
- The default suite checks the contract and algorithm-owned local end-to-end adapter.
|
|
290
|
+
- `meds_dev` registers `algorithms/<profile>/model.yaml` and runs it in MEDS-DEV's isolated environment.
|
|
291
|
+
- `real_data` builds or reuses the MEDS MIMIC-IV demo, extracts MEDS-DEV task
|
|
292
|
+
`mortality/in_icu/first_24h`, reuses MEDS-DEV's MIMIC predicates, and runs the full selected algorithm profile.
|
|
293
|
+
|
|
294
|
+
The implementation guide defines what follows these commands: a report/review gate after the demo, then
|
|
295
|
+
an explicitly authorized run on the selected full dataset and final report. The demo's required task is
|
|
296
|
+
ICU mortality; additional MEDS-DEV MIMIC-supported tasks are optional coverage checks, not a mandatory
|
|
297
|
+
task benchmark.
|
|
298
|
+
The full-data evaluation instead uses a separately reviewed, shared task bundle for the target dataset
|
|
299
|
+
(clinical ACES tasks or randomly sampled code-by-horizon tasks), so algorithm comparisons on that dataset use
|
|
300
|
+
the same task definitions and labels. Selecting another full dataset does not change the provided MIMIC-IV demo code.
|
|
301
|
+
|
|
302
|
+
Set `MEDS_DEV_DIR=/path/to/MEDS-DEV` to reuse a checkout and `MEDS_DEMO_DIR=/path/to/demo` to reuse the
|
|
303
|
+
dataset. A bare test run never clones MEDS-DEV or downloads MIMIC data.
|
|
304
|
+
|
|
305
|
+
Until MEDS-DEV PR #330 is merged, automatic integration provisioning pins its head commit
|
|
306
|
+
`19a8aa3417fae3586b2e8f0f17aba19ddb0560d4`. That commit is on top of `dev`, so it supplies both the
|
|
307
|
+
`predicates_path` passthrough (PR #325) and the `task_criteria_path` passthrough that zero-shot profiles
|
|
308
|
+
use. Set `MEDS_DEV_REF` to select another revision containing those capabilities. Reused `MEDS_DEV_DIR`
|
|
309
|
+
checkouts are capability-checked rather than silently using a algorithm-side fallback. Only zero-shot
|
|
310
|
+
repositories require `task_criteria_path`.
|
|
311
|
+
|
|
312
|
+
## Cluster and result interfaces
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
$EDITOR slurm/config.sh
|
|
316
|
+
./slurm/submit.sh --dry-run
|
|
317
|
+
./slurm/submit.sh
|
|
318
|
+
scripts/github-sync.sh <run-id>
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Each command manifest records wall time and sampled process-tree PSS/RSS. Structured run evidence is kept
|
|
322
|
+
under `runs/<run-id>/`. GitHub synchronization publishes a run branch; it does not commit datasets,
|
|
323
|
+
checkpoints, credentials, or raw logs.
|
|
324
|
+
|
|
325
|
+
## Develop the Copier template
|
|
326
|
+
|
|
327
|
+
From the parent repository root:
|
|
328
|
+
|
|
329
|
+
```bash
|
|
330
|
+
uv sync --group dev
|
|
331
|
+
uv run pytest tests/test_render.py -q
|
|
332
|
+
uv run pytest tests/ -q
|
|
333
|
+
uv run ruff check tests/test_render.py
|
|
334
|
+
uv run ruff format --check tests/test_render.py
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
`tests/test_render.py` renders all six algorithm profiles, compiles the generated repositories, validates command
|
|
338
|
+
registries and operational files, tests measurement manifests and run results, and exercises MEDS-DEV
|
|
339
|
+
registration. To test the rendered repository itself, render it into a temporary directory and run:
|
|
340
|
+
|
|
341
|
+
```bash
|
|
342
|
+
uv run --project /tmp/my-render --extra test pytest /tmp/my-render/tests -q -rs
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
The authority is [`template/SPEC.md`](template/SPEC.md), which Copier renders as `SPEC.md` in generated
|
|
346
|
+
repositories. Files under `template/` are the generated payload; root tests
|
|
347
|
+
validate that payload without imposing a algorithm implementation.
|
|
348
|
+
|
|
349
|
+
Profile selection and the distinct version 4 step names are described in [profiles](https://github.com/McDermottHealthAI/MEDS_algorithm_template/blob/main/docs/profiles.md).
|
|
350
|
+
See the [software contract](https://github.com/McDermottHealthAI/meds-algorithm/blob/v0.4.0a4/src/meds_algorithm/CONTRACT.md), [migration guide](https://github.com/McDermottHealthAI/MEDS_algorithm_template/blob/main/docs/migration-v4.md),
|
|
351
|
+
and [shared-package assessment](https://github.com/McDermottHealthAI/MEDS_algorithm_template/blob/main/docs/shared-package-assessment.md).
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
meds_algorithm_template/__init__.py,sha256=Two0EmxT5dWWsmyyudQB_IUPxjXRkt-kPZ-lWfCYB60,89
|
|
2
|
+
meds_algorithm_template/cli.py,sha256=L36iRC4C1b3-H3ebChsGKi118zpp4IdCfMyJljC1QuQ,1582
|
|
3
|
+
meds_algorithm_template-0.4.0a1.dist-info/METADATA,sha256=vW8UVQw8dFTBy6sanD4c6LPLmyKAcfJn9Y5CqYMVxOA,21286
|
|
4
|
+
meds_algorithm_template-0.4.0a1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
5
|
+
meds_algorithm_template-0.4.0a1.dist-info/entry_points.txt,sha256=J8Ut4h_AMQpIzftTpxkuW1rNjYEyVGJR1FmH4YbK_64,77
|
|
6
|
+
meds_algorithm_template-0.4.0a1.dist-info/licenses/LICENSE,sha256=k0wqQurs6KfFG-mjx2fUCVlEqpUSNyiyO2sGtU8U-Ac,1119
|
|
7
|
+
meds_algorithm_template-0.4.0a1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Matthew McDermott and the MEDS_algorithm_template contributors
|
|
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.
|