kalecardiac 0.1.0a2__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.
- kalecardiac-0.1.0a2/AGENTS.md +173 -0
- kalecardiac-0.1.0a2/API_overview.md +355 -0
- kalecardiac-0.1.0a2/LICENSE +21 -0
- kalecardiac-0.1.0a2/MANIFEST.in +18 -0
- kalecardiac-0.1.0a2/PKG-INFO +244 -0
- kalecardiac-0.1.0a2/README.md +193 -0
- kalecardiac-0.1.0a2/docs/architecture.md +173 -0
- kalecardiac-0.1.0a2/docs/conf.py +50 -0
- kalecardiac-0.1.0a2/docs/images/kalecardiac_logo_long.png +0 -0
- kalecardiac-0.1.0a2/docs/index.rst +45 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.auto.rst +19 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.evaluate.rst +33 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.interpret.rst +19 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.loaddata.rst +33 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.model.embed.rst +40 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.model.layers.rst +47 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.model.predict.rst +19 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.model.rst +5 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.pipeline.rst +19 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.prepdata.rst +26 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.rst +12 -0
- kalecardiac-0.1.0a2/docs/kalecardiac.utils.rst +26 -0
- kalecardiac-0.1.0a2/docs/models.md +258 -0
- kalecardiac-0.1.0a2/docs/multimodal_fusion.md +135 -0
- kalecardiac-0.1.0a2/docs/quickstart.md +204 -0
- kalecardiac-0.1.0a2/docs/requirements.txt +3 -0
- kalecardiac-0.1.0a2/examples/README.md +79 -0
- kalecardiac-0.1.0a2/examples/__init__.py +1 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/README.md +112 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/__init__.py +1 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/config.py +125 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/configs/full.yaml +67 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/configs/quick.yaml +55 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/data.py +266 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/main.py +58 -0
- kalecardiac-0.1.0a2/examples/cardiovae_multimodal/runner.py +136 -0
- kalecardiac-0.1.0a2/examples/cli.py +59 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/README.md +136 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/__init__.py +1 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/config.py +130 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/configs/full.yaml +68 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/configs/quick.yaml +53 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/data.py +307 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/main.py +65 -0
- kalecardiac-0.1.0a2/examples/lsemvae_ecg/runner.py +279 -0
- kalecardiac-0.1.0a2/examples/synthetic_data.py +543 -0
- kalecardiac-0.1.0a2/kalecardiac/__init__.py +40 -0
- kalecardiac-0.1.0a2/kalecardiac/_version.txt +1 -0
- kalecardiac-0.1.0a2/kalecardiac/auto/__init__.py +67 -0
- kalecardiac-0.1.0a2/kalecardiac/auto/endpoint.py +277 -0
- kalecardiac-0.1.0a2/kalecardiac/auto/workflow.py +501 -0
- kalecardiac-0.1.0a2/kalecardiac/config.py +277 -0
- kalecardiac-0.1.0a2/kalecardiac/evaluate/__init__.py +61 -0
- kalecardiac-0.1.0a2/kalecardiac/evaluate/classification_metrics.py +170 -0
- kalecardiac-0.1.0a2/kalecardiac/evaluate/cross_validation.py +157 -0
- kalecardiac-0.1.0a2/kalecardiac/evaluate/predictions.py +151 -0
- kalecardiac-0.1.0a2/kalecardiac/evaluate/regression_metrics.py +38 -0
- kalecardiac-0.1.0a2/kalecardiac/interpret/__init__.py +55 -0
- kalecardiac-0.1.0a2/kalecardiac/interpret/attribution.py +532 -0
- kalecardiac-0.1.0a2/kalecardiac/interpret/latent.py +151 -0
- kalecardiac-0.1.0a2/kalecardiac/loaddata/__init__.py +131 -0
- kalecardiac-0.1.0a2/kalecardiac/loaddata/image_access.py +422 -0
- kalecardiac-0.1.0a2/kalecardiac/loaddata/multimodal_access.py +608 -0
- kalecardiac-0.1.0a2/kalecardiac/loaddata/signal_access.py +645 -0
- kalecardiac-0.1.0a2/kalecardiac/loaddata/splitting.py +352 -0
- kalecardiac-0.1.0a2/kalecardiac/model/__init__.py +67 -0
- kalecardiac-0.1.0a2/kalecardiac/model/embed/__init__.py +85 -0
- kalecardiac-0.1.0a2/kalecardiac/model/embed/cardiovae.py +255 -0
- kalecardiac-0.1.0a2/kalecardiac/model/embed/encoders.py +242 -0
- kalecardiac-0.1.0a2/kalecardiac/model/embed/lsemvae.py +151 -0
- kalecardiac-0.1.0a2/kalecardiac/model/embed/multimodal_fusion.py +387 -0
- kalecardiac-0.1.0a2/kalecardiac/model/embed/multimodal_vae.py +342 -0
- kalecardiac-0.1.0a2/kalecardiac/model/layers/__init__.py +81 -0
- kalecardiac-0.1.0a2/kalecardiac/model/layers/conv1d.py +285 -0
- kalecardiac-0.1.0a2/kalecardiac/model/layers/conv2d.py +261 -0
- kalecardiac-0.1.0a2/kalecardiac/model/layers/gaussian.py +425 -0
- kalecardiac-0.1.0a2/kalecardiac/model/layers/mlp.py +53 -0
- kalecardiac-0.1.0a2/kalecardiac/model/layers/residual1d.py +161 -0
- kalecardiac-0.1.0a2/kalecardiac/model/layers/transformer.py +162 -0
- kalecardiac-0.1.0a2/kalecardiac/model/predict/__init__.py +46 -0
- kalecardiac-0.1.0a2/kalecardiac/model/predict/heads.py +124 -0
- kalecardiac-0.1.0a2/kalecardiac/model/predict/losses.py +243 -0
- kalecardiac-0.1.0a2/kalecardiac/pipeline/__init__.py +33 -0
- kalecardiac-0.1.0a2/kalecardiac/pipeline/task.py +396 -0
- kalecardiac-0.1.0a2/kalecardiac/pipeline/trainer.py +209 -0
- kalecardiac-0.1.0a2/kalecardiac/prepdata/__init__.py +81 -0
- kalecardiac-0.1.0a2/kalecardiac/prepdata/ecg_transform.py +247 -0
- kalecardiac-0.1.0a2/kalecardiac/prepdata/image_transform.py +186 -0
- kalecardiac-0.1.0a2/kalecardiac/prepdata/signal_transform.py +251 -0
- kalecardiac-0.1.0a2/kalecardiac/py.typed +0 -0
- kalecardiac-0.1.0a2/kalecardiac/utils/__init__.py +19 -0
- kalecardiac-0.1.0a2/kalecardiac/utils/io.py +145 -0
- kalecardiac-0.1.0a2/kalecardiac/utils/renames.py +98 -0
- kalecardiac-0.1.0a2/kalecardiac/utils/seed.py +65 -0
- kalecardiac-0.1.0a2/kalecardiac.egg-info/PKG-INFO +244 -0
- kalecardiac-0.1.0a2/kalecardiac.egg-info/SOURCES.txt +157 -0
- kalecardiac-0.1.0a2/kalecardiac.egg-info/dependency_links.txt +1 -0
- kalecardiac-0.1.0a2/kalecardiac.egg-info/requires.txt +32 -0
- kalecardiac-0.1.0a2/kalecardiac.egg-info/top_level.txt +1 -0
- kalecardiac-0.1.0a2/pyproject.toml +139 -0
- kalecardiac-0.1.0a2/setup.cfg +4 -0
- kalecardiac-0.1.0a2/tests/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/auto/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/auto/test_endpoint.py +271 -0
- kalecardiac-0.1.0a2/tests/auto/test_workflow.py +410 -0
- kalecardiac-0.1.0a2/tests/conftest.py +123 -0
- kalecardiac-0.1.0a2/tests/evaluate/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/evaluate/test_cross_validation.py +134 -0
- kalecardiac-0.1.0a2/tests/evaluate/test_predictions.py +130 -0
- kalecardiac-0.1.0a2/tests/examples/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/examples/test_cli.py +119 -0
- kalecardiac-0.1.0a2/tests/examples/test_config_wiring.py +312 -0
- kalecardiac-0.1.0a2/tests/examples/test_endpoints.py +93 -0
- kalecardiac-0.1.0a2/tests/examples/test_example_workflows.py +372 -0
- kalecardiac-0.1.0a2/tests/examples/test_robustness.py +140 -0
- kalecardiac-0.1.0a2/tests/examples/test_synthetic_data.py +173 -0
- kalecardiac-0.1.0a2/tests/examples/test_tutorials.py +298 -0
- kalecardiac-0.1.0a2/tests/interpret/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/interpret/test_attribution.py +437 -0
- kalecardiac-0.1.0a2/tests/interpret/test_latent.py +163 -0
- kalecardiac-0.1.0a2/tests/loaddata/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/loaddata/test_image_access.py +288 -0
- kalecardiac-0.1.0a2/tests/loaddata/test_multimodal.py +266 -0
- kalecardiac-0.1.0a2/tests/loaddata/test_signal_access.py +453 -0
- kalecardiac-0.1.0a2/tests/loaddata/test_splitting.py +198 -0
- kalecardiac-0.1.0a2/tests/model/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/model/embed/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/model/embed/test_cardiac_models.py +361 -0
- kalecardiac-0.1.0a2/tests/model/embed/test_encoders.py +41 -0
- kalecardiac-0.1.0a2/tests/model/embed/test_multimodal_fusion.py +254 -0
- kalecardiac-0.1.0a2/tests/model/embed/test_multimodal_vae.py +290 -0
- kalecardiac-0.1.0a2/tests/model/layers/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/model/layers/test_backbones.py +359 -0
- kalecardiac-0.1.0a2/tests/model/layers/test_gaussian.py +380 -0
- kalecardiac-0.1.0a2/tests/model/predict/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/model/predict/test_heads.py +71 -0
- kalecardiac-0.1.0a2/tests/model/predict/test_losses.py +213 -0
- kalecardiac-0.1.0a2/tests/pipeline/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/pipeline/test_task.py +269 -0
- kalecardiac-0.1.0a2/tests/pipeline/test_trainer.py +292 -0
- kalecardiac-0.1.0a2/tests/prepdata/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/prepdata/test_ecg_transform.py +174 -0
- kalecardiac-0.1.0a2/tests/prepdata/test_image_transform.py +139 -0
- kalecardiac-0.1.0a2/tests/prepdata/test_signal_transform.py +202 -0
- kalecardiac-0.1.0a2/tests/regression/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/regression/test_end_to_end.py +402 -0
- kalecardiac-0.1.0a2/tests/test_config.py +193 -0
- kalecardiac-0.1.0a2/tests/test_docs.py +51 -0
- kalecardiac-0.1.0a2/tests/test_package_structure.py +211 -0
- kalecardiac-0.1.0a2/tests/utils/__init__.py +0 -0
- kalecardiac-0.1.0a2/tests/utils/test_io.py +147 -0
- kalecardiac-0.1.0a2/tests/utils/test_renames.py +65 -0
- kalecardiac-0.1.0a2/tests/utils/test_seed.py +86 -0
- kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_cardiovae_finetune.yaml +33 -0
- kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_cardiovae_pretrain.yaml +46 -0
- kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_lsemvae_finetune.yaml +41 -0
- kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_lsemvae_pretrain.yaml +56 -0
- kalecardiac-0.1.0a2/tutorials/mdas_tutorial/tutorial-CardioVAE.ipynb +807 -0
- kalecardiac-0.1.0a2/tutorials/mdas_tutorial/tutorial-LSEMVAE.ipynb +858 -0
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Instructions for coding agents working in this repository. Human contributors should read [README.md](README.md) and [docs/architecture.md](docs/architecture.md).
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
Python 3.10–3.12 is required. Install PyTorch first if a specific CUDA build is needed — PyKale 0.2 requires `torch<=2.6.0`, so a newer build would be replaced — then:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
python -m venv .venv
|
|
11
|
+
.venv/bin/pip install -e ".[dev,interpret,ecg,imaging]" # Windows: .venv/Scripts/pip
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
`interpret`, `ecg` and `imaging` are the extras the tests exercise; without them a few tests skip.
|
|
15
|
+
|
|
16
|
+
Verify the install:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
.venv/bin/python -c "import kalecardiac, torch, kale; print(kalecardiac.__version__)"
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Commands
|
|
23
|
+
|
|
24
|
+
| Task | Command |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| Run tests, including the library's doctests | `.venv/bin/pytest` |
|
|
27
|
+
| Run tests, skipping the whole-workflow runs | `.venv/bin/pytest -m "not slow"` |
|
|
28
|
+
| Run tests with coverage | `.venv/bin/pytest --cov=kalecardiac --cov-report=term-missing` |
|
|
29
|
+
| Format | `.venv/bin/ruff format .` |
|
|
30
|
+
| Lint | `.venv/bin/ruff check .` |
|
|
31
|
+
| Run an example end to end | `.venv/bin/python -m examples.lsemvae_ecg.main --cfg examples/lsemvae_ecg/configs/quick.yaml` |
|
|
32
|
+
| Build the documentation | `.venv/bin/pip install -r docs/requirements.txt`, then `.venv/bin/sphinx-build -W --keep-going -b html docs docs/_build/html` |
|
|
33
|
+
|
|
34
|
+
Both `pre-commit run --all-files` (ruff, ruff-format, mypy) and `pytest` must pass before a change is complete. These are the same checks CI runs.
|
|
35
|
+
|
|
36
|
+
## Data
|
|
37
|
+
|
|
38
|
+
**There is no data in this repository, and none may be added.** Both studies this package was built from were developed on private clinical cohorts, and nothing patient-derived belongs here: no recordings, no images, no identifiers, no labels, no derived per-subject files, no credentials, no pretrained artefacts trained on them.
|
|
39
|
+
|
|
40
|
+
Tests and examples use `examples/synthetic_data.py`, which generates cohorts with a real dependence between signal and endpoint — so a broken pipeline scores about 0.5 and a working one scores clearly above it. They are **not** physiologically accurate ECGs.
|
|
41
|
+
|
|
42
|
+
Nothing in the test suite may reach the network. A run on synthetic data is a verification, never a result; say so when reporting one, as the examples do in their first log line.
|
|
43
|
+
|
|
44
|
+
Cohort layouts are documented in each example's README so that a researcher with approved access can supply `DATASET.ROOT`. Document a schema; never commit one.
|
|
45
|
+
|
|
46
|
+
## Layout
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
kalecardiac/
|
|
50
|
+
├── auto/ workflows read from a configuration: the endpoint, pretraining, fine-tuning over folds
|
|
51
|
+
├── loaddata/ access APIs per modality, plus subject-level splitting
|
|
52
|
+
├── prepdata/ transforms over signals and images
|
|
53
|
+
├── model/ layers/ blocks, embed/ encoders and models, predict/ heads and objectives
|
|
54
|
+
├── pipeline/ the trainer and its tasks
|
|
55
|
+
├── evaluate/ metrics and prediction scoring, by task
|
|
56
|
+
├── interpret/ attribution, lead importance, latent inspection
|
|
57
|
+
├── utils/ seeding, artefact writing, checkpoint loading
|
|
58
|
+
└── config.py configuration schema and defaults
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### There is one trainer
|
|
62
|
+
|
|
63
|
+
`CardiacTrainer` takes a *model* and a *task*, and neither constrains the other. Do not add `CardioVAETrainer`, `LSEMVAETrainer`, `ECGTrainer` or `CXRTrainer` — there is nothing for one to add, because the model is an argument and the objective is an argument.
|
|
64
|
+
|
|
65
|
+
A task decides exactly four things: the head, the loss, what the model is asked to produce (`forward_kwargs`), and the epoch metric. **A new endpoint is a new `PredictionTask`, never a new trainer.**
|
|
66
|
+
|
|
67
|
+
**Pretraining is a task.** `ReconstructionTask` supervises on the batch's own modalities and takes no labels, which is why representation learning needs no second trainer and is not a pipeline stage.
|
|
68
|
+
|
|
69
|
+
### There is one multimodal VAE
|
|
70
|
+
|
|
71
|
+
`MultimodalVAE` with a `fusion` argument and a decoder mapping covers five published models. `CardioVAE` and `LSEMVAE` are thin configurations of it, exported under those names because that is what the literature calls them.
|
|
72
|
+
|
|
73
|
+
**Do not add a model class for an ablation.** "Without the mixture step" is `fusion="poe"`. "Without the shared decoder" is `shared_decoder=False`. If a change can be a constructor argument, it is one.
|
|
74
|
+
|
|
75
|
+
### `loaddata/` is one access API per kind of data
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
loaddata/
|
|
79
|
+
├── signal_access.py ECGArraySource, ECGFileSource, LeadSource, get_lead_sources, the lead vocabulary
|
|
80
|
+
├── image_access.py ImageArraySource, ImageFileSource, and reading DICOM through PyKale's reader
|
|
81
|
+
├── multimodal_access.py MultimodalDataset, ModalitySource, ColumnTarget, the record types
|
|
82
|
+
└── splitting.py HoldOutSplit, CrossValidationSplit, PredefinedSplit -- scikit-learn's shape
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Adding a modality is a dictionary entry. Adding a *kind* of modality is one `ModalitySource` subclass. Never a new dataset class per combination.
|
|
86
|
+
|
|
87
|
+
### `model/` is three stages, and a class belongs to exactly one
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
model/
|
|
91
|
+
├── layers/ blocks that transform tensors and know no modality
|
|
92
|
+
├── embed/ encoders adapted to a contract, and the models that fuse them
|
|
93
|
+
└── predict/ heads, and every objective including the ELBO
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
A **layer** transforms tensors. An **embedder** adapts one to a contract (`out_dim`, or `latent_dim` and a posterior). A **head** turns a representation into a score. Put a new block in `layers/` and adapt it in `embed/`, never both at once.
|
|
97
|
+
|
|
98
|
+
### Splitting stays in `loaddata/`, not `prepdata/`
|
|
99
|
+
|
|
100
|
+
A splitter decides which subjects load into which loader; `prepdata/` is transforms. The thing that creates the folds cannot be state belonging to one. scikit-learn draws the same line between `model_selection` and `preprocessing`.
|
|
101
|
+
|
|
102
|
+
### `auto/` is the one stage that reads a configuration
|
|
103
|
+
|
|
104
|
+
Every other stage takes explicit arguments. `kalecardiac.auto` reads them from a `CfgNode` and holds what every experiment does with the same settings the same way: the endpoint a configured column defines, the task and metrics it implies, pretraining, and fine-tuning, scoring and interpreting over the folds. A step two examples would otherwise both write belongs here.
|
|
105
|
+
|
|
106
|
+
## Constraints
|
|
107
|
+
|
|
108
|
+
These are enforced by [`tests/test_package_structure.py`](tests/test_package_structure.py), which parses every library module. They are not style preferences.
|
|
109
|
+
|
|
110
|
+
- **Nothing in `kalecardiac/` may name a dataset, a cohort, a registry or an experiment.** Not in code, not in a comment. Docstrings are exempt, because that is where a refactored model credits the study it came from.
|
|
111
|
+
- **No absolute paths.** A path is an experiment's, never a library's.
|
|
112
|
+
- **The library never imports `examples/`.** The dependency runs one way.
|
|
113
|
+
- **Stage imports follow the pipeline order.** `loaddata` must not import `model`; no stage may import `pipeline`.
|
|
114
|
+
- **Every module, public class and public function has a docstring.**
|
|
115
|
+
|
|
116
|
+
Further constraints that tests check case by case:
|
|
117
|
+
|
|
118
|
+
- **Splitting is subject-level.** A subject's recordings must never span two splits — including the train/validation carve, not only train/test.
|
|
119
|
+
- **Validation is always carved out of the training half**, never out of the test set.
|
|
120
|
+
- **Anything derived from labels is computed on the training split of each fold.** A class weight most obviously; recomputing it per fold is not optional.
|
|
121
|
+
- **Missing modalities are carried by the presence mask**, never inferred from zeros. A zero-filled placeholder keeps a batch rectangular and is never evidence.
|
|
122
|
+
- **Lead names are matched canonically.** `aVR`, `AVR` and `LEAD_aVR` are one lead. The reference implementation this package refactors has aVL and aVF transposed between its preprocessing script and its encoder index map, which silently trains a per-lead model on the wrong lead.
|
|
123
|
+
- **`persistent_workers` loaders are released with `release_workers`** when the split that built them is finished.
|
|
124
|
+
|
|
125
|
+
## Preserving scientific behaviour
|
|
126
|
+
|
|
127
|
+
This package is a refactor of published work, not a rewrite of it.
|
|
128
|
+
|
|
129
|
+
Where a model here corresponds to a published one, its mathematical behaviour must match. Where it deliberately does not — because the original contains a bug, an ambiguity or a numerical hazard — **document the departure in [docs/models.md](docs/models.md), and test it.** Three are documented already: the discarded prior expert, the KL term taken against a posterior that was never sampled, and sampling that depended on a module flag.
|
|
130
|
+
|
|
131
|
+
Do not change an algorithm silently, and do not "fix" something that merely looks odd without establishing that it is wrong.
|
|
132
|
+
|
|
133
|
+
## Examples
|
|
134
|
+
|
|
135
|
+
Named `<method>_<modality>`. Each has the same five parts — `README.md`, `config.py`, `data.py`, `runner.py`, `main.py` — plus `configs/quick.yaml` (synthetic, about a minute) and `configs/full.yaml` (the published setup).
|
|
136
|
+
|
|
137
|
+
Examples run as modules from the repository root — `python -m examples.<name>.main` — so their imports resolve as ordinary packages. Do not add `sys.path` manipulation. What the examples share that is not a mechanism stays beside them: the synthetic cohorts in `examples/synthetic_data.py`, and the command line's group flag, configuration loading and results table in `examples/cli.py`.
|
|
138
|
+
|
|
139
|
+
**An example composes the library; it never defines a model.** A test asserts that neither runner contains `nn.Module`:
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
# Right
|
|
143
|
+
from kalecardiac.model.embed import LSEMVAE
|
|
144
|
+
model = LSEMVAE(leads=cfg.ECG.LEADS, fusion=cfg.FUSION.LATENT_METHOD)
|
|
145
|
+
|
|
146
|
+
# Wrong
|
|
147
|
+
class LSEMVAE(nn.Module): # 500 lines redefining what the library already has
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
An example owns its configuration, its cohort construction -- where the files are and what the columns mean -- the model it builds from the cohort's shapes, what it compares, and any report of its own. The workflow is `kalecardiac.auto`'s: an example calls `pretrain` and `cross_validate` rather than copying them, and a test fails if a runner defines either again.
|
|
151
|
+
|
|
152
|
+
## Conventions
|
|
153
|
+
|
|
154
|
+
- Follow [PyKale](https://github.com/pykale/pykale) conventions: verb-oriented stages, Google-style docstrings, type hints, YACS configuration.
|
|
155
|
+
- **Name things as PyKale does.** Modules are named for the modality they serve (`signal_access`, `image_access`, `signal_transform`). A function that acts starts with a verb -- `load_`, `get_`, `check_`, `normalize_`, `interpolate_`, `resample_`; a factory returning a transform is `get_<x>_transform`, one building a module is `build_<x>`. Metrics and losses are nouns, as in scikit-learn and `torch.nn.functional`. Splitters end in `Split`, as scikit-learn's do. Identifiers use American spelling (`normalize`, `summarize`), as PyKale, scikit-learn and PyTorch do; prose may stay British. Where PyKale has the function, use PyKale's name.
|
|
156
|
+
- **Do not wrap what a dependency already provides.** Chain transforms with `torchvision.transforms.Compose`; call PyTorch's losses directly; take class weights from scikit-learn's `compute_class_weight`, metrics from `sklearn.metrics`, resampling from `scipy.signal`, freezing from `module.requires_grad_`. Define something here only when no dependency has it.
|
|
157
|
+
- **Reuse PyKale APIs where one exists rather than reimplementing.** Where something is reimplemented — `Conv1dEncoder` over `SignalVAEEncoder`, `LinearHead` over `kale.predict.decode` — the reason is in the module docstring, and a test asserts the two agree where their shapes do.
|
|
158
|
+
- Line length 120. Formatting is enforced by ruff-format; do not hand-format.
|
|
159
|
+
- Comments explain why, not what. Do not restate the code.
|
|
160
|
+
- New configuration belongs in `kalecardiac/config.py`, never hardcoded in a module — unless it names a dataset, in which case it belongs in an example's `config.py`.
|
|
161
|
+
- An error message should say what to do next. `"crop or pad the cohort first; see kalecardiac.prepdata.crop_or_pad_signal"` beats `"shape mismatch"`.
|
|
162
|
+
|
|
163
|
+
## Adding a component
|
|
164
|
+
|
|
165
|
+
1. Implement it in the matching `kalecardiac/` subpackage.
|
|
166
|
+
2. Export it from that subpackage's `__init__.py`.
|
|
167
|
+
3. Add tests in the mirrored `tests/` path, using synthetic data.
|
|
168
|
+
4. Add any new setting to `kalecardiac/config.py` with a comment saying why it exists.
|
|
169
|
+
5. A new module needs an `automodule` entry in the matching `docs/kalecardiac.<stage>.rst`; `tests/test_docs.py` fails until it has one.
|
|
170
|
+
6. Title the pull request as its changelog entry and give it one label; the changelog is generated at release (see [CONTRIBUTING.md](CONTRIBUTING.md#releasing)).
|
|
171
|
+
7. Run the format, lint and test commands above.
|
|
172
|
+
|
|
173
|
+
Before adding an abstraction, check it has a second user. This package has no protocol with one implementation, no registry with one entry, and no factory that exists for theoretical extensibility.
|
|
@@ -0,0 +1,355 @@
|
|
|
1
|
+
# API overview
|
|
2
|
+
|
|
3
|
+
The public API of `kalecardiac`, stage by stage, following the pipeline:
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
load → preprocess → embed → fuse → predict → evaluate → interpret
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
For *why* it is shaped this way, see [docs/architecture.md](docs/architecture.md). For a running example, [docs/quickstart.md](docs/quickstart.md).
|
|
10
|
+
|
|
11
|
+
**Names follow PyKale.** Modules are named for the modality they serve (`signal_access`, `image_access`, `signal_transform`, `image_transform`), functions that act start with a verb (`load_`, `get_`, `check_`, `normalize_`, `interpolate_`, `resample_`), and spelling is American, as in PyKale, scikit-learn and PyTorch. Where PyKale already has a function, the name is PyKale's: `interpolate_signal` and `normalize_signal` are the functions `kale.prepdata.signal_transform` has, for the `(channels, samples)` layout used here. Metrics and losses are nouns, as in scikit-learn and `torch.nn.functional`.
|
|
12
|
+
|
|
13
|
+
**Nothing here duplicates a library this one depends on.** Transforms are chained with `torchvision.transforms.Compose`; classification and regression losses are PyTorch's; class weights come from scikit-learn's `compute_class_weight`; resampling is SciPy's polyphase `resample_poly`; R², RMSE and MAE are scikit-learn's. What this package defines is what those libraries do not have.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## The whole workflow in one page
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from kalecardiac.loaddata import ColumnTarget, ECGArraySource, CrossValidationSplit, MultimodalDataset, get_lead_sources
|
|
21
|
+
from kalecardiac.prepdata import get_ecg_transform
|
|
22
|
+
from kalecardiac.model.embed import LSEMVAE, MultimodalPredictor
|
|
23
|
+
from kalecardiac.pipeline import CardiacTrainer, ClassificationTask, ReconstructionTask
|
|
24
|
+
from kalecardiac.evaluate import binary_metrics, predict_split
|
|
25
|
+
from kalecardiac.interpret import attribution_ratios, modality_attributions
|
|
26
|
+
|
|
27
|
+
# load ------------------------------------------------------------------ #
|
|
28
|
+
recordings = ECGArraySource(
|
|
29
|
+
arrays, leads=LEADS, sampling_rate=500, transform=get_ecg_transform(length=5000, sampling_rate=500)
|
|
30
|
+
)
|
|
31
|
+
sources = get_lead_sources(recordings) # one modality per lead
|
|
32
|
+
target = ColumnTarget(table, columns={"label": "has_ph"}, id_column="subject_id")
|
|
33
|
+
dataset = MultimodalDataset(subject_ids, sources, target=target)
|
|
34
|
+
|
|
35
|
+
# embed and fuse: pretrain a representation, with no labels -------------- #
|
|
36
|
+
vae = LSEMVAE(leads=LEADS, length=5000, latent_dim=256, fusion="hime")
|
|
37
|
+
CardiacTrainer(vae, ReconstructionTask(alignment_weight=0.1))
|
|
38
|
+
|
|
39
|
+
# predict: fine-tune onto an endpoint, on a subset of the leads ---------- #
|
|
40
|
+
task = ClassificationTask(pos_weight=3.0)
|
|
41
|
+
predictor = MultimodalPredictor(vae.latent_embedders(SIX_LEADS, frozen=True), task.build_head)
|
|
42
|
+
model = CardiacTrainer(predictor, task)
|
|
43
|
+
|
|
44
|
+
# evaluate and interpret ------------------------------------------------- #
|
|
45
|
+
predictions = predict_split(model, test_loader, split="test")
|
|
46
|
+
metrics = binary_metrics(predictions.targets["label"], predictions.scores)
|
|
47
|
+
shares = attribution_ratios(modality_attributions(model.model, batch.modalities))
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## `loaddata` — access, by modality
|
|
53
|
+
|
|
54
|
+
### Records
|
|
55
|
+
|
|
56
|
+
| Name | What it is |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `SubjectSample` | One subject: `subject_id`, `modalities`, `present`, `target`, `metadata` |
|
|
59
|
+
| `SubjectBatch` | The collated form, with a leading batch dimension and a `.to(device)` |
|
|
60
|
+
| `collate_subjects` | The `collate_fn` a DataLoader needs |
|
|
61
|
+
| `release_workers(*loaders)` | Shut down persistent worker pools deliberately, rather than racing interpreter shutdown |
|
|
62
|
+
|
|
63
|
+
### Sources
|
|
64
|
+
|
|
65
|
+
A `ModalitySource` answers two questions per subject: what its value is, and what shape to substitute when there is not one. Implement it to add a *kind* of modality; adding a modality is a dictionary entry.
|
|
66
|
+
|
|
67
|
+
| Name | Reads |
|
|
68
|
+
| --- | --- |
|
|
69
|
+
| `ECGArraySource` | Recordings in memory, by named lead |
|
|
70
|
+
| `ECGFileSource` | One recording file per subject, lazily, with a one-entry cache |
|
|
71
|
+
| `ECGFileSource.from_dicom(root, select=None, transform=None)` | A folder of DICOM ECG exports, one folder per subject: the leads and their rate are read from the headers, and every subject's leads are found by name |
|
|
72
|
+
| `LeadSource` | A single lead of an ECG source, as its own modality |
|
|
73
|
+
| `get_lead_sources(source, leads=None, prefix="")` | **Splits a recording into one source per lead** — the whole of "each lead is a modality" |
|
|
74
|
+
| `ImageArraySource` / `ImageFileSource` | Any 2-D cardiac modality |
|
|
75
|
+
| `ImageFileSource.from_dicom(root, transform=None)` | A folder of DICOM image exports, one folder per subject, each image as a viewer displays it |
|
|
76
|
+
| `ArraySource` | Anything already one array per subject — a clinical vector, a frozen embedding |
|
|
77
|
+
| `MultimodalDataset.from_arrays({"signal": ecg, "image": cxr}, targets={"label": y})` | A cohort straight from aligned tensors, as PyKale's `SignalImageDataset` takes them |
|
|
78
|
+
|
|
79
|
+
### Lead vocabulary
|
|
80
|
+
|
|
81
|
+
`STANDARD_12_LEAD`, `LIMB_LEADS`, `PRECORDIAL_LEADS`, and `normalize_lead_name` / `normalize_lead_names` / `get_lead_indices`, which match names case-insensitively with a `LEAD_` or `Lead` prefix stripped -- so DICOM's `Lead I (Einthoven)` is lead `I`. `check_ecg_array` and `check_image_array` coerce shapes, transposing only where it is unambiguous.
|
|
82
|
+
|
|
83
|
+
### DICOM
|
|
84
|
+
|
|
85
|
+
Read with PyKale's `kale.loaddata.image_access.read_dicom_phases`, one subject per folder, the folder's name -- not the header's `PatientID` -- identifying the subject, since that is what pairs one modality's export with another's. Needs the `imaging` extra.
|
|
86
|
+
|
|
87
|
+
| Name | What it does |
|
|
88
|
+
| --- | --- |
|
|
89
|
+
| `get_dicom_paths(root)` | Each subject's folder (or `.dcm` file) under `root`, keyed by name |
|
|
90
|
+
| `read_dicom(path)` | The one DICOM a subject's folder holds, as a `pydicom` dataset; several are an error, not a guess |
|
|
91
|
+
| `read_dicom_ecg(path, group=None)` | `(recording, leads, rate)`: the recorded waveform -- not a derived median beat -- in millivolts, its leads named canonically |
|
|
92
|
+
| `read_dicom_image(path)` | The pixels after the modality LUT, the VOI LUT or window, and a `MONOCHROME1` inversion |
|
|
93
|
+
|
|
94
|
+
### Supervision
|
|
95
|
+
|
|
96
|
+
| Name | What it does |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| `ColumnTarget(frame, columns, id_column)` | Reads named columns of a table; `{"label": "has_ph"}` or `{"value": "mpap_mmhg"}` |
|
|
99
|
+
| `ColumnTarget.from_mapping({"label": {...}})` | The door in for a cohort that never had a table |
|
|
100
|
+
| `Target`, `check_target` | The contract, and the runtime check a `Protocol` alone cannot give |
|
|
101
|
+
| `LABEL_KEY`, `VALUE_KEY` | The batch target keys, so nothing guesses at a name |
|
|
102
|
+
|
|
103
|
+
### Splitting
|
|
104
|
+
|
|
105
|
+
Splitter objects with scikit-learn's shape, producing a **named** mapping rather than a pair. Rows sharing `group_by` always land together — in a cardiac cohort that is not a formality, since one subject often contributes several recordings.
|
|
106
|
+
|
|
107
|
+
| Name | Test set |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| `HoldOutSplit(test_size, val_size, group_by, stratify_by)` | One stratified, grouped draw |
|
|
110
|
+
| `CrossValidationSplit(n_splits, ...)` | Each fold in turn. The default for a cohort of a few hundred |
|
|
111
|
+
| `PredefinedSplit(assignment, ...)` | An assignment the study fixed |
|
|
112
|
+
|
|
113
|
+
`SPLIT_NAMES` is `("train", "val", "test")`. Validation is always carved out of the training half; `val_size=0` gives a plain two-way split. Each splitter draws its folds with scikit-learn's `StratifiedGroupKFold`, `StratifiedKFold` or `StratifiedShuffleSplit` and adds what those lack: a third, validation set, and stratification by several columns at once (`get_stratification_labels`).
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## `prepdata` — transforms
|
|
118
|
+
|
|
119
|
+
**Nothing here is fitted.** Every transform is a function of one recording or one image, so a source may apply it without knowing which split the subject landed in.
|
|
120
|
+
|
|
121
|
+
### Signals — `(channels, samples)` in, the same out
|
|
122
|
+
|
|
123
|
+
| Name | Does |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| `interpolate_signal` | Fills NaNs along time. Runs first: a NaN spreads through everything after it |
|
|
126
|
+
| `crop_or_pad_signal(signal, length, center=False)` | Forces one length |
|
|
127
|
+
| `resample_signal(signal, source_rate, target_rate)` | SciPy's polyphase resampler: filters before it decimates, so nothing aliases |
|
|
128
|
+
| `normalize_signal(signal, per_channel=True)` | Zero mean, unit variance — PyKale's function, channels first. Discards absolute millivolts |
|
|
129
|
+
| `scale_signal(signal, scale)` | Divides by a constant, **keeping** absolute amplitude |
|
|
130
|
+
| `clip_signal(signal, limit)` | Bounds a saturated electrode's excursion |
|
|
131
|
+
| `check_signal(signal)` | Coerces to a float32 `(channels, samples)` array, as scikit-learn's `check_array` does |
|
|
132
|
+
| `get_ecg_transform(length, sampling_rate, ..., interleave=False)` | The usual four, in the order that is not interchangeable, as a `Compose`; `interleave` adds `interleave_leads` last |
|
|
133
|
+
|
|
134
|
+
Steps are chained with `torchvision.transforms.Compose`; a source's `transform` takes one.
|
|
135
|
+
|
|
136
|
+
### ECG — the part that needs to know a lead from a channel
|
|
137
|
+
|
|
138
|
+
| Name | Does |
|
|
139
|
+
| --- | --- |
|
|
140
|
+
| `select_leads(signal, available, wanted)` | Selection *and* ordering in one operation |
|
|
141
|
+
| `derive_limb_leads(signal, available, wanted)` | Reconstructs III, aVR, aVL, aVF from I and II — exactly, by Einthoven and Goldberger |
|
|
142
|
+
| `get_lead_selector(available, wanted, derive=False)` | The one-argument callable form, for a `Compose` |
|
|
143
|
+
| `interleave_leads(signal)` | `(leads, samples)` to `(1, samples * leads)`, sample by sample, as CardioVAE reads an ECG |
|
|
144
|
+
| `DERIVABLE_LIMB_LEADS` | Which leads follow from I and II, and how |
|
|
145
|
+
|
|
146
|
+
### Images — `(channels, height, width)` in, the same out
|
|
147
|
+
|
|
148
|
+
`resize_image`, `scale_image_intensity`, `normalize_image`, `check_image`, and `get_image_transform(size, scale=True)`, which returns a `Compose`.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## `model.layers` — blocks that know no modality
|
|
153
|
+
|
|
154
|
+
### Gaussian experts — the mathematical core
|
|
155
|
+
|
|
156
|
+
All take `mean` and `log_var` of `(M, B, D)` and an optional `(M, B)` mask, and return a `GaussianPosterior`.
|
|
157
|
+
|
|
158
|
+
| Name | Combines by |
|
|
159
|
+
| --- | --- |
|
|
160
|
+
| `product_of_experts` | Precision-weighted product. Never less certain than any expert |
|
|
161
|
+
| `mixture_of_experts` | Weighted parameter average. No expert dominates |
|
|
162
|
+
| `mean_of_experts` | The equal-weight case |
|
|
163
|
+
| `hierarchical_experts(..., num_groups)` | Product within groups, average across them (HiME) |
|
|
164
|
+
| `wasserstein_barycenter` | Mean of means and of **standard deviations** |
|
|
165
|
+
| `EXPERT_FUSIONS`, `build_expert_fusion(name, **kw)` | The registry, and construction by name |
|
|
166
|
+
| `get_expert_groups(num_experts, num_groups)` | Contiguous grouping that uses **every** expert |
|
|
167
|
+
| `prior_expert(shape)` | The standard-normal expert |
|
|
168
|
+
| `reparameterize(mean, log_var)` | The differentiable sample. Always samples |
|
|
169
|
+
| `GaussianPosterior` | `.mean`, `.log_var`, `.variance`, `.stddev`, `.sample()` |
|
|
170
|
+
| `GaussianHead(in_features, latent_dim)` | Features to a posterior |
|
|
171
|
+
|
|
172
|
+
### Backbones and decoders
|
|
173
|
+
|
|
174
|
+
`Conv1dEncoder` / `Conv1dDecoder`, `Conv2dEncoder` / `Conv2dDecoder`, `ResidualConv1dEncoder`, `TransformerSignalEncoder`, `MLP`, plus `conv_output_length` and `conv_output_size`.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## `model.embed` — encoders, models, and fusion
|
|
179
|
+
|
|
180
|
+
### Adapters
|
|
181
|
+
|
|
182
|
+
| Name | Turns a backbone into |
|
|
183
|
+
| --- | --- |
|
|
184
|
+
| `VariationalEncoder(backbone, latent_dim)` | A modality of a multimodal VAE |
|
|
185
|
+
| `FeatureEmbedder(backbone, out_dim=None)` | A modality of a predictor, trained from scratch |
|
|
186
|
+
| `LatentEmbedder(encoder, frozen=True)` | **The transfer bridge**: a pretrained encoder's posterior mean, as an embedding |
|
|
187
|
+
| `build_signal_encoder(name, ...)`, `build_image_encoder(...)` | Construction by name; `SIGNAL_ENCODERS` lists them |
|
|
188
|
+
|
|
189
|
+
Freezing is PyTorch's own `module.requires_grad_(False)`, which `LatentEmbedder` calls.
|
|
190
|
+
|
|
191
|
+
### Generative models
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
MultimodalVAE(encoders, decoders, latent_dim, fusion="poe", use_prior=True, **fusion_kwargs)
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- `.encode(modalities, present, only=None)` → `(joint, per_modality)` posteriors
|
|
198
|
+
- `.decode(latent)` → one reconstruction per decoded modality
|
|
199
|
+
- `.forward(modalities, present, unimodal_streams=False)` → `VAEOutput`
|
|
200
|
+
- `.latent_embedders(modalities=None, frozen=True)` → the embedders a predictor fuses
|
|
201
|
+
|
|
202
|
+
`VAEOutput` carries `joint` (a `VAEStream`), `unimodal`, `modality_posteriors` and `present`, with `.posterior` and `.latent` as shorthands for the joint.
|
|
203
|
+
|
|
204
|
+
Named configurations: `CardioVAE(..., fusion="poe")` and `LSEMVAE(leads=..., fusion="hime")`. Both take `fusion`, `use_prior` and `kernel_size`, so an ablation is an argument rather than a model.
|
|
205
|
+
|
|
206
|
+
`CardioVAE()` with its defaults is PyKale's `SignalImageVAE()` parameter for parameter, and `CardioVAE.load_pykale_state_dict(state_dict)` loads the weights PyKale -- or the reference implementation -- saved; `remap_pykale_state_dict` is the renaming it applies.
|
|
207
|
+
|
|
208
|
+
### Discriminative model
|
|
209
|
+
|
|
210
|
+
```python
|
|
211
|
+
MultimodalPredictor(embedders, head_factory, method="concat", fusion_dim=None, modality_dropout=0.0)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Returns a `PredictionOutput` with `prediction`, `representation`, `embeddings` and, for attention fusion, `weights`. Fusion blocks: `ConcatFusion`, `MeanFusion`, `AttentionFusion`, with `FUSION_METHODS` and `build_fusion`. `modality_dropout` teaches a model to survive a missing lead.
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## `model.predict` — heads and objectives
|
|
219
|
+
|
|
220
|
+
| Head | For |
|
|
221
|
+
| --- | --- |
|
|
222
|
+
| `LinearHead(in_features, out_features=1)` | A linear map; right when the encoder is large and the cohort small |
|
|
223
|
+
| `MLPHead(in_features, out_features, hidden_dims, dropout)` | One hidden layer and dropout, as both cardiac studies use |
|
|
224
|
+
|
|
225
|
+
| Objective | For |
|
|
226
|
+
| --- | --- |
|
|
227
|
+
| `elbo_loss(reconstructions, targets, posterior, weights, present, kinds, annealing_factor, scale_factor, free_bits)` | The multimodal ELBO |
|
|
228
|
+
| `gaussian_kl_divergence(posterior, free_bits=0.0)` | The KL term, clamped so an untrained encoder cannot produce a NaN |
|
|
229
|
+
| `reconstruction_loss(recon, target, present, kind)` | Per modality, excluding absent subjects |
|
|
230
|
+
| `latent_alignment_loss(modality_posteriors, joint, present)` | Pulls each modality towards the consensus. The joint is detached |
|
|
231
|
+
|
|
232
|
+
The discriminative objectives are PyTorch's: a task calls `binary_cross_entropy_with_logits`, `cross_entropy` and `mse_loss` directly. A class weight comes from scikit-learn's `compute_class_weight("balanced", ...)`, over the **training** split only.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## `pipeline` — one trainer, several tasks
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
CardiacTrainer(model, task, optimizer=None, max_epochs=50, init_lr=1e-3, grad_clip=0.0)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
`.forward(batch)`, `.predict(batch)` (no gradients, mode restored), `.compute_loss(batch, split_name)`, and `.monitor` / `.monitor_mode` for configuring a checkpoint or early-stopping callback without knowing which way the metric runs.
|
|
243
|
+
|
|
244
|
+
| Task | Supervises on | Metric |
|
|
245
|
+
| --- | --- | --- |
|
|
246
|
+
| `ReconstructionTask(weights, scale_factor, annealing_epochs, alignment_weight, unimodal_streams, kinds, free_bits)` | The batch's own modalities — **no labels** | The objective |
|
|
247
|
+
| `ClassificationTask(num_classes=2, pos_weight, class_weight, hidden_dims, dropout)` | `label` | ROC-AUC; macro one-versus-rest above two classes |
|
|
248
|
+
| `RegressionTask(hidden_dims, dropout)` | `value` | R² |
|
|
249
|
+
|
|
250
|
+
A task decides exactly four things: the head, the loss, what the model is asked to produce (`forward_kwargs`), and the epoch metric. A new endpoint is a new task, never a new trainer.
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## `evaluate` — scoring, by task
|
|
255
|
+
|
|
256
|
+
| Name | Returns |
|
|
257
|
+
| --- | --- |
|
|
258
|
+
| `roc_auc(labels, scores)` | The area |
|
|
259
|
+
| `sensitivity_specificity(labels, scores, threshold)` | The clinical pair |
|
|
260
|
+
| `binary_metrics(labels, scores, threshold)` | Counts, ranking metrics, threshold metrics and the confusion matrix, JSON-ready |
|
|
261
|
+
| `multiclass_roc_auc(labels, scores)` | Macro one-versus-rest area: every class weighs the same, however rare |
|
|
262
|
+
| `multiclass_metrics(labels, scores, class_names)` | Accuracy, balanced accuracy, macro F1, the macro area and the confusion matrix |
|
|
263
|
+
| `mean_roc_curve(labels_per_run, scores_per_run)` | Curves interpolated onto a shared grid, with a variability band |
|
|
264
|
+
| `regression_metrics(targets, predictions, unit)` | RMSE, MAE and R², plus the signed bias, in the endpoint's units |
|
|
265
|
+
| `predict_split(model, loader, split, fold)` | A `SplitPredictions`, traceable by `subject_id` |
|
|
266
|
+
| `save_predictions(out_dir, predictions, metrics)` | A CSV and a JSON |
|
|
267
|
+
| `summarize_folds(fold_metrics)` | Mean and spread **over folds** |
|
|
268
|
+
| `flatten_fold_summary(summary)` | One results-table row from a fold summary |
|
|
269
|
+
| `pool_folds(fold_predictions)` | Every fold's labels and scores, for a **pooled** metric |
|
|
270
|
+
| `bootstrap_ci(labels, scores, metric, ...)` | A percentile interval, resampling *subjects* |
|
|
271
|
+
|
|
272
|
+
Binary labels must be exactly 0 or 1, and multiclass labels must be valid class indices. A two-column multiclass score uses binary ROC-AUC. Bootstrap resamples with NaN or infinite metrics are skipped; a non-finite metric on the full split raises `MetricError`.
|
|
273
|
+
|
|
274
|
+
`MetricError` is raised where a metric cannot be computed — a one-class split, say — which a trainer treats as "skip this epoch's metric" rather than a failure.
|
|
275
|
+
|
|
276
|
+
Scores may be logits or probabilities throughout. Binary scores in `[0, 1]` and multiclass rows in `[0, 1]` that sum to one are read as probabilities, and anything else as logits. Multiclass logits pass through a softmax because one-versus-rest ranking can change after that conversion.
|
|
277
|
+
|
|
278
|
+
`pool_folds` pairs each fold's targets with its scores and rejects a fold with unequal lengths. Pool predictions from different fitted models only when their scores share a comparable scale, such as calibrated probabilities; otherwise summarize the metric calculated separately for each fold.
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
## `interpret` — what the model used
|
|
283
|
+
|
|
284
|
+
| Name | Answers |
|
|
285
|
+
| --- | --- |
|
|
286
|
+
| `modality_attributions(model, modalities, target, present, n_steps, baselines)` | Where in each modality the evidence was. Attributes only what the model reads |
|
|
287
|
+
| `attribution_ratio(attribution, threshold)` | How much of one modality was strongly attributed |
|
|
288
|
+
| `attribution_ratios(attributions, threshold)` | Per modality, with each one's share — the lead-importance table |
|
|
289
|
+
| `segment_attribution_ratios(attribution, segments, window, threshold)` | Which part of the cardiac cycle |
|
|
290
|
+
| `delineate_ecg_waves(signal, sampling_rate)` | Where P, Q, R, S and T are (needs `[ecg]`) |
|
|
291
|
+
| `modality_ablation(model, loader, metric, target_key, modalities=None)` | What the metric loses when a modality is withheld. The metric sees `(N,)` scores, or `(N, K)` logits for a multiclass model |
|
|
292
|
+
| `progressive_ablation(model, loader, metric, target_key, order)` | How the metric degrades as modalities are withheld cumulatively — the reduced-lead deployment curve |
|
|
293
|
+
| `collect_latents(model, loader, per_modality=False)` | The learned representation over a cohort |
|
|
294
|
+
| `project_latents(features, method="pca"|"umap", ...)` | A low-dimensional projection of it |
|
|
295
|
+
| `normalize_attribution(attribution)` | Min-max rescaling, with its caveat documented |
|
|
296
|
+
|
|
297
|
+
Everything returns arrays and dictionaries. Nothing plots.
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
## `auto` — the same workflow, read from a configuration
|
|
302
|
+
|
|
303
|
+
Every stage above takes explicit arguments. `kalecardiac.auto` reads them from a YACS configuration instead, and holds what every experiment does with the same settings the same way, so an example keeps only where its cohort is, what its columns mean and which model it builds:
|
|
304
|
+
|
|
305
|
+
```python
|
|
306
|
+
from kalecardiac.auto import check_endpoint, cross_validate, derive_endpoint, get_endpoint_target, get_folds, pretrain
|
|
307
|
+
|
|
308
|
+
check_endpoint(cfg) # before any data is read
|
|
309
|
+
table = derive_endpoint(cfg, table) # adds label, and value, from ENDPOINT
|
|
310
|
+
target = get_endpoint_target(cfg, table, "subject_id")
|
|
311
|
+
pretrained = pretrain(cfg, LSEMVAE(leads=LEADS, length=5000), MultimodalDataset(unlabelled_ids, sources), out_dir)
|
|
312
|
+
summary = cross_validate(cfg, pretrained, six_lead_sources, target, get_folds(cfg, table), out_dir / "six_leads")
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
| Name | Reads | Does |
|
|
316
|
+
| --- | --- | --- |
|
|
317
|
+
| `check_endpoint(cfg)` | `ENDPOINT` | Refuses an endpoint that cannot be built, before any data is read |
|
|
318
|
+
| `derive_endpoint(cfg, table)` | `ENDPOINT` | Adds `label` — a threshold on `VALUE_COLUMN`, or a class read from `LABEL_COLUMN` — and `value`; drops subjects with no endpoint |
|
|
319
|
+
| `get_endpoint_target(cfg, table, id_column)` | `ENDPOINT` | The `ColumnTarget` the task is supervised by |
|
|
320
|
+
| `get_prediction_task(cfg, labels)` | `ENDPOINT`, `MODEL`, `OBJECTIVE` | The task, its class weights taken from the training fold's labels by `compute_class_weight` |
|
|
321
|
+
| `score_predictions(cfg, predictions)` | `ENDPOINT` | Binary, multiclass or regression metrics |
|
|
322
|
+
| `get_headline_metric(cfg)`, `get_ablation_metric(cfg)` | `ENDPOINT` | The metric a run is summarized by, and the threshold-free one a withheld modality is measured in |
|
|
323
|
+
| `get_ecg_transform_from_cfg(cfg, length=None, num_leads=None)` | `ECG` | `prepdata.get_ecg_transform` with its arguments read from `ECG`; `NUM_CHANNELS` 1 interleaves the leads |
|
|
324
|
+
| `get_folds(cfg, table)` | `DATASET`, `SOLVER` | `Fold`s, from `CrossValidationSplit` or `HoldOutSplit` |
|
|
325
|
+
| `pretrain(cfg, model, dataset, out_dir, kinds=None)` | `OBJECTIVE`, `SOLVER`, `MODEL` | Learns a representation without labels, or loads `MODEL.PRETRAINED` strictly |
|
|
326
|
+
| `fine_tune(cfg, pretrained, sources, target, fold, out_dir)` | `FINETUNE`, `FUSION`, `MODEL` | One fold: a predictor over the pretrained encoders, its best checkpoint restored, its test split scored |
|
|
327
|
+
| `cross_validate(cfg, pretrained, sources, target, folds, out_dir, report=None)` | the above, `OUTPUT` | A fresh copy per fold; predictions and metrics written; the last fold interpreted; `report` called after each fold, off the training's random stream |
|
|
328
|
+
| `interpret_model(cfg, model, loader, out_dir)` | `OUTPUT` | Attribution and modality ablation, written as `interpretation.json` and `attribution.csv` |
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## `utils` and `config`
|
|
333
|
+
|
|
334
|
+
`set_seed`, `seed_worker`, `ensure_dir`, `write_json`, `write_csv`, and `load_checkpoint(path, model, strict)` — which unwraps a `torch.compile` or Lightning prefix, so loading a pretrained cardiac model is one line rather than a key-mangling dictionary comprehension.
|
|
335
|
+
|
|
336
|
+
`preserve_rng_state()` is a context manager for work that only reports — an ablation, an attribution, a latent projection. Every DataLoader pass draws from PyTorch's generator, so without it, turning a report on or off would change every model trained after it.
|
|
337
|
+
|
|
338
|
+
`get_cfg_defaults()` returns the YACS schema; `parse_weights(["ecg:10", "cxr:1"])` reads per-modality weights, which are pairs because the modality names belong to the dataset rather than to the schema.
|
|
339
|
+
|
|
340
|
+
`kalecardiac.utils.renames` lists the names the API had before it took PyKale's. Each subpackage consults it, so `from kalecardiac.prepdata import standardise` fails saying it is now `normalize_signal`, and a YAML file setting `ECG.STANDARDISE` fails saying `ECG.NORMALIZE`, rather than either failing as a name that never existed.
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## What the boundary looks like in practice
|
|
345
|
+
|
|
346
|
+
| Belongs in `kalecardiac/` | Belongs in `examples/` |
|
|
347
|
+
| --- | --- |
|
|
348
|
+
| `ECGArraySource`, `get_lead_sources` | Where the recordings are on disk |
|
|
349
|
+
| `get_ecg_transform` | Which rate *this* cohort was recorded at |
|
|
350
|
+
| `hierarchical_experts`, `LSEMVAE` | Which lead configuration a study fine-tunes on |
|
|
351
|
+
| `elbo_loss`, `latent_alignment_loss` | The weights a paper reported |
|
|
352
|
+
| `binary_metrics`, `bootstrap_ci` | What the endpoint is, and where its threshold falls |
|
|
353
|
+
| `modality_ablation` | The figure it goes into |
|
|
354
|
+
|
|
355
|
+
Enforced by [`tests/test_package_structure.py`](tests/test_package_structure.py), which fails if a library module names a cohort outside a docstring, hardcodes an absolute path, or imports from `examples/`.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PyKale
|
|
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,18 @@
|
|
|
1
|
+
# The source distribution carries what running the test suite needs: the tests, and the
|
|
2
|
+
# examples they compose. Neither holds data -- every cohort a test uses is generated --
|
|
3
|
+
# and the exclusions below keep anything recording-, image- or checkpoint-shaped out.
|
|
4
|
+
# The wheel is unaffected: it ships the library alone.
|
|
5
|
+
graft tests
|
|
6
|
+
# Tests of the repository's .github automation, which a distribution does not carry.
|
|
7
|
+
prune tests/github
|
|
8
|
+
graft examples
|
|
9
|
+
graft docs
|
|
10
|
+
graft tutorials
|
|
11
|
+
include AGENTS.md API_overview.md
|
|
12
|
+
|
|
13
|
+
prune outputs
|
|
14
|
+
# The tutorials run from their own folder, so that is where they download and unpack their
|
|
15
|
+
# dataset and write their runs; none of it belongs in a distribution.
|
|
16
|
+
prune tutorials/*/data
|
|
17
|
+
prune tutorials/*/outputs
|
|
18
|
+
global-exclude __pycache__ *.py[cod] *.npy *.npz *.pt *.pth *.ckpt *.dcm *.edf *.hea *.dat *.zip
|