deepecgkit 0.2.0__tar.gz → 0.3.0__tar.gz

deepecgkit-0.3.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: deepecgkit
+Version: 0.3.0
+Summary: A deep learning toolkit for ECG analysis
+Author-email: Steven <steven@simula.no>
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: scipy>=1.8.0
+Requires-Dist: torch>=2.1.0
+Requires-Dist: pandas>=1.4.0
+Requires-Dist: scikit-learn>=1.1.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: wfdb>=4.0.0
+Requires-Dist: seaborn>=0.11.2
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: ruff>=0.11.13; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == "docs"
+Requires-Dist: mkdocs-autorefs>=1.0.0; extra == "docs"
+Dynamic: license-file
+
+# DeepECG-Kit
+
+A deep learning library for ECG analysis and arrhythmia classification. Provides a CLI for
+training, evaluation, inference, feature extraction, and explainability across 26 model
+architectures and 5 ECG datasets.
+
+**Documentation:** https://stevenah.github.io/deepecg-kit/
+
+## Installation
+
+```bash
+pip install deepecgkit
+```
+
+For local development (Python ≥ 3.10):
+
+```bash
+uv sync --group dev        # blessed path
+pip install -e ".[dev]"    # pip alternative
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
+
+## Usage
+
+```bash
+deepecg train -m kanres -d af-classification        # train (downloads the dataset, ~100 MB)
+deepecg evaluate --checkpoint runs/<run> -d af-classification
+deepecg predict --checkpoint runs/<run> --input ecg.npy --sampling-rate 300
+deepecg extract-features --checkpoint runs/<run> -d af-classification -o features.npz
+deepecg explain --checkpoint runs/<run> --input ecg.npy -o explanations/
+deepecg list-models                                  # all 26 architectures
+deepecg list-datasets                                # sizes, signal shape, local status
+deepecg info -m kanres
+```
+
+Training writes a run directory `runs/{timestamp}-{model}-{dataset}-seed{seed}/` containing
+checkpoints (top 3 by validation loss), training plots, test metrics
+(`classification_metrics.csv`, confusion matrix, calibration curve), and run metadata, and ends
+by printing the best checkpoint. Anywhere a checkpoint is expected, the run directory can be
+passed instead and stands for that best checkpoint.
+
+Checkpoints describe themselves: they record the architecture, the class names, and the
+preprocessing the training data went through (sampling rate, segment length, normalisation).
+That is why `--model` is optional above, why `deepecg evaluate` rebuilds the dataset the way
+the model was trained, and why `deepecg predict` can take a raw recording: it is resampled,
+segmented and normalised to match before it reaches the model.
+
+Run `deepecg list-models` and `deepecg list-datasets` for the full catalogs — datasets cover
+PhysioNet 2017 (`af-classification`), PTB-XL (`ptbxl`), MIT-BIH AFDB (`mitbih-afdb`),
+Long-Term AFDB (`ltafdb`), and the combined `unified-af`. Each dataset is used at its own
+sampling rate (300 Hz for the AF datasets, 500 Hz for PTB-XL) unless `--sampling-rate` says
+otherwise.
+
+Datasets are downloaded on first use into `~/.deepecgkit/datasets`; set `DEEPECGKIT_HOME` to
+keep them somewhere else. Downloads come from PhysioNet's open-data mirror, fall back to
+physionet.org, and resume if interrupted.
+
+## Experiments
+
+Experiment sweeps are defined in `experiments.yaml` and run via
+`python scripts/run_experiments.py`. Each experiment trains every configured model on every
+dataset across multiple seeds (default `seeds: [42, 43, 44, 45, 46]` — 5 runs per
+model/dataset pair), saving to `runs/{model}-{dataset}-seed{seed}/`.
+
+Aggregate and analyse finished runs with:
+
+```bash
+deepecg aggregate --runs-dir runs --output-dir analysis --emit-latex
+deepecg rank --runs-dir runs --metric f1
+```
+
+### Default Training Parameters
+
+Defined once in `deepecgkit/cli/defaults.py`:
+
+| Parameter | Value |
+|-----------|-------|
+| Epochs | 50 |
+| Batch size | 32 |
+| Learning rate | 0.001 |
+| Optimizer | Adam |
+| LR scheduler | ReduceLROnPlateau (factor=0.5, patience=5) |
+| Early stopping patience | 10 |
+| Validation split | 0.2 |
+| Test split | 0.1 |
+| Seed | 42 |
+| Sampling rate | the dataset's own (override with `--sampling-rate`) |
+| Data loader workers | 0 |
+
+## References
+
+### Datasets
+
+1. **af-classification** — Clifford GD, Liu C, Moody B, Li-wei HL, Silva I, Li Q, Johnson AE, Mark RG. "AF Classification from a Short Single Lead ECG Recording: The PhysioNet/Computing in Cardiology Challenge 2017." *Computing in Cardiology (CinC)*, 2017. [[PhysioNet]](https://physionet.org/content/challenge-2017/1.0.0/)
+
+2. **ptbxl** — Wagner P, Strodthoff N, Bousseljot RD, Kreiseler D, Lunze FI, Samek W, Schaeffter T. "PTB-XL, a Large Publicly Available Electrocardiography Dataset." *Scientific Data*, 7(1):154, 2020. [[PhysioNet]](https://physionet.org/content/ptb-xl/1.0.3/)
+
+3. **mitbih-afdb** — Moody GB, Mark RG. "A New Method for Detecting Atrial Fibrillation Using R-R Intervals." *Computers in Cardiology*, 10:227–230, 1983. [[PhysioNet]](https://physionet.org/content/afdb/1.0.0/)
+
+4. **ltafdb** — Petrutiu S, Sahakian AV, Swiryn S. "Abrupt Changes in Fibrillatory Wave Characteristics at the Termination of Paroxysmal Atrial Fibrillation in Humans." *Europace*, 9(7):466–470, 2007. [[PhysioNet]](https://physionet.org/content/ltafdb/1.0.0/)
+
+5. **unified-af** — Combined cross-dataset using af-classification, mitbih-afdb, and ltafdb (see references above).
+
+### Models
+
+6. **convnext-v2** — Woo S, Debnath S, Hu R, Chen X, Liu Z, Kweon IS, Xie S. "ConvNeXt V2: Co-designing and Scaling ConvNets with Masked Autoencoders." *CVPR*, 2023. [[GitHub]](https://github.com/facebookresearch/ConvNeXt-V2)
+
+7. **deep-res-cnn** — Elyamani H. "ECG Classification Using Deep Residual CNN." 2022. [[GitHub]](https://github.com/HaneenElyamani/ECG-classification)
+
+8. **inception-time** — Fawaz HI, Lucas B, Forestier G, Pelletier C, Schmidt DF, Weber J, Webb GI, Idoumghar L, Muller PA, Petitjean F. "InceptionTime: Finding AlexNet for Time Series Classification." *Data Mining and Knowledge Discovery*, 34:1936–1962, 2020. [[GitHub]](https://github.com/hfawaz/InceptionTime)
+
+9. **xresnet / xresnet1d-benchmark** — Strodthoff N, Wagner P, Schaeffter T, Samek W. "Deep Learning for ECG Analysis: Benchmarks and Insights from PTB-XL." *IEEE Journal of Biomedical and Health Informatics*, 25(5):1519–1528, 2021. [[GitHub]](https://github.com/helme/ecg_ptbxl_benchmarking)

deepecgkit-0.3.0/README.md

@@ -0,0 +1,113 @@
+# DeepECG-Kit
+
+A deep learning library for ECG analysis and arrhythmia classification. Provides a CLI for
+training, evaluation, inference, feature extraction, and explainability across 26 model
+architectures and 5 ECG datasets.
+
+**Documentation:** https://stevenah.github.io/deepecg-kit/
+
+## Installation
+
+```bash
+pip install deepecgkit
+```
+
+For local development (Python ≥ 3.10):
+
+```bash
+uv sync --group dev        # blessed path
+pip install -e ".[dev]"    # pip alternative
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
+
+## Usage
+
+```bash
+deepecg train -m kanres -d af-classification        # train (downloads the dataset, ~100 MB)
+deepecg evaluate --checkpoint runs/<run> -d af-classification
+deepecg predict --checkpoint runs/<run> --input ecg.npy --sampling-rate 300
+deepecg extract-features --checkpoint runs/<run> -d af-classification -o features.npz
+deepecg explain --checkpoint runs/<run> --input ecg.npy -o explanations/
+deepecg list-models                                  # all 26 architectures
+deepecg list-datasets                                # sizes, signal shape, local status
+deepecg info -m kanres
+```
+
+Training writes a run directory `runs/{timestamp}-{model}-{dataset}-seed{seed}/` containing
+checkpoints (top 3 by validation loss), training plots, test metrics
+(`classification_metrics.csv`, confusion matrix, calibration curve), and run metadata, and ends
+by printing the best checkpoint. Anywhere a checkpoint is expected, the run directory can be
+passed instead and stands for that best checkpoint.
+
+Checkpoints describe themselves: they record the architecture, the class names, and the
+preprocessing the training data went through (sampling rate, segment length, normalisation).
+That is why `--model` is optional above, why `deepecg evaluate` rebuilds the dataset the way
+the model was trained, and why `deepecg predict` can take a raw recording: it is resampled,
+segmented and normalised to match before it reaches the model.
+
+Run `deepecg list-models` and `deepecg list-datasets` for the full catalogs — datasets cover
+PhysioNet 2017 (`af-classification`), PTB-XL (`ptbxl`), MIT-BIH AFDB (`mitbih-afdb`),
+Long-Term AFDB (`ltafdb`), and the combined `unified-af`. Each dataset is used at its own
+sampling rate (300 Hz for the AF datasets, 500 Hz for PTB-XL) unless `--sampling-rate` says
+otherwise.
+
+Datasets are downloaded on first use into `~/.deepecgkit/datasets`; set `DEEPECGKIT_HOME` to
+keep them somewhere else. Downloads come from PhysioNet's open-data mirror, fall back to
+physionet.org, and resume if interrupted.
+
+## Experiments
+
+Experiment sweeps are defined in `experiments.yaml` and run via
+`python scripts/run_experiments.py`. Each experiment trains every configured model on every
+dataset across multiple seeds (default `seeds: [42, 43, 44, 45, 46]` — 5 runs per
+model/dataset pair), saving to `runs/{model}-{dataset}-seed{seed}/`.
+
+Aggregate and analyse finished runs with:
+
+```bash
+deepecg aggregate --runs-dir runs --output-dir analysis --emit-latex
+deepecg rank --runs-dir runs --metric f1
+```
+
+### Default Training Parameters
+
+Defined once in `deepecgkit/cli/defaults.py`:
+
+| Parameter | Value |
+|-----------|-------|
+| Epochs | 50 |
+| Batch size | 32 |
+| Learning rate | 0.001 |
+| Optimizer | Adam |
+| LR scheduler | ReduceLROnPlateau (factor=0.5, patience=5) |
+| Early stopping patience | 10 |
+| Validation split | 0.2 |
+| Test split | 0.1 |
+| Seed | 42 |
+| Sampling rate | the dataset's own (override with `--sampling-rate`) |
+| Data loader workers | 0 |
+
+## References
+
+### Datasets
+
+1. **af-classification** — Clifford GD, Liu C, Moody B, Li-wei HL, Silva I, Li Q, Johnson AE, Mark RG. "AF Classification from a Short Single Lead ECG Recording: The PhysioNet/Computing in Cardiology Challenge 2017." *Computing in Cardiology (CinC)*, 2017. [[PhysioNet]](https://physionet.org/content/challenge-2017/1.0.0/)
+
+2. **ptbxl** — Wagner P, Strodthoff N, Bousseljot RD, Kreiseler D, Lunze FI, Samek W, Schaeffter T. "PTB-XL, a Large Publicly Available Electrocardiography Dataset." *Scientific Data*, 7(1):154, 2020. [[PhysioNet]](https://physionet.org/content/ptb-xl/1.0.3/)
+
+3. **mitbih-afdb** — Moody GB, Mark RG. "A New Method for Detecting Atrial Fibrillation Using R-R Intervals." *Computers in Cardiology*, 10:227–230, 1983. [[PhysioNet]](https://physionet.org/content/afdb/1.0.0/)
+
+4. **ltafdb** — Petrutiu S, Sahakian AV, Swiryn S. "Abrupt Changes in Fibrillatory Wave Characteristics at the Termination of Paroxysmal Atrial Fibrillation in Humans." *Europace*, 9(7):466–470, 2007. [[PhysioNet]](https://physionet.org/content/ltafdb/1.0.0/)
+
+5. **unified-af** — Combined cross-dataset using af-classification, mitbih-afdb, and ltafdb (see references above).
+
+### Models
+
+6. **convnext-v2** — Woo S, Debnath S, Hu R, Chen X, Liu Z, Kweon IS, Xie S. "ConvNeXt V2: Co-designing and Scaling ConvNets with Masked Autoencoders." *CVPR*, 2023. [[GitHub]](https://github.com/facebookresearch/ConvNeXt-V2)
+
+7. **deep-res-cnn** — Elyamani H. "ECG Classification Using Deep Residual CNN." 2022. [[GitHub]](https://github.com/HaneenElyamani/ECG-classification)
+
+8. **inception-time** — Fawaz HI, Lucas B, Forestier G, Pelletier C, Schmidt DF, Weber J, Webb GI, Idoumghar L, Muller PA, Petitjean F. "InceptionTime: Finding AlexNet for Time Series Classification." *Data Mining and Knowledge Discovery*, 34:1936–1962, 2020. [[GitHub]](https://github.com/hfawaz/InceptionTime)
+
+9. **xresnet / xresnet1d-benchmark** — Strodthoff N, Wagner P, Schaeffter T, Samek W. "Deep Learning for ECG Analysis: Benchmarks and Insights from PTB-XL." *IEEE Journal of Biomedical and Health Informatics*, 25(5):1519–1528, 2021. [[GitHub]](https://github.com/helme/ecg_ptbxl_benchmarking)

deepecgkit-0.3.0/deepecgkit/__init__.py

@@ -0,0 +1,104 @@
+"""DeepECG-Kit: Deep learning library for ECG analysis and arrhythmia classification."""
+
+import importlib
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from deepecgkit.datasets import ECGDataModule
+    from deepecgkit.evaluation import ECGEvaluator
+    from deepecgkit.explainability import Attribution, ECGExplainer, explain
+    from deepecgkit.features import FeatureExtractor, FeatureSet, extract_features
+    from deepecgkit.models import KanResWideX
+    from deepecgkit.models.factory import build_model, build_model_from_checkpoint
+    from deepecgkit.registry import (
+        get_dataset_names,
+        get_model_names,
+        register_dataset,
+        register_model,
+    )
+    from deepecgkit.training import ECGTrainer
+    from deepecgkit.utils import read_csv
+    from deepecgkit.utils.device import resolve_device
+
+try:
+    __version__ = version("deepecgkit")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"
+
+__author__ = "DeepECG Kit Contributors"
+__license__ = "Apache-2.0"
+
+__all__ = [
+    "Attribution",
+    "ECGDataModule",
+    "ECGEvaluator",
+    "ECGExplainer",
+    "ECGTrainer",
+    "FeatureExtractor",
+    "FeatureSet",
+    "KanResWideX",
+    "build_model",
+    "build_model_from_checkpoint",
+    "explain",
+    "extract_features",
+    "get_dataset_names",
+    "get_model_names",
+    "read_csv",
+    "register_dataset",
+    "register_model",
+    "resolve_device",
+]
+
+#: Where each public name lives. A name is imported when it is first asked
+#: for, so `import deepecgkit` and the commands that need little of the
+#: package do not load PyTorch and the rest of the scientific stack.
+_EXPORTS = {
+    "Attribution": "deepecgkit.explainability",
+    "ECGDataModule": "deepecgkit.datasets",
+    "ECGEvaluator": "deepecgkit.evaluation",
+    "ECGExplainer": "deepecgkit.explainability",
+    "ECGTrainer": "deepecgkit.training",
+    "FeatureExtractor": "deepecgkit.features",
+    "FeatureSet": "deepecgkit.features",
+    "KanResWideX": "deepecgkit.models",
+    "build_model": "deepecgkit.models.factory",
+    "build_model_from_checkpoint": "deepecgkit.models.factory",
+    "explain": "deepecgkit.explainability",
+    "extract_features": "deepecgkit.features",
+    "get_dataset_names": "deepecgkit.registry",
+    "get_model_names": "deepecgkit.registry",
+    "read_csv": "deepecgkit.utils",
+    "register_dataset": "deepecgkit.registry",
+    "register_model": "deepecgkit.registry",
+    "resolve_device": "deepecgkit.utils.device",
+}
+_SUBMODULES = frozenset(
+    {
+        "analysis",
+        "cli",
+        "datasets",
+        "evaluation",
+        "explainability",
+        "features",
+        "models",
+        "registry",
+        "training",
+        "utils",
+    }
+)
+
+
+def __getattr__(name: str) -> Any:
+    if name in _EXPORTS:
+        value = getattr(importlib.import_module(_EXPORTS[name]), name)
+    elif name in _SUBMODULES:
+        value = importlib.import_module(f"{__name__}.{name}")
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *__all__, *_SUBMODULES})

deepecgkit-0.3.0/deepecgkit/_batching.py

@@ -0,0 +1,115 @@
+"""Shared input normalisation for model wrappers (internal).
+
+FeatureExtractor and ECGExplainer accept the same family of inputs — arrays,
+tensors, recording files, Datasets, DataLoaders, and ECGDataModules — and both
+need them as a non-shuffling DataLoader so row order stays joinable to external
+metadata. The dispatch lives here once.
+"""
+
+import warnings
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+from torch.utils.data import DataLoader, Dataset, RandomSampler, TensorDataset
+
+from deepecgkit.datasets.io import as_model_input, read_ecg_recording
+from deepecgkit.datasets.modules import ECGDataModule
+
+__all__ = ["as_inference_dataloader", "unpack_batch"]
+
+
+def as_inference_dataloader(
+    data: Any,
+    *,
+    split: str,
+    batch_size: int,
+    num_workers: int,
+    input_channels: int | None,
+    verb: str = "processed",
+) -> DataLoader:
+    """Normalise any supported input to a non-shuffling DataLoader.
+
+    Args:
+        data: An array, tensor, file path, Dataset, DataLoader, or ECGDataModule
+        split: Split name, used only for an ECGDataModule; "all" selects the
+            full dataset
+        batch_size: Batch size for loaders constructed here
+        num_workers: Worker count for loaders constructed here
+        input_channels: Lead count used to shape raw arrays for the model
+        verb: Past-tense verb naming the operation ("extracted", "explained"),
+            used in the shuffling warning
+
+    Returns:
+        A loader yielding either signals alone or (signals, labels).
+
+    Raises:
+        TypeError: If the input type is not supported.
+        RuntimeError: If a data module split is unavailable.
+    """
+
+    def build_loader(dataset: Dataset) -> DataLoader:
+        return DataLoader(
+            dataset,
+            batch_size=batch_size,
+            shuffle=False,
+            num_workers=num_workers,
+        )
+
+    if isinstance(data, ECGDataModule):
+        # The module's own train_dataloader shuffles, which would scramble row
+        # order, so the loader is constructed here instead.
+        if data.dataset is None or data.train_dataset is None:
+            data.setup()
+        subset = data.dataset if split == "all" else getattr(data, f"{split}_dataset")
+        if subset is None:
+            raise RuntimeError(f"Data module has no '{split}' split available.")
+        return build_loader(subset)
+
+    if isinstance(data, DataLoader):
+        if isinstance(data.sampler, RandomSampler):
+            warnings.warn(
+                f"The supplied DataLoader shuffles, so {verb} rows will not follow "
+                "dataset order and cannot be joined to external metadata. Pass "
+                "shuffle=False for a reproducible ordering.",
+                RuntimeWarning,
+                stacklevel=4,
+            )
+        return data
+
+    if isinstance(data, Dataset):
+        return build_loader(data)
+
+    if isinstance(data, str | Path):
+        array = as_model_input(read_ecg_recording(data), input_channels)
+        return build_loader(TensorDataset(torch.as_tensor(array)))
+
+    if isinstance(data, torch.Tensor):
+        array = as_model_input(data.detach().cpu().numpy(), input_channels)
+        return build_loader(TensorDataset(torch.as_tensor(array)))
+
+    if isinstance(data, np.ndarray):
+        array = as_model_input(data, input_channels)
+        return build_loader(TensorDataset(torch.as_tensor(array)))
+
+    raise TypeError(
+        f"Unsupported input type: {type(data).__name__}. Pass an array, tensor, file path, "
+        f"Dataset, DataLoader, or ECGDataModule."
+    )
+
+
+def unpack_batch(batch: Any) -> tuple[torch.Tensor, torch.Tensor | None]:
+    """Split a batch into signals and optional labels.
+
+    Args:
+        batch: A tensor, or a sequence whose first element is the signals
+
+    Returns:
+        Tuple of the signals and the labels, which are None when absent.
+    """
+    if isinstance(batch, list | tuple):
+        signals = batch[0]
+        labels = batch[1] if len(batch) > 1 else None
+        return signals, labels
+    return batch, None

deepecgkit-0.3.0/deepecgkit/_model_loading.py

@@ -0,0 +1,90 @@
+"""Shared model-loading machinery for wrapper classes (internal).
+
+FeatureExtractor and ECGExplainer both wrap a model they can load from
+registered pretrained weights, and both need to split caller kwargs between
+their own constructor and the model's. That logic lives here once.
+"""
+
+import inspect
+from pathlib import Path
+from typing import Any
+
+from torch import nn
+
+from deepecgkit.models.factory import infer_input_channels
+from deepecgkit.models.pretrained import from_pretrained, model_name_for_weights
+
+__all__ = [
+    "load_pretrained_resolving_name",
+    "model_input_channels",
+    "split_wrapper_kwargs",
+]
+
+
+def model_input_channels(model: nn.Module) -> int | None:
+    """Lead count declared by the model, or recovered from its weights.
+
+    Args:
+        model: The wrapped model
+
+    Returns:
+        The lead count, or None when unrecoverable.
+    """
+    declared = getattr(model, "input_channels", None)
+    if isinstance(declared, int):
+        return declared
+    return infer_input_channels(model.state_dict())
+
+
+def split_wrapper_kwargs(
+    wrapper_cls: type, kwargs: dict[str, Any]
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Split kwargs between a wrapper class's constructor and the model's.
+
+    The wrapper's accepted names are read from its ``__init__`` signature, so
+    adding a constructor parameter never requires updating a hand-maintained
+    key list.
+
+    Args:
+        wrapper_cls: The wrapper class (FeatureExtractor, ECGExplainer, ...)
+        kwargs: Mixed keyword arguments from the caller
+
+    Returns:
+        Tuple of (wrapper kwargs, model kwargs).
+    """
+    accepted = set(inspect.signature(wrapper_cls.__init__).parameters) - {
+        "self",
+        "model",
+        "model_name",
+    }
+    wrapper_kwargs = {k: v for k, v in kwargs.items() if k in accepted}
+    model_kwargs = {k: v for k, v in kwargs.items() if k not in accepted}
+    return wrapper_kwargs, model_kwargs
+
+
+def load_pretrained_resolving_name(
+    weights: str | Path,
+    model_name: str | None = None,
+    **model_kwargs: Any,
+) -> tuple[nn.Module, str]:
+    """Load pretrained weights, resolving the model name from the registry.
+
+    Args:
+        weights: Name of registered pretrained weights, or a path
+        model_name: Registered model name; inferred from the weight registry
+            when the weights are registered
+        **model_kwargs: Constructor arguments forwarded to the model
+
+    Returns:
+        Tuple of the loaded model and the resolved registry name.
+
+    Raises:
+        ValueError: If the model name is neither given nor inferable.
+    """
+    resolved = model_name or model_name_for_weights(str(weights))
+    if resolved is None:
+        raise ValueError(
+            f"Could not determine which model '{weights}' belongs to. Pass model_name explicitly."
+        )
+    model = from_pretrained(resolved, weights, **model_kwargs)
+    return model, resolved

deepecgkit-0.3.0/deepecgkit/analysis/__init__.py

@@ -0,0 +1,71 @@
+"""Post-hoc analysis of finished training runs.
+
+This subpackage aggregates the metrics written by completed runs, summarises
+them across random seeds, and tests whether cross-dataset ranking reversals
+survive that variance. It is distinct from
+:mod:`deepecgkit.evaluation`, which evaluates a live model.
+"""
+
+from deepecgkit.analysis.aggregation import (
+    RunRecord,
+    aggregate_runs,
+    discover_runs,
+    read_run_metrics,
+    reconcile_averaging,
+    runs_to_frame,
+)
+from deepecgkit.analysis.latex import (
+    escape_latex,
+    flip_survival_table,
+    rank_distribution_table,
+    results_table,
+    tau_table,
+    transfer_matrix_table,
+    write_tables,
+)
+from deepecgkit.analysis.ranking import (
+    all_flip_tests,
+    evaluate_rank_claim,
+    rank_distribution,
+    rank_within_seed,
+    tau_summary,
+)
+from deepecgkit.analysis.statistics import (
+    benjamini_yekutieli_adjust,
+    holm_adjust,
+    is_bimodal,
+    kendall_tau,
+    min_attainable_kendall_p,
+    nadeau_bengio_factor,
+    paired_summary,
+    summarize_scores,
+)
+
+__all__ = [
+    "RunRecord",
+    "aggregate_runs",
+    "all_flip_tests",
+    "benjamini_yekutieli_adjust",
+    "discover_runs",
+    "escape_latex",
+    "evaluate_rank_claim",
+    "flip_survival_table",
+    "holm_adjust",
+    "is_bimodal",
+    "kendall_tau",
+    "min_attainable_kendall_p",
+    "nadeau_bengio_factor",
+    "paired_summary",
+    "rank_distribution",
+    "rank_distribution_table",
+    "rank_within_seed",
+    "read_run_metrics",
+    "reconcile_averaging",
+    "results_table",
+    "runs_to_frame",
+    "summarize_scores",
+    "tau_summary",
+    "tau_table",
+    "transfer_matrix_table",
+    "write_tables",
+]