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.
Files changed (159) hide show
  1. kalecardiac-0.1.0a2/AGENTS.md +173 -0
  2. kalecardiac-0.1.0a2/API_overview.md +355 -0
  3. kalecardiac-0.1.0a2/LICENSE +21 -0
  4. kalecardiac-0.1.0a2/MANIFEST.in +18 -0
  5. kalecardiac-0.1.0a2/PKG-INFO +244 -0
  6. kalecardiac-0.1.0a2/README.md +193 -0
  7. kalecardiac-0.1.0a2/docs/architecture.md +173 -0
  8. kalecardiac-0.1.0a2/docs/conf.py +50 -0
  9. kalecardiac-0.1.0a2/docs/images/kalecardiac_logo_long.png +0 -0
  10. kalecardiac-0.1.0a2/docs/index.rst +45 -0
  11. kalecardiac-0.1.0a2/docs/kalecardiac.auto.rst +19 -0
  12. kalecardiac-0.1.0a2/docs/kalecardiac.evaluate.rst +33 -0
  13. kalecardiac-0.1.0a2/docs/kalecardiac.interpret.rst +19 -0
  14. kalecardiac-0.1.0a2/docs/kalecardiac.loaddata.rst +33 -0
  15. kalecardiac-0.1.0a2/docs/kalecardiac.model.embed.rst +40 -0
  16. kalecardiac-0.1.0a2/docs/kalecardiac.model.layers.rst +47 -0
  17. kalecardiac-0.1.0a2/docs/kalecardiac.model.predict.rst +19 -0
  18. kalecardiac-0.1.0a2/docs/kalecardiac.model.rst +5 -0
  19. kalecardiac-0.1.0a2/docs/kalecardiac.pipeline.rst +19 -0
  20. kalecardiac-0.1.0a2/docs/kalecardiac.prepdata.rst +26 -0
  21. kalecardiac-0.1.0a2/docs/kalecardiac.rst +12 -0
  22. kalecardiac-0.1.0a2/docs/kalecardiac.utils.rst +26 -0
  23. kalecardiac-0.1.0a2/docs/models.md +258 -0
  24. kalecardiac-0.1.0a2/docs/multimodal_fusion.md +135 -0
  25. kalecardiac-0.1.0a2/docs/quickstart.md +204 -0
  26. kalecardiac-0.1.0a2/docs/requirements.txt +3 -0
  27. kalecardiac-0.1.0a2/examples/README.md +79 -0
  28. kalecardiac-0.1.0a2/examples/__init__.py +1 -0
  29. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/README.md +112 -0
  30. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/__init__.py +1 -0
  31. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/config.py +125 -0
  32. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/configs/full.yaml +67 -0
  33. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/configs/quick.yaml +55 -0
  34. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/data.py +266 -0
  35. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/main.py +58 -0
  36. kalecardiac-0.1.0a2/examples/cardiovae_multimodal/runner.py +136 -0
  37. kalecardiac-0.1.0a2/examples/cli.py +59 -0
  38. kalecardiac-0.1.0a2/examples/lsemvae_ecg/README.md +136 -0
  39. kalecardiac-0.1.0a2/examples/lsemvae_ecg/__init__.py +1 -0
  40. kalecardiac-0.1.0a2/examples/lsemvae_ecg/config.py +130 -0
  41. kalecardiac-0.1.0a2/examples/lsemvae_ecg/configs/full.yaml +68 -0
  42. kalecardiac-0.1.0a2/examples/lsemvae_ecg/configs/quick.yaml +53 -0
  43. kalecardiac-0.1.0a2/examples/lsemvae_ecg/data.py +307 -0
  44. kalecardiac-0.1.0a2/examples/lsemvae_ecg/main.py +65 -0
  45. kalecardiac-0.1.0a2/examples/lsemvae_ecg/runner.py +279 -0
  46. kalecardiac-0.1.0a2/examples/synthetic_data.py +543 -0
  47. kalecardiac-0.1.0a2/kalecardiac/__init__.py +40 -0
  48. kalecardiac-0.1.0a2/kalecardiac/_version.txt +1 -0
  49. kalecardiac-0.1.0a2/kalecardiac/auto/__init__.py +67 -0
  50. kalecardiac-0.1.0a2/kalecardiac/auto/endpoint.py +277 -0
  51. kalecardiac-0.1.0a2/kalecardiac/auto/workflow.py +501 -0
  52. kalecardiac-0.1.0a2/kalecardiac/config.py +277 -0
  53. kalecardiac-0.1.0a2/kalecardiac/evaluate/__init__.py +61 -0
  54. kalecardiac-0.1.0a2/kalecardiac/evaluate/classification_metrics.py +170 -0
  55. kalecardiac-0.1.0a2/kalecardiac/evaluate/cross_validation.py +157 -0
  56. kalecardiac-0.1.0a2/kalecardiac/evaluate/predictions.py +151 -0
  57. kalecardiac-0.1.0a2/kalecardiac/evaluate/regression_metrics.py +38 -0
  58. kalecardiac-0.1.0a2/kalecardiac/interpret/__init__.py +55 -0
  59. kalecardiac-0.1.0a2/kalecardiac/interpret/attribution.py +532 -0
  60. kalecardiac-0.1.0a2/kalecardiac/interpret/latent.py +151 -0
  61. kalecardiac-0.1.0a2/kalecardiac/loaddata/__init__.py +131 -0
  62. kalecardiac-0.1.0a2/kalecardiac/loaddata/image_access.py +422 -0
  63. kalecardiac-0.1.0a2/kalecardiac/loaddata/multimodal_access.py +608 -0
  64. kalecardiac-0.1.0a2/kalecardiac/loaddata/signal_access.py +645 -0
  65. kalecardiac-0.1.0a2/kalecardiac/loaddata/splitting.py +352 -0
  66. kalecardiac-0.1.0a2/kalecardiac/model/__init__.py +67 -0
  67. kalecardiac-0.1.0a2/kalecardiac/model/embed/__init__.py +85 -0
  68. kalecardiac-0.1.0a2/kalecardiac/model/embed/cardiovae.py +255 -0
  69. kalecardiac-0.1.0a2/kalecardiac/model/embed/encoders.py +242 -0
  70. kalecardiac-0.1.0a2/kalecardiac/model/embed/lsemvae.py +151 -0
  71. kalecardiac-0.1.0a2/kalecardiac/model/embed/multimodal_fusion.py +387 -0
  72. kalecardiac-0.1.0a2/kalecardiac/model/embed/multimodal_vae.py +342 -0
  73. kalecardiac-0.1.0a2/kalecardiac/model/layers/__init__.py +81 -0
  74. kalecardiac-0.1.0a2/kalecardiac/model/layers/conv1d.py +285 -0
  75. kalecardiac-0.1.0a2/kalecardiac/model/layers/conv2d.py +261 -0
  76. kalecardiac-0.1.0a2/kalecardiac/model/layers/gaussian.py +425 -0
  77. kalecardiac-0.1.0a2/kalecardiac/model/layers/mlp.py +53 -0
  78. kalecardiac-0.1.0a2/kalecardiac/model/layers/residual1d.py +161 -0
  79. kalecardiac-0.1.0a2/kalecardiac/model/layers/transformer.py +162 -0
  80. kalecardiac-0.1.0a2/kalecardiac/model/predict/__init__.py +46 -0
  81. kalecardiac-0.1.0a2/kalecardiac/model/predict/heads.py +124 -0
  82. kalecardiac-0.1.0a2/kalecardiac/model/predict/losses.py +243 -0
  83. kalecardiac-0.1.0a2/kalecardiac/pipeline/__init__.py +33 -0
  84. kalecardiac-0.1.0a2/kalecardiac/pipeline/task.py +396 -0
  85. kalecardiac-0.1.0a2/kalecardiac/pipeline/trainer.py +209 -0
  86. kalecardiac-0.1.0a2/kalecardiac/prepdata/__init__.py +81 -0
  87. kalecardiac-0.1.0a2/kalecardiac/prepdata/ecg_transform.py +247 -0
  88. kalecardiac-0.1.0a2/kalecardiac/prepdata/image_transform.py +186 -0
  89. kalecardiac-0.1.0a2/kalecardiac/prepdata/signal_transform.py +251 -0
  90. kalecardiac-0.1.0a2/kalecardiac/py.typed +0 -0
  91. kalecardiac-0.1.0a2/kalecardiac/utils/__init__.py +19 -0
  92. kalecardiac-0.1.0a2/kalecardiac/utils/io.py +145 -0
  93. kalecardiac-0.1.0a2/kalecardiac/utils/renames.py +98 -0
  94. kalecardiac-0.1.0a2/kalecardiac/utils/seed.py +65 -0
  95. kalecardiac-0.1.0a2/kalecardiac.egg-info/PKG-INFO +244 -0
  96. kalecardiac-0.1.0a2/kalecardiac.egg-info/SOURCES.txt +157 -0
  97. kalecardiac-0.1.0a2/kalecardiac.egg-info/dependency_links.txt +1 -0
  98. kalecardiac-0.1.0a2/kalecardiac.egg-info/requires.txt +32 -0
  99. kalecardiac-0.1.0a2/kalecardiac.egg-info/top_level.txt +1 -0
  100. kalecardiac-0.1.0a2/pyproject.toml +139 -0
  101. kalecardiac-0.1.0a2/setup.cfg +4 -0
  102. kalecardiac-0.1.0a2/tests/__init__.py +0 -0
  103. kalecardiac-0.1.0a2/tests/auto/__init__.py +0 -0
  104. kalecardiac-0.1.0a2/tests/auto/test_endpoint.py +271 -0
  105. kalecardiac-0.1.0a2/tests/auto/test_workflow.py +410 -0
  106. kalecardiac-0.1.0a2/tests/conftest.py +123 -0
  107. kalecardiac-0.1.0a2/tests/evaluate/__init__.py +0 -0
  108. kalecardiac-0.1.0a2/tests/evaluate/test_cross_validation.py +134 -0
  109. kalecardiac-0.1.0a2/tests/evaluate/test_predictions.py +130 -0
  110. kalecardiac-0.1.0a2/tests/examples/__init__.py +0 -0
  111. kalecardiac-0.1.0a2/tests/examples/test_cli.py +119 -0
  112. kalecardiac-0.1.0a2/tests/examples/test_config_wiring.py +312 -0
  113. kalecardiac-0.1.0a2/tests/examples/test_endpoints.py +93 -0
  114. kalecardiac-0.1.0a2/tests/examples/test_example_workflows.py +372 -0
  115. kalecardiac-0.1.0a2/tests/examples/test_robustness.py +140 -0
  116. kalecardiac-0.1.0a2/tests/examples/test_synthetic_data.py +173 -0
  117. kalecardiac-0.1.0a2/tests/examples/test_tutorials.py +298 -0
  118. kalecardiac-0.1.0a2/tests/interpret/__init__.py +0 -0
  119. kalecardiac-0.1.0a2/tests/interpret/test_attribution.py +437 -0
  120. kalecardiac-0.1.0a2/tests/interpret/test_latent.py +163 -0
  121. kalecardiac-0.1.0a2/tests/loaddata/__init__.py +0 -0
  122. kalecardiac-0.1.0a2/tests/loaddata/test_image_access.py +288 -0
  123. kalecardiac-0.1.0a2/tests/loaddata/test_multimodal.py +266 -0
  124. kalecardiac-0.1.0a2/tests/loaddata/test_signal_access.py +453 -0
  125. kalecardiac-0.1.0a2/tests/loaddata/test_splitting.py +198 -0
  126. kalecardiac-0.1.0a2/tests/model/__init__.py +0 -0
  127. kalecardiac-0.1.0a2/tests/model/embed/__init__.py +0 -0
  128. kalecardiac-0.1.0a2/tests/model/embed/test_cardiac_models.py +361 -0
  129. kalecardiac-0.1.0a2/tests/model/embed/test_encoders.py +41 -0
  130. kalecardiac-0.1.0a2/tests/model/embed/test_multimodal_fusion.py +254 -0
  131. kalecardiac-0.1.0a2/tests/model/embed/test_multimodal_vae.py +290 -0
  132. kalecardiac-0.1.0a2/tests/model/layers/__init__.py +0 -0
  133. kalecardiac-0.1.0a2/tests/model/layers/test_backbones.py +359 -0
  134. kalecardiac-0.1.0a2/tests/model/layers/test_gaussian.py +380 -0
  135. kalecardiac-0.1.0a2/tests/model/predict/__init__.py +0 -0
  136. kalecardiac-0.1.0a2/tests/model/predict/test_heads.py +71 -0
  137. kalecardiac-0.1.0a2/tests/model/predict/test_losses.py +213 -0
  138. kalecardiac-0.1.0a2/tests/pipeline/__init__.py +0 -0
  139. kalecardiac-0.1.0a2/tests/pipeline/test_task.py +269 -0
  140. kalecardiac-0.1.0a2/tests/pipeline/test_trainer.py +292 -0
  141. kalecardiac-0.1.0a2/tests/prepdata/__init__.py +0 -0
  142. kalecardiac-0.1.0a2/tests/prepdata/test_ecg_transform.py +174 -0
  143. kalecardiac-0.1.0a2/tests/prepdata/test_image_transform.py +139 -0
  144. kalecardiac-0.1.0a2/tests/prepdata/test_signal_transform.py +202 -0
  145. kalecardiac-0.1.0a2/tests/regression/__init__.py +0 -0
  146. kalecardiac-0.1.0a2/tests/regression/test_end_to_end.py +402 -0
  147. kalecardiac-0.1.0a2/tests/test_config.py +193 -0
  148. kalecardiac-0.1.0a2/tests/test_docs.py +51 -0
  149. kalecardiac-0.1.0a2/tests/test_package_structure.py +211 -0
  150. kalecardiac-0.1.0a2/tests/utils/__init__.py +0 -0
  151. kalecardiac-0.1.0a2/tests/utils/test_io.py +147 -0
  152. kalecardiac-0.1.0a2/tests/utils/test_renames.py +65 -0
  153. kalecardiac-0.1.0a2/tests/utils/test_seed.py +86 -0
  154. kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_cardiovae_finetune.yaml +33 -0
  155. kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_cardiovae_pretrain.yaml +46 -0
  156. kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_lsemvae_finetune.yaml +41 -0
  157. kalecardiac-0.1.0a2/tutorials/mdas_tutorial/configs/config_lsemvae_pretrain.yaml +56 -0
  158. kalecardiac-0.1.0a2/tutorials/mdas_tutorial/tutorial-CardioVAE.ipynb +807 -0
  159. 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