quantized-lab 0.8.0__py3-none-any.whl

quantized/io/spc.py

@@ -0,0 +1,311 @@
+"""GRAMS/Thermo Scientific ``.spc`` spectral binary parser.
+
+**NOT a MATLAB port.** ``quantized_matlab`` never implemented
+``importSPC.m`` — the roadmap explicitly parks it "Paused (awaiting example
+files)" (``quantized_matlab/plans/archive/parser-roadmap.md`` item 4;
+``PORT_CHECKLIST.md`` line 46) and no source or test exists to freeze golden
+values from. This is an independent implementation against the published
+Galactic Industries "SPC" binary layout (the field names below — ``ftflgs``,
+``fnpts``, ``fexp``, ... — are the format's own defined struct fields,
+reproduced from the widely-republished ``SPC.H`` header spec, not copied
+from any single implementation's source code). Cross-validated against four
+real-world instrument files (Horiba Raman, Perkin-Elmer FTIR, a Kr
+calibration-lamp spectrum, and a Nicolet FTIR/Raman scan) during development
+— see the parser test file for the offset-by-offset sanity checks that
+matched every one of those independently-produced binary files.
+
+Only the modern "new format, LSB-first" sub-version (``fversn == 0x4B``) is
+implemented — the sub-version every real sample file used, and the one
+every actively-maintained OPUS/SPC reader targets. The old pre-1996 format
+(``0x4D``), the rare new-format MSB variant (``0x4C``), and the
+Shimadzu-specific variant (``0xCF``) are recognized but rejected with a
+clear error rather than guessed at (no example file / spec text was
+available to validate them against).
+
+Binary layout (new format, 512-byte main header)
+--------------------------------------------------
+Bytes  0        ftflgs   (flags, see ``_FLAG_BITS``)
+Bytes  1        fversn   (0x4B for this parser)
+Bytes  2        fexper   (experiment-type code, see ``_EXPERIMENT_TYPES``)
+Bytes  3        fexp     (signed; y-scaling exponent, or -128 = IEEE float32 y)
+Bytes  4-7      fnpts    (points per subfile, uint32)
+Bytes  8-15     ffirst   (first x value, float64)
+Bytes 16-23     flast    (last x value, float64)
+Bytes 24-27     fnsub    (number of subfiles, uint32)
+Bytes 28-31     fxtype, fytype, fztype, fpost  (axis unit codes)
+Bytes 32-35     fdate    (packed year<<20|month<<16|day<<11|hour<<6|minute)
+Bytes 36-44     fres     (resolution description, 9 bytes text)
+Bytes 45-53     fsource  (source instrument, 9 bytes text)
+Bytes 54-247    fpeakpt, fspare, fcmnt, fcatxt (comment / custom axis labels)
+Bytes 248-251   flogoff  (byte offset of the trailer log block; 0 = none)
+Bytes 252-511   fmods, fprocs, flevel, fsampin, ffactor, fmethod, fzinc,
+                fwplanes, fwinc, fwtype, freserv (processing/4-D metadata)
+
+Each subfile is a 32-byte subheader followed by its y data (and, when the
+``txyxys`` flag is set, its own x data first). See ``_SUBHEAD_FMT``.
+"""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["import_spc", "is_spc"]
+
+# ── Binary layout constants ──────────────────────────────────────────────
+_HEAD_SIZE = 512
+_SUBHEAD_SIZE = 32
+_LOG_HEAD_SIZE = 64
+_FLOAT_EXP_SENTINEL = -128  # fexp/subexp value meaning "y is IEEE float32"
+
+_HEAD_FMT = "<BBBbIddIBBBBI9s9sh32s130s30sIIBBhf48sfIfB187s"
+_HEAD_FIELDS = (
+    "ftflgs", "fversn", "fexper", "fexp", "fnpts", "ffirst", "flast", "fnsub",
+    "fxtype", "fytype", "fztype", "fpost", "fdate", "fres", "fsource",
+    "fpeakpt", "fspare", "fcmnt", "fcatxt", "flogoff", "fmods", "fprocs",
+    "flevel", "fsampin", "ffactor", "fmethod", "fzinc", "fwplanes", "fwinc",
+    "fwtype", "freserv",
+)
+assert struct.calcsize(_HEAD_FMT) == _HEAD_SIZE
+
+_SUBHEAD_FMT = "<BbhfffIIf4s"
+_SUBHEAD_FIELDS = (
+    "subflgs", "subexp", "subindx", "subtime", "subnext", "subnois",
+    "subnpts", "subscan", "subwlevel", "subresv",
+)
+assert struct.calcsize(_SUBHEAD_FMT) == _SUBHEAD_SIZE
+
+_LOG_FMT = "<IIIII44s"
+assert struct.calcsize(_LOG_FMT) == _LOG_HEAD_SIZE
+
+# ftflgs bit -> name (LSB first; matches the SPC spec's TSPREC..TXVALS bits)
+_FLAG_BITS = ("tsprec", "tcgram", "tmulti", "trandm", "tordrd", "talabs", "txyxys", "txvals")
+
+_UNSUPPORTED_FVERSN = {
+    0x4C: "new-format MSB-first",
+    0x4D: "old format (pre-1996)",
+    0xCF: "Shimadzu-specific variant",
+}
+
+# X/Z axis unit codes (fxtype/fztype) — the SPC spec's defined enumeration.
+_XZ_UNITS = (
+    "Arbitrary", "Wavenumber (cm-1)", "Micrometers (um)", "Nanometers (nm)",
+    "Seconds", "Minutes", "Hertz (Hz)", "Kilohertz (KHz)", "Megahertz (MHz)",
+    "Mass (M/z)", "Parts per million (PPM)", "Days", "Years",
+    "Raman Shift (cm-1)", "eV", "XYZ text labels in fcatxt", "Diode Number",
+    "Channel", "Degrees", "Temperature (F)", "Temperature (C)",
+    "Temperature (K)", "Data Points", "Milliseconds (mSec)",
+    "Microseconds (uSec)", "Nanoseconds (nSec)", "Gigahertz (GHz)",
+    "Centimeters (cm)", "Meters (m)", "Millimeters (mm)", "Hours",
+)
+# Y axis unit codes (fytype): 0-26 direct table, 128-131 a second table.
+_Y_UNITS = (
+    "Arbitrary Intensity", "Interferogram", "Absorbance", "Kubelka-Munk",
+    "Counts", "Volts", "Degrees", "Milliamps", "Millimeters", "Millivolts",
+    "Log(1/R)", "Percent", "Intensity", "Relative Intensity", "Energy", "",
+    "Decibel", "", "", "Temperature (F)", "Temperature (C)",
+    "Temperature (K)", "Index of Refraction [N]", "Extinction Coeff. [K]",
+    "Real", "Imaginary", "Complex",
+)
+_Y_UNITS_ALT = ("Transmission", "Reflectance", "Arbitrary or Single Beam", "Emission")
+
+_EXPERIMENT_TYPES = (
+    "General SPC", "Gas Chromatogram", "General Chromatogram",
+    "HPLC Chromatogram", "FT-IR, FT-NIR, FT-Raman Spectrum or Igram",
+    "NIR Spectrum", "UV-VIS Spectrum", "X-ray Diffraction Spectrum",
+    "Mass Spectrum", "NMR Spectrum or FID", "Raman Spectrum",
+    "Fluorescence Spectrum", "Atomic Spectrum", "Chromatography Diode Array Spectra",
+)
+
+
+def _axis_label(code: int) -> str:
+    return _XZ_UNITS[code] if 0 <= code < len(_XZ_UNITS) else "Unknown"
+
+
+def _y_label(code: int) -> str:
+    if 0 <= code < len(_Y_UNITS):
+        return _Y_UNITS[code] or "Arbitrary Intensity"
+    if 128 <= code < 128 + len(_Y_UNITS_ALT):
+        return _Y_UNITS_ALT[code - 128]
+    return "Unknown"
+
+
+def is_spc(path: str | Path) -> bool:
+    """Sniff a file as SPC via the ``fversn`` byte (0x4B/0x4C/0x4D/0xCF)."""
+    try:
+        with Path(path).open("rb") as fh:
+            head = fh.read(2)
+    except OSError:
+        return False
+    return len(head) == 2 and head[1] in (0x4B, 0x4C, 0x4D, 0xCF)
+
+
+def _decode_flags(ftflgs: int) -> dict[str, bool]:
+    return {name: bool(ftflgs & (1 << bit)) for bit, name in enumerate(_FLAG_BITS)}
+
+
+def _decode_date(fdate: int) -> dict[str, int] | None:
+    if fdate == 0:
+        return None
+    return {
+        "year": fdate >> 20,
+        "month": (fdate >> 16) % 16,
+        "day": (fdate >> 11) % 32,
+        "hour": (fdate >> 6) % 32,
+        "minute": fdate % 64,
+    }
+
+
+def _null_str(raw: bytes) -> str:
+    return raw.split(b"\x00", 1)[0].decode("latin-1", errors="replace").strip()
+
+
+def _parse_log_block(raw: bytes, flogoff: int) -> dict[str, Any] | None:
+    """Trailer log block: a small binary header, then '\\n'-joined text lines,
+    each either a ``KEY=value`` pair or free text."""
+    if flogoff <= 0 or flogoff + _LOG_HEAD_SIZE > len(raw):
+        return None
+    logsizd, _logsizm, logtxto, _logbins, _logdsks, _logspar = struct.unpack_from(
+        _LOG_FMT, raw, flogoff
+    )
+    log_pos = flogoff + logtxto
+    log_end = log_pos + logsizd
+    if log_pos < 0 or log_end > len(raw) or log_end < log_pos:
+        return None
+    lines = raw[log_pos:log_end].replace(b"\r", b"").split(b"\n")
+    pairs: dict[str, str] = {}
+    other: list[str] = []
+    for raw_line in lines:
+        text = raw_line.decode("latin-1", errors="replace")
+        if "=" in text:
+            key, _, value = text.partition("=")
+            pairs[key.strip()] = value.strip()
+        elif text.strip():
+            other.append(text.strip())
+    return {"fields": pairs, "text": other}
+
+
+def _y_from_ints(raw_ints: NDArray[np.integer[Any]], exp: int, bits: int) -> NDArray[np.float64]:
+    return np.asarray(raw_ints, dtype=float) * (2.0 ** (exp - bits))
+
+
+def _read_subfile(
+    raw: bytes, pos: int, *, fnpts: int, fexp: int, tmulti: bool, tsprec: bool, txyxys: bool
+) -> tuple[NDArray[np.float64] | None, NDArray[np.float64], int, dict[str, Any]]:
+    """Returns (own_x or None, y, bytes_consumed, subheader_info)."""
+    sub = dict(zip(_SUBHEAD_FIELDS, struct.unpack_from(_SUBHEAD_FMT, raw, pos), strict=True))
+    exp = int(sub["subexp"]) if tmulti else fexp
+    pts = int(sub["subnpts"]) if (txyxys and sub["subnpts"] > 0) else fnpts
+    cursor = pos + _SUBHEAD_SIZE
+
+    own_x = None
+    if txyxys:
+        # Per-subfile x is fixed-point scaled int32 (same exponent formula as y).
+        x_ints = np.frombuffer(raw, dtype="<i4", count=pts, offset=cursor)
+        own_x = _y_from_ints(x_ints, exp, 32)
+        cursor += 4 * pts
+
+    if exp == _FLOAT_EXP_SENTINEL:
+        y = np.frombuffer(raw, dtype="<f4", count=pts, offset=cursor).astype(float)
+        cursor += 4 * pts
+    elif tsprec:
+        y_ints = np.frombuffer(raw, dtype="<i2", count=pts, offset=cursor)
+        y = _y_from_ints(y_ints, exp, 16)
+        cursor += 2 * pts
+    else:
+        y_ints = np.frombuffer(raw, dtype="<i4", count=pts, offset=cursor)
+        y = _y_from_ints(y_ints, exp, 32)
+        cursor += 4 * pts
+
+    return own_x, y, cursor - pos, sub
+
+
+def import_spc(filepath: str | Path) -> DataStruct:
+    """Import a GRAMS/Thermo ``.spc`` spectral file into a DataStruct."""
+    path = Path(filepath)
+    raw = path.read_bytes()
+    if len(raw) < 2:
+        raise ValueError(f"file too small to be an SPC file: {path.name}")
+    fversn = raw[1]
+    if fversn in _UNSUPPORTED_FVERSN:
+        raise ValueError(
+            f"SPC sub-format '{_UNSUPPORTED_FVERSN[fversn]}' (fversn=0x{fversn:02x}) is "
+            f"recognized but not implemented (no example file to validate against): "
+            f"{path.name}. Only the modern format (fversn=0x4B) is supported."
+        )
+    if fversn != 0x4B or len(raw) < _HEAD_SIZE:
+        raise ValueError(f"not a recognized SPC file (fversn byte 0x{fversn:02x}): {path.name}")
+
+    head = dict(zip(_HEAD_FIELDS, struct.unpack_from(_HEAD_FMT, raw, 0), strict=True))
+    flags = _decode_flags(head["ftflgs"])
+    fnpts, fnsub, fexp = int(head["fnpts"]), int(head["fnsub"]), int(head["fexp"])
+    if fnpts <= 0 or fnsub <= 0:
+        raise ValueError(f"empty SPC file (fnpts={fnpts}, fnsub={fnsub}): {path.name}")
+
+    pos = _HEAD_SIZE
+    global_x: NDArray[np.float64] | None = None
+    if flags["txvals"] and not flags["txyxys"]:
+        global_x = np.frombuffer(raw, dtype="<f4", count=fnpts, offset=pos).astype(float)
+        pos += 4 * fnpts
+    elif not flags["txyxys"]:
+        global_x = np.linspace(head["ffirst"], head["flast"], fnpts)
+
+    subfiles: list[tuple[NDArray[np.float64] | None, NDArray[np.float64], dict[str, Any]]] = []
+    for _ in range(fnsub):
+        own_x, y, consumed, sub_info = _read_subfile(
+            raw, pos, fnpts=fnpts, fexp=fexp, tmulti=flags["tmulti"],
+            tsprec=flags["tsprec"], txyxys=flags["txyxys"],
+        )
+        subfiles.append((own_x, y, sub_info))
+        pos += consumed
+
+    x_label = _axis_label(head["fxtype"])
+    y_label = _y_label(head["fytype"])
+    if flags["talabs"]:
+        parts = head["fcatxt"].split(b"\x00")
+        if len(parts) >= 2:
+            xl, yl = _null_str(parts[0]), _null_str(parts[1])
+            x_label = xl or x_label
+            y_label = yl or y_label
+
+    multi_x = flags["txyxys"] and fnsub > 1
+    if multi_x:
+        # Per-subfile x-axes can't share one DataStruct time column (jcamp.py
+        # precedent: use the first block, note the rest in metadata).
+        x, y_cols, y_labels = subfiles[0][0], subfiles[0][1][:, None], [y_label]
+    else:
+        x = global_x if global_x is not None else subfiles[0][0]
+        y_cols = np.column_stack([y for _own_x, y, _info in subfiles])
+        y_labels = [y_label] if fnsub == 1 else [f"{y_label} {i + 1}" for i in range(fnsub)]
+    assert x is not None
+
+    metadata: dict[str, Any] = {
+        "source": str(path),
+        "parser_name": "import_spc",
+        "x_column_name": x_label,
+        "x_column_unit": "",
+        "experiment_type": (
+            _EXPERIMENT_TYPES[head["fexper"]]
+            if head["fexper"] < len(_EXPERIMENT_TYPES)
+            else "Unknown"
+        ),
+        "comment": _null_str(head["fcmnt"]),
+        "source_instrument": _null_str(head["fres"]) or _null_str(head["fsource"]),
+        "date": _decode_date(head["fdate"]),
+        "n_subfiles": fnsub,
+        "flags": flags,
+        "log": _parse_log_block(raw, int(head["flogoff"])),
+    }
+    if multi_x:
+        metadata["multi_x_subfiles"] = True
+        metadata["n_subfiles_with_own_x"] = fnsub
+
+    return DataStruct.create(
+        x, y_cols, labels=y_labels, units=[y_label] * len(y_labels), metadata=metadata
+    )

