MaldiAMRKit 0.1.0__py3-none-any.whl

maldiamrkit/__init__.py

@@ -0,0 +1,19 @@
+from .config import PreprocessingSettings
+from .preprocessing import preprocess, bin_spectrum
+from .io import read_spectrum
+from .dataset import MaldiSet
+from .spectrum import MaldiSpectrum
+
+__version__ = "0.1.0"
+__author__ = "Ettore Rocchi"
+
+__all__ = [
+    "MaldiSpectrum",
+    "MaldiSet",
+    "PreprocessingSettings",
+    "preprocess",
+    "bin_spectrum",
+    "read_spectrum",
+    "__version__",
+    "__author__",
+]

maldiamrkit/config.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+
+@dataclass()
+class PreprocessingSettings:
+
+    trim_from: int = 2_000
+    trim_to:   int = 20_000
+
+    savgol_window: int = 20
+    savgol_poly:   int = 2
+    baseline_half_window: int = 40
+
+    def as_dict(self) -> dict:
+        return self.__dict__.copy()

maldiamrkit/dataset.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+from pathlib import Path
+import pandas as pd
+import matplotlib.pyplot as plt
+import numpy as np
+
+from .spectrum import MaldiSpectrum
+from .config import PreprocessingSettings
+
+
+class MaldiSet:
+    """
+    A collection of spectra with metadata.
+
+    Example
+    -------
+    >>> ds = MaldiSet.from_directory(
+                "spectra/", "meta.csv",
+                aggregate_by=dict(antibiotic="Ceftriaxone")
+        )
+    >>> ds.X.shape, ds.y.value_counts()
+    """
+
+    def __init__(
+            self,
+            spectra: list[MaldiSpectrum],
+            meta: pd.DataFrame,
+            *,
+            aggregate_by: dict[str, str],
+            bin_width: int = 3,
+            verbose: bool = False,
+        ) -> MaldiSet:
+        self.spectra = spectra
+        self.meta = meta.set_index("ID")
+
+        self.antibiotic = aggregate_by.get("antibiotic")
+        self.species = aggregate_by.get("species")
+        self.bin_width = bin_width
+
+        self.verbose = verbose      
+        if verbose:
+            print(f"INFO: Dataset created: {len(self.spectra)} spectra")
+
+    @classmethod
+    def from_directory(
+            self,
+            spectra_dir: str | Path,
+            meta_file: str | Path,
+            *,
+            aggregate_by: dict[str, str],
+            cfg: PreprocessingSettings | None = None,
+            bin_width: int = 3,
+            verbose: bool = False,
+        ) -> MaldiSet:
+        spectra_dir = Path(spectra_dir)
+        specs = [MaldiSpectrum(p, cfg=cfg).bin(bin_width) for p in spectra_dir.glob("*.txt")]
+        meta = pd.read_csv(meta_file)
+        return self(specs, meta, aggregate_by=aggregate_by, bin_width=bin_width, verbose=verbose)
+
+    @property
+    def X(self) -> pd.DataFrame:
+        """
+        Return matrix (n_samples, n_features) limited to the configured subset.
+        """
+        rows = []
+        for s in self.spectra:
+            sid = s.id
+            if sid not in self.meta.index and self.verbose:
+                print(f"WARNING: ID {sid} missing in metadata - skipped.")
+                continue
+            row = (s.binned if s._binned is not None else s.bin(self.bin_width).binned) \
+                    .set_index("mass")["intensity"].rename(sid)
+            rows.append(row)
+
+        df = pd.concat(rows, axis=1).T
+
+        df = df.join(self.meta, how="left")
+        if self.antibiotic:
+            df = df[df[self.antibiotic].notna()]
+        if self.species:
+            df = df[df["Species"] == self.species]
+
+        return df.select_dtypes("number")
+
+    @property
+    def y(self) -> pd.Series:
+        """Return the classification/label vector (antibiotic resistance)."""
+        return self.meta.loc[self.X.index, self.antibiotic]
+
+    def plot_pseudogel(
+        self,
+        *,
+        antibiotic: str | None = None,
+        cmap: str = "inferno",
+        vmin: float | None = None,
+        vmax: float | None = None,
+        figsize: tuple[int, int] | None = None,
+        log_scale: bool = True,
+        sort_by_intensity: bool = True,
+        title: str | None = None,
+        show: bool = True,
+    ):
+        """
+        Displays a pseudogel heatmap of the spectra, with one subplot
+        for each unique value of the antibiotic column.
+
+        Parameters
+        ----------
+        antibiotic : str | None
+            Name of the target column to use (default: self.antibiotic).
+        cmap : str
+            Matplotlib colormap to use (default: "inferno").
+        vmin, vmax : float | None
+            Color scale limits. Use None for automatic scaling.
+        figsize : (int, int) | None
+            Figure size. If None, it is automatically set based on the number of subplots.
+        log_scale : bool
+            Apply log1p to intensity values to emphasize weaker signals.
+        sort_by_intensity : bool
+            Sort samples by average intensity before plotting.
+        title : str | None
+            Title of the overall figure.
+        show : bool
+            If True, calls plt.show() at the end of the method.
+
+        Returns
+        -------
+        fig, axes : matplotlib.figure.Figure, ndarray[Axes]
+            Matplotlib figure and axes objects, useful for further customization.
+        """
+        if antibiotic is None:
+            antibiotic = self.antibiotic
+        if antibiotic is None:
+            raise ValueError(
+                "Antibiotic column not defined. "
+            )
+
+        X = self.X
+        y = self.y
+
+        groups = y.groupby(y).groups
+        n_groups = len(groups)
+        if figsize is None:
+            figsize = (6.0, 2.5 * n_groups)
+
+        fig, axes = plt.subplots(
+            n_groups, 1, figsize=figsize, sharex=True, constrained_layout=True
+        )
+        if n_groups == 1:
+            axes = np.asarray([axes])
+
+        for ax, (label, idx) in zip(axes, sorted(groups.items(), key=lambda t: str(t[0]))):
+            M = X.loc[idx].to_numpy()
+            if sort_by_intensity:
+                order = np.argsort(M.mean(axis=1))[::-1]
+                M = M[order]
+            if log_scale:
+                M = np.log1p(M)
+
+            im = ax.imshow(
+                M,
+                aspect="auto",
+                interpolation="nearest",
+                cmap=cmap,
+                vmin=vmin,
+                vmax=vmax,
+            )
+            ax.set_ylabel(f"{label}\n(n={M.shape[0]})", rotation=0, ha="right", va="center")
+            ax.set_yticks([])
+
+        xticks = np.linspace(0, X.shape[1] - 1, 6, dtype=int)
+        axes[-1].set_xticks(xticks)
+        axes[-1].set_xticklabels([f"{m}" for m in X.columns[xticks]])
+        axes[-1].set_xlabel("m/z (binned)")
+
+        cbar = fig.colorbar(im, ax=axes, orientation="vertical", pad=0.01)
+        cbar.set_label("Log(intensity + 1)" if log_scale else "intensity")
+
+        if title:
+            fig.suptitle(title, y=1.02)
+
+        if show:
+            plt.show()
+
+        return fig, axes

