chromparser 0.1.0__py3-none-any.whl

chromparser/vendors/andi/ms.py

@@ -0,0 +1,358 @@
+"""ANDI-MS netCDF files: centroided GC-MS runs.
+
+One file holds one run: per-scan variables on the scan dimension
+(`scan_acquisition_time` in seconds, `total_intensity`, `scan_index`,
+`point_count`, ...) and the peaks of all scans back to back on the point
+dimension (`mass_values`, `intensity_values`). See `docs/formats/andi.md`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from ... import _netcdf3 as nc
+from ...errors import CorruptFile, UnsupportedVariant, warn
+from ...model import Injection, MSData
+from .common import (
+    apply_scale,
+    attribute_metadata,
+    check_variables,
+    has_variable,
+    injection_of,
+    is_fill,
+    json_value,
+    open_andi,
+)
+
+KEY = "mass_values"
+CENTROID = "Centroided Mass Spectrum"
+MASS_SCAN = "Mass Scan"
+IONISATION = {"Electron Impact": "EI", "Chemical Ionization": "CI"}
+POLARITY = {"Positive Polarity": "positive", "Negative Polarity": "negative"}
+
+#: Per-scan variables of the template that hold no data chromparser keeps
+#: (sentinels such as -9999 or 0 in the files seen so far).
+IGNORED_PER_SCAN = (
+    "a_d_sampling_rate",
+    "a_d_coaddition_factor",
+    "scan_duration",
+    "inter_scan_time",
+    "resolution",
+    "time_range_min",
+    "time_range_max",
+)
+PER_SCAN = (
+    "scan_acquisition_time",
+    "actual_scan_number",
+    "total_intensity",
+    "scan_index",
+    "point_count",
+    "flag_count",
+    "mass_range_min",
+    "mass_range_max",
+    *IGNORED_PER_SCAN,
+)
+PER_POINT = ("mass_values", "intensity_values", "time_values")
+#: instrument variable -> metadata key
+INSTRUMENT = {
+    "instrument_name": "instrument",
+    "instrument_model": "instrument_model",
+    "instrument_app_version": "software",
+    "instrument_id": "andi_instrument_id",
+    "instrument_mfr": "andi_instrument_mfr",
+    "instrument_serial_no": "andi_instrument_serial_no",
+    "instrument_sw_version": "andi_instrument_sw_version",
+    "instrument_fw_version": "andi_instrument_fw_version",
+    "instrument_os_version": "andi_instrument_os_version",
+    "instrument_comments": "andi_instrument_comments",
+}
+KNOWN = {*PER_SCAN, *PER_POINT, *INSTRUMENT, "error_log"}
+#: Prefixes of global attributes that go to the MS metadata.
+MS_ATTRIBUTES = ("test_", "raw_data_")
+
+
+def _strings(f: nc.File, name: str) -> list[str]:
+    if name not in f.variables:
+        return []
+    return [s for s in nc.strings(f.read(name)) if s]
+
+
+def _per_scan(f: nc.File, name: str, n_scans: int, file: str) -> np.ndarray | None:
+    """Read a per-scan variable (`None` when absent); unwritten scans raise."""
+    if name not in f.variables:
+        return None
+    variable = f.variables[name]
+    data = f.read(name)
+    if data.shape != (n_scans,):
+        raise CorruptFile(f"{file}: {name} has shape {data.shape}, not ({n_scans},).")
+    unwritten = np.flatnonzero(is_fill(data, variable.attributes, variable.nc_type))
+    if len(unwritten):
+        raise CorruptFile(
+            f"{file}: {name} is not written from scan index {unwritten[0]} on "
+            f"({len(unwritten)} of {n_scans} scans hold the netCDF fill value); "
+            "the export did not finish."
+        )
+    return data
+
+
+def _peak_offset(
+    scan_index: np.ndarray | None, point_count: np.ndarray | None, file: str
+) -> np.ndarray:
+    if point_count is None and scan_index is None:
+        raise UnsupportedVariant(f"{file}: neither scan_index nor point_count.")
+    if point_count is not None:
+        counts = point_count.astype(np.int64)
+        if np.any(counts < 0):
+            raise CorruptFile(f"{file}: negative point_count.")
+        offset = np.zeros(len(counts) + 1, np.int64)
+        np.cumsum(counts, out=offset[1:])
+        if scan_index is not None and not np.array_equal(scan_index, offset[:-1]):
+            bad = int(np.flatnonzero(scan_index != offset[:-1])[0])
+            raise CorruptFile(
+                f"{file}: scan_index and point_count disagree from scan index {bad} on."
+            )
+        return offset
+    index = scan_index.astype(np.int64)
+    if len(index) and (index[0] != 0 or np.any(np.diff(index) < 0)):
+        raise CorruptFile(f"{file}: scan_index does not start at 0 and increase.")
+    return np.append(index, -1)  # the total is filled in from the point dimension
+
+
+def _ms_metadata(f: nc.File, metadata: dict) -> None:
+    for variable, key in INSTRUMENT.items():
+        values = _strings(f, variable)
+        if values:
+            metadata[key] = values[0] if len(values) == 1 else values
+    errors = _strings(f, "error_log")
+    if errors:
+        metadata["andi_error_log"] = errors
+    attributes = f.attributes
+    mode = json_value(attributes.get("test_ionization_mode"))
+    polarity = json_value(attributes.get("test_ionization_polarity"))
+    for key, value in attribute_metadata(
+        {k: v for k, v in attributes.items() if k.startswith(MS_ATTRIBUTES)}
+    ).items():
+        metadata[key] = value
+    if mode in IONISATION:
+        metadata["ionisation"] = IONISATION[mode]
+        del metadata["andi_test_ionization_mode"]
+    if polarity in POLARITY:
+        metadata["polarity"] = POLARITY[polarity]
+        del metadata["andi_test_ionization_polarity"]
+
+
+def decode_andi_ms(f: nc.File, file: str = "andi") -> tuple[MSData, Injection]:
+    """Decode an open ANDI-MS file.
+
+    Parameters
+    ----------
+    f : chromparser._netcdf3.File
+        The open file.
+    file : str
+        File name for messages.
+
+    Returns
+    -------
+    MSData, Injection
+        The MS run (named ``"MS"``) and its injection (without the MS run).
+
+    Raises
+    ------
+    UnsupportedVariant
+        For profile or library spectra, SIM, flagged peaks, per-peak times or
+        variables on the data dimensions that the reader does not know.
+    CorruptFile
+        For inconsistent or unfinished files.
+    """
+    attributes = f.attributes
+    ms_metadata: dict = {}
+    experiment = json_value(attributes.get("experiment_type"))
+    if experiment is None:
+        warn(ms_metadata, f"{file}: no experiment_type; centroided spectra assumed.")
+    elif experiment != CENTROID:
+        raise UnsupportedVariant(
+            f"{file}: experiment_type {experiment!r} (only {CENTROID!r} is read)."
+        )
+    scan_function = json_value(attributes.get("test_scan_function"))
+    if scan_function not in (None, MASS_SCAN):
+        raise UnsupportedVariant(
+            f"{file}: test_scan_function {scan_function!r} (only {MASS_SCAN!r} is read)."
+        )
+    for name in ("scan_acquisition_time", "intensity_values"):
+        if name not in f.variables:
+            raise UnsupportedVariant(f"{file}: ANDI-MS file without {name}.")
+    scan_dim = f.variables["scan_acquisition_time"].dimensions
+    point_dim = f.variables[KEY].dimensions
+    if len(scan_dim) != 1 or len(point_dim) != 1:
+        raise UnsupportedVariant(
+            f"{file}: scan_acquisition_time or mass_values is not 1D."
+        )
+    check_variables(f, KNOWN, {scan_dim[0], point_dim[0]}, ms_metadata, file)
+
+    n_scans = f.variables["scan_acquisition_time"].shape[0]
+    seconds = _per_scan(f, "scan_acquisition_time", n_scans, file)
+    unit = json_value(f.variables["scan_acquisition_time"].attributes.get("units"))
+    if unit not in (None, "Seconds", "seconds", "s"):
+        raise UnsupportedVariant(f"{file}: scan_acquisition_time in {unit!r}.")
+    scan_index = _per_scan(f, "scan_index", n_scans, file)
+    point_count = _per_scan(f, "point_count", n_scans, file)
+    offset = _peak_offset(scan_index, point_count, file)
+    flag_count = _per_scan(f, "flag_count", n_scans, file)
+    if flag_count is not None and np.any(flag_count):
+        raise UnsupportedVariant(
+            f"{file}: {int(np.sum(flag_count, dtype=np.int64))} flagged peaks; "
+            "the ANDI flag encoding is not supported yet (no sample file)."
+        )
+
+    variable = f.variables[KEY]
+    numrecs = None
+    stored = variable.shape[0]
+    if offset[-1] < 0:
+        offset[-1] = stored
+    if variable.is_record and f.numrecs == 0 and offset[-1] > 0:
+        if f.records_in_file() < offset[-1]:
+            raise CorruptFile(
+                f"{file}: the header says 0 records and the file holds fewer "
+                "peaks than point_count says."
+            )
+        warn(
+            ms_metadata,
+            f"{file}: the header says 0 records (the file was not closed); "
+            f"read the {offset[-1]} peaks point_count says.",
+        )
+        numrecs = stored = int(offset[-1])
+    if stored != offset[-1]:
+        raise CorruptFile(
+            f"{file}: {stored} peaks stored, point_count adds up to {offset[-1]}."
+        )
+    if offset[-1] < (offset[-2] if n_scans else 0):
+        raise CorruptFile(f"{file}: scan_index points past the peaks.")
+
+    mz = apply_scale(f, KEY, f.read(KEY, numrecs), ms_metadata, "mass")
+    intensity = apply_scale(
+        f,
+        "intensity_values",
+        f.read("intensity_values", numrecs),
+        ms_metadata,
+        "intensity",
+    )
+    if "time_values" in f.variables:
+        times = f.variables["time_values"]
+        data = f.read("time_values", numrecs)
+        if not np.all(is_fill(data, times.attributes, times.nc_type)):
+            raise UnsupportedVariant(f"{file}: per-peak time_values are not supported.")
+
+    computed = []
+    scan_number = None
+    numbers = f.variables.get("actual_scan_number")
+    if numbers is not None:
+        data = f.read("actual_scan_number")
+        usable = not np.any(is_fill(data, numbers.attributes, numbers.nc_type))
+        if usable and len(data) > 1 and np.any(np.diff(data.astype(np.int64)) <= 0):
+            usable = False
+        if usable:
+            scan_number = data.astype(np.int32)
+        else:
+            warn(
+                ms_metadata,
+                f"{file}: actual_scan_number is not usable; scans numbered from 1.",
+            )
+    if scan_number is None:
+        scan_number = np.arange(1, n_scans + 1, dtype=np.int32)
+        computed.append("scan_number")
+
+    counts = np.diff(offset)
+    sums = np.bincount(
+        np.repeat(np.arange(n_scans), counts),
+        weights=intensity.astype(np.float64),
+        minlength=n_scans,
+    )
+    tic = _per_scan(f, "total_intensity", n_scans, file)
+    if tic is None:
+        tic = sums
+        computed.append("tic")
+    else:
+        tic = tic.astype(np.float64)
+        tolerance = 0 if intensity.dtype.kind in "iu" else 1e-6
+        bad = int(np.count_nonzero(~np.isclose(sums, tic, rtol=tolerance, atol=0)))
+        if bad:
+            warn(ms_metadata, f"{file}: {bad} scans do not add up to total_intensity.")
+    if computed:
+        ms_metadata["computed"] = computed
+
+    # a scan range, if every scan has the same one; a minimum of 0 is taken
+    # as "not recorded" (all scans of example_ms.cdf say 0-500, its peaks
+    # start at m/z 44.95)
+    ranges = [
+        f.read(n) for n in ("mass_range_min", "mass_range_max") if n in f.variables
+    ]
+    if len(ranges) == 2 and n_scans:
+        low, high = ranges
+        if (
+            low.shape == high.shape == (n_scans,)
+            and np.all(low == low[0])
+            and np.all(high == high[0])
+            and 0 < low[0] < high[0] < nc.FILL[6]
+        ):
+            ms_metadata["mass_range_min"] = float(low[0])
+            ms_metadata["mass_range_max"] = float(high[0])
+    _ms_metadata(f, ms_metadata)
+
+    ms = MSData(
+        name="MS",
+        scan_number=scan_number,
+        retention_time=seconds.astype(np.float64) / 60.0,
+        tic=tic,
+        base_peak_mz=None,
+        base_peak_intensity=None,
+        filters=None,
+        mz=mz,
+        intensity=intensity,
+        peak_offset=offset,
+        metadata=ms_metadata,
+        spectrum_type="centroid",
+    )
+    injection = injection_of(
+        f,
+        file,
+        "experiment_date_time_stamp",
+        lambda k: k == "experiment_type" or k.startswith(MS_ATTRIBUTES),
+    )
+    return ms, injection
+
+
+def read_andi_ms(path: str | Path) -> list[Injection]:
+    """Read an ANDI-MS netCDF file (centroided GC-MS run).
+
+    Parameters
+    ----------
+    path : str or Path
+        The `.cdf` file.
+
+    Returns
+    -------
+    list of Injection
+        One injection with one MS run named ``"MS"``. `inject_time` is
+        the ``experiment_date_time_stamp`` (aware when it has an offset).
+
+    Raises
+    ------
+    UnsupportedFormat
+        If the file is not netCDF or has no ``mass_values``.
+    UnsupportedVariant
+        For netCDF-4 files and the variants `decode_andi_ms` refuses.
+    CorruptFile
+        For inconsistent or unfinished files.
+    """
+    path = Path(path)
+    with open_andi(path, KEY, "ANDI-MS") as f:
+        ms, injection = decode_andi_ms(f, path.name)
+    injection.ms["MS"] = ms
+    return [injection]
+
+
+def sniff_andi_ms(path: str | Path) -> bool:
+    """Whether `path` is a netCDF file with a ``mass_values`` variable."""
+    return has_variable(path, KEY)

chromparser/vendors/andi/write.py

@@ -0,0 +1,320 @@
+r"""Write injections as ANDI netCDF files (classic format, ``CDF\x01``).
+
+One ANDI-MS file per `MSData` and one ANDI chromatography (AIA) file per
+`Signal`, so that tools such as AMDIS, NIST MS Search, MZmine, OpenChrom,
+MS-DIAL and XCMS can open data from any format chromparser reads. ANDI is an
+export: what it does not carry is listed in `docs/formats/andi.md`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ... import _netcdf3 as nc
+from ...model import Injection, MSData, Signal
+from .common import format_timestamp
+from .ms import CENTROID, INSTRUMENT, IONISATION, MASS_SCAN, POLARITY
+
+#: Values the template uses for "not recorded" in the per-scan variables.
+NOT_RECORDED = -9999
+#: Template attributes; the revisions are those of the vendor exports we have.
+MS_TEMPLATE = {
+    "dataset_completeness": "C1+C2",
+    "ms_template_revision": "1.0.1",
+    "netcdf_revision": "2.3.2",
+    "languages": "English",
+}
+CHROM_TEMPLATE = {
+    "dataset_completeness": "C1+C2",
+    "aia_template_revision": "1.0",
+    "netcdf_revision": "2.3.2",
+    "languages": "English",
+}
+_FORMAT_NAME = {1: "Byte", 3: "Short", 4: "Long", 5: "Float", 6: "Double"}
+_INT32 = np.iinfo(np.int32)
+
+
+def netcdf_values(data: np.ndarray) -> np.ndarray:
+    """Convert an array to a netCDF-3 type, keeping its dtype where possible.
+
+    netCDF-3 has no unsigned or 64-bit integers: uint8 becomes int16, uint16
+    int32, and wider integers int32 when all values fit, float64 otherwise.
+    float16 becomes float32.
+    """
+    data = np.asarray(data)
+    kind, size = data.dtype.kind, data.dtype.itemsize
+    if kind == "f":
+        return data.astype(np.float32 if size <= 4 else np.float64, copy=False)
+    if kind == "b":
+        return data.astype(np.int8)
+    if kind not in "iu":
+        raise ValueError(f"Cannot write {data.dtype} data to netCDF-3.")
+    if kind == "i" and size <= 4:
+        return data
+    if kind == "u" and size <= 2:
+        return data.astype(np.int16 if size == 1 else np.int32)
+    if not data.size or (data.min() >= _INT32.min and data.max() <= _INT32.max):
+        return data.astype(np.int32)
+    return data.astype(np.float64)
+
+
+def _safe(text: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", text).strip("_") or "unnamed"
+
+
+def _stem(injection: Injection) -> str:
+    source = injection.metadata.get("source_file")
+    if isinstance(source, str) and source:
+        return _safe(Path(source).stem)
+    return _safe(injection.name or "injection")
+
+
+def _common(injection: Injection) -> dict[str, Any]:
+    metadata = injection.metadata
+    return {
+        "experiment_title": injection.name or None,
+        "sample_name": _text(metadata.get("sample_name")),
+        "operator_name": _text(metadata.get("operator")),
+        "source_file_reference": _text(metadata.get("source_file")),
+    }
+
+
+def _stamp(when: datetime | None) -> str | None:
+    """Format `when` (whole seconds) as ANDI timestamp; now (UTC) for `None`."""
+    if when is None:
+        when = datetime.now(timezone.utc)
+    return format_timestamp(when.replace(microsecond=0))
+
+
+def _injected(injection: Injection, start: datetime | None) -> str | None:
+    """Stamp the injection time, or the acquisition start (UTC) if unknown."""
+    when = injection.inject_time or start
+    return _stamp(when) if when else None
+
+
+def _text(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _lookup(key: str, *metadata: dict) -> Any:
+    return next((m[key] for m in metadata if key in m), None)
+
+
+def _ms_file(path: Path, injection: Injection, ms: MSData) -> None:
+    n_scans, n_peaks = len(ms), int(ms.peak_offset[-1])
+    if n_peaks > _INT32.max:
+        raise ValueError(f"{ms.name}: {n_peaks} peaks exceed ANDI's int32 scan_index.")
+    attributes = dict(MS_TEMPLATE)
+    attributes["netcdf_file_date_time_stamp"] = _stamp(None)
+    attributes["experiment_date_time_stamp"] = _injected(
+        injection, ms.acquisition_start
+    )
+    attributes.update(_common(injection))
+    mz = netcdf_values(ms.mz)
+    intensity = netcdf_values(ms.intensity)
+    mode = _lookup("ionisation", ms.metadata)
+    polarity = _lookup("polarity", ms.metadata)
+    attributes.update(
+        {
+            "experiment_type": (
+                CENTROID
+                if ms.spectrum_type == "centroid"
+                else "Continuum Mass Spectrum"
+            ),
+            "test_ionization_mode": {v: k for k, v in IONISATION.items()}.get(
+                mode, _text(ms.metadata.get("andi_test_ionization_mode"))
+            ),
+            "test_ionization_polarity": {v: k for k, v in POLARITY.items()}.get(
+                polarity, _text(ms.metadata.get("andi_test_ionization_polarity"))
+            ),
+            "test_scan_function": MASS_SCAN,
+            "raw_data_mass_format": _FORMAT_NAME[nc.nc_type_of(mz.dtype)],
+            "raw_data_time_format": "Double",
+            "raw_data_intensity_format": _FORMAT_NAME[nc.nc_type_of(intensity.dtype)],
+        }
+    )
+
+    counts = np.diff(ms.peak_offset)
+    mass_range = {}
+    for side, reduce in (("min", np.minimum), ("max", np.maximum)):
+        stored = ms.metadata.get(f"mass_range_{side}")
+        if isinstance(stored, (int, float)) and not isinstance(stored, bool):
+            mass_range[side] = np.full(n_scans, float(stored))
+        else:  # the observed range of each scan, 0 for empty scans
+            mass_range[side] = np.zeros(n_scans)
+            filled = counts > 0
+            if filled.any():
+                starts = ms.peak_offset[:-1][filled]
+                mass_range[side][filled] = reduce.reduceat(
+                    mz.astype(np.float64), starts
+                )
+
+    scan = ("scan_number",)
+    not_recorded = np.full(n_scans, float(NOT_RECORDED))
+    variables = {
+        "error_log": nc.NewVariable(
+            ("error_number", "_64_byte_string"), nc.char_array([""], 64)
+        ),
+        "a_d_sampling_rate": nc.NewVariable(scan, not_recorded),
+        "a_d_coaddition_factor": nc.NewVariable(
+            scan, np.full(n_scans, NOT_RECORDED, np.int16)
+        ),
+        "scan_acquisition_time": nc.NewVariable(
+            scan, np.asarray(ms.retention_time, np.float64) * 60.0, {"units": "Seconds"}
+        ),
+        "scan_duration": nc.NewVariable(scan, not_recorded),
+        "inter_scan_time": nc.NewVariable(scan, not_recorded),
+        "resolution": nc.NewVariable(scan, not_recorded),
+        "actual_scan_number": nc.NewVariable(
+            scan, np.asarray(ms.scan_number, np.int32)
+        ),
+        "total_intensity": nc.NewVariable(
+            scan, np.asarray(ms.tic, np.float64), {"units": "Arbitrary Intensity Units"}
+        ),
+        "mass_range_min": nc.NewVariable(scan, mass_range["min"]),
+        "mass_range_max": nc.NewVariable(scan, mass_range["max"]),
+        "time_range_min": nc.NewVariable(scan, not_recorded),
+        "time_range_max": nc.NewVariable(scan, not_recorded),
+        "scan_index": nc.NewVariable(scan, ms.peak_offset[:-1].astype(np.int32)),
+        "point_count": nc.NewVariable(scan, counts.astype(np.int32)),
+        "flag_count": nc.NewVariable(scan, np.zeros(n_scans, np.int32)),
+        "mass_values": nc.NewVariable(("point_number",), mz, {"units": "M/Z"}),
+        "intensity_values": nc.NewVariable(
+            ("point_number",), intensity, {"units": "Arbitrary Intensity Units"}
+        ),
+    }
+    for variable, key in INSTRUMENT.items():
+        value = _text(_lookup(key, ms.metadata, injection.metadata)) or ""
+        variables[variable] = nc.NewVariable(
+            ("instrument_number", "_32_byte_string"), nc.char_array([value], 32)
+        )
+    dimensions = {
+        "_32_byte_string": 32,
+        "_64_byte_string": 64,
+        "error_number": 1,
+        "scan_number": n_scans,
+        "point_number": n_peaks,
+        "instrument_number": 1,
+    }
+    nc.write(path, dimensions, attributes, variables)
+
+
+def _chrom_file(path: Path, injection: Injection, signal: Signal) -> None:
+    values = netcdf_values(signal.values)
+    n = len(values)
+    interval = float(signal.sampling_interval)
+    delay = float(signal.time[0]) * 60.0 if n else 0.0
+    attributes = dict(CHROM_TEMPLATE)
+    attributes["dataset_date_time_stamp"] = _stamp(None)
+    attributes["injection_date_time_stamp"] = _injected(
+        injection, signal.acquisition_start
+    )
+    attributes.update(_common(injection))
+    attributes.update(
+        {
+            "detector_name": signal.channel or None,
+            "detector_unit": signal.unit,
+            "retention_unit": "Seconds",
+        }
+    )
+    finite = values[np.isfinite(values)] if values.dtype.kind == "f" else values
+    variables = {
+        "actual_sampling_interval": nc.NewVariable((), np.float64(interval)),
+        "actual_delay_time": nc.NewVariable((), np.float64(delay)),
+        "actual_run_time_length": nc.NewVariable((), np.float64(delay + n * interval)),
+    }
+    if finite.size:
+        variables["detector_maximum_value"] = nc.NewVariable(
+            (), np.float64(finite.max())
+        )
+        variables["detector_minimum_value"] = nc.NewVariable(
+            (), np.float64(finite.min())
+        )
+    variables["ordinate_values"] = nc.NewVariable(
+        ("point_number",), values, {"uniform_sampling_flag": "Y"}
+    )
+    nc.write(path, {"point_number": n}, attributes, variables)
+
+
+def write_andi(
+    injections: Injection | Iterable[Injection],
+    folder: str | Path,
+    *,
+    overwrite: bool = False,
+) -> list[Path]:
+    """Write injections as ANDI netCDF files.
+
+    Parameters
+    ----------
+    injections : Injection or iterable of Injection
+        What to write.
+    folder : str or Path
+        Output folder (created if missing).
+    overwrite : bool
+        Replace existing files.
+
+    Returns
+    -------
+    list of Path
+        One ANDI-MS file per `MSData` and one ANDI chromatography file per
+        `Signal`, named ``<stem>_<channel>.cdf``; ``<stem>`` is the stem of
+        ``metadata["source_file"]`` (else the injection name), followed by the
+        injection number when several injections share it.
+
+    Raises
+    ------
+    ValueError
+        If a signal is not regularly sampled (`sampling_interval` is `None`;
+        checked before anything is written), or data does not fit the
+        ANDI/netCDF classic format.
+    FileExistsError
+        If an output file exists and `overwrite` is False. Nothing is written
+        then.
+    """
+    if isinstance(injections, Injection):
+        injections = [injections]
+    injections = list(injections)
+    folder = Path(folder)
+    stems = [_stem(injection) for injection in injections]
+    shared = Counter(stems)
+    number: Counter = Counter()
+    taken: set[str] = set()
+    jobs = []
+
+    def target(base: str, name: str) -> Path:
+        candidate, n = f"{base}_{_safe(name)}", 1
+        while candidate.lower() in taken:
+            n += 1
+            candidate = f"{base}_{_safe(name)}_{n}"
+        taken.add(candidate.lower())
+        return folder / f"{candidate}.cdf"
+
+    for injection, stem in zip(injections, stems, strict=True):
+        number[stem] += 1
+        width = len(str(shared[stem]))
+        base = f"{stem}_{number[stem]:0{width}d}" if shared[stem] > 1 else stem
+        for signal in injection.signals.values():
+            if signal.sampling_interval is None:
+                raise ValueError(
+                    f"Signal {signal.channel!r} is not regularly sampled; ANDI "
+                    "chromatography files need a sampling interval."
+                )
+            jobs.append((target(base, signal.channel), _chrom_file, injection, signal))
+        for ms in injection.ms.values():
+            jobs.append((target(base, ms.name), _ms_file, injection, ms))
+    existing = [str(path) for path, *_ in jobs if path.exists()]
+    if existing and not overwrite:
+        raise FileExistsError(
+            f"{', '.join(existing)} exist(s), use overwrite=True to replace."
+        )
+    folder.mkdir(parents=True, exist_ok=True)
+    for path, write, injection, data in jobs:
+        write(path, injection, data)
+    return [path for path, *_ in jobs]

chromparser/vendors/chromeleon/__init__.py

@@ -0,0 +1,19 @@
+"""Thermo Chromeleon 7: `.cmbx` archives, raw signal files and text exports."""
+
+from __future__ import annotations
+
+from .archive import extract_ms_raw, read_cmbx, sniff_cmbx
+from .raw import decode_signal, read_chromeleon_raw, read_signal, sniff_chromeleon_raw
+from .txt import read_chromeleon_txt, sniff_chromeleon_txt
+
+__all__ = [
+    "decode_signal",
+    "extract_ms_raw",
+    "read_chromeleon_raw",
+    "read_chromeleon_txt",
+    "read_cmbx",
+    "read_signal",
+    "sniff_chromeleon_raw",
+    "sniff_chromeleon_txt",
+    "sniff_cmbx",
+]