quantized/io/xrd_csv.py

@@ -0,0 +1,308 @@
+"""XRD data CSV / Origin-ASCII exporter. Port of MATLAB ``+utilities/writeXRDcsv.m``.
+
+This is the first *writer* in ``io/`` (readers parse files into a
+``DataStruct``; this goes the other way: ``DataStruct`` -> CSV text/file).
+
+Two output formats mirror the MATLAB original exactly:
+
+* ``"standard"`` — comma-delimited; one header row; optional ``# ``-prefixed
+  metadata block.
+* ``"origin"`` — tab-delimited Origin ASCII; three header rows (long name,
+  units, X/Y designation); optional ``#\\t``-prefixed metadata block.
+
+Number formatting matches MATLAB ``fprintf``: x-axis values use ``%.6f``,
+intensity values use ``%.6g``.
+
+Pure layer: ``DataStruct`` in -> string/file out. No fastapi/pydantic imports.
+
+The string-producing :func:`format_xrd_csv` is the testable core;
+:func:`write_xrd_csv` is a thin disk wrapper around it.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Mapping
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["format_xrd_csv", "write_xrd_csv"]
+
+_FORMATS = ("standard", "origin")
+_INTENSITIES = ("both", "cps", "counts")
+
+
+def write_xrd_csv(
+    data: DataStruct,
+    output_path: str | Path,
+    *,
+    fmt: str = "standard",
+    intensity: str = "both",
+    include_metadata: bool = True,
+) -> None:
+    """Write XRD ``data`` to ``output_path`` as CSV or Origin ASCII.
+
+    Parameters
+    ----------
+    data:
+        ``DataStruct`` from an XRD parser (first value column is intensity).
+    output_path:
+        Destination ``.csv`` file. Its parent directory must exist (mirrors
+        the MATLAB ``isfolder`` check).
+    fmt:
+        ``"standard"`` (comma) or ``"origin"`` (tab, 3-row header). Case
+        insensitive (mirrors MATLAB ``validatestring``).
+    intensity:
+        ``"both"`` | ``"cps"`` | ``"counts"`` — which intensity column(s) to
+        emit. Case insensitive.
+    include_metadata:
+        Emit a comment-prefixed metadata header block.
+    """
+    out = Path(output_path)
+    parent = out.parent
+    # Mirror MATLAB: only validate the directory when one is specified.
+    if str(parent) not in ("", ".") and not parent.is_dir():
+        raise FileNotFoundError(f"Output directory does not exist: {parent}")
+
+    text = format_xrd_csv(
+        data, fmt=fmt, intensity=intensity, include_metadata=include_metadata
+    )
+    # newline="" so the explicit "\n" in the text is written verbatim (no
+    # platform translation), matching MATLAB's byte-for-byte fprintf output.
+    out.write_text(text, encoding="utf-8", newline="")
+
+
+def format_xrd_csv(
+    data: DataStruct,
+    *,
+    fmt: str = "standard",
+    intensity: str = "both",
+    include_metadata: bool = True,
+) -> str:
+    """Return the CSV / Origin-ASCII text for ``data`` (no disk I/O).
+
+    See :func:`write_xrd_csv` for parameter meanings. Lines are joined with
+    ``"\\n"`` and the text ends with a trailing newline, matching MATLAB.
+    """
+    fmt_norm = _validate_choice(fmt, _FORMATS, "Format")
+    intensity_norm = _validate_choice(intensity, _INTENSITIES, "Intensity")
+
+    int_vals, int_labels, int_units = _resolve_intensity_columns(data, intensity_norm)
+
+    x_label = _x_axis_label(data)
+    x_unit = _x_axis_unit(data)
+
+    is_origin = fmt_norm == "origin"
+    sep = "\t" if is_origin else ","
+    prefix = "#\t" if is_origin else "# "
+
+    lines: list[str] = []
+    if include_metadata:
+        lines.extend(_metadata_block(data, prefix))
+
+    if is_origin:
+        names = [x_label, *int_labels]
+        units = [x_unit, *int_units]
+        designations = ["X", *(["Y"] * len(int_labels))]
+        lines.append(sep.join(names))
+        lines.append(sep.join(units))
+        lines.append(sep.join(designations))
+    else:
+        lines.append(sep.join([x_label, *int_labels]))
+
+    time = np.asarray(data.time, dtype=float)
+    for row in range(int_vals.shape[0]):
+        cells = [f"{time[row]:.6f}"]
+        cells.extend(f"{int_vals[row, col]:.6g}" for col in range(int_vals.shape[1]))
+        lines.append(sep.join(cells))
+
+    # Trailing newline after the final row (MATLAB writes "\n" after each row).
+    return "\n".join(lines) + "\n"
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────
+
+
+def _validate_choice(value: str, allowed: tuple[str, ...], label: str) -> str:
+    """Case-insensitive choice validation (mirrors MATLAB ``validatestring``)."""
+    norm = str(value).strip().lower()
+    if norm not in allowed:
+        opts = ", ".join(f'"{a}"' for a in allowed)
+        raise ValueError(f"{label} must be one of [{opts}]; got {value!r}")
+    return norm
+
+
+def _meta_get(meta: Mapping[str, Any], *keys: str, default: Any = None) -> Any:
+    """First present, non-empty metadata value among ``keys`` (or ``default``).
+
+    Accepts both quantized's flat snake_case keys and the MATLAB-style camelCase
+    keys (and a nested ``parser_specific`` / ``parserSpecific`` mapping), so the
+    writer is robust to either DataStruct provenance.
+    """
+    sources: list[Mapping[str, Any]] = [meta]
+    for nested_key in ("parser_specific", "parserSpecific"):
+        nested = meta.get(nested_key)
+        if isinstance(nested, Mapping):
+            sources.append(nested)
+    for src in sources:
+        for key in keys:
+            if key in src:
+                val = src[key]
+                if val is None:
+                    continue
+                if isinstance(val, str) and val == "":
+                    continue
+                return val
+    return default
+
+
+def _counting_time(data: DataStruct) -> float:
+    """Counting time (s/point) or NaN. Mirrors MATLAB's parserSpecific lookup."""
+    val = _meta_get(data.metadata, "counting_time", "countingTime", default=None)
+    if val is None:
+        return float("nan")
+    try:
+        return float(val)
+    except (TypeError, ValueError):
+        return float("nan")
+
+
+def _resolve_intensity_columns(
+    data: DataStruct, intensity: str
+) -> tuple[NDArray[np.float64], list[str], list[str]]:
+    """Select / convert intensity columns. Port of ``resolveIntensityColumns``.
+
+    Returns ``(values[N, k], labels[k], units[k])``.
+    """
+    original_unit = data.units[0] if data.units else ""
+    original = np.asarray(data.values[:, 0], dtype=float)
+    counting_time = _counting_time(data)
+    has_ct = not np.isnan(counting_time)
+    is_cps = "cps" in original_unit.lower()
+
+    if intensity == "both":
+        if not has_ct:
+            # Can't convert; write only the original column.
+            if is_cps:
+                return original.reshape(-1, 1), ["Intensity (cps)"], ["cps"]
+            return original.reshape(-1, 1), ["Intensity (counts)"], ["counts"]
+        if is_cps:
+            counts = original * counting_time
+            stacked = np.column_stack([original, counts])
+        else:
+            cps = original / counting_time
+            stacked = np.column_stack([cps, original])
+        return (
+            stacked,
+            ["Intensity (cps)", "Intensity (counts)"],
+            ["cps", "counts"],
+        )
+
+    if intensity == "cps":
+        if is_cps:
+            vals = original
+        elif not has_ct:
+            warnings.warn(
+                "Cannot convert counts to cps (countingTime not available). "
+                "Writing counts.",
+                stacklevel=2,
+            )
+            vals = original
+        else:
+            vals = original / counting_time
+        return vals.reshape(-1, 1), ["Intensity (cps)"], ["cps"]
+
+    # intensity == "counts"
+    is_counts = "counts" in original_unit.lower()
+    if is_counts:
+        vals = original
+    elif not has_ct:
+        warnings.warn(
+            "Cannot convert cps to counts (countingTime not available). "
+            "Writing cps.",
+            stacklevel=2,
+        )
+        vals = original
+    else:
+        vals = original * counting_time
+    return vals.reshape(-1, 1), ["Intensity (counts)"], ["counts"]
+
+
+def _x_axis_label(data: DataStruct) -> str:
+    """Build the x-axis column label. Port of ``getXAxisLabel``."""
+    name = _meta_get(data.metadata, "x_column_name", "xColumnName", default=None)
+    if name is None:
+        return "X Axis"
+    unit = _x_axis_unit(data)
+    return f"{name} ({unit})" if unit else str(name)
+
+
+def _x_axis_unit(data: DataStruct) -> str:
+    """X-axis unit string ('' when unknown). Port of ``getXAxisUnit``."""
+    unit = _meta_get(data.metadata, "x_column_unit", "xColumnUnit", default="")
+    return "" if unit is None else str(unit)
+
+
+def _metadata_block(data: DataStruct, prefix: str) -> list[str]:
+    """Comment-prefixed metadata lines. Port of ``writeMetadataBlock``.
+
+    Field presence/order matches the MATLAB original. The "Export date" line
+    is non-deterministic (current time) by design — golden parity tests freeze
+    with ``include_metadata=False``.
+    """
+    meta = data.metadata
+    lines: list[str] = [f"{prefix}XRD Batch Export"]
+
+    source = _meta_get(meta, "source", "sourceFile", default=None)
+    if source is not None:
+        lines.append(f"{prefix}Source: {source}")
+
+    parser = _meta_get(meta, "parser_name", "parser", default=None)
+    if parser is not None:
+        lines.append(f"{prefix}Parser: {parser}")
+
+    sample = _meta_get(
+        meta, "sample_name", "sampleName", "sampleID", default=None
+    )
+    if sample is not None:
+        lines.append(f"{prefix}Sample: {sample}")
+
+    anode = _meta_get(meta, "anode_material", "anodeMaterial", default=None)
+    if anode is not None:
+        kv = _meta_get(meta, "tension_kV", "tension_kv", default=None)
+        ma = _meta_get(meta, "current_mA", "current_ma", default=None)
+        if kv is not None and ma is not None:
+            lines.append(f"{prefix}Anode: {anode} ({kv:.1f} kV / {ma:.1f} mA)")
+        else:
+            lines.append(f"{prefix}Anode: {anode}")
+
+    ka1 = _meta_get(meta, "k_alpha1", "kAlpha1", default=None)
+    if ka1 is not None:
+        lines.append(f"{prefix}Wavelength: Ka1 = {float(ka1):.5g} A")
+
+    start = _meta_get(meta, "start_angle", "startAngle", default=None)
+    end = _meta_get(meta, "end_angle", "endAngle", default=None)
+    if start is not None and end is not None:
+        lines.append(
+            f"{prefix}2-theta range: {float(start):.4f} - {float(end):.4f} deg"
+        )
+
+    step = _meta_get(meta, "step_size", "stepSize", default=None)
+    npts = _meta_get(meta, "n_points", "nPoints", "num_points", default=None)
+    if step is not None and npts is not None:
+        lines.append(f"{prefix}Step size: {float(step):.6f} deg ({int(npts)} points)")
+
+    ct = _counting_time(data)
+    if not np.isnan(ct):
+        lines.append(f"{prefix}Counting time: {ct:.3f} s/point")
+
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    lines.append(f"{prefix}Export date: {now}")
+    lines.append(prefix)
+    return lines