Latest release v0.4.0

One Python ecosystem for MALDI-TOF antimicrobial resistance research.

Preprocessing, batch correction and deep-learning classifiers that share one data model and the scikit-learn API.

pip install maldisuite
  • Python 3.10+
  • MIT license
  • scikit-learn API
  • 3 packages
Example spectrum

m/z (Da). A spectrum from the MaldiAMRKit example data, before and after the default preprocessing.

Why MaldiSuite

One data model and one API, whichever package you use.

Shared data model

MaldiSet keeps the spectra and their metadata (species, batch, MIC, acquisition date) under the same sample IDs, and correctors match batch labels and covariates to the spectra by ID, not by position.

Leak-safe by construction

Every transformer is fitted on the training folds and applied unchanged to held-out data, and grouped cross-validation keeps all spectra of a patient, or of an isolate, in the same fold.

scikit-learn native

Correctors and classifiers are estimators, so Pipeline, cross_val_score and GridSearchCV work without glue code.

Reproducible

Fixed seeds, versions pinned by the meta-package and a Bruker-native data path make reruns from raw spectra repeatable in the same environment.

Packages

Three packages, one install.

Each package has its own repository, documentation and release cycle. Install them one by one, or all together with the maldisuite meta-package.

v0.22.3

MaldiAMRKit

Data model, preprocessing and AMR-aware evaluation for MALDI-TOF spectra

  • Bruker fid/1r, txt and mzML/mzXML I/O, with DRIAMS and MARISMa layouts
  • Composable PreprocessingPipeline, serialisable to JSON/YAML
  • Seven warping methods, on binned or full-resolution spectra
  • VME, ME and categorical agreement, with patient-grouped splitters
  • MIC encoding with bundled EUCAST breakpoint tables
  • Differential analysis and drift monitoring
pip install maldiamrkit
v0.2.2

MaldiBatchKit

Batch-effect correction for multi-site MALDI-TOF spectra

  • ComBat (Johnson, Fortin, CovBat), Limma and Harmony
  • MALDI-specific BatchAwareWarping, QualityWeightedComBat and SpeciesAwareComBat
  • Fitted on training data, applied unchanged to held-out folds
  • AutoCorrector to pick the corrector inside GridSearchCV
  • kBET, LISI and silhouette diagnostics, and BatchCorrectionBenchmark
  • MaldiSetAdapter and a command-line interface
pip install maldibatchkit
v0.4.0

MaldiDeepKit

Deep-learning classifiers for binned MALDI-TOF spectra

  • MaldiMLPClassifier, MaldiCNNClassifier, MaldiResNetClassifier and MaldiTransformerClassifier
  • Defaults tuned for 6000-bin spectra, from_spectrum() for other layouts
  • Dual-branch (spectrum + side features) and self-training classifiers
  • Self-supervised pre-training on unlabelled spectra with MaldiSpectrumEncoder
  • MC Dropout, Laplace and split conformal uncertainty
  • Leak-safe warping, fitted on the training split only
pip install maldideepkit

The maldisuite meta-package

One command installs the three packages at versions tested together, with the mzML/mzXML, batch-correction and plotting extras.

pip install maldisuite
Versions pinned by maldisuite 0.4.0
PackagePinned rangeLatest on PyPI
MaldiAMRKit [batch,formats] >=0.22.2,<0.23 0.22.3
MaldiBatchKit [viz] >=0.2.0,<0.3 0.2.2
MaldiDeepKit >=0.4.0,<0.5 0.4.0

Latest versions are read from PyPI when the page loads.

Combine

Use one package, or combine them.

Each package can be used on its own. Because they share the MaldiSet data model and the scikit-learn API, they also fit in a single Pipeline when a study needs more than one. This is one way to combine all three.

  1. Raw spectra

    Bruker fid/1r, txt, mzML/mzXML

    + metadata: species, drug, MIC, site, date

  2. MaldiAMRKit

    • I/O and dataset layouts
    • Preprocessing pipeline
    • Warping and peak detection
    • AMR metrics, grouped CV
  3. MaldiBatchKit

    • 11 correctors
    • MALDI-specific corrections
    • kBET, LISI, silhouette
    • Fit on train, apply to held-out
  4. MaldiDeepKit

    • MLP, 1-D CNN, ResNet, 1-D ViT
    • Any bin layout
    • Uncertainty estimates
    • Self-supervised pre-training
    • Leak-safe warping and scaling
  5. Predictions

    R / S per isolate

    scored with VME, ME and AUROC

Any package can be left out or used on its own. MaldiBatchKit, for example, is useful only when spectra come from several sites or instruments.

Quick start

A first result in a few lines.

  1. 1Install

    pip install maldiamrkit

    Python 3.10 or newer. scikit-learn is installed with it.

  2. 2Load your cohort

    Point MaldiSet at a folder of spectra, one .txt file per spectrum named after its ID, and a metadata CSV with an ID column, the resistance label and the patient. Labels are encoded as R = 1, S = 0. See the MaldiAMRKit example data for both formats.

  3. 3Evaluate with AMR metrics

    Warping and the classifier are refitted inside every training fold, vme_scorer reports the very major error rate, and CaseGroupedKFold keeps all spectra of a patient in the same fold.

amr_quickstart.py
from maldiamrkit import MaldiSet
from maldiamrkit.alignment import Warping
from maldiamrkit.evaluation import CaseGroupedKFold, vme_scorer
from maldiamrkit.susceptibility import LabelEncoder
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import cross_val_score
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler

# metadata.csv: ID, Drug (R/S), patient_id
data = MaldiSet.from_directory("spectra/", "metadata.csv", bin_width=3)
meta = data.meta.loc[data.X.index]
y = LabelEncoder().fit_transform(data.get_y_single("Drug"))  # R=1, S=0

pipe = Pipeline([
    ("warp",  Warping(method="shift")),
    ("scale", StandardScaler()),
    ("clf",   LogisticRegression(max_iter=1000)),
])

scores = cross_val_score(
    pipe, data.X, y,
    scoring=vme_scorer,
    cv=CaseGroupedKFold(n_splits=5, random_state=0),
    groups=meta["patient_id"],
)
print(f"VME: {-scores.mean():.3f}")

Tested with maldiamrkit 0.22.3.

Results

Benchmarked on the DRIAMS multi-site cohort.

Aggregated results from the analysis behind the MaldiSuite Application Note (under review), on the four DRIAMS sites. Classification scores are means over 3 repeats × 5 folds.

best classifier at each site. n/a: drug not tested at that site. Hover or focus a cell for balanced accuracy, MCC, VME and ME.

Data: results/ of the MaldiSuite-paper repository. Spectra from DRIAMS (Weis et al., Nature Medicine 2022).

Research

The scientific work behind the suite.

MaldiSuite is described in an Application Note currently under review.

Publications using MaldiSuite

Using MaldiSuite in your research? Let us know on GitHub and we will list it here.

Roadmap

Where each package is heading.

The latest release of each package, what is in development and what is planned after it. Order and scope may change.

  • Released
  • In development
  • Planned