maldiamrkit/io.py

@@ -0,0 +1,31 @@
+import csv
+from pathlib import Path
+import pandas as pd
+
+def sniff_delimiter(path: str | Path, sample_lines: int = 10) -> str:
+    with open(path, "r", newline="") as f:
+        dialect = csv.Sniffer().sniff(
+            "".join([next(f) for _ in range(sample_lines)]),
+            delimiters=",;\t "
+        )
+    return dialect.delimiter
+
+def read_spectrum(path: str | Path) -> pd.DataFrame:
+    """
+    Read raw txt/csv file with two unnamed columns into a DataFrame
+    with columns ['mass', 'intensity'].
+    """
+    try:
+        delim = sniff_delimiter(path)
+    except:
+        delim = "\s+"
+    
+    df = pd.read_csv(
+        path,
+        sep=delim,
+        comment="#",
+        header=None,
+        names=["mass", "intensity"]
+    )
+    
+    return df

maldiamrkit/peak_detector.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+from scipy.signal import find_peaks
+
+
+class MaldiPeakDetector(BaseEstimator, TransformerMixin):
+    """
+    Peak detector for MALDI-TOF spectra.
+
+    The transformer keeps the original feature dimension; all non-peak
+    positions are set to 0.  Peaks can be returned as **binary flags**
+    or with their original intensities.
+
+    Parameters
+    ----------
+    binary : bool, default=True
+        If *True* every peak is marked with 1; otherwise its original
+        intensity is kept.
+    **kwargs :
+        Any keyword accepted by :func:`scipy.signal.find_peaks`
+        (e.g. `prominence`, `height`, `distance`, …).
+    """
+
+    def __init__(
+            self,
+            binary: bool = True,
+            **kwargs
+        ) -> MaldiPeakDetector:
+        self.binary = binary
+        self.kwargs = kwargs
+
+    def fit(self, X: pd.DataFrame, y=None):
+        """No learning required, just return *self*."""
+        return self
+
+    def transform(self, X: pd.DataFrame):
+        """Detect peaks in *each* sample independently and mask everything else."""
+        X_out = X.copy()
+
+        for i in range(X_out.shape[0]):
+            row = X_out.iloc[i].values
+            peaks, _ = find_peaks(row, **self.kwargs)
+
+            masked = np.zeros_like(row, dtype=row.dtype)
+            if self.binary:
+                masked[peaks] = 1
+            else:
+                masked[peaks] = row[peaks]
+            X_out.iloc[i] = masked
+
+        return X_out
+
+    def fit_transform(self, X: pd.DataFrame, y=None, **fit_params):
+        """Convenience shortcut."""
+        return self.fit(X, y).transform(X)

