prideQC 0.2.0__py3-none-any.whl

prideqc/__init__.py

@@ -0,0 +1,13 @@
+"""QC and technical annotations from one pass over mass spectrometry data."""
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover - source tree before the Hatch VCS hook runs
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("prideQC")
+    except PackageNotFoundError:
+        __version__ = "0+unknown"
+
+__all__ = ["__version__"]

prideqc/__main__.py

@@ -0,0 +1,5 @@
+"""Support ``python -m prideqc``."""
+
+from prideqc.cli import main
+
+raise SystemExit(main())

prideqc/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

prideqc/annotations.py

@@ -0,0 +1,217 @@
+"""Technical evidence and conservative, auditable SDRF suggestions."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+
+import numpy as np
+
+from prideqc.metrics import RunSummary
+from prideqc.models import Annotation, CVTerm, EvidenceKind, RunMetadata, Spectrum
+
+OBSERVED = EvidenceKind.OBSERVED
+INFERRED = EvidenceKind.INFERRED
+UNAVAILABLE = EvidenceKind.UNAVAILABLE
+
+
+class TechnicalAnnotator:
+    """Separate measured header/scan facts from acquisition-mode heuristics."""
+
+    def annotate(self, metadata: RunMetadata, run: RunSummary) -> list[Annotation]:
+        annotations = []
+        for name, terms, column in (
+            ("instrument", metadata.instruments, "comment[instrument]"),
+            ("mass_analyzers", metadata.analyzers, None),
+            ("ionization", metadata.ionization, None),
+        ):
+            annotations.append(Annotation(
+                name, [{"accession": t.accession, "name": t.name} for t in terms] or None,
+                OBSERVED if terms else UNAVAILABLE, "mzML instrumentConfiguration CV terms",
+                "All configurations are reported; only an unambiguous instrument is proposed.",
+                sdrf_column=column,
+                sdrf_value=terms[0].sdrf_value() if len(terms) == 1 and column else None,
+            ))
+        annotations.append(Annotation(
+            "instrument_details",
+            metadata.instrument_details or None,
+            OBSERVED if metadata.instrument_details else UNAVAILABLE,
+            "OpenMS ExperimentalSettings instrument fields",
+            "Plain instrument fields are preserved as observed metadata; no CV accession is inferred.",
+        ))
+        annotations.append(Annotation("instrument_serial_numbers", metadata.serial_numbers or None,
+                                      OBSERVED if metadata.serial_numbers else UNAVAILABLE,
+                                      "mzML instrument serial number"))
+        for level, summary in sorted(run.levels.items()):
+            if level < 2:
+                continue
+            methods = [
+                {"accession": key[0], "name": key[1], "count": count}
+                for key, count in sorted(summary.activation.items())
+            ]
+            only = next(iter(summary.activation)) if len(summary.activation) == 1 else None
+            complete = summary.missing_activation == 0
+            annotations.append(Annotation(
+                f"dissociation_ms{level}", methods or None, OBSERVED if methods else UNAVAILABLE,
+                "mzML precursor activation; scan counts per method",
+                "Co-occurring methods are preserved; missing activation prevents automatic fill.",
+                support=summary.count - summary.missing_activation, total=summary.count,
+                sdrf_column="comment[dissociation method]" if level == 2 else None,
+                sdrf_value=CVTerm(*only).sdrf_value() if only and complete and level == 2 else None,
+            ))
+            energies = [f"{value:g} {unit}" for value, unit in sorted(summary.collision_energy)]
+            annotations.append(Annotation(
+                f"collision_energy_ms{level}", energies or None,
+                OBSERVED if energies else UNAVAILABLE, "mzML activation energy with preserved units",
+                "Multiple recorded values do not establish stepped energy within each scan.",
+                support=summary.count - summary.missing_collision_energy, total=summary.count,
+                sdrf_column="comment[collision energy]" if level == 2 else None,
+                sdrf_value=";".join(
+                    energies,
+                ) if energies and level == 2 and summary.missing_collision_energy == 0 else None,
+            ))
+        annotations.extend(self._acquisition(run))
+        for name, column in (
+            ("precursor_mass_tolerance", "comment[precursor mass tolerance]"),
+            ("fragment_mass_tolerance", "comment[fragment mass tolerance]"),
+        ):
+            annotations.append(Annotation(
+                name, None, UNAVAILABLE, "No calibrated mass-error estimator configured",
+                "Search tolerances cannot be measured from instrument class or isolation width.",
+                sdrf_column=column,
+            ))
+        return annotations
+
+    def _acquisition(self, run: RunSummary) -> list[Annotation]:
+        summary = run.levels.get(2)
+        widths = np.asarray(summary.isolation_widths) if summary else np.array([])
+        total = summary.count if summary else 0
+        label, accession, support, support_total = None, None, 0, total
+        method = (
+            "acquisition heuristic v2: >=100 MS2, >=90% width coverage; fixed-cycle DIA "
+            "requires >=20 cycles, >=8 MS2/cycle, >=90% cycle/set/order consensus, target-grid "
+            "agreement, and median width >=5 Th; narrow DDA requires >=500 unique targets"
+        )
+        detail = (
+            "High-specificity inference only. Wide-window consensus supports DIA. Stable repeated "
+            "MS1-delimited cycles with non-narrow isolation also support DIA. Narrow isolation is "
+            "called DDA only when many distinct precursor targets are observed; small fixed-target "
+            "narrow runs abstain because PRM and narrow-window DIA are ambiguous. Width unit is Th (m/z)."
+        )
+
+        if summary is not None and widths.size >= 100 and total and widths.size / total >= 0.9:
+            narrow = int(np.count_nonzero(widths <= 3))
+            wide = int(np.count_nonzero(widths >= 15))
+            narrow_fraction = narrow / widths.size
+            wide_fraction = wide / widths.size
+            median_width = float(np.median(widths))
+
+            cycle = run.acquisition_cycles.metrics()
+            cycle_count = int(cycle["AcquisitionCycle_Count"] or 0)
+            cycle_mode = int(cycle["AcquisitionCycle_MS2Count_Mode"] or 0)
+            cycle_modal_fraction = cycle["AcquisitionCycle_MS2Count_ModalFraction"]
+            target_coverage = cycle["AcquisitionCycle_TargetCoverageFraction"]
+            target_eligible_fraction = cycle["AcquisitionCycle_TargetEligibleFraction"]
+            set_modal_fraction = cycle["AcquisitionCycle_TargetSetModalFraction"]
+            order_modal_fraction = cycle["AcquisitionCycle_TargetOrderModalFraction"]
+
+            rounded_targets = np.round(np.asarray(summary.isolation_precursor_mz), 1)
+            unique_targets = int(np.unique(rounded_targets).size) if rounded_targets.size else 0
+            target_grid_tolerance = max(1, int(round(cycle_mode * 0.1)))
+
+            stable_cycle = (
+                cycle_count >= 20
+                and cycle_mode >= 8
+                and 8 <= unique_targets <= 200
+                and abs(unique_targets - cycle_mode) <= target_grid_tolerance
+                and cycle_modal_fraction is not None and cycle_modal_fraction >= 0.9
+                and target_coverage is not None and target_coverage >= 0.9
+                and target_eligible_fraction is not None and target_eligible_fraction >= 0.9
+                and set_modal_fraction is not None and set_modal_fraction >= 0.9
+                and order_modal_fraction is not None and order_modal_fraction >= 0.9
+            )
+
+            if wide_fraction >= 0.9:
+                label, accession, support = "Data-independent acquisition", "PRIDE:0000450", wide
+            elif stable_cycle and median_width >= 5:
+                label, accession = "Data-independent acquisition", "PRIDE:0000450"
+                modal_cycles = int(round(order_modal_fraction * cycle_count))
+                support_total = total
+                support = min(total, modal_cycles * cycle_mode)
+            elif narrow_fraction >= 0.9 and unique_targets >= 500:
+                label, accession, support = "Data-dependent acquisition", "PRIDE:0000627", narrow
+
+        return [Annotation(
+            "acquisition_method", label, INFERRED if label else UNAVAILABLE,
+            method,
+            detail,
+            support=support, total=support_total,
+            sdrf_column="comment[proteomics data acquisition method]",
+            sdrf_value=CVTerm(accession, label).sdrf_value() if accession and label else None,
+        )]
+
+
+class DiagnosticIonCollector:
+    """Optional lightweight signature screen; never asserts a PTM or label plex.
+
+    Count centroid MS2/MS3 spectra with several reporter/diagnostic ions. No
+    database search, mass-shift pairing, random null model, or stale dependency.
+    """
+
+    TARGETS = {
+        "TMT_family": (126.127726, 127.131081, 128.134436, 129.137790, 130.141145, 131.138180),
+        "iTRAQ_family": (114.1112, 115.1083, 116.1116, 117.1150),
+        "glycan_oxonium": (204.0867, 366.1395),
+    }
+
+    def __init__(self, ppm: float = 20.0, min_relative_intensity: float = 0.01) -> None:
+        if not math.isfinite(ppm) or ppm <= 0:
+            raise ValueError("Diagnostic tolerance must be finite and positive.")
+        if not 0 < min_relative_intensity <= 1:
+            raise ValueError("Relative intensity threshold must be in (0, 1].")
+        self.ppm = ppm
+        self.min_relative_intensity = min_relative_intensity
+        self.counts: Counter[str] = Counter()
+        self.total = 0
+        self.skipped_profile = 0
+
+    def consume_spectrum(self, spectrum: Spectrum) -> None:
+        if spectrum.ms_level not in (2, 3):
+            return
+        if spectrum.representation != "centroid":
+            self.skipped_profile += 1
+            return
+        self.total += 1
+        mz, intensity = spectrum.mz, spectrum.intensity
+        valid = np.isfinite(mz) & (mz > 0) & np.isfinite(intensity) & (intensity > 0)
+        mz, intensity = mz[valid], intensity[valid]
+        if not mz.size:
+            return
+        mz = np.sort(mz[intensity >= intensity.max() * self.min_relative_intensity])
+        for name, targets in self.TARGETS.items():
+            masses = np.array(targets)
+            delta = masses * self.ppm / 1e6
+            matches = np.searchsorted(
+                mz,
+                masses + delta,
+                side="right",
+            ) > np.searchsorted(
+                mz,
+                masses - delta,
+                side="left",
+            )
+            required = 2 if name == "glycan_oxonium" else 3
+            self.counts[name] += int(np.count_nonzero(matches) >= required)
+
+    def annotations(self) -> list[Annotation]:
+        return [Annotation(
+            f"signature_{name}", {"matching_spectra": self.counts[name], "eligible_spectra": self.total,
+                                  "excluded_profile_or_unknown": self.skipped_profile},
+            INFERRED if self.counts[name] else UNAVAILABLE,
+            f"diagnostic ion screen v1; {self.ppm:g} ppm; relative intensity >= {self.min_relative_intensity:g}",
+            (
+                "Candidate evidence only; not proof of a modification, enrichment, labeling "
+                "channel, or plex. Never written into SDRF automatically."
+            ),
+            support=self.counts[name], total=self.total,
+        ) for name in self.TARGETS]