Tutorials

Interactive tutorials demonstrating MaldiAMRKit usage.

• MaldiAMRKit - Quick Start
  • Import MaldiAMRKit
  • Preprocessing Pipeline
  • Load and Preprocess a Single Spectrum
  • Quality Assessment
  • Binning Methods
  • Build a Dataset from Multiple Spectra
  • Label Encoding
  • Filtering Datasets
  • Custom Preprocessing Pipelines
• MaldiAMRKit - Peak Detection
  • Import Libraries
  • Load Dataset
  • Peak Detection with Local Maxima
  • Peak Detection with Persistent Homology
  • Binary vs Intensity Mode
  • Parallelization
• MaldiAMRKit - Spectral Alignment
  • Import Libraries
  • Load Dataset
  • Warping Methods
  • Alignment Quality Assessment
  • Raw Spectra Warping
  • Parallelization
  • RawWarping in sklearn Pipeline
• MaldiAMRKit - Evaluation & Splitting
  • Dataset
  • Import Libraries
  • AMR Evaluation Metrics
  • Load the Dataset
  • Splitting Utilities
  • Cross-Validation Splitters
  • sklearn Scorers
• MaldiAMRKit - Exploration & Similarity
  • Dataset
  • Load the Dataset
  • PCA
  • t-SNE
  • UMAP
  • Spectral Similarity
  • Batch Effect Correction
• MaldiAMRKit - Differential Analysis
  • Dataset
  • Load the Dataset
  • Run the Differential Analysis
  • Volcano Plot
  • Manhattan Plot along the m/z Axis
  • Compare across Multiple Drugs
  • Choosing a Test and Correction
  • Optional: Scoping Filters
  • See Also
• MaldiAMRKit - Drift Monitoring
  • Dataset
  • Load the Dataset
  • Fit the DriftMonitor
  • 1. Reference Similarity
  • 2. PCA Centroid Trajectory
  • 3. Peak-Selection Stability
  • 4. Per-Peak Effect-Size Drift
  • See Also
• MaldiAMRKit - Susceptibility & MIC regression
  • Imports
  • Loading a breakpoint table
  • MICEncoder - parse MIC strings into ML targets
  • mic_regression_report - clinically-grounded evaluation
• MaldiAMRKit - Peak Sets
  • Import Libraries
  • Load Dataset
  • Extract a PeakList from binned spectra
  • Inspect a single PeakSet
  • Rank and keep the strongest peaks
  • Persistent-homology ranking
  • Pad to a dense array for modelling
  • Index and slice a PeakList
  • Persist and cache
  • Binning-free extraction from raw files
  • Fit-free peak alignment
  • Avoiding data leakage

Datasets

Notebooks 01–03, 08, and 09 run on the small example dataset bundled with the repository under data/ or are fully self-contained. Notebooks 04–07 require more samples and use the real MALDI-Kleb-AI archive (Rocchi et al., 2026; Zenodo DOI 10.5281/zenodo.17405072) via the notebooks/_demo.py helper. The helper caches the 370 MB tarball under ~/.cache/maldiamrkit/ (or $MALDIAMRKIT_CACHE_DIR) on first use, and by default restricts the dataset to the Rome sub-cohort (single acquisition centre, ~470 spectra) so that the demonstrations do not require batch-effect correction.

Example Workflows

Basic Classification Pipeline

from maldiamrkit import MaldiSet
from maldiamrkit.alignment import Warping
from maldiamrkit.detection import MaldiPeakDetector
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import cross_val_score, StratifiedKFold

# Load data
data = MaldiSet.from_directory(
    "spectra/", "meta.csv",
    aggregate_by=dict(antibiotics="Ceftriaxone")
)

# Build pipeline
pipe = Pipeline([
    ("peaks", MaldiPeakDetector(binary=False, prominence=0.005)),
    ("warp", Warping(method="piecewise")),
    ("scaler", StandardScaler()),
    ("clf", RandomForestClassifier(n_estimators=100, random_state=42))
])

# Cross-validation
cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
scores = cross_val_score(
    pipe, data.X, data.get_y_single(),
    cv=cv, scoring="accuracy"
)
print(f"CV Accuracy: {scores.mean():.3f} +/- {scores.std():.3f}")

Raw Spectra Alignment

from maldiamrkit.alignment import RawWarping, create_raw_input

# Build input DataFrame from spectrum directory
X_raw = create_raw_input("spectra/")

# Use raw warping for better alignment
warper = RawWarping(method="piecewise", bin_width=3, max_shift_da=10.0)

# Fit and transform
warper.fit(X_raw)
X_aligned = warper.transform(X_raw)

Building Datasets

from maldiamrkit.data import DatasetBuilder, FlatLayout, ProcessingHandler
from maldiamrkit.preprocessing import PreprocessingPipeline

# Build a dataset with year-based subfolders
layout = FlatLayout("spectra/", "metadata.csv", year_column="acquisition_date")
report = DatasetBuilder(layout, "output/my_dataset").build()
print(f"Processed {report.succeeded}/{report.total} spectra")
print(f"Folders: {report.folders_created}")

# Add extra processing variants
sqrt_pipe = PreprocessingPipeline.from_yaml("sqrt_pipeline.yaml")
report = DatasetBuilder(
    layout, "output/my_dataset",
    extra_handlers=[
        ProcessingHandler("preprocessed_sqrt", "preprocessed",
                          pipeline=sqrt_pipe),
        ProcessingHandler("binned_3000", "binned", bin_width=6),
    ],
).build()

# Build from Bruker binary data (e.g. MARISMa)
from maldiamrkit.data import BrukerTreeLayout

bruker_layout = BrukerTreeLayout("path/to/MARISMa", "path/to/AMR.csv")
report = DatasetBuilder(bruker_layout, "output/marisma_built").build()