chromparser 0.1.0__py3-none-any.whl

chromparser/vendors/andi/chrom.py

@@ -0,0 +1,181 @@
+"""ANDI chromatography (AIA) netCDF files: one detector trace.
+
+The trace is `ordinate_values`, sampled every `actual_sampling_interval`
+seconds from `actual_delay_time` on. A peak table (variables on the peak
+dimension), if present, is kept in the signal metadata. 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, Signal
+from .common import (
+    apply_scale,
+    check_variables,
+    has_variable,
+    injection_of,
+    json_value,
+    open_andi,
+)
+
+KEY = "ordinate_values"
+SCALARS = (
+    "actual_sampling_interval",
+    "actual_delay_time",
+    "actual_run_time_length",
+    "detector_maximum_value",
+    "detector_minimum_value",
+)
+#: Global attributes that describe the signal.
+SIGNAL_ATTRIBUTES = {"detector_unit", "detector_name", "retention_unit"}
+SECONDS = ("Seconds", "seconds", "s")
+
+
+def _scalar(f: nc.File, name: str) -> float | None:
+    if name not in f.variables:
+        return None
+    data = f.read(name).ravel()
+    if data.size != 1:
+        raise UnsupportedVariant(f"{f.path.name}: {name} holds {data.size} values.")
+    return float(data[0])
+
+
+def _peak_table(f: nc.File, dimension: str) -> dict[str, list]:
+    table = {}
+    for variable in f.variables.values():
+        if not variable.dimensions or variable.dimensions[0] != dimension:
+            continue
+        data = f.read(variable.name)
+        if variable.nc_type == 2:
+            values = nc.strings(data) if data.size else []
+        else:
+            values = [json_value(v) for v in data.tolist()]
+        table[variable.name] = values
+    return table
+
+
+def decode_andi_chrom(f: nc.File, file: str = "andi") -> tuple[Signal, Injection]:
+    """Decode an open ANDI chromatography file.
+
+    Parameters
+    ----------
+    f : chromparser._netcdf3.File
+        The open file.
+    file : str
+        File name for messages.
+
+    Returns
+    -------
+    Signal, Injection
+        The signal (channel ``detector_name``, or ``"detector"``) and its
+        injection (without the signal).
+
+    Raises
+    ------
+    UnsupportedVariant
+        For irregular sampling, times in other units than seconds, or
+        variables on the point dimension that the reader does not know.
+    CorruptFile
+        For unfinished files.
+    """
+    attributes = f.attributes
+    metadata: dict = {}
+    variable = f.variables[KEY]
+    if len(variable.dimensions) != 1:
+        raise UnsupportedVariant(f"{file}: {KEY} is not 1D.")
+    peak_dim = "peak_number"
+    known = {KEY, *SCALARS}
+    known |= {v.name for v in f.variables.values() if v.dimensions[:1] == (peak_dim,)}
+    check_variables(f, known, {variable.dimensions[0]}, metadata, file)
+
+    uniform = json_value(variable.attributes.get("uniform_sampling_flag"))
+    if uniform not in (None, "Y"):
+        raise UnsupportedVariant(
+            f"{file}: uniform_sampling_flag {uniform!r}; irregularly sampled "
+            "signals are not supported."
+        )
+    unit = json_value(attributes.get("retention_unit"))
+    if unit is None:
+        warn(metadata, f"{file}: no retention_unit; seconds assumed.")
+    elif unit not in SECONDS:
+        raise UnsupportedVariant(f"{file}: retention_unit {unit!r} (only seconds).")
+    interval = _scalar(f, "actual_sampling_interval")
+    if interval is None or not interval > 0:
+        raise UnsupportedVariant(f"{file}: no positive actual_sampling_interval.")
+    delay = _scalar(f, "actual_delay_time")
+    if delay is None:
+        warn(metadata, f"{file}: no actual_delay_time; 0 assumed.")
+        delay = 0.0
+    if variable.is_record and f.numrecs == 0 and f.records_in_file():
+        raise CorruptFile(
+            f"{file}: the header says 0 records but the file holds "
+            f"{f.records_in_file()}; the export did not finish."
+        )
+
+    values = apply_scale(f, KEY, f.read(KEY), metadata, "ordinate")
+    for name in SCALARS[2:]:
+        value = _scalar(f, name)
+        if value is not None:
+            metadata[f"andi_{name}"] = value
+    for key in ("uniform_sampling_flag", "autosampler_position"):
+        value = json_value(variable.attributes.get(key))
+        if value is not None:
+            metadata[f"andi_{key}"] = value
+    if peak_dim in f.dimensions:
+        table = _peak_table(f, peak_dim)
+        if table:
+            metadata["andi_peak_table"] = table
+    channel = json_value(attributes.get("detector_name")) or "detector"
+    signal = Signal(
+        channel=channel,
+        time=(delay + interval * np.arange(len(values))) / 60.0,
+        values=values,
+        unit=json_value(attributes.get("detector_unit")),
+        metadata=metadata,
+        sampling_interval=interval,
+    )
+    injection = injection_of(
+        f, file, "injection_date_time_stamp", SIGNAL_ATTRIBUTES.__contains__
+    )
+    return signal, injection
+
+
+def read_andi_chrom(path: str | Path) -> list[Injection]:
+    """Read an ANDI chromatography (AIA) netCDF file.
+
+    Parameters
+    ----------
+    path : str or Path
+        The `.cdf` file.
+
+    Returns
+    -------
+    list of Injection
+        One injection with one signal. `inject_time` is the
+        ``injection_date_time_stamp`` (aware when it has an offset).
+
+    Raises
+    ------
+    UnsupportedFormat
+        If the file is not netCDF or has no ``ordinate_values``.
+    UnsupportedVariant
+        For netCDF-4 files and the variants `decode_andi_chrom` refuses.
+    CorruptFile
+        For unfinished files.
+    """
+    path = Path(path)
+    with open_andi(path, KEY, "ANDI chromatography") as f:
+        signal, injection = decode_andi_chrom(f, path.name)
+    injection.signals[signal.channel] = signal
+    return [injection]
+
+
+def sniff_andi_chrom(path: str | Path) -> bool:
+    """Whether `path` is a netCDF file with an ``ordinate_values`` variable."""
+    return has_variable(path, KEY)

chromparser/vendors/andi/common.py

@@ -0,0 +1,232 @@
+"""Helpers shared by the ANDI-MS and ANDI chromatography (AIA) readers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from contextlib import contextmanager
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ... import _netcdf3 as nc
+from ..._util import existing_file, head
+from ...errors import UnsupportedFormat, UnsupportedVariant, warn
+from ...hdf5 import HDF5_MAGIC
+from ...model import Injection
+
+_TIMESTAMP = re.compile(r"^(\d{14})(?:([+-])(\d{2})(\d{2}))?$")
+
+
+def parse_timestamp(text: str) -> datetime | None:
+    """Parse an ANDI timestamp, ``YYYYMMDDHHMMSS`` with optional ``±ZZZZ``.
+
+    Returns
+    -------
+    datetime or None
+        Timezone-aware with an offset, naive without; `None` if `text` is not
+        such a timestamp.
+    """
+    match = _TIMESTAMP.match(text.strip())
+    if not match:
+        return None
+    digits, sign, hours, minutes = match.groups()
+    try:
+        value = datetime.strptime(digits, "%Y%m%d%H%M%S")
+    except ValueError:
+        return None
+    if sign is None:
+        return value
+    offset = timedelta(hours=int(hours), minutes=int(minutes))
+    return value.replace(tzinfo=timezone(-offset if sign == "-" else offset))
+
+
+def format_timestamp(value: datetime) -> str:
+    """Format a datetime as an ANDI timestamp (offset only if it is aware)."""
+    text = value.strftime("%Y%m%d%H%M%S")
+    offset = value.utcoffset()
+    if offset is None:
+        return text
+    minutes = int(offset.total_seconds()) // 60
+    sign = "-" if minutes < 0 else "+"
+    return f"{text}{sign}{abs(minutes) // 60:02d}{abs(minutes) % 60:02d}"
+
+
+def json_value(value: Any) -> Any:
+    """Return an attribute value as a JSON type (`None` for empty values)."""
+    if isinstance(value, str):
+        return value.strip() or None
+    if isinstance(value, np.ndarray):
+        return [json_value(v) for v in value.tolist()] or None
+    if isinstance(value, np.generic):
+        value = value.item()
+    if isinstance(value, float) and not np.isfinite(value):
+        return None
+    return value
+
+
+def attribute_metadata(attributes: dict[str, Any]) -> dict[str, Any]:
+    """Global attributes as ``andi_<name>`` metadata.
+
+    Timestamps become ISO 8601 strings; empty values are left out.
+    """
+    metadata = {}
+    for key, value in attributes.items():
+        value = json_value(value)
+        if value is None:
+            continue
+        if key.endswith("date_time_stamp") and isinstance(value, str):
+            parsed = parse_timestamp(value)
+            value = parsed.isoformat() if parsed else value
+        metadata[f"andi_{key}"] = value
+    return metadata
+
+
+def is_fill(data: np.ndarray, attributes: dict[str, Any], nc_type: int) -> np.ndarray:
+    """Mask of values equal to the variable's ``_FillValue`` or the default fill."""
+    fills = [nc.FILL[nc_type]]
+    if "_FillValue" in attributes:
+        fills.append(attributes["_FillValue"])
+    mask = np.zeros(data.shape, bool)
+    for fill in fills:
+        mask |= data == np.asarray(fill).astype(data.dtype)
+    return mask
+
+
+def _netcdf4_variables(path: Path) -> set[str]:
+    """Root dataset names of an HDF5 (netCDF-4) file; empty for other files."""
+    if head(path, 8) != HDF5_MAGIC:
+        return set()
+    import h5py
+
+    try:
+        with h5py.File(path, "r") as hdf:
+            return set(hdf.keys())
+    except (OSError, ValueError):
+        return set()
+
+
+def has_variable(path: str | Path, name: str) -> bool:
+    """Whether `path` is a netCDF file (3 or 4) with the variable `name`."""
+    path = Path(path)
+    if not path.is_file():
+        return False
+    try:
+        if nc.is_netcdf3(head(path, 4)):
+            with nc.File(path) as f:
+                return name in f.variables
+        return name in _netcdf4_variables(path)
+    except (ValueError, OSError):
+        return False
+
+
+@contextmanager
+def open_andi(path: str | Path, key: str, what: str):
+    """Open an ANDI file as a netCDF-3 `File`.
+
+    Raises
+    ------
+    UnsupportedVariant
+        For a netCDF-4 (HDF5) file with `key`, or a CDF-5 file.
+    UnsupportedFormat
+        If the file is not netCDF-3 or has no variable `key`.
+    """
+    path = existing_file(path)
+    if key in _netcdf4_variables(path):
+        raise UnsupportedVariant(
+            f"{path.name} is a netCDF-4 (HDF5) {what} file; only netCDF-3 "
+            "(classic and 64-bit offset) files are read."
+        )
+    with nc.File(path) as f:
+        if key not in f.variables:
+            raise UnsupportedFormat(f"{path.name} is not an {what} file (no {key}).")
+        yield f
+
+
+def check_variables(
+    f: nc.File, known: set[str], data_dims: set[str], metadata: dict, name: str
+) -> None:
+    """Refuse unknown variables on the data dimensions, warn about others.
+
+    Raises
+    ------
+    UnsupportedVariant
+        If a variable outside `known` uses one of `data_dims`.
+    """
+    unknown = [v for v in f.variables.values() if v.name not in known]
+    on_data = [v.name for v in unknown if data_dims & set(v.dimensions)]
+    if on_data:
+        raise UnsupportedVariant(
+            f"{name}: variable(s) {', '.join(on_data)} on the data dimensions "
+            "are not understood by this reader."
+        )
+    if unknown:
+        warn(
+            metadata,
+            f"{name}: variable(s) not read: {', '.join(v.name for v in unknown)}.",
+        )
+
+
+def injection_of(
+    f: nc.File, file: str, stamp_key: str, elsewhere: Callable[[str], bool]
+) -> Injection:
+    """Build the injection (without data) from the global attributes.
+
+    Parameters
+    ----------
+    f : chromparser._netcdf3.File
+        The open file.
+    file : str
+        File name for messages.
+    stamp_key : str
+        Attribute holding the injection time.
+    elsewhere : callable
+        Whether an attribute belongs to the signal or MS metadata instead.
+
+    Returns
+    -------
+    Injection
+        `name` from ``experiment_title`` or ``sample_name``; ``sample_name``
+        and ``operator`` (``operator_name``) metadata; the other attributes
+        as ``andi_<name>``.
+    """
+    attributes = f.attributes
+    metadata: dict = {}
+    sample = json_value(attributes.get("sample_name"))
+    title = json_value(attributes.get("experiment_title"))
+    operator = json_value(attributes.get("operator_name"))
+    if sample:
+        metadata["sample_name"] = sample
+    if operator:
+        metadata["operator"] = operator
+    stamp = json_value(attributes.get(stamp_key))
+    inject_time = parse_timestamp(stamp) if isinstance(stamp, str) else None
+    if stamp is not None and inject_time is None:
+        warn(metadata, f"{file}: {stamp_key} {stamp!r} is not an ANDI timestamp.")
+        metadata[f"andi_{stamp_key}"] = stamp
+    mapped = {"experiment_title", "sample_name", "operator_name", stamp_key}
+    rest = {k: v for k, v in attributes.items() if k not in mapped and not elsewhere(k)}
+    metadata.update(attribute_metadata(rest))
+    return Injection(
+        name=title or sample or "", inject_time=inject_time, metadata=metadata
+    )
+
+
+def apply_scale(
+    f: nc.File, name: str, data: np.ndarray, metadata: dict, key: str
+) -> np.ndarray:
+    """Apply `scale_factor` / `add_offset` when they change the values."""
+    attributes = f.variables[name].attributes
+    scale = attributes.get("scale_factor")
+    offset = attributes.get("add_offset")
+    if scale is not None:
+        metadata[f"andi_{key}_scale_factor"] = json_value(scale)
+    if offset is not None:
+        metadata[f"andi_{key}_add_offset"] = json_value(offset)
+    scale = 1 if scale is None else float(np.asarray(scale).ravel()[0])
+    offset = 0 if offset is None else float(np.asarray(offset).ravel()[0])
+    if scale == 1 and offset == 0:
+        return data
+    return data.astype(np.float64) * scale + offset