maldiamrkit/preprocessing.py

@@ -0,0 +1,67 @@
+import numpy as np
+import pandas as pd
+from pybaselines import Baseline
+from scipy.signal import savgol_filter
+
+from .config import PreprocessingSettings
+
+
+def preprocess(
+        df: pd.DataFrame,
+        cfg: PreprocessingSettings = PreprocessingSettings()
+    ) -> pd.DataFrame:
+    """Return intensity-normalised, baseline-corrected and trimmed spectrum."""
+    df = df.copy()
+    df["intensity"] = df["intensity"].clip(lower=0)
+
+    # smooth+sqrt
+    intensity = np.sqrt(df["intensity"])
+    intensity = savgol_filter(intensity,
+                              window_length=cfg.savgol_window,
+                              polyorder=cfg.savgol_poly)
+
+    # baseline correction
+    bkg = Baseline(x_data=df["mass"]).snip(
+        intensity,
+        max_half_window=cfg.baseline_half_window,
+        decreasing=True,
+        smooth_half_window=0
+    )[0]
+    intensity -= bkg
+    intensity[intensity < 0] = 0  # remove any small negative values post-baseline
+
+    out = pd.DataFrame({"mass": df["mass"], "intensity": intensity})
+
+    mmin, mmax = cfg.trim_from, cfg.trim_to
+    out = out[(out.mass.between(mmin, mmax))].reset_index(drop=True)
+
+    total = out["intensity"].sum()
+    if total > 0:
+        out["intensity"] /= total
+    return out
+
+
+def bin_spectrum(
+        df: pd.DataFrame,
+        cfg: PreprocessingSettings,
+        bin_width: int | float | None = None,
+    ) -> pd.DataFrame:
+    """
+    Bin intensities using *inclusive left* intervals
+    [start, start+bin_width). Returns DataFrame («mass», «intensity»).
+    """
+    if bin_width is None:
+        raise ValueError(" 'bin_width=None': no binning requested.")
+
+    edges = np.arange(cfg.trim_from, cfg.trim_to + bin_width, bin_width)
+    labels = edges[:-1].astype(str)
+    binned = (
+        df
+        .assign(bins=pd.cut(df.mass, edges, labels=labels, include_lowest=True))
+        .groupby("bins", observed=True)["intensity"]
+        .sum()
+        .reindex(labels, fill_value=0.0)
+        .reset_index()
+        .rename(columns={"bins": "mass"})
+    )
+    return binned

