MaldiDeepKit 0.1.0__tar.gz → 0.3.0__tar.gz

{maldideepkit-0.1.0 → maldideepkit-0.3.0/MaldiDeepKit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiDeepKit
-Version: 0.1.0
+Version: 0.3.0
 Summary: A catalog of sklearn-compatible deep learning classifiers for MALDI-TOF binned spectra
 Author-email: Ettore Rocchi <ettore.rocchi3@unibo.it>
 License-Expression: MIT
@@ -30,7 +30,7 @@ Requires-Dist: scikit-learn>=1.3.0
 Requires-Dist: matplotlib>=3.4.0
 Requires-Dist: torch>=2.0.0
 Requires-Dist: einops>=0.7.0
-Requires-Dist: maldiamrkit>=0.12.0
+Requires-Dist: maldiamrkit>=0.19.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -45,6 +45,13 @@ Requires-Dist: sphinx-design>=0.6.0; extra == "docs"
 Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
 Requires-Dist: ipykernel>=6.0.0; extra == "docs"
 Requires-Dist: ipywidgets>=8.0.0; extra == "docs"
+Provides-Extra: uncertainty
+Requires-Dist: laplace-torch<1.0,>=0.2; extra == "uncertainty"
+Provides-Extra: rdkit
+Requires-Dist: rdkit>=2026.3.1; extra == "rdkit"
+Provides-Extra: all
+Requires-Dist: rdkit>=2026.3.1; extra == "all"
+Requires-Dist: laplace-torch<1.0,>=0.2; extra == "all"
 Dynamic: license-file
 
 # MaldiDeepKit
@@ -77,7 +84,7 @@ Dynamic: license-file
   <a href="#license">License</a>
 </p>
 
-MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit): where MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation, and MaldiBatchKit harmonises multi-centre spectra, MaldiDeepKit focuses on the *classification* step, providing four PyTorch architectures wrapped in a unified scikit-learn estimator API with defaults calibrated for 6000-bin MALDI-TOF input.
+MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit): where MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation, and MaldiBatchKit harmonises multi-centre spectra, MaldiDeepKit focuses on the *classification* step, providing four PyTorch backbone architectures (MLP, 1-D CNN, 1-D ResNet, and 1-D Vision Transformer) plus a dual-branch classifier for spectrum + side-feature inputs and a self-training meta-classifier for semi-supervised data, all wrapped in a unified scikit-learn estimator API with defaults calibrated for 6000-bin MALDI-TOF input.
 
 ## Installation
 
@@ -85,7 +92,31 @@ MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKi
 pip install maldideepkit
 ```
 
-`maldiamrkit` is a core dependency and is installed automatically - MaldiDeepKit duck-types on the `MaldiSet` data model and reuses `maldiamrkit.alignment.Warping` for leak-safe spectral warping.
+`maldiamrkit` is a core dependency and is installed automatically (MaldiDeepKit duck-types on the `MaldiSet` data model and reuses `maldiamrkit.alignment.Warping` for leak-safe spectral warping).
+
+To enable the Laplace-approximation estimator in `maldideepkit.uncertainty`, install the optional `uncertainty` extra (pulls in [`laplace-torch`](https://github.com/aleximmer/Laplace)):
+
+```bash
+pip install "maldideepkit[uncertainty]"
+```
+
+Monte Carlo Dropout and split conformal prediction work without any extra.
+
+The `smiles_to_fingerprint` helper used in `MaldiDualBranchClassifier` workflows requires RDKit, available via the `rdkit` extra:
+
+```bash
+pip install "maldideepkit[rdkit]"
+```
+
+### Install the full MaldiSuite
+
+To install MaldiDeepKit together with [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit) at compatible versions, install the [`maldisuite`](https://pypi.org/project/maldisuite/) meta-package:
+
+```bash
+pip install maldisuite
+```
+
+Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSuite/>.
 
 ### Development Installation
 
@@ -108,10 +139,11 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for coding conventions, testing, and PR
   - `MaldiTransformerClassifier` - 1-D Vision Transformer with global self-attention, pre-norm, LayerScale, and stochastic depth.
 - **MALDI-TOF defaults**: kernel sizes, depths, patch widths, and warmup / cosine-annealing schedules are tuned for 6000-bin spectra in the 2000-20000 Da range.
 - **Auto-scaling for non-default layouts**: every classifier ships a `from_spectrum(bin_width, input_dim, **overrides)` factory that rescales conv kernels and patches when the user trims the m/z range or picks a different bin width. See the [Spectrum scaling guide](https://maldideepkit.readthedocs.io/en/latest/spectrum_scaling.html).
-- **Training recipes**: AdamW-on-`weight_decay` dispatch, gradient clipping, linear warmup + cosine annealing, focal loss, label smoothing, mixed precision (AMP), Stochastic Weight Averaging, Sharpness-Aware Minimization, post-hoc threshold tuning, and temperature scaling - all exposed as classifier kwargs.
+- **Training recipes**: AdamW-on-`weight_decay` dispatch, gradient clipping, linear warmup + cosine annealing, focal loss, label smoothing, mixed precision (AMP), Stochastic Weight Averaging, Sharpness-Aware Minimization, post-hoc threshold tuning, and temperature scaling (all exposed as classifier kwargs).
 - **Leak-safe spectral warping**: pass any sklearn-style transformer ([`maldiamrkit.alignment.Warping`](https://github.com/EttoreRocchi/MaldiAMRKit)) via `warping=`; it is fitted on the training fold only and applied to both splits during training and to new spectra at `predict` time, *before* per-feature standardization.
 - **MaldiSet integration**: pass a `maldiamrkit.MaldiSet` directly to `fit` / `predict`; MaldiDeepKit duck-types on the DataFrame-like `.X` attribute, so MaldiSuite's data model flows end-to-end.
 - **Persistence**: `save()` writes a state-dict `.pt` plus a hyperparameter `.json` (and a sibling `.warper.pkl` if a warper was fitted); `load()` fails fast on class or `input_dim` mismatches.
+- **Uncertainty quantification**: `maldideepkit.uncertainty` subpackage ships three drop-in estimators sharing a single `predict_with_uncertainty` interface. `MCDropoutEstimator` (Monte Carlo Dropout with epistemic / aleatoric decomposition), `LaplaceEstimator` (last-layer or full-network Laplace via the optional `laplace-torch` dependency), and `ConformalPredictor` (split conformal prediction with the LAC non-conformity score).
 - **CPU-friendly**: every classifier runs on CPU, which is what the project's CI tests against; CUDA speeds up the models' training significantly.
 
 ## Documentation
@@ -143,7 +175,7 @@ acc = clf.score(X, y)
 weights = clf.get_attention_weights(X[:10])  # (10, hidden_dim)
 ```
 
