labmcp-ms-data 0.1.0__py3-none-any.whl

labmcp_ms_data/__init__.py

@@ -0,0 +1 @@
+"""LabMCP server for Mass Spectrometry Data (mzML, Bruker TDF, vendor conversion)."""

labmcp_ms_data/analysis.py

@@ -0,0 +1,148 @@
+"""Numerical helpers: chromatogram downsampling, XIC peak integration, spectrum peak lists (numpy only)."""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+PROTON_MASS = 1.007276
+
+
+def downsample_max_indices(y: np.ndarray, max_points: int) -> np.ndarray:
+    """Indices kept by :func:`downsample_max` (the highest point of each of ``max_points`` bins)."""
+    y = np.asarray(y, dtype=float)
+    if y.size <= max_points:
+        return np.arange(y.size)
+    bins = np.array_split(np.arange(y.size), max_points)
+    return np.array([b[int(np.argmax(y[b]))] for b in bins if b.size], dtype=np.int64)
+
+
+def downsample_max(x: np.ndarray, y: np.ndarray, max_points: int) -> tuple[list[float], list[float]]:
+    """Split into ``max_points`` contiguous bins and keep, per bin, the point with the highest ``y``.
+
+    Keeping the maximum (not the mean) preserves chromatographic peak heights and apex positions.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    idx = downsample_max_indices(y, max_points)
+    return x[idx].tolist(), y[idx].tolist()
+
+
+def trapezoid(y: np.ndarray, x: np.ndarray) -> float:
+    y = np.asarray(y, dtype=float)
+    x = np.asarray(x, dtype=float)
+    if y.size < 2:
+        return 0.0
+    return float(np.sum((y[1:] + y[:-1]) * np.diff(x)) / 2.0)
+
+
+@dataclass
+class ChromPeak:
+    apex_rt_min: float
+    apex_intensity: float
+    start_rt_min: float
+    end_rt_min: float
+    area: float  # intensity x minutes, baseline not subtracted
+    fwhm_s: float | None
+    points_across_peak: int
+
+
+def _half_crossing(
+    x: np.ndarray, y: np.ndarray, i: int, level: float, step: int, lo: int, hi: int
+) -> float | None:
+    """RT where the trace first falls below ``level`` walking from ``i``, within ``lo..hi`` only."""
+    j = i
+    while lo <= j + step <= hi:
+        k = j + step
+        if y[k] < level:
+            frac = (y[j] - level) / (y[j] - y[k]) if y[j] != y[k] else 0.0
+            return float(x[j] + frac * (x[k] - x[j]))
+        j = k
+    return None
+
+
+def integrate_apex_peak(
+    rt_min: np.ndarray, y: np.ndarray, *, stop_fraction: float = 0.01
+) -> ChromPeak | None:
+    """Find the most intense point and integrate the peak around it.
+
+    The peak extends from the apex on each side until the trace falls below ``stop_fraction`` (1 %) of the
+    apex or reaches a valley (a point lower than the next 2 points on that side). Area is the
+    trapezoidal integral of intensity over retention time in minutes, without baseline subtraction.
+    """
+    rt = np.asarray(rt_min, dtype=float)
+    y = np.asarray(y, dtype=float)
+    if y.size == 0 or not np.any(y > 0):
+        return None
+    i = int(np.argmax(y))
+    apex = float(y[i])
+    stop = stop_fraction * apex
+
+    def walk(step: int) -> int:
+        j = i
+        while 0 <= j + step < y.size:
+            k = j + step
+            if y[k] <= stop:
+                return k
+            k2 = k + step
+            k3 = k2 + step
+            if 0 <= k3 < y.size and y[k2] > y[k] and y[k3] > y[k]:
+                return k  # valley
+            j = k
+        return j
+
+    lo, hi = walk(-1), walk(+1)
+    # FWHM of the apex peak only: a co-eluting neighbour beyond a valley must not widen it.
+    left = _half_crossing(rt, y, i, apex / 2, -1, lo, hi)
+    right = _half_crossing(rt, y, i, apex / 2, +1, lo, hi)
+    fwhm = (right - left) * 60.0 if left is not None and right is not None else None
+    return ChromPeak(
+        apex_rt_min=float(rt[i]),
+        apex_intensity=apex,
+        start_rt_min=float(rt[lo]),
+        end_rt_min=float(rt[hi]),
+        area=trapezoid(y[lo : hi + 1], rt[lo : hi + 1]),
+        fwhm_s=fwhm,
+        points_across_peak=int(hi - lo + 1),
+    )
+
+
+def tolerance_da(mz: float, tol: float, unit: str) -> float:
+    return mz * tol * 1e-6 if unit == "ppm" else tol
+
+
+def local_maxima(mz: np.ndarray, intensity: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Crude centroiding of profile data: keep points higher than both neighbours."""
+    if intensity.size < 3:
+        return mz, intensity
+    y = intensity
+    keep = np.zeros(y.size, dtype=bool)
+    keep[1:-1] = (y[1:-1] > y[:-2]) & (y[1:-1] >= y[2:])
+    keep[0] = y[0] > y[1]
+    keep[-1] = y[-1] > y[-2]
+    return mz[keep], y[keep]
+
+
+def write_csv(path: Path, header: list[str], columns: list[np.ndarray | list], *, overwrite: bool = False) -> str:
+    """Write equal-length columns to CSV and return the absolute path.
+
+    Without ``overwrite`` the file is created exclusively (``FileExistsError`` if it appeared meanwhile).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w" if overwrite else "x", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        writer.writerow(header)
+        for row in zip(*columns, strict=True):
+            out = []
+            for v in row:
+                if v is None or (isinstance(v, float) and not np.isfinite(v)):
+                    out.append("")
+                elif isinstance(v, (float, np.floating)):
+                    out.append(f"{float(v):.8g}")
+                else:
+                    out.append(str(v))
+            writer.writerow(out)
+    return str(path)

labmcp_ms_data/converter.py

@@ -0,0 +1,277 @@
+"""Vendor-file conversion to mzML with a converter the USER has installed.
+
+No vendor libraries are bundled or downloaded (their licences do not allow redistribution).
+Supported converters (command lines checked against the official documentation):
+
+* **ProteoWizard msconvert** (https://proteowizard.sourceforge.io/tools/msconvert.html), native
+  on Windows with the vendor readers::
+
+      msconvert <input> -o <outdir> --mzML --zlib [--gzip] [--filter "peakPicking vendor msLevel=1-"]
+
+  (``peakPicking [<PickerType> [snr=] [peakSpace=] [msLevel=<ms_levels>]]``; it must be the first
+  filter to use the vendor centroiding.)
+* **msconvert in Docker** on Linux/macOS, using the image
+  ``proteowizard/pwiz-skyline-i-agree-to-the-vendor-licenses`` (by pulling it the user accepts
+  the vendor licences; https://hub.docker.com/r/proteowizard/pwiz-skyline-i-agree-to-the-vendor-licenses)::
+
+      docker run --rm -e WINEDEBUG=-all -v <input dir>:/data:ro -v <output dir>:/out <image> \
+          wine msconvert /data/<file> -o /out ...
+
+  Only the input's folder (read-only) and the output folder are mounted.
+
+* **ThermoRawFileParser** (https://github.com/compomics/ThermoRawFileParser), cross-platform .NET,
+  Thermo ``.raw`` only. Options only work in ``-option=value`` form::
+
+      ThermoRawFileParser -i=<input.raw> -o=<outdir> -f=2 [-p] [-g]
+
+  (``-f=2`` indexed mzML; ``-p`` disables the native Thermo peak picking; ``-g`` gzips the output.)
+
+Argument lists are built as lists and run without a shell, with a timeout. On timeout the whole
+process tree is killed (converters are often started through wrapper scripts), and a Docker
+container is killed by name.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import signal
+import subprocess
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from labmcp import InstrumentProtocolError
+
+from labmcp_ms_data.files import FORMATS, run_stem
+
+DOCKER_IMAGE = "proteowizard/pwiz-skyline-i-agree-to-the-vendor-licenses"
+CONVERTERS = ("auto", "msconvert", "docker", "thermorawfileparser")
+CONVERTIBLE = {"thermo_raw", "waters_raw", "agilent_d", "bruker_baf", "bruker_tdf", "sciex_wiff",
+               "shimadzu_lcd", "mzxml"}  # fmt: skip
+_TRFP_NAMES = ("ThermoRawFileParser", "ThermoRawFileParser.sh", "ThermoRawFileParser.exe")
+_MSCONVERT_NAMES = ("msconvert", "msconvert.exe")
+
+
+@dataclass
+class ConversionPlan:
+    converter: str
+    argv: list[str]
+    output: Path
+    notes: list[str] = field(default_factory=list)
+    container_name: str | None = None
+
+
+@dataclass
+class ConversionResult:
+    returncode: int | None
+    duration_s: float
+    stdout_tail: str
+    stderr_tail: str
+    timed_out: bool
+
+
+def _which(names: tuple[str, ...]) -> str | None:
+    for n in names:
+        found = shutil.which(n)
+        if found:
+            return found
+    return None
+
+
+def _launcher(path: str) -> list[str]:
+    """How to start a .NET tool given as a .dll / .exe path (ThermoRawFileParser releases)."""
+    low = path.lower()
+    if low.endswith(".dll"):
+        return ["dotnet", path]
+    if low.endswith(".exe") and os.name != "nt":
+        return ["mono", path]
+    return [path]
+
+
+def choose_converter(fmt: str, requested: str, converter_path: str | None) -> tuple[str, str | None]:
+    """Return (converter, executable) for ``fmt``; raise with install hints if none is usable."""
+    requested = (requested or "auto").lower()
+    if requested not in CONVERTERS:
+        raise InstrumentProtocolError(
+            f"--option converter must be one of {', '.join(CONVERTERS)} (got {requested!r})."
+        )
+    if requested == "thermorawfileparser" and fmt != "thermo_raw":
+        raise InstrumentProtocolError(
+            "ThermoRawFileParser only reads Thermo .raw files. Use converter=msconvert or converter=docker."
+        )
+    if requested != "auto":
+        exe = converter_path
+        if exe is None:
+            exe = {
+                "msconvert": _which(_MSCONVERT_NAMES),
+                "docker": _which(("docker",)),
+                "thermorawfileparser": _which(_TRFP_NAMES),
+            }[requested]
+        return requested, exe
+    if converter_path:  # auto, but the user named the program: tell which one it is from its name
+        name = Path(converter_path).name.lower()
+        for conv, key in (("thermorawfileparser", "thermorawfileparser"), ("docker", "docker"),
+                          ("msconvert", "msconvert")):  # fmt: skip
+            if key in name:
+                return choose_converter(fmt, conv, converter_path)
+        raise InstrumentProtocolError(
+            f"Cannot tell which converter {converter_path!r} is. Add --option converter=msconvert, "
+            "docker or thermorawfileparser."
+        )
+    order = ["thermorawfileparser", "msconvert", "docker"] if fmt == "thermo_raw" else ["msconvert", "docker"]
+    for conv in order:
+        exe = {
+            "msconvert": _which(_MSCONVERT_NAMES),
+            "docker": _which(("docker",)),
+            "thermorawfileparser": _which(_TRFP_NAMES),
+        }[conv]
+        if exe:
+            return conv, exe
+    return "none", None
+
+
+INSTALL_HELP = (
+    "No converter found. Install one and restart the server with --option converter=...: "
+    "ThermoRawFileParser for Thermo .raw (https://github.com/compomics/ThermoRawFileParser, any OS); "
+    "ProteoWizard msconvert on Windows (https://proteowizard.sourceforge.io/download.html); or Docker with "
+    f"`docker pull {DOCKER_IMAGE}` on Linux/macOS (pulling it means you accept the vendor licences). "
+    "Use --option converter_path=<path> if the program is not on PATH."
+)
+
+
+def plan_conversion(
+    input_path: Path,
+    fmt: str,
+    out_dir: Path,
+    *,
+    converter: str = "auto",
+    converter_path: str | None = None,
+    docker_image: str | None = None,
+    peak_picking: bool = True,
+    gzip: bool = False,
+) -> ConversionPlan:
+    if fmt not in CONVERTIBLE:
+        raise InstrumentProtocolError(
+            f"{input_path.name} is {FORMATS.get(fmt, ('', fmt, False))[1]}; it can be read directly, no conversion needed."
+            if fmt in ("mzml", "mzmlb")
+            else f"{input_path.name} is not a convertible vendor format."
+        )
+    conv, exe = choose_converter(fmt, converter, converter_path)
+    if conv == "none" or not exe:
+        raise InstrumentProtocolError(
+            INSTALL_HELP if conv == "none" else f"{conv} was not found on PATH. {INSTALL_HELP}"
+        )
+    ext = ".mzML.gz" if gzip else ".mzML"
+    output = out_dir / (run_stem(input_path) + ext)
+    notes: list[str] = []
+    if conv == "thermorawfileparser":
+        argv = _launcher(exe) + [f"-i={input_path}", f"-o={out_dir}", "-f=2"]
+        if not peak_picking:
+            argv.append("-p")
+        if gzip:
+            argv.append("-g")
+        return ConversionPlan(conv, argv, output, notes)
+    flags = ["--mzML", "--zlib"]
+    if gzip:
+        flags.append("--gzip")
+    if peak_picking:
+        flags += ["--filter", "peakPicking vendor msLevel=1-"]
+    if conv == "msconvert":
+        if os.name != "nt":
+            notes.append(
+                "Native msconvert reads vendor formats only on Windows; on Linux/macOS use converter=docker."
+            )
+        return ConversionPlan(conv, [exe, str(input_path), "-o", str(out_dir), *flags], output, notes)
+    # docker + wine
+    image = docker_image or DOCKER_IMAGE
+    name = f"labmcp-msconvert-{uuid.uuid4().hex[:12]}"
+    in_dir = input_path.parent  # the whole folder: SCIEX .wiff needs its .wiff.scan sidecar
+    for d in (in_dir, out_dir):
+        if not _docker_mountable(d):
+            raise InstrumentProtocolError(
+                f"Docker cannot mount {str(d)!r}: the path contains ':' or ','. Rename the folder, or use "
+                "another converter."
+            )
+    argv = [exe, "run", "--rm", "--name", name, "-e", "WINEDEBUG=-all"]
+    if platform.machine().lower() in ("arm64", "aarch64"):
+        argv += ["--platform", "linux/amd64"]  # the image is x86-64 only (runs under emulation)
+        notes.append("Apple Silicon / ARM: the x86-64 image runs under emulation and is slow.")
+    # Input folder read-only; only the output folder is writable.
+    argv += ["-v", f"{in_dir}:/data:ro", "-v", f"{out_dir}:/out"]
+    argv += [image, "wine", "msconvert", f"/data/{input_path.name}", "-o", "/out", *flags]
+    if os.name == "posix" and platform.system() == "Linux":
+        notes.append("On Linux the output file is owned by root (written inside the container).")
+    return ConversionPlan(conv, argv, output, notes, container_name=name)
+
+
+def _docker_mountable(path: Path) -> bool:
+    """False if ``docker -v <path>:...`` would split the path (':' separates fields; ',' breaks --mount)."""
+    text = str(path)
+    if os.name == "nt" and len(text) >= 2 and text[1] == ":":
+        text = text[2:]  # the drive letter
+    return ":" not in text and "," not in text
+
+
+def _tail(text: str | bytes | None, n: int = 1500) -> str:
+    if text is None:
+        return ""
+    if isinstance(text, bytes):
+        text = text.decode(errors="replace")
+    return text[-n:]
+
+
+def _kill_tree(proc: subprocess.Popen[str]) -> None:
+    """Kill the converter and everything it started (wrapper scripts start mono/dotnet/wine)."""
+    try:
+        if os.name == "nt":
+            subprocess.run(  # noqa: S603, S607
+                ["taskkill", "/T", "/F", "/PID", str(proc.pid)], capture_output=True, timeout=30, check=False
+            )
+        else:
+            os.killpg(proc.pid, signal.SIGKILL)  # the child leads its own session / process group
+    except (OSError, subprocess.SubprocessError):
+        pass
+    try:
+        proc.kill()
+    except OSError:
+        pass
+
+
+def run_conversion(plan: ConversionPlan, timeout_s: float) -> ConversionResult:
+    t0 = time.monotonic()
+    group: dict[str, object] = (
+        {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} if os.name == "nt" else {"start_new_session": True}
+    )
+    try:
+        proc = subprocess.Popen(  # noqa: S603 - argv list, no shell
+            plan.argv,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            errors="replace",
+            shell=False,
+            **group,  # type: ignore[arg-type]
+        )
+    except OSError as exc:
+        raise InstrumentProtocolError(f"Could not start {plan.argv[0]!r}: {exc}. {INSTALL_HELP}") from exc
+    try:
+        out, err = proc.communicate(timeout=timeout_s)
+    except subprocess.TimeoutExpired as exc:
+        _kill_tree(proc)
+        if plan.container_name:  # killing the docker client does not stop the container
+            try:
+                subprocess.run(  # noqa: S603
+                    [plan.argv[0], "kill", plan.container_name], capture_output=True, timeout=30, check=False
+                )
+            except (OSError, subprocess.SubprocessError):
+                pass
+        try:
+            out, err = proc.communicate(timeout=10)
+        except subprocess.TimeoutExpired:  # something still holds the pipes; give up on the log
+            out, err = exc.stdout, exc.stderr
+        return ConversionResult(None, time.monotonic() - t0, _tail(out), _tail(err), True)
+    return ConversionResult(proc.returncode, time.monotonic() - t0, _tail(out), _tail(err), False)