maldiamrkit/spectrum.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+from pathlib import Path
+import pandas as pd
+
+from .config import PreprocessingSettings
+from .preprocessing import preprocess, bin_spectrum
+from .io import read_spectrum
+
+
+class MaldiSpectrum:
+    """
+    A single MALDI-TOF spectrum.
+
+    Workflow
+    --------
+    >>> spec = MaldiSpectrum("raw/abc.txt")
+    >>> spec.preprocess()
+    >>> spec.bin(3)
+    """
+
+    def __init__(
+            self,
+            source: str | Path | pd.DataFrame,
+            *,
+            cfg: PreprocessingSettings | None = None,
+            verbose: bool = False,
+        ) -> MaldiSpectrum:
+        self.cfg = cfg or PreprocessingSettings()
+        self._raw: pd.DataFrame
+        self._preprocessed: pd.DataFrame | None = None
+        self._binned: pd.DataFrame | None = None
+        self.verbose = verbose
+
+        if isinstance(source, (str, Path)):
+            self.path = Path(source)
+            self._raw = read_spectrum(self.path)
+            self.id = self.path.stem
+        elif isinstance(source, pd.DataFrame):
+            self.path = None
+            self._raw = source.copy()
+            self.id = "in-memory"
+        else:
+            raise TypeError("Unsupported source type for MaldiSpectrum")
+
+    @property
+    def raw(self) -> pd.DataFrame:
+        return self._raw.copy()
+    
+    @property
+    def bin_width(self) -> int | float | None:
+        return self._bin_width
+
+    @property
+    def preprocessed(self) -> pd.DataFrame:
+        if self._preprocessed is None:
+            raise RuntimeError("Call .preprocess() before accessing this property.")
+        return self._preprocessed.copy()
+
+    @property
+    def binned(self) -> pd.DataFrame:
+        if self._binned is None:
+            raise RuntimeError("Call .bin() before accessing this property.")
+        return self._binned.copy()
+
+    def preprocess(self, **override) -> MaldiSpectrum:
+        """
+        Run baseline correction, smoothing, normalisation, trimming.
+        Optionally override parameters from the current `PreprocessingSettings`
+        with `**override` *kwargs*.
+        """
+        cfg = self.cfg if not override else self.cfg.__class__(**{**self.cfg.as_dict(), **override})
+        self._preprocessed = preprocess(self._raw, cfg)
+        if self.verbose:
+            print(f"INFO: Preprocessed spectrum {self.id}")
+        return self
+
+    def bin(self, bin_width: int | float) -> MaldiSpectrum:
+        """
+        Binning. If `bin_width` is None we skip binning.
+        """
+        self._bin_width = bin_width
+
+        if self._preprocessed is None:
+            self.preprocess()
+
+        self._binned = bin_spectrum(self._preprocessed, self.cfg, self._bin_width)
+        if self.verbose:
+            print(F"INFO: Binned spectrum {self.id} (w={self._bin_width})")
+        return self
+
+    def plot(self, binned: bool = True, ax=None, **kwargs):
+        import matplotlib.pyplot as plt
+        import seaborn as sns
+        _ax = ax or plt.subplots(figsize=(10, 4))[1]
+        data = self.binned if binned else (self.preprocessed if self._preprocessed is not None else self.raw)
+        if binned:
+            sns.barplot(data=data, x="mass", y="intensity", ax=_ax, **kwargs)
+        else:
+            _ax.plot(data.mass, data.intensity, **kwargs)
+        _ax.set(
+            title=f"{self.id}{' (binned)' if binned else ''}",
+            xlabel="m/z", ylabel="intensity", xticks=[],
+            ylim=[0,(data.intensity.max())*1.05]
+        )
+        return _ax

maldiamrkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: MaldiAMRKit
+Version: 0.1.0
+Summary: Toolkit to read and preprocess MALDI-TOF mass-spectra for AMR analyses.
+Author-email: Ettore Rocchi <ettoreroc@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EttoreRocchi/MaldiAMRKit
+Project-URL: Documentation, https://github.com/EttoreRocchi/MaldiAMRKit#readme
+Project-URL: Source, https://github.com/EttoreRocchi/MaldiAMRKit
+Project-URL: Issues, https://github.com/EttoreRocchi/MaldiAMRKit/issues
+Keywords: MALDI,mass-spectrometry,machine-learning,scikit-learn
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
+Requires-Dist: pybaselines
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Dynamic: license-file
+
+# MaldiAMRKit
+
+<p align="center">
+  <img src="docs/maldiamrkit.png" alt="MaldiAMRKit" width="250"/>
+</p>
+<p align="center">
+  <strong>Toolkit to read and preprocess MALDI-TOF mass-spectra for AMR analyses</strong>
+</p>
+
+## 🚀 Installation
+
+```bash
+pip install maldiamrkit
+```
+
+## 🏃 Quick Start
+
+```python
+from maldiamrkit.spectrum import MaldiSpectrum
+from maldiamrkit.dataset import MaldiSet
+from maldiamrkit.peak_detector import MaldiPeakDetector
+
+# Load and preprocess a single spectrum
+spec = MaldiSpectrum("data/1s.txt").preprocess() # smoothing, baseline removal, normalisation
+spec.bin(3) # [optional] bin width 3 Da
+spec.plot(binned=True) # plot
+
+# Build a dataset from a directory of spectra + metadata CSV
+data = MaldiSet.from_directory(
+  "data/", "data/metadata/metadata.csv",
+  aggregate_by=dict(antibiotic="Drug"),
+  bin_width=3
+)
+X, y = data.X, data.y
+
+# Machine learning pipeline
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.linear_model import LogisticRegression
+
+pipe = Pipeline([
+    ("peaks", MaldiPeakDetector(binary=False, prominence=0.05)),
+    ("scaler", StandardScaler()),
+    ("clf", LogisticRegression(max_iter=500))
+])
+pipe.fit(X, y)
+```
+For further details please see the [quick guide](docs/quick_guide.ipynb).
+
+## 🤝 Contributing
+
+Pull requests, bug reports, and feature ideas are welcome: feel free to open a PR!
+
+## 📝 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

maldiamrkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+maldiamrkit/__init__.py,sha256=PWufJsuW3fEoO-eXr5TvnttWdmPPKdMZjuBqUJEwho8,418
+maldiamrkit/config.py,sha256=BkfMteV_N7-W1etqi_Jm1wupa9QcJafp3nSp5spl_SI,292
+maldiamrkit/dataset.py,sha256=bH7f7FQV5xuIF6jcktgjna7gpJlXR0tVTrFUmS_7k6o,5939
+maldiamrkit/io.py,sha256=ENWzDFKxC6-3wzWOOyoV52tmk2CkWS8Xk0icOP8sp9o,762
+maldiamrkit/peak_detector.py,sha256=emlf_-KaWMnHocvhJw3leTKXerygtzjQuZBqDauKPJs,1736
+maldiamrkit/preprocessing.py,sha256=wec26M0BWXlGM-LIx7rbjLOrw60-5w8cIfj6k-4JZZ0,2053
+maldiamrkit/spectrum.py,sha256=A_MYkTdVxjW2MaZ3s87czaEmy-_dSuhgEA5aXHhYZ_M,3490
+maldiamrkit-0.1.0.dist-info/licenses/LICENSE,sha256=O34CBRTmdL59PxDYOa6nq1N0-2A9xyXGkBXKbsL1NeY,1070
+maldiamrkit-0.1.0.dist-info/METADATA,sha256=zKLqMaWa0fWIA5D4VES5uWaxttxFk4DrWjqOinaZ_uA,2620
+maldiamrkit-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+maldiamrkit-0.1.0.dist-info/top_level.txt,sha256=Xws_Zvs9hgSfp2yNawSCSC84sYt0_AJmyJzYEjEMFZA,12
+maldiamrkit-0.1.0.dist-info/RECORD,,

maldiamrkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

maldiamrkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ettore Rocchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maldiamrkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+maldiamrkit