-### Inside an Sklearn Pipeline
+### Inside a scikit-learn `Pipeline`
 
 ```python
 from sklearn.model_selection import StratifiedKFold, cross_val_score
@@ -215,8 +247,15 @@ For more examples covering training recipes, calibration, attention inspection,
 | `MaldiCNNClassifier`           | 1-D Conv1D + BatchNorm + ReLU + MaxPool blocks         | Local pattern learning from binned spectra             |
 | `MaldiResNetClassifier`        | 1-D ResNet-18-style residual blocks                    | Deeper convolutional backbone                          |
 | `MaldiTransformerClassifier`   | 1-D Vision Transformer (LayerScale, stochastic depth)  | Long-range peak combinations via global self-attention |
+| `MaldiDualBranchClassifier`    | Spectrum branch + per-row side-feature branch + fused head | Multi-modal: condition on antibiotic fingerprint, instrument ID, patient feature, ... |
+
+All five inherit from `BaseSpectralClassifier` (or its dual-input subclass `BaseDualSpectralClassifier`) and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
 
-All four inherit from `BaseSpectralClassifier` and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
+### Semi-supervised wrapper
+
+| Class | Purpose |
+|---|---|
+| `MaldiSelfTrainingClassifier` | Iterative pseudo-labeling on a labeled seed plus an unlabeled pool (rows marked `-1` by default). Wraps any classifier (defaults to `MaldiMLPClassifier`); follows the `sklearn.semi_supervised.SelfTrainingClassifier` API. |
 
 ### Shared Training Knobs
 
@@ -226,7 +265,7 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 | Gradient clipping                  | `grad_clip_norm`               | `clip_grad_norm_` before every step. Default on (`1.0`) for the deep models.        |
 | Warmup + cosine annealing          | `warmup_epochs`                | Replaces plateau scheduler. Default `5` (deep models), `0` (MLP/CNN).               |
 | Stochastic depth (Transformer)     | `drop_path_rate`               | Linearly ramped across blocks. Default `0.1`.                                       |
-| LayerScale (Transformer)           | `layerscale_init`              | Per-channel residual scaling initialised near zero - crucial on small cohorts.      |
+| LayerScale (Transformer)           | `layerscale_init`              | Per-channel residual scaling initialised near zero (crucial on small cohorts).      |
 | Focal loss                         | `loss="focal"` + `focal_gamma` | For imbalanced binary problems.                                                     |
 | Label smoothing                    | `label_smoothing`              | Passed to both cross-entropy and focal paths.                                       |
 | Stochastic Weight Averaging        | `swa_start_epoch`              | `AveragedModel` replaces best-val at end of fit.                                    |
@@ -234,6 +273,8 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 | Temperature scaling                | `calibrate_temperature`        | One-parameter LBFGS calibration on val logits.                                      |
 | Sharpness-Aware Minimization       | `use_sam` + `sam_rho`          | Two-pass training, ~2× compute.                                                     |
 | Spectral warping                   | `warping`                      | Any `Warping`-like sklearn transformer; fitted on train only, applied before standardization.      |
+| Per-sample weighting               | `sample_weight` (`fit`)        | sklearn-style weighted-mean loss; composes with `class_weight` and flows into early stopping, threshold tuning, and temperature scaling. |
+| Warm-start / resume                | `warm_start` (`fit`)           | Reuse the existing fitted module as the training start point (continual / federated / fine-tuning).  |
 
 ### Utilities
 
@@ -241,7 +282,7 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 
 - **`find_lr(clf, X, y)`** - learning-rate finder.
 - **`tune_threshold` / `fit_temperature`** - post-hoc calibrators usable standalone.
-- **`FocalLoss`, `SAMOptimizer`, `DropPath`** - building blocks for custom training loops.
+- **`FocalLoss`, `SAMOptimizer`** - loss / optimizer building blocks for custom training loops. Composable `nn.Module` primitives (`DropPath`, `PatchEmbed1D`, the full backbones) live under `maldideepkit.blocks`.
 
 ## Tutorials
 
@@ -251,16 +292,17 @@ For more detailed examples, see the notebooks:
 - [Model Comparison](notebooks/02_model_comparison.ipynb) - Train all four classifiers on the same dataset and compare accuracy.
 - [Attention Interpretation](notebooks/03_attention_interpretation.ipynb) - Visualise the sigmoid-gated attention learned by `MaldiMLPClassifier`.
 - [Full Pipeline](notebooks/04_full_pipeline.ipynb) - End-to-end template: MaldiAMRKit preprocessing + MaldiDeepKit classification.
+- [Uncertainty Quantification](notebooks/05_uncertainty.ipynb) - MC Dropout, split conformal prediction, and Laplace approximation on a fitted classifier; selective prediction curves.
 
 ## MaldiSuite Ecosystem
 
-MaldiDeepKit is the third package of the MaldiSuite ecosystem:
+MaldiDeepKit is the deep-learning package of the **MaldiSuite** ecosystem:
 
 - **[MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit)** - preprocessing, alignment, peak detection, differential analysis, and classical-ML evaluation for MALDI-TOF AMR workflows.
 - **[MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit)** - batch-effect correction and harmonisation for multi-centre / multi-instrument MALDI-TOF spectra.
 - **MaldiDeepKit** (this package) - sklearn-compatible deep learning classifiers.
 
-The three packages share the `MaldiSet` / `MaldiSpectrum` data model and are designed to compose in a single end-to-end pipeline.
+The three packages share the `MaldiSet` / `MaldiSpectrum` data model and are designed to compose in a single end-to-end pipeline. Install the full suite with `pip install maldisuite`. Landing page: [MaldiSuite](<https://ettorerocchi.github.io/MaldiSuite/>).
 
 ## Requirements
 
@@ -272,11 +314,9 @@ Pull requests, bug reports, and feature ideas are welcome. See the [Contributing
 
 ## Citing
 
-If you use MaldiDeepKit, please cite this repository until the companion paper is available.
-
-Related publications from the MaldiSuite ecosystem:
+If you use MaldiDeepKit in academic work please cite:
 
-> Rocchi, E., Nicitra, E., Calvo, M. et al. *Combining mass spectrometry and machine learning models for predicting Klebsiella pneumoniae antimicrobial resistance: a multicenter experience from clinical isolates in Italy*. **BMC Microbiol** (2026). [doi:10.1186/s12866-025-04657-2](https://link.springer.com/article/10.1186/s12866-025-04657-2)
+> _Citation will be available soon._
 
 See the [full publications list](https://maldideepkit.readthedocs.io/en/latest/papers.html) for more papers using the MaldiSuite.
 

{maldideepkit-0.1.0 → maldideepkit-0.3.0}/MaldiDeepKit.egg-info/SOURCES.txt

@@ -1,8 +1,11 @@
 LICENSE
 README.md
 pyproject.toml
+requirements-all.txt
 requirements-dev.txt
 requirements-docs.txt
+requirements-rdkit.txt
+requirements-uncertainty.txt
 requirements.txt
 MaldiDeepKit.egg-info/PKG-INFO
 MaldiDeepKit.egg-info/SOURCES.txt
@@ -22,12 +25,24 @@ maldideepkit/augment/spectra.py
 maldideepkit/base/__init__.py
 maldideepkit/base/classifier.py
 maldideepkit/base/data.py
+maldideepkit/base/dual.py
 maldideepkit/cnn/__init__.py
 maldideepkit/cnn/cnn.py
+maldideepkit/dual_branch/__init__.py
+maldideepkit/dual_branch/_smiles.py
+maldideepkit/dual_branch/classifier.py
 maldideepkit/resnet/__init__.py
 maldideepkit/resnet/resnet.py
+maldideepkit/semisupervised/__init__.py
+maldideepkit/semisupervised/self_training.py
 maldideepkit/transformer/__init__.py
 maldideepkit/transformer/transformer.py
+maldideepkit/uncertainty/__init__.py
+maldideepkit/uncertainty/_base.py
+maldideepkit/uncertainty/_result.py
+maldideepkit/uncertainty/conformal.py
+maldideepkit/uncertainty/laplace.py
+maldideepkit/uncertainty/mc_dropout.py
 maldideepkit/utils/__init__.py
 maldideepkit/utils/calibration.py
 maldideepkit/utils/ensemble.py
@@ -42,6 +57,7 @@ tests/test_bin_scaling.py
 tests/test_blocks.py
 tests/test_calibration.py
 tests/test_cnn.py
+tests/test_dual_branch.py
 tests/test_ensemble.py
 tests/test_loss.py
 tests/test_lr_finder.py
@@ -49,6 +65,10 @@ tests/test_maldiset_integration.py
 tests/test_mlp.py
 tests/test_resnet.py
 tests/test_sam.py
+tests/test_sample_weight.py
+tests/test_self_training.py
 tests/test_sklearn_compat.py
 tests/test_transformer.py
+tests/test_uncertainty.py
+tests/test_warm_start.py
 tests/test_warping.py

{maldideepkit-0.1.0 → maldideepkit-0.3.0}/MaldiDeepKit.egg-info/requires.txt

@@ -5,7 +5,11 @@ scikit-learn>=1.3.0
 matplotlib>=3.4.0
 torch>=2.0.0
 einops>=0.7.0
-maldiamrkit>=0.12.0
+maldiamrkit>=0.19.0
+
+[all]
+rdkit>=2026.3.1
+laplace-torch<1.0,>=0.2
 
 [dev]
 pytest>=7.0.0
@@ -22,3 +26,9 @@ sphinx-design>=0.6.0
 nbsphinx>=0.9.0
 ipykernel>=6.0.0
 ipywidgets>=8.0.0
+
+[rdkit]
+rdkit>=2026.3.1
+
+[uncertainty]
+laplace-torch<1.0,>=0.2

{maldideepkit-0.1.0/MaldiDeepKit.egg-info → maldideepkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiDeepKit
-Version: 0.1.0
+Version: 0.3.0
 Summary: A catalog of sklearn-compatible deep learning classifiers for MALDI-TOF binned spectra
 Author-email: Ettore Rocchi <ettore.rocchi3@unibo.it>
 License-Expression: MIT
@@ -30,7 +30,7 @@ Requires-Dist: scikit-learn>=1.3.0
 Requires-Dist: matplotlib>=3.4.0
 Requires-Dist: torch>=2.0.0
 Requires-Dist: einops>=0.7.0
-Requires-Dist: maldiamrkit>=0.12.0
+Requires-Dist: maldiamrkit>=0.19.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -45,6 +45,13 @@ Requires-Dist: sphinx-design>=0.6.0; extra == "docs"
 Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
 Requires-Dist: ipykernel>=6.0.0; extra == "docs"
 Requires-Dist: ipywidgets>=8.0.0; extra == "docs"
+Provides-Extra: uncertainty
+Requires-Dist: laplace-torch<1.0,>=0.2; extra == "uncertainty"
+Provides-Extra: rdkit
+Requires-Dist: rdkit>=2026.3.1; extra == "rdkit"
+Provides-Extra: all
+Requires-Dist: rdkit>=2026.3.1; extra == "all"
+Requires-Dist: laplace-torch<1.0,>=0.2; extra == "all"
 Dynamic: license-file
 
 # MaldiDeepKit
@@ -77,7 +84,7 @@ Dynamic: license-file
   <a href="#license">License</a>
 </p>
 
-MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit): where MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation, and MaldiBatchKit harmonises multi-centre spectra, MaldiDeepKit focuses on the *classification* step, providing four PyTorch architectures wrapped in a unified scikit-learn estimator API with defaults calibrated for 6000-bin MALDI-TOF input.
+MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit): where MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation, and MaldiBatchKit harmonises multi-centre spectra, MaldiDeepKit focuses on the *classification* step, providing four PyTorch backbone architectures (MLP, 1-D CNN, 1-D ResNet, and 1-D Vision Transformer) plus a dual-branch classifier for spectrum + side-feature inputs and a self-training meta-classifier for semi-supervised data, all wrapped in a unified scikit-learn estimator API with defaults calibrated for 6000-bin MALDI-TOF input.
 
 ## Installation
 
@@ -85,7 +92,31 @@ MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKi
 pip install maldideepkit
 ```
 
