chromparser 0.1.0__py3-none-any.whl

chromparser/vendors/chromeleon/archive.py

@@ -0,0 +1,310 @@
+"""Chromeleon 7 `.cmbx` archives ("Export to archive").
+
+A `.cmbx` archive is a zip file with a `header.xml` manifest describing the
+exported items (sequence, injections, signals, ...), the serialized sequence
+(`*.cmd`) and one raw data file per signal, audit trail and MS data item. MS
+data items are complete Thermo `.raw` files.
+"""
+
+from __future__ import annotations
+
+import shutil
+import warnings
+import xml.etree.ElementTree as ET
+import zipfile
+from collections.abc import Iterator
+from pathlib import Path
+
+from ..._util import existing_file
+from ...errors import ChromparserWarning, UnsupportedFormat
+from ...model import Injection
+from ..thermo.raw import decode_thermo_raw
+from .raw import decode_signal
+from .sequence import SignalInfo, parse_sequence
+
+_SIGNAL = "Dionex.Chromeleon.Data.Signal"
+_MS_RAW = "Dionex.Chromeleon.Data.MSRawItem"
+_INJECTION = "Dionex.Chromeleon.Data.Injection"
+_SEQUENCE = "Dionex.Chromeleon.Data.Sequence"
+
+
+def _data_vault(url: str) -> str | None:
+    # chrom://<computer>/<data vault>/<folders...>
+    parts = url.split("/")
+    return parts[3] if url.startswith("chrom://") and len(parts) > 3 else None
+
+
+def _iter_injections(
+    root: ET.Element,
+) -> Iterator[tuple[ET.Element, ET.Element | None]]:
+    """Yield (injection, sequence) elements of `header.xml`."""
+
+    def walk(element, sequence):
+        for child in element:
+            item_type = child.get("ItemType")
+            if item_type == _INJECTION:
+                yield child, sequence
+            else:
+                yield from walk(child, child if item_type == _SEQUENCE else sequence)
+
+    yield from walk(root, None)
+
+
+def _raw_items(injection: ET.Element, item_type: str) -> list[ET.Element]:
+    return [e for e in injection.iter() if e.get("ItemType") == item_type]
+
+
+def _open(path: str | Path) -> tuple[zipfile.ZipFile, dict[str, str], ET.Element]:
+    """Open an archive: zip file, member names by lower case name, `header.xml`."""
+    path = existing_file(path)
+    try:
+        archive = zipfile.ZipFile(path)
+    except zipfile.BadZipFile as e:
+        raise UnsupportedFormat(f"'{path}' is not a .cmbx archive: {e}") from e
+    members = {name.lower(): name for name in archive.namelist()}
+    if "header.xml" not in members:
+        archive.close()
+        raise UnsupportedFormat(f"'{path}' is not a .cmbx archive (no header.xml).")
+    return archive, members, ET.fromstring(archive.read(members["header.xml"]))
+
+
+def _injections_with_data(root: ET.Element, members: dict[str, str]):
+    """Yield (injection, sequence, signal items, MS items) of injections with data.
+
+    Only injections whose signals or MS data are in the archive are yielded,
+    in archive order. The position in this sequence is the injection number,
+    as used by `read_cmbx`, the HDF5 layout and `extract_ms_raw`.
+    """
+    for element, sequence in _iter_injections(root):
+        signals = _raw_items(element, _SIGNAL)
+        ms_items = [
+            item
+            for item in _raw_items(element, _MS_RAW)
+            if (item.get("RawDataFilename") or "").lower() in members
+        ]
+        present = [
+            item
+            for item in signals
+            if (item.get("RawDataFilename") or "").lower() in members
+        ]
+        if present or ms_items:
+            yield element, sequence, signals, ms_items
+
+
+def read_cmbx(path: str | Path, *, ms: bool = True) -> list[Injection]:
+    """Read all injections with signals or MS data from a `.cmbx` archive.
+
+    Metadata (signal unit, inject time, injection type and status, instrument
+    method, detector, ...) is read from the sequence file in the archive. Audit
+    trails are skipped, and so are injections without signals and MS data.
+
+    Parameters
+    ----------
+    path : str or Path
+        The `.cmbx` file.
+    ms : bool
+        Read MS data (Thermo `.raw` files). Unsupported MS data raises; pass
+        ``ms=False`` to read only the signals.
+
+    Returns
+    -------
+    list of Injection
+        Injections in archive order.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    UnsupportedFormat
+        If the file is not a `.cmbx` archive.
+    UnsupportedVariant, CorruptFile
+        If a signal or MS data item is unsupported or malformed.
+    """
+    path = Path(path)
+    archive, members, root = _open(path)
+    with archive:
+        sequences: dict[str, dict[str, SignalInfo]] = {}
+
+        def sequence_info(sequence) -> dict[str, SignalInfo]:
+            name = sequence.get("Filename") if sequence is not None else None
+            if not name or name.lower() not in members:
+                return {}
+            if name not in sequences:
+                try:
+                    sequences[name] = parse_sequence(
+                        archive.read(members[name.lower()])
+                    )
+                except Exception as e:
+                    warnings.warn(
+                        f"Could not read metadata from sequence {name}: {e}",
+                        ChromparserWarning,
+                        stacklevel=3,
+                    )
+                    sequences[name] = {}
+            return sequences[name]
+
+        injections = []
+        for element, sequence, signal_elements, ms_elements in _injections_with_data(
+            root, members
+        ):
+            injection = Injection(
+                name=element.get("Name", ""),
+                metadata={
+                    "url": element.get("Url"),
+                    "data_vault": _data_vault(element.get("Url", "")),
+                    "sequence": sequence.get("Name") if sequence is not None else None,
+                },
+            )
+            for signal_element in signal_elements:
+                raw_name = signal_element.get("RawDataFilename")
+                if not raw_name or raw_name.lower() not in members:
+                    warnings.warn(
+                        f"Raw data of signal {signal_element.get('Name')!r} "
+                        f"is missing in {path}.",
+                        ChromparserWarning,
+                        stacklevel=2,
+                    )
+                    continue
+                signal = decode_signal(archive.read(members[raw_name.lower()]))
+                signal.channel = signal_element.get("Name") or signal.channel
+                raw_id = signal_element.get("RawDataFileId", "")
+                signal.metadata.update(
+                    url=signal_element.get("Url"),
+                    raw_data_file=raw_name,
+                    raw_data_file_id=raw_id or None,
+                )
+
+                info = sequence_info(sequence).get(raw_id.lower())
+                if info is not None:
+                    signal.unit = info.unit
+                    signal.metadata.update(info.metadata)
+                    if info.expected_points not in (None, len(signal)):
+                        warnings.warn(
+                            f"Signal {signal.channel!r} in {path} has {len(signal)} "
+                            f"data points, the sequence lists {info.expected_points}.",
+                            ChromparserWarning,
+                            stacklevel=2,
+                        )
+                    if info.injection_name:
+                        injection.name = info.injection_name
+                    injection.inject_time = injection.inject_time or info.inject_time
+                    injection.metadata.update(info.injection_metadata)
+
+                signal.metadata = {
+                    k: v for k, v in signal.metadata.items() if v is not None
+                }
+                injection.signals[signal.channel] = signal
+
+            for ms_element in ms_elements if ms else []:
+                raw_name = ms_element.get("RawDataFilename")
+                name = ms_element.get("Name") or "MS"
+                try:
+                    ms_data = decode_thermo_raw(
+                        archive.read(members[raw_name.lower()]), name
+                    )
+                except ValueError as e:
+                    raise type(e)(
+                        f"MS data {name!r} ({raw_name}) in {path}: {e} "
+                        "Use ms=False (--no-ms) to read only the signals, or "
+                        "extract the Thermo .raw file with extract_ms_raw "
+                        "(chromparser extract-ms)."
+                    ) from e
+                ms_data.metadata.update(
+                    url=ms_element.get("Url"),
+                    raw_data_file=raw_name,
+                    raw_data_file_id=ms_element.get("RawDataFileId") or None,
+                )
+                ms_data.metadata = {
+                    k: v for k, v in ms_data.metadata.items() if v is not None
+                }
+                injection.ms[name] = ms_data
+
+            if injection.signals or injection.ms:
+                if injection.signals:
+                    first = next(iter(injection.signals.values()))
+                    injection.metadata["guid"] = first.metadata.get("injection_guid")
+                injection.metadata = {
+                    k: v for k, v in injection.metadata.items() if v is not None
+                }
+                injections.append(injection)
+
+    if not injections:
+        warnings.warn(f"No signals found in {path}.", ChromparserWarning, stacklevel=2)
+    return injections
+
+
+def extract_ms_raw(
+    path: str | Path,
+    directory: str | Path | None = None,
+    *,
+    overwrite: bool = False,
+) -> list[Path]:
+    """Write the Thermo `.raw` files embedded in a `.cmbx` archive to a directory.
+
+    The files are written unchanged and can be opened with any tool for Thermo
+    raw files. They are named ``<archive>_injection_<n>_<item>.raw``, where
+    ``n`` is the injection number as in `read_cmbx` and the HDF5 layout (from
+    1) and ``item`` the name of the MS data item, e.g.
+    ``run_injection_0001_MSDevice.raw``.
+
+    Parameters
+    ----------
+    path : str or Path
+        The `.cmbx` file.
+    directory : str or Path, optional
+        Output directory, created if needed. Defaults to the directory of the
+        archive.
+    overwrite : bool
+        Replace existing files.
+
+    Returns
+    -------
+    list of Path
+        Paths of the written files (empty if the archive has no MS data).
+
+    Raises
+    ------
+    FileExistsError
+        If an output file exists and `overwrite` is False.
+    UnsupportedFormat
+        If the file is not a `.cmbx` archive.
+    """
+    path = Path(path)
+    directory = Path(directory) if directory is not None else path.parent
+    archive, members, root = _open(path)
+    written = []
+    with archive:
+        targets = []
+        for number, (_, _, _, ms_elements) in enumerate(
+            _injections_with_data(root, members), start=1
+        ):
+            for item in ms_elements:
+                name = (item.get("Name") or "MS").replace("/", "_")
+                target = directory / f"{path.stem}_injection_{number:04d}_{name}.raw"
+                if target.exists() and not overwrite:
+                    raise FileExistsError(
+                        f"{target} exists, use overwrite=True to replace it."
+                    )
+                targets.append((members[item.get("RawDataFilename").lower()], target))
+        if targets:
+            directory.mkdir(parents=True, exist_ok=True)
+        for member, target in targets:
+            with archive.open(member) as source, target.open("wb") as output:
+                shutil.copyfileobj(source, output, 1 << 20)
+            written.append(target)
+    return written
+
+
+def sniff_cmbx(path: str | Path) -> bool:
+    """Whether `path` is a zip archive with a Chromeleon `header.xml`."""
+    if not Path(path).is_file() or not zipfile.is_zipfile(path):
+        return False
+    try:
+        with zipfile.ZipFile(path) as archive:
+            names = {name.lower(): name for name in archive.namelist()}
+            if "header.xml" not in names:
+                return False
+            with archive.open(names["header.xml"]) as f:
+                return b"Dionex.Chromeleon" in f.read(1 << 16)
+    except (zipfile.BadZipFile, OSError):
+        return False