MaldiDeepKit 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiDeepKit
-Version: 0.2.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"
@@ -47,6 +47,11 @@ 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
@@ -79,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
 
@@ -87,7 +92,7 @@ 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)):
 
@@ -97,6 +102,12 @@ 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:
@@ -128,7 +139,7 @@ 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.
@@ -236,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.
+
+### Semi-supervised wrapper
 
-All four inherit from `BaseSpectralClassifier` and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
+| 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
 
@@ -247,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.                                    |
@@ -255,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
 

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

@@ -1,8 +1,10 @@
 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
@@ -23,10 +25,16 @@ 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
@@ -49,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
@@ -56,6 +65,8 @@ 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

{maldideepkit-0.2.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
@@ -23,5 +27,8 @@ 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.2.0/MaldiDeepKit.egg-info → maldideepkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MaldiDeepKit
-Version: 0.2.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"
@@ -47,6 +47,11 @@ 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
@@ -79,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
 
@@ -87,7 +92,7 @@ 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)):
 
@@ -97,6 +102,12 @@ 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:
@@ -128,7 +139,7 @@ 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.
@@ -236,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.
+
+### Semi-supervised wrapper
 
-All four inherit from `BaseSpectralClassifier` and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
+| 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
 
@@ -247,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.                                    |
@@ -255,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
 

{maldideepkit-0.2.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,7 @@ 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)):
 
@@ -46,6 +46,12 @@ 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:
@@ -77,7 +83,7 @@ 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.
@@ -185,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.
+
+### Semi-supervised wrapper
 
-All four inherit from `BaseSpectralClassifier` and share the same hyperparameter surface for optimisation, device placement, early stopping, calibration, and persistence.
+| 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
 
@@ -196,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.                                    |
@@ -204,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
 

{maldideepkit-0.2.0 → maldideepkit-0.3.0}/maldideepkit/__init__.py

@@ -6,16 +6,23 @@ a scikit-learn compatible estimator with sensible defaults.
 
 Subpackages
 -----------
-- ``maldideepkit.base`` - ``BaseSpectralClassifier``, ``SpectralDataset``,
-  ``make_loaders``.
+- ``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
@@ -38,22 +45,29 @@ 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.2.0"
+__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",
 ]

{maldideepkit-0.2.0 → maldideepkit-0.3.0}/maldideepkit/attention/mlp.py

@@ -261,13 +261,19 @@ class MaldiMLPClassifier(BaseSpectralClassifier):
         return logits
 
     def fit(  # type: ignore[override]
-        self, X: Any, y: Any, *, warm_start: bool = False
+        self,
+        X: Any,
+        y: Any,
+        *,
+        sample_weight: Any | None = None,
+        warm_start: bool = False,
     ) -> MaldiMLPClassifier:
         """Fit the model and cache attention weights from the final batch.
 
-        See :meth:`BaseSpectralClassifier.fit` for shared parameters, including ``warm_start``.
+        See :meth:`BaseSpectralClassifier.fit` for shared parameters,
+        including ``sample_weight`` and ``warm_start``.
         """
-        super().fit(X, y, warm_start=warm_start)
+        super().fit(X, y, sample_weight=sample_weight, warm_start=warm_start)
         if self.use_attention:
             X_np = _to_numpy(X)
             tail = X_np[: min(len(X_np), 64)]

{maldideepkit-0.2.0 → maldideepkit-0.3.0}/maldideepkit/augment/mixing.py

@@ -38,7 +38,11 @@ def apply_mixup(
     y_oh: torch.Tensor,
     alpha: float,
     generator: torch.Generator | None = None,
-) -> tuple[torch.Tensor, torch.Tensor]:
+    *,
+    sample_weight: torch.Tensor | None = None,
+) -> (
+    tuple[torch.Tensor, torch.Tensor] | tuple[torch.Tensor, torch.Tensor, torch.Tensor]
+):
     """Mixup: convex-combine two random permutations of the batch.
 
     Parameters
@@ -52,11 +56,19 @@ def apply_mixup(
         values 0.1-0.4 for tabular-ish inputs. Must be ``> 0``.
     generator : torch.Generator or None, default=None
         Seeded RNG for reproducibility.
+    sample_weight : torch.Tensor or None, keyword-only, default=None
+        Optional per-sample weight tensor of shape ``(batch,)``. When
+        given, the function returns a 3-tuple whose third element is
+        ``lam * sample_weight + (1 - lam) * sample_weight[perm]`` (the
+        same convex combination applied to ``y_oh``). When ``None``
+        the function returns a 2-tuple for backward compatibility.
 
     Returns
     -------
     tuple of torch.Tensor
-        ``(x_mixed, y_mixed)`` with the same shapes as the inputs.
+        ``(x_mixed, y_mixed)`` or ``(x_mixed, y_mixed, sw_mixed)``
+        when ``sample_weight`` is provided. ``x_mixed`` and ``y_mixed``
+        have the same shape as the inputs.
     """
     if alpha <= 0:
         raise ValueError(f"mixup alpha must be > 0; got {alpha!r}.")
