chromparser 0.1.0__py3-none-any.whl

chromparser/__init__.py

@@ -0,0 +1,183 @@
+"""Read chromatography raw files into one data model; write HDF5 and ANDI.
+
+Supported: Chromeleon 7 (`.cmbx`, raw signal files, text exports), Thermo MS
+`.raw` (embedded in `.cmbx`), Agilent (`.ch`, `.D`, `.dx`), Shimadzu
+GCMSsolution (`.qgd`, `.gcd`) and ANDI netCDF (`.cdf`, MS and chromatography;
+also written by `write_andi`). See the README for the scope of each reader.
+"""
+
+from __future__ import annotations
+
+import inspect
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any
+
+from .errors import (
+    ChromparserError,
+    ChromparserWarning,
+    CorruptFile,
+    UnsupportedFormat,
+    UnsupportedVariant,
+)
+from .hdf5 import read_hdf5, write_hdf5
+from .model import SATURATED, Injection, MSData, Signal
+from .sniff import HDF5, sniff
+from .vendors import FORMATS
+from .vendors.andi import write_andi
+from .vendors.chromeleon import extract_ms_raw
+
+try:
+    __version__ = version("chromparser")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0+unknown"
+
+#: Options that some readers take; `read` passes each reader those it accepts.
+READ_OPTIONS = ("ms", "signal_unit", "dayfirst", "channel", "name")
+
+
+def _reader(fmt: str):
+    if fmt == HDF5:
+        return read_hdf5
+    return next(f.read for f in FORMATS if f.id == fmt)
+
+
+def read(path: str | Path, **options: Any) -> list[Injection]:
+    """Read any supported file; the format is detected from the content.
+
+    Parameters
+    ----------
+    path : str or Path
+        File or Agilent `.D` folder; also chromparser/cmbx-reader HDF5 files.
+    **options
+        Reader options (`READ_OPTIONS`): ``ms`` (read MS data of `.cmbx`),
+        ``signal_unit`` (Chromeleon raw signal files), ``dayfirst``
+        (Chromeleon text exports), ``channel`` (Agilent `.ch`), ``name``
+        (Thermo raw). Options a reader does not take are ignored.
+
+    Returns
+    -------
+    list of Injection
+        ``metadata["source_file"]`` is set to the file name.
+
+    Raises
+    ------
+    TypeError
+        For an unknown option.
+    UnsupportedFormat, UnsupportedVariant, CorruptFile
+        See `chromparser.errors`.
+    """
+    unknown = set(options) - set(READ_OPTIONS)
+    if unknown:
+        raise TypeError(f"Unknown read option(s): {', '.join(sorted(unknown))}")
+    path = Path(path)
+    reader = _reader(sniff(path))
+    accepted = inspect.signature(reader).parameters
+    injections = reader(path, **{k: v for k, v in options.items() if k in accepted})
+    for injection in injections:
+        injection.metadata.setdefault("source_file", path.name)
+    return injections
+
+
+def read_one(path: str | Path, **options: Any) -> Injection:
+    """Read a file that holds exactly one injection.
+
+    Parameters
+    ----------
+    path : str or Path
+        See `read`.
+    **options
+        See `read`.
+
+    Returns
+    -------
+    Injection
+        The injection.
+
+    Raises
+    ------
+    ValueError
+        If the file holds no or several injections.
+    """
+    injections = read(path, **options)
+    if len(injections) != 1:
+        raise ValueError(
+            f"{Path(path).name} holds {len(injections)} injections; use read()."
+        )
+    return injections[0]
+
+
+def convert(
+    source: str | Path,
+    destination: str | Path | None = None,
+    *,
+    overwrite: bool = False,
+    compression: bool = True,
+    **options: Any,
+) -> Path:
+    """Convert a file to HDF5 (layout v3).
+
+    Parameters
+    ----------
+    source : str or Path
+        Any file `read` accepts, including HDF5 files of older layouts.
+    destination : str or Path, optional
+        Output file. Defaults to `source` with suffix `.h5` (for a `.h5`
+        source: ``<name>.v3.h5``).
+    overwrite : bool
+        Replace an existing output file.
+    compression : bool
+        Compress datasets.
+    **options
+        Reader options, see `read`.
+
+    Returns
+    -------
+    Path
+        The written file.
+    """
+    source = Path(source)
+    fmt = sniff(source)
+    if destination is None:
+        suffix = ".v3.h5" if fmt == HDF5 else ".h5"
+        destination = source.with_name(source.name.removesuffix(source.suffix) + suffix)
+    injections = read(source, **options)
+    if fmt == HDF5:
+        import h5py
+
+        from .hdf5 import _value
+
+        with h5py.File(source, "r") as hdf:
+            fmt = _value(hdf.attrs.get("source_format", HDF5))
+    return write_hdf5(
+        injections,
+        destination,
+        overwrite=overwrite,
+        compression=compression,
+        source=source,
+        source_format=fmt,
+    )
+
+
+__all__ = [
+    "FORMATS",
+    "READ_OPTIONS",
+    "SATURATED",
+    "ChromparserError",
+    "ChromparserWarning",
+    "CorruptFile",
+    "Injection",
+    "MSData",
+    "Signal",
+    "UnsupportedFormat",
+    "UnsupportedVariant",
+    "__version__",
+    "convert",
+    "extract_ms_raw",
+    "read",
+    "read_hdf5",
+    "read_one",
+    "sniff",
+    "write_andi",
+    "write_hdf5",
+]

chromparser/__main__.py

@@ -0,0 +1,7 @@
+"""Run the command line interface: ``python -m chromparser``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+raise SystemExit(main())