-`maldiamrkit` is a core dependency and is installed automatically - MaldiDeepKit duck-types on the `MaldiSet` data model and reuses `maldiamrkit.alignment.Warping` for leak-safe spectral warping.
+`maldiamrkit` is a core dependency and is installed automatically (MaldiDeepKit duck-types on the `MaldiSet` data model and reuses `maldiamrkit.alignment.Warping` for leak-safe spectral warping).
+
+To enable the Laplace-approximation estimator in `maldideepkit.uncertainty`, install the optional `uncertainty` extra (pulls in [`laplace-torch`](https://github.com/aleximmer/Laplace)):
+
+```bash
+pip install "maldideepkit[uncertainty]"
+```
+
+Monte Carlo Dropout and split conformal prediction work without any extra.
+
+The `smiles_to_fingerprint` helper used in `MaldiDualBranchClassifier` workflows requires RDKit, available via the `rdkit` extra:
+
+```bash
+pip install "maldideepkit[rdkit]"
+```
+
+### Install the full MaldiSuite
+
+To install MaldiDeepKit together with [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit) at compatible versions, install the [`maldisuite`](https://pypi.org/project/maldisuite/) meta-package:
+
+```bash
+pip install maldisuite
+```
+
+Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSuite/>.
 
 ### Development Installation
 
@@ -108,10 +139,11 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for coding conventions, testing, and PR
   - `MaldiTransformerClassifier` - 1-D Vision Transformer with global self-attention, pre-norm, LayerScale, and stochastic depth.
 - **MALDI-TOF defaults**: kernel sizes, depths, patch widths, and warmup / cosine-annealing schedules are tuned for 6000-bin spectra in the 2000-20000 Da range.
 - **Auto-scaling for non-default layouts**: every classifier ships a `from_spectrum(bin_width, input_dim, **overrides)` factory that rescales conv kernels and patches when the user trims the m/z range or picks a different bin width. See the [Spectrum scaling guide](https://maldideepkit.readthedocs.io/en/latest/spectrum_scaling.html).
-- **Training recipes**: AdamW-on-`weight_decay` dispatch, gradient clipping, linear warmup + cosine annealing, focal loss, label smoothing, mixed precision (AMP), Stochastic Weight Averaging, Sharpness-Aware Minimization, post-hoc threshold tuning, and temperature scaling - all exposed as classifier kwargs.
+- **Training recipes**: AdamW-on-`weight_decay` dispatch, gradient clipping, linear warmup + cosine annealing, focal loss, label smoothing, mixed precision (AMP), Stochastic Weight Averaging, Sharpness-Aware Minimization, post-hoc threshold tuning, and temperature scaling (all exposed as classifier kwargs).
 - **Leak-safe spectral warping**: pass any sklearn-style transformer ([`maldiamrkit.alignment.Warping`](https://github.com/EttoreRocchi/MaldiAMRKit)) via `warping=`; it is fitted on the training fold only and applied to both splits during training and to new spectra at `predict` time, *before* per-feature standardization.
 - **MaldiSet integration**: pass a `maldiamrkit.MaldiSet` directly to `fit` / `predict`; MaldiDeepKit duck-types on the DataFrame-like `.X` attribute, so MaldiSuite's data model flows end-to-end.
 - **Persistence**: `save()` writes a state-dict `.pt` plus a hyperparameter `.json` (and a sibling `.warper.pkl` if a warper was fitted); `load()` fails fast on class or `input_dim` mismatches.
+- **Uncertainty quantification**: `maldideepkit.uncertainty` subpackage ships three drop-in estimators sharing a single `predict_with_uncertainty` interface. `MCDropoutEstimator` (Monte Carlo Dropout with epistemic / aleatoric decomposition), `LaplaceEstimator` (last-layer or full-network Laplace via the optional `laplace-torch` dependency), and `ConformalPredictor` (split conformal prediction with the LAC non-conformity score).
 - **CPU-friendly**: every classifier runs on CPU, which is what the project's CI tests against; CUDA speeds up the models' training significantly.
 
 ## Documentation
@@ -143,7 +175,7 @@ acc = clf.score(X, y)
 weights = clf.get_attention_weights(X[:10])  # (10, hidden_dim)
 ```
 
-### Inside an Sklearn Pipeline
+### Inside a scikit-learn `Pipeline`
 
 ```python
 from sklearn.model_selection import StratifiedKFold, cross_val_score
@@ -215,8 +247,15 @@ For more examples covering training recipes, calibration, attention inspection,
 | `MaldiCNNClassifier`           | 1-D Conv1D + BatchNorm + ReLU + MaxPool blocks         | Local pattern learning from binned spectra             |
 | `MaldiResNetClassifier`        | 1-D ResNet-18-style residual blocks                    | Deeper convolutional backbone                          |
 | `MaldiTransformerClassifier`   | 1-D Vision Transformer (LayerScale, stochastic depth)  | Long-range peak combinations via global self-attention |
+| `MaldiDualBranchClassifier`    | Spectrum branch + per-row side-feature branch + fused head | Multi-modal: condition on antibiotic fingerprint, instrument ID, patient feature, ... |
+
+All five inherit from `BaseSpectralClassifier` (or its dual-input subclass `BaseDualSpectralClassifier`) and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
 
-All four inherit from `BaseSpectralClassifier` and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
+### Semi-supervised wrapper
+
+| Class | Purpose |
+|---|---|
+| `MaldiSelfTrainingClassifier` | Iterative pseudo-labeling on a labeled seed plus an unlabeled pool (rows marked `-1` by default). Wraps any classifier (defaults to `MaldiMLPClassifier`); follows the `sklearn.semi_supervised.SelfTrainingClassifier` API. |
 
 ### Shared Training Knobs
 
@@ -226,7 +265,7 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 | Gradient clipping                  | `grad_clip_norm`               | `clip_grad_norm_` before every step. Default on (`1.0`) for the deep models.        |
 | Warmup + cosine annealing          | `warmup_epochs`                | Replaces plateau scheduler. Default `5` (deep models), `0` (MLP/CNN).               |
 | Stochastic depth (Transformer)     | `drop_path_rate`               | Linearly ramped across blocks. Default `0.1`.                                       |
-| LayerScale (Transformer)           | `layerscale_init`              | Per-channel residual scaling initialised near zero - crucial on small cohorts.      |
+| LayerScale (Transformer)           | `layerscale_init`              | Per-channel residual scaling initialised near zero (crucial on small cohorts).      |
 | Focal loss                         | `loss="focal"` + `focal_gamma` | For imbalanced binary problems.                                                     |
 | Label smoothing                    | `label_smoothing`              | Passed to both cross-entropy and focal paths.                                       |
 | Stochastic Weight Averaging        | `swa_start_epoch`              | `AveragedModel` replaces best-val at end of fit.                                    |
@@ -234,6 +273,8 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 | Temperature scaling                | `calibrate_temperature`        | One-parameter LBFGS calibration on val logits.                                      |
 | Sharpness-Aware Minimization       | `use_sam` + `sam_rho`          | Two-pass training, ~2× compute.                                                     |
 | Spectral warping                   | `warping`                      | Any `Warping`-like sklearn transformer; fitted on train only, applied before standardization.      |
+| Per-sample weighting               | `sample_weight` (`fit`)        | sklearn-style weighted-mean loss; composes with `class_weight` and flows into early stopping, threshold tuning, and temperature scaling. |
+| Warm-start / resume                | `warm_start` (`fit`)           | Reuse the existing fitted module as the training start point (continual / federated / fine-tuning).  |
 
 ### Utilities
 
@@ -241,7 +282,7 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 
 - **`find_lr(clf, X, y)`** - learning-rate finder.
 - **`tune_threshold` / `fit_temperature`** - post-hoc calibrators usable standalone.
-- **`FocalLoss`, `SAMOptimizer`, `DropPath`** - building blocks for custom training loops.
+- **`FocalLoss`, `SAMOptimizer`** - loss / optimizer building blocks for custom training loops. Composable `nn.Module` primitives (`DropPath`, `PatchEmbed1D`, the full backbones) live under `maldideepkit.blocks`.
 
 ## Tutorials
 
@@ -251,16 +292,17 @@ For more detailed examples, see the notebooks:
 - [Model Comparison](notebooks/02_model_comparison.ipynb) - Train all four classifiers on the same dataset and compare accuracy.
 - [Attention Interpretation](notebooks/03_attention_interpretation.ipynb) - Visualise the sigmoid-gated attention learned by `MaldiMLPClassifier`.
 - [Full Pipeline](notebooks/04_full_pipeline.ipynb) - End-to-end template: MaldiAMRKit preprocessing + MaldiDeepKit classification.
+- [Uncertainty Quantification](notebooks/05_uncertainty.ipynb) - MC Dropout, split conformal prediction, and Laplace approximation on a fitted classifier; selective prediction curves.
 
 ## MaldiSuite Ecosystem
 
-MaldiDeepKit is the third package of the MaldiSuite ecosystem:
+MaldiDeepKit is the deep-learning package of the **MaldiSuite** ecosystem:
 
 - **[MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit)** - preprocessing, alignment, peak detection, differential analysis, and classical-ML evaluation for MALDI-TOF AMR workflows.
 - **[MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit)** - batch-effect correction and harmonisation for multi-centre / multi-instrument MALDI-TOF spectra.
 - **MaldiDeepKit** (this package) - sklearn-compatible deep learning classifiers.
 
-The three packages share the `MaldiSet` / `MaldiSpectrum` data model and are designed to compose in a single end-to-end pipeline.
+The three packages share the `MaldiSet` / `MaldiSpectrum` data model and are designed to compose in a single end-to-end pipeline. Install the full suite with `pip install maldisuite`. Landing page: [MaldiSuite](<https://ettorerocchi.github.io/MaldiSuite/>).
 
 ## Requirements
 
@@ -272,11 +314,9 @@ Pull requests, bug reports, and feature ideas are welcome. See the [Contributing
 
 ## Citing
 
-If you use MaldiDeepKit, please cite this repository until the companion paper is available.
-
-Related publications from the MaldiSuite ecosystem:
+If you use MaldiDeepKit in academic work please cite:
 
-> Rocchi, E., Nicitra, E., Calvo, M. et al. *Combining mass spectrometry and machine learning models for predicting Klebsiella pneumoniae antimicrobial resistance: a multicenter experience from clinical isolates in Italy*. **BMC Microbiol** (2026). [doi:10.1186/s12866-025-04657-2](https://link.springer.com/article/10.1186/s12866-025-04657-2)
+> _Citation will be available soon._
 
 See the [full publications list](https://maldideepkit.readthedocs.io/en/latest/papers.html) for more papers using the MaldiSuite.
 

{maldideepkit-0.1.0 → maldideepkit-0.3.0}/README.md

@@ -28,7 +28,7 @@
   <a href="#license">License</a>
 </p>
 
-MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit): where MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation, and MaldiBatchKit harmonises multi-centre spectra, MaldiDeepKit focuses on the *classification* step, providing four PyTorch architectures wrapped in a unified scikit-learn estimator API with defaults calibrated for 6000-bin MALDI-TOF input.
+MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit): where MaldiAMRKit handles preprocessing, alignment and AMR-aware evaluation, and MaldiBatchKit harmonises multi-centre spectra, MaldiDeepKit focuses on the *classification* step, providing four PyTorch backbone architectures (MLP, 1-D CNN, 1-D ResNet, and 1-D Vision Transformer) plus a dual-branch classifier for spectrum + side-feature inputs and a self-training meta-classifier for semi-supervised data, all wrapped in a unified scikit-learn estimator API with defaults calibrated for 6000-bin MALDI-TOF input.
 
 ## Installation
 
@@ -36,7 +36,31 @@ MaldiDeepKit is part of the **MaldiSuite** ecosystem and complements [MaldiAMRKi
 pip install maldideepkit
 ```
 
-`maldiamrkit` is a core dependency and is installed automatically - MaldiDeepKit duck-types on the `MaldiSet` data model and reuses `maldiamrkit.alignment.Warping` for leak-safe spectral warping.
+`maldiamrkit` is a core dependency and is installed automatically (MaldiDeepKit duck-types on the `MaldiSet` data model and reuses `maldiamrkit.alignment.Warping` for leak-safe spectral warping).
+
+To enable the Laplace-approximation estimator in `maldideepkit.uncertainty`, install the optional `uncertainty` extra (pulls in [`laplace-torch`](https://github.com/aleximmer/Laplace)):
+
+```bash
+pip install "maldideepkit[uncertainty]"
+```
+
+Monte Carlo Dropout and split conformal prediction work without any extra.
+
+The `smiles_to_fingerprint` helper used in `MaldiDualBranchClassifier` workflows requires RDKit, available via the `rdkit` extra:
+
+```bash
+pip install "maldideepkit[rdkit]"
+```
+
+### Install the full MaldiSuite
+
+To install MaldiDeepKit together with [MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit) and [MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit) at compatible versions, install the [`maldisuite`](https://pypi.org/project/maldisuite/) meta-package:
+
+```bash
+pip install maldisuite
+```
+
+Visit the **MaldiSuite** landing page at <https://ettorerocchi.github.io/MaldiSuite/>.
 
 ### Development Installation
 
@@ -59,10 +83,11 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for coding conventions, testing, and PR
   - `MaldiTransformerClassifier` - 1-D Vision Transformer with global self-attention, pre-norm, LayerScale, and stochastic depth.
 - **MALDI-TOF defaults**: kernel sizes, depths, patch widths, and warmup / cosine-annealing schedules are tuned for 6000-bin spectra in the 2000-20000 Da range.
 - **Auto-scaling for non-default layouts**: every classifier ships a `from_spectrum(bin_width, input_dim, **overrides)` factory that rescales conv kernels and patches when the user trims the m/z range or picks a different bin width. See the [Spectrum scaling guide](https://maldideepkit.readthedocs.io/en/latest/spectrum_scaling.html).
-- **Training recipes**: AdamW-on-`weight_decay` dispatch, gradient clipping, linear warmup + cosine annealing, focal loss, label smoothing, mixed precision (AMP), Stochastic Weight Averaging, Sharpness-Aware Minimization, post-hoc threshold tuning, and temperature scaling - all exposed as classifier kwargs.
+- **Training recipes**: AdamW-on-`weight_decay` dispatch, gradient clipping, linear warmup + cosine annealing, focal loss, label smoothing, mixed precision (AMP), Stochastic Weight Averaging, Sharpness-Aware Minimization, post-hoc threshold tuning, and temperature scaling (all exposed as classifier kwargs).
 - **Leak-safe spectral warping**: pass any sklearn-style transformer ([`maldiamrkit.alignment.Warping`](https://github.com/EttoreRocchi/MaldiAMRKit)) via `warping=`; it is fitted on the training fold only and applied to both splits during training and to new spectra at `predict` time, *before* per-feature standardization.
 - **MaldiSet integration**: pass a `maldiamrkit.MaldiSet` directly to `fit` / `predict`; MaldiDeepKit duck-types on the DataFrame-like `.X` attribute, so MaldiSuite's data model flows end-to-end.
 - **Persistence**: `save()` writes a state-dict `.pt` plus a hyperparameter `.json` (and a sibling `.warper.pkl` if a warper was fitted); `load()` fails fast on class or `input_dim` mismatches.
+- **Uncertainty quantification**: `maldideepkit.uncertainty` subpackage ships three drop-in estimators sharing a single `predict_with_uncertainty` interface. `MCDropoutEstimator` (Monte Carlo Dropout with epistemic / aleatoric decomposition), `LaplaceEstimator` (last-layer or full-network Laplace via the optional `laplace-torch` dependency), and `ConformalPredictor` (split conformal prediction with the LAC non-conformity score).
 - **CPU-friendly**: every classifier runs on CPU, which is what the project's CI tests against; CUDA speeds up the models' training significantly.
 
 ## Documentation
@@ -94,7 +119,7 @@ acc = clf.score(X, y)
 weights = clf.get_attention_weights(X[:10])  # (10, hidden_dim)
 ```
 
-### Inside an Sklearn Pipeline
+### Inside a scikit-learn `Pipeline`
 
 ```python
 from sklearn.model_selection import StratifiedKFold, cross_val_score
@@ -166,8 +191,15 @@ For more examples covering training recipes, calibration, attention inspection,
 | `MaldiCNNClassifier`           | 1-D Conv1D + BatchNorm + ReLU + MaxPool blocks         | Local pattern learning from binned spectra             |
 | `MaldiResNetClassifier`        | 1-D ResNet-18-style residual blocks                    | Deeper convolutional backbone                          |
 | `MaldiTransformerClassifier`   | 1-D Vision Transformer (LayerScale, stochastic depth)  | Long-range peak combinations via global self-attention |
+| `MaldiDualBranchClassifier`    | Spectrum branch + per-row side-feature branch + fused head | Multi-modal: condition on antibiotic fingerprint, instrument ID, patient feature, ... |
+
+All five inherit from `BaseSpectralClassifier` (or its dual-input subclass `BaseDualSpectralClassifier`) and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
 
-All four inherit from `BaseSpectralClassifier` and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
+### Semi-supervised wrapper
+
+| Class | Purpose |
+|---|---|
+| `MaldiSelfTrainingClassifier` | Iterative pseudo-labeling on a labeled seed plus an unlabeled pool (rows marked `-1` by default). Wraps any classifier (defaults to `MaldiMLPClassifier`); follows the `sklearn.semi_supervised.SelfTrainingClassifier` API. |
 
 ### Shared Training Knobs
 
@@ -177,7 +209,7 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 | Gradient clipping                  | `grad_clip_norm`               | `clip_grad_norm_` before every step. Default on (`1.0`) for the deep models.        |
 | Warmup + cosine annealing          | `warmup_epochs`                | Replaces plateau scheduler. Default `5` (deep models), `0` (MLP/CNN).               |
 | Stochastic depth (Transformer)     | `drop_path_rate`               | Linearly ramped across blocks. Default `0.1`.                                       |
-| LayerScale (Transformer)           | `layerscale_init`              | Per-channel residual scaling initialised near zero - crucial on small cohorts.      |
+| LayerScale (Transformer)           | `layerscale_init`              | Per-channel residual scaling initialised near zero (crucial on small cohorts).      |
 | Focal loss                         | `loss="focal"` + `focal_gamma` | For imbalanced binary problems.                                                     |
 | Label smoothing                    | `label_smoothing`              | Passed to both cross-entropy and focal paths.                                       |
 | Stochastic Weight Averaging        | `swa_start_epoch`              | `AveragedModel` replaces best-val at end of fit.                                    |
@@ -185,6 +217,8 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 | Temperature scaling                | `calibrate_temperature`        | One-parameter LBFGS calibration on val logits.                                      |
 | Sharpness-Aware Minimization       | `use_sam` + `sam_rho`          | Two-pass training, ~2× compute.                                                     |
 | Spectral warping                   | `warping`                      | Any `Warping`-like sklearn transformer; fitted on train only, applied before standardization.      |
+| Per-sample weighting               | `sample_weight` (`fit`)        | sklearn-style weighted-mean loss; composes with `class_weight` and flows into early stopping, threshold tuning, and temperature scaling. |
+| Warm-start / resume                | `warm_start` (`fit`)           | Reuse the existing fitted module as the training start point (continual / federated / fine-tuning).  |
 
 ### Utilities
 
@@ -192,7 +226,7 @@ All four inherit from `BaseSpectralClassifier` and share the same hyperparameter
 
 - **`find_lr(clf, X, y)`** - learning-rate finder.
 - **`tune_threshold` / `fit_temperature`** - post-hoc calibrators usable standalone.
-- **`FocalLoss`, `SAMOptimizer`, `DropPath`** - building blocks for custom training loops.
+- **`FocalLoss`, `SAMOptimizer`** - loss / optimizer building blocks for custom training loops. Composable `nn.Module` primitives (`DropPath`, `PatchEmbed1D`, the full backbones) live under `maldideepkit.blocks`.
 
 ## Tutorials
 
@@ -202,16 +236,17 @@ For more detailed examples, see the notebooks:
 - [Model Comparison](notebooks/02_model_comparison.ipynb) - Train all four classifiers on the same dataset and compare accuracy.
 - [Attention Interpretation](notebooks/03_attention_interpretation.ipynb) - Visualise the sigmoid-gated attention learned by `MaldiMLPClassifier`.
 - [Full Pipeline](notebooks/04_full_pipeline.ipynb) - End-to-end template: MaldiAMRKit preprocessing + MaldiDeepKit classification.
+- [Uncertainty Quantification](notebooks/05_uncertainty.ipynb) - MC Dropout, split conformal prediction, and Laplace approximation on a fitted classifier; selective prediction curves.
 
 ## MaldiSuite Ecosystem
 
-MaldiDeepKit is the third package of the MaldiSuite ecosystem:
+MaldiDeepKit is the deep-learning package of the **MaldiSuite** ecosystem:
 
 - **[MaldiAMRKit](https://github.com/EttoreRocchi/MaldiAMRKit)** - preprocessing, alignment, peak detection, differential analysis, and classical-ML evaluation for MALDI-TOF AMR workflows.
 - **[MaldiBatchKit](https://github.com/EttoreRocchi/MaldiBatchKit)** - batch-effect correction and harmonisation for multi-centre / multi-instrument MALDI-TOF spectra.
 - **MaldiDeepKit** (this package) - sklearn-compatible deep learning classifiers.
 
-The three packages share the `MaldiSet` / `MaldiSpectrum` data model and are designed to compose in a single end-to-end pipeline.
+The three packages share the `MaldiSet` / `MaldiSpectrum` data model and are designed to compose in a single end-to-end pipeline. Install the full suite with `pip install maldisuite`. Landing page: [MaldiSuite](<https://ettorerocchi.github.io/MaldiSuite/>).
 
 ## Requirements
 
@@ -223,11 +258,9 @@ Pull requests, bug reports, and feature ideas are welcome. See the [Contributing
 
 ## Citing
 
-If you use MaldiDeepKit, please cite this repository until the companion paper is available.
-
-Related publications from the MaldiSuite ecosystem:
+If you use MaldiDeepKit in academic work please cite:
 
-> Rocchi, E., Nicitra, E., Calvo, M. et al. *Combining mass spectrometry and machine learning models for predicting Klebsiella pneumoniae antimicrobial resistance: a multicenter experience from clinical isolates in Italy*. **BMC Microbiol** (2026). [doi:10.1186/s12866-025-04657-2](https://link.springer.com/article/10.1186/s12866-025-04657-2)
+> _Citation will be available soon._
 
 See the [full publications list](https://maldideepkit.readthedocs.io/en/latest/papers.html) for more papers using the MaldiSuite.
 

maldideepkit-0.3.0/maldideepkit/__init__.py

@@ -0,0 +1,73 @@
+"""MaldiDeepKit - deep learning classifiers for MALDI-TOF binned spectra.
+
+Provides a catalog of PyTorch architectures (MLP, CNN, ResNet,
+Transformer) adapted to 1-D binned MALDI-TOF spectra, each wrapped in
+a scikit-learn compatible estimator with sensible defaults.
+
+Subpackages
+-----------
+- ``maldideepkit.base`` - ``BaseSpectralClassifier``,
+  ``BaseDualSpectralClassifier``, ``SpectralDataset``, ``make_loaders``.
+- ``maldideepkit.attention`` - ``MaldiMLPClassifier`` (MLP with optional
+  sigmoid-gated attention).
+- ``maldideepkit.cnn`` - ``MaldiCNNClassifier`` (Conv1D blocks).
+- ``maldideepkit.resnet`` - ``MaldiResNetClassifier`` (1-D ResNet-18).
+- ``maldideepkit.transformer`` - ``MaldiTransformerClassifier`` (1-D ViT).
+- ``maldideepkit.dual_branch`` - ``MaldiDualBranchClassifier``
+  (spectrum + per-row side feature) and ``smiles_to_fingerprint``
+  helper (requires the ``[rdkit]`` extra).
+- ``maldideepkit.semisupervised`` - ``MaldiSelfTrainingClassifier``
+  (iterative pseudo-labeling meta-classifier).
+- ``maldideepkit.blocks`` - re-exports of every backbone and
+  composable primitive for users embedding components into their own
+  networks.
+- ``maldideepkit.augment`` - per-batch training-time augmentations
+  (``SpectrumAugment``, MixUp / CutMix helpers).
+- ``maldideepkit.utils`` - reproducibility helpers and shared
+  training primitives.
+- ``maldideepkit.uncertainty`` - uncertainty-quantification
+  estimators (MC Dropout, Laplace approximation, split conformal
+  prediction) for fitted classifiers.
+
+Examples
+--------
+>>> import numpy as np
+>>> from maldideepkit import MaldiMLPClassifier
+>>> rng = np.random.default_rng(0)
+>>> X = rng.standard_normal((64, 256)).astype("float32")
+>>> y = rng.integers(0, 2, size=64)
+>>> clf = MaldiMLPClassifier(epochs=2, batch_size=16, random_state=0)
+>>> _ = clf.fit(X, y)
+>>> proba = clf.predict_proba(X)
+"""
+
+from . import uncertainty
+from .attention.mlp import MaldiMLPClassifier
+from .base.classifier import BaseSpectralClassifier
+from .base.data import SpectralDataset, make_loaders
+from .base.dual import BaseDualSpectralClassifier
+from .cnn.cnn import MaldiCNNClassifier
+from .dual_branch import MaldiDualBranchClassifier, smiles_to_fingerprint
+from .resnet.resnet import MaldiResNetClassifier
+from .semisupervised import MaldiSelfTrainingClassifier
+from .transformer.transformer import MaldiTransformerClassifier
+
+__version__ = "0.3.0"
+__author__ = "Ettore Rocchi"
+
+__all__ = [
+    "BaseDualSpectralClassifier",
+    "BaseSpectralClassifier",
+    "MaldiCNNClassifier",
+    "MaldiDualBranchClassifier",
+    "MaldiMLPClassifier",
+    "MaldiResNetClassifier",
+    "MaldiSelfTrainingClassifier",
+    "MaldiTransformerClassifier",
+    "SpectralDataset",
+    "__author__",
+    "__version__",
+    "make_loaders",
+    "smiles_to_fingerprint",
+    "uncertainty",
+]