@@ -64,7 +76,11 @@ def apply_mixup(
     perm = torch.randperm(x.shape[0], generator=generator).to(x.device)
     x_mixed = lam * x + (1.0 - lam) * x[perm]
     y_mixed = lam * y_oh + (1.0 - lam) * y_oh[perm]
-    return x_mixed, y_mixed
+    if sample_weight is None:
+        return x_mixed, y_mixed
+    sw = sample_weight.to(device=x.device)
+    sw_mixed = lam * sw + (1.0 - lam) * sw[perm]
+    return x_mixed, y_mixed, sw_mixed
 
 
 def apply_cutmix(
@@ -72,7 +88,12 @@ def apply_cutmix(
     y_oh: torch.Tensor,
     alpha: float,
     generator: torch.Generator | None = None,
-) -> tuple[torch.Tensor, torch.Tensor]:
+    *,
+    sample_weight: torch.Tensor | None = None,
+    n_spec_cols: int | None = None,
+) -> (
+    tuple[torch.Tensor, torch.Tensor] | tuple[torch.Tensor, torch.Tensor, torch.Tensor]
+):
     """CutMix on 1-D spectra: splice a contiguous m/z window.
 
     A window of length ``w = round(n_bins * (1 - lam))`` is drawn
@@ -90,24 +111,55 @@ def apply_cutmix(
         value 1.0 (uniform over window fractions). Must be ``> 0``.
     generator : torch.Generator or None, default=None
         Seeded RNG for reproducibility.
+    n_spec_cols : int or None, keyword-only, default=None
+        Number of leading spectrum columns. When given (dual-input
+        models, where ``x`` is ``[ X_spec | X_side ]``), the spliced
+        window is drawn **inside the spectrum block only** and the
+        window fraction is taken relative to ``n_spec_cols`` rather
+        than the full width. The trailing side columns are instead
+        convex-combined with the same ``effective_lam`` and the same
+        permutation, so a contiguous m/z window never straddles the
+        spectrum / side boundary and ``(x, y)`` stay consistent.
+        ``None`` treats every column as spectrum.
+    sample_weight : torch.Tensor or None, keyword-only, default=None
+        Optional per-sample weight tensor of shape ``(batch,)``. When
+        given, the function returns a 3-tuple whose third element is
+        ``effective_lam * sample_weight + (1 - effective_lam) *
+        sample_weight[perm]`` (matching how labels are mixed). When
+        ``None`` the function returns a 2-tuple for backward
+        compatibility.
 
     Returns
     -------
     tuple of torch.Tensor
-        ``(x_mixed, y_mixed)`` with the same shapes as the inputs.
+        ``(x_mixed, y_mixed)`` or ``(x_mixed, y_mixed, sw_mixed)``
+        when ``sample_weight`` is provided.
     """
     if alpha <= 0:
         raise ValueError(f"cutmix alpha must be > 0; got {alpha!r}.")
     batch, n_bins = x.shape
+    n_cut = n_bins if n_spec_cols is None else min(int(n_spec_cols), n_bins)
+    if n_cut <= 0:
+        raise ValueError(f"n_spec_cols must be > 0; got {n_spec_cols!r}.")
     lam = _sample_beta(alpha, generator)
-    window = int(round(n_bins * (1.0 - lam)))
-    window = max(0, min(window, n_bins))
+    window = int(round(n_cut * (1.0 - lam)))
+    window = max(0, min(window, n_cut))
     if window == 0:
-        return x.clone(), y_oh.clone()
-    start = int(torch.randint(0, n_bins - window + 1, (1,), generator=generator).item())
+        if sample_weight is None:
+            return x.clone(), y_oh.clone()
+        return x.clone(), y_oh.clone(), sample_weight.to(device=x.device).clone()
+    start = int(torch.randint(0, n_cut - window + 1, (1,), generator=generator).item())
     perm = torch.randperm(batch, generator=generator).to(x.device)
     x_mixed = x.clone()
     x_mixed[:, start : start + window] = x[perm][:, start : start + window]
-    effective_lam = 1.0 - window / n_bins
+    effective_lam = 1.0 - window / n_cut
+    if n_cut < n_bins:
+        x_mixed[:, n_cut:] = (
+            effective_lam * x[:, n_cut:] + (1.0 - effective_lam) * x[perm][:, n_cut:]
+        )
     y_mixed = effective_lam * y_oh + (1.0 - effective_lam) * y_oh[perm]
-    return x_mixed, y_mixed
+    if sample_weight is None:
+        return x_mixed, y_mixed
+    sw = sample_weight.to(device=x.device)
+    sw_mixed = effective_lam * sw + (1.0 - effective_lam) * sw[perm]
+    return x_mixed, y_mixed, sw_mixed

maldideepkit-0.3.0/maldideepkit/base/__init__.py

@@ -0,0 +1,23 @@
+"""Shared primitives for MaldiDeepKit classifiers.
+
+Exposes:
+
+- :class:`BaseSpectralClassifier` - abstract base for the four
+  single-input classifier families (MLP, CNN, ResNet, Transformer).
+- :class:`BaseDualSpectralClassifier` - abstract base for dual-input
+  classifiers (e.g. spectrum + antibiotic fingerprint); the side
+  input is packed into ``X`` by concatenation to stay
+  sklearn-pipeline-friendly.
+- :class:`SpectralDataset` / :func:`make_loaders` - data utilities.
+"""
+
+from .classifier import BaseSpectralClassifier
+from .data import SpectralDataset, make_loaders
+from .dual import BaseDualSpectralClassifier
+
+__all__ = [
+    "BaseDualSpectralClassifier",
+    "BaseSpectralClassifier",
+    "SpectralDataset",
+    "make_loaders",
+]