quantized-lab 0.8.0__py3-none-any.whl

quantized/io/opus.py

@@ -0,0 +1,231 @@
+"""Bruker OPUS FTIR/NIR/Raman binary spectrum parser (``.opus``).
+
+**NOT a MATLAB port.** ``quantized_matlab`` never implemented
+``importOpus.m`` — the roadmap parks it "Paused (awaiting example files)"
+(``quantized_matlab/plans/archive/parser-roadmap.md`` item 3;
+``PORT_CHECKLIST.md`` line 46) and no source or test exists to freeze golden
+values from. This is an independent implementation against Bruker's
+block-directory OPUS layout. The block-type/channel-type dispatch table
+below is the format's own fixed vocabulary (facts about the binary
+protocol, not one implementation's expression of it) — cross-checked
+against the open-source readers ``qedsoftware/brukeropusreader``
+(LGPL-3.0) and ``Bjorn-G-S/UiO-IR-Reader`` for consistency; no code from
+either was copied (both are GPL-family and incompatible with this
+project's Apache-2.0 runtime regardless).
+
+No real ``.opus`` sample file was available to validate against (unlike
+``spc.py``, which was checked against four real instrument files) — this
+parser is exercised with synthetic fixtures built directly from the layout
+below. That is an honest gap, not a fabricated golden result.
+
+Binary layout
+-------------
+Bytes 0-23    file header (magic/version bytes; not decoded here)
+Bytes 24-503  up to 40 directory entries, 12 bytes each:
+    byte 0        data_type     (block category)
+    byte 1        channel_type  (sub-category: which channel/plane)
+    byte 2        text_type     (further sub-category, text blocks only)
+    byte 3        reserved
+    bytes 4-7     chunk_size    (uint32 LE, in 4-byte WORDS)
+    bytes 8-11    offset        (uint32 LE, absolute byte offset of the chunk)
+A directory entry with ``offset <= 0`` terminates the directory early.
+
+Each chunk is one of three kinds:
+  - **text**   raw Latin-1 text (history, sample form, signature, ...)
+  - **series** ``chunk_size`` little-endian float32 values (a spectrum)
+  - **param**  a sequence of ``{3-byte name}{1 reserved}{type:u16}{size:u16}
+    {value: 2*size bytes}`` records terminated by name ``"END"``; value
+    type 0=int32, 1=float64, 2-4=null-terminated Latin-1 string.
+
+The primary spectrum is chosen by priority: ``AB`` (final absorbance /
+transmittance result) > ``ScSm`` (sample single-channel spectrum) > ``IgSm``
+(sample interferogram) > ``PhSm`` > ``PwSm`` > any other series block found.
+Its companion ``"<Name> Data Parameter"`` block supplies ``FXV``/``LXV``/
+``NPT`` (the x-axis range) and ``DXU`` (the x-axis unit code).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from struct import calcsize, unpack_from
+from struct import error as struct_error
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["import_opus", "is_opus"]
+
+_HEADER_LEN = 504
+_DIR_START = 24
+_DIR_ENTRY_SIZE = 12
+
+# (data_type, channel_type) -> block name. channel_type=None matches any
+# (param/text blocks that don't distinguish by channel).
+_SERIES_BLOCKS: dict[tuple[int, int], str] = {
+    (7, 4): "ScSm", (7, 8): "IgSm", (7, 12): "PhSm", (7, 56): "PwSm",
+    (11, 4): "ScRf", (11, 8): "IgRf", (11, 12): "PhRf", (11, 56): "PwRf",
+}
+_PARAM_CHANNEL_BLOCKS: dict[tuple[int, int], str] = {
+    (23, 4): "ScSm Data Parameter", (23, 8): "IgSm Data Parameter",
+    (23, 12): "PhSm Data Parameter", (23, 56): "PwSm Data Parameter",
+    (27, 4): "ScRf Data Parameter", (27, 8): "IgRf Data Parameter",
+    (27, 12): "PhRf Data Parameter", (27, 56): "PwRf Data Parameter",
+}
+_PARAM_BLOCKS: dict[int, str] = {
+    31: "AB Data Parameter", 32: "Instrument", 40: "Instrument (Rf)",
+    48: "Acquisition", 56: "Acquisition (Rf)", 64: "Fourier Transformation",
+    72: "Fourier Transformation (Rf)", 96: "Optik", 104: "Optik (Rf)",
+    160: "Sample",
+}
+_TEXT_BLOCKS: dict[int, str] = {
+    8: "Info Block", 104: "History", 152: "Curve Fit", 168: "Signature",
+    240: "Integration Method",
+}
+_AB_SERIES_TYPE = 15  # data_type for the final absorbance/transmittance block
+
+_PRIMARY_PRIORITY = ("AB", "ScSm", "IgSm", "PhSm", "PwSm", "ScRf", "IgRf", "PhRf", "PwRf")
+
+_DXU_UNITS = {
+    "WN": "Wavenumber (cm-1)", "MI": "Minutes", "PNT": "Data Points", "WL": "Wavelength (nm)",
+}
+
+
+def _block_name(data_type: int, channel_type: int, text_type: int) -> tuple[str, str] | None:
+    """Returns (name, kind) where kind is 'text'/'series'/'param', or None to skip."""
+    if data_type == 0:
+        return _TEXT_BLOCKS.get(text_type, "Text Information"), "text"
+    if data_type == _AB_SERIES_TYPE:
+        return "AB", "series"
+    name = _SERIES_BLOCKS.get((data_type, channel_type))
+    if name is not None:
+        return name, "series"
+    name = _PARAM_CHANNEL_BLOCKS.get((data_type, channel_type))
+    if name is not None:
+        return name, "param"
+    name = _PARAM_BLOCKS.get(data_type)
+    if name is not None:
+        return name, "param"
+    return None  # unknown block type: skip (matches every known OPUS reader's behaviour)
+
+
+def _parse_directory(header: bytes, file_size: int) -> list[tuple[int, int, int, int, int]]:
+    entries: list[tuple[int, int, int, int, int]] = []
+    cursor = _DIR_START
+    while cursor + _DIR_ENTRY_SIZE <= _HEADER_LEN:
+        data_type, channel_type, text_type = header[cursor], header[cursor + 1], header[cursor + 2]
+        chunk_size, offset = unpack_from("<II", header, cursor + 4)
+        if offset <= 0:
+            break
+        entries.append((data_type, channel_type, text_type, chunk_size, offset))
+        if offset + 4 * chunk_size >= file_size:
+            break
+        cursor += _DIR_ENTRY_SIZE
+    return entries
+
+
+def _parse_params(chunk: bytes) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    cursor = 0
+    while cursor + 8 <= len(chunk):
+        name = chunk[cursor : cursor + 3].decode("ascii", errors="replace")
+        if name == "END":
+            break
+        type_index = unpack_from("<H", chunk, cursor + 4)[0]
+        size_words = unpack_from("<H", chunk, cursor + 6)[0]
+        value = chunk[cursor + 8 : cursor + 8 + 2 * size_words]
+        try:
+            if type_index == 0 and len(value) >= calcsize("<i"):
+                params[name] = unpack_from("<i", value)[0]
+            elif type_index == 1 and len(value) >= calcsize("<d"):
+                params[name] = unpack_from("<d", value)[0]
+            else:
+                end = value.find(b"\x00")
+                params[name] = value[: end if end >= 0 else len(value)].decode(
+                    "latin-1", errors="replace"
+                )
+        except struct_error:
+            break
+        cursor += 8 + 2 * size_words
+    return params
+
+
+def _parse_series(chunk: bytes, chunk_size: int) -> NDArray[np.float64]:
+    n = min(chunk_size, len(chunk) // 4)
+    return np.frombuffer(chunk, dtype="<f4", count=n).astype(float)
+
+
+def is_opus(path: str | Path) -> bool:
+    """Sniff a file as OPUS: a well-formed block directory with >= 1 entry."""
+    try:
+        raw = Path(path).read_bytes()
+    except OSError:
+        return False
+    if len(raw) < _HEADER_LEN:
+        return False
+    return len(_parse_directory(raw[:_HEADER_LEN], len(raw))) > 0
+
+
+def import_opus(filepath: str | Path) -> DataStruct:
+    """Import a Bruker OPUS binary spectrum into a DataStruct."""
+    path = Path(filepath)
+    raw = path.read_bytes()
+    if len(raw) < _HEADER_LEN:
+        raise ValueError(f"file too small to be an OPUS file: {path.name}")
+
+    entries = _parse_directory(raw[:_HEADER_LEN], len(raw))
+    if not entries:
+        raise ValueError(f"no OPUS block directory found (not an OPUS file?): {path.name}")
+
+    blocks: dict[str, Any] = {}
+    for data_type, channel_type, text_type, chunk_size, offset in entries:
+        resolved = _block_name(data_type, channel_type, text_type)
+        if resolved is None:
+            continue
+        name, kind = resolved
+        chunk = raw[offset : offset + 4 * chunk_size]
+        if kind == "text":
+            blocks[name] = chunk.decode("latin-1", errors="replace").strip("\x00").strip()
+        elif kind == "series":
+            blocks[name] = _parse_series(chunk, chunk_size)
+        else:
+            blocks[name] = _parse_params(chunk)
+
+    primary = next(
+        (n for n in _PRIMARY_PRIORITY if isinstance(blocks.get(n), np.ndarray)), None
+    )
+    if primary is None:
+        primary = next((n for n, v in blocks.items() if isinstance(v, np.ndarray)), None)
+    if primary is None:
+        raise ValueError(
+            f"no spectral data block (AB/ScSm/IgSm/...) found in OPUS file: {path.name}"
+        )
+
+    y = blocks[primary]
+    params = blocks.get(f"{primary} Data Parameter", {})
+    npt = len(y)
+    fxv = float(params.get("FXV", 0.0))
+    lxv = float(params.get("LXV", float(npt - 1)))
+    x = np.linspace(fxv, lxv, npt) if npt > 1 else np.array([fxv])
+    dxu = str(params.get("DXU", ""))
+
+    y_label = "Absorbance" if primary == "AB" else "Intensity"
+    param_blocks = {
+        name: value for name, value in blocks.items() if isinstance(value, dict)
+    }
+    text_blocks = {
+        name: value for name, value in blocks.items() if isinstance(value, str)
+    }
+    metadata: dict[str, Any] = {
+        "source": str(path),
+        "parser_name": "import_opus",
+        "primary_block": primary,
+        "x_column_name": _DXU_UNITS.get(dxu, dxu or "Wavenumber (cm-1)"),
+        "x_column_unit": dxu,
+        "blocks_found": sorted(blocks.keys()),
+        "parameters": param_blocks,
+        "text": text_blocks,
+    }
+    return DataStruct.create(x, y, labels=[y_label], units=[""], metadata=metadata)

quantized/io/origin.py

@@ -0,0 +1,346 @@
+"""Origin export: a paired CSV + LabTalk ``.ogs`` script. Port of MATLAB
+``+utilities/exportOriginScript.m``.
+
+The ``.ogs`` script, when run in OriginPro, imports the accompanying CSV, sets
+column designations (X / Y / yErr by label), long names + units, and optionally
+builds a graph — a maintainable alternative to writing binary ``.opju`` files.
+
+Pure layer: ``format_origin_script`` returns ``(csv_text, ogs_text)`` (no disk
+I/O). The ``created`` timestamp is injected by the caller so the function stays
+deterministic (the route passes the wall-clock time; tests pass a fixed value).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["GraphSpec", "format_origin_project_script", "format_origin_script"]
+
+_ERR_KEYWORDS = ("err", "dr", "std", "sigma")
+
+
+@dataclass(frozen=True, slots=True)
+class GraphSpec:
+    """Current plot-state snapshot for the ``.ogs`` GRAPH block (item 26) —
+    a LabTalk mirror of ``calc.plotting.PlotState`` plus axis limits.
+
+    ``y_keys``/``x_key``/``y2_keys`` are 0-based value-channel indices (the
+    same indexing as ``DataStruct.labels``/``.values`` columns — worksheet
+    column ``idx + 2``, since column 1 is X). ``y_keys=None`` means "all
+    channels" (mirrors ``PlotState``/``build_series``'s default). Channels
+    listed in ``y2_keys`` are drawn on a secondary (right) Y axis; they
+    should be a subset of the effective y-key set.
+    """
+
+    y_keys: tuple[int, ...] | None = None
+    x_key: int | None = None
+    x_log: bool = False
+    y_log: bool = False
+    x_lim: tuple[float, float] | None = None
+    y_lim: tuple[float, float] | None = None
+    y2_keys: tuple[int, ...] = ()
+
+
+def _meta_get(meta: dict[str, Any], *keys: str, default: Any = None) -> Any:
+    """First present, non-empty metadata value among ``keys`` (snake/camel)."""
+    for key in keys:
+        val = meta.get(key)
+        if val not in (None, ""):
+            return val
+    return default
+
+
+def _escape_lt(text: str) -> str:
+    """Escape double-quotes for a LabTalk string literal."""
+    return text.replace('"', '\\"')
+
+
+def _sanitize(name: str) -> str:
+    """LabTalk-safe identifier: non-word chars -> underscore (MATLAB \\W)."""
+    return re.sub(r"\W", "_", name)
+
+
+def _is_err_label(label: str) -> bool:
+    low = label.lower()
+    return any(kw in low for kw in _ERR_KEYWORDS)
+
+
+def _col(idx: int) -> int:
+    """Worksheet column (1-based) for value-channel index ``idx`` (0-based).
+    Column 1 is X; channels start at column 2 (mirrors the designations loop
+    in ``format_origin_script``)."""
+    return idx + 2
+
+
+def _axis_title(label: str, unit: str) -> str:
+    return label + (f" ({unit})" if unit else "")
+
+
+def _plot_state_graph(
+    graph: GraphSpec,
+    *,
+    labels: list[str],
+    units: list[str],
+    x_name: str,
+    x_unit: str,
+    sheet: str,
+) -> list[str]:
+    """LabTalk lines recreating the CURRENT PLOT STATE (item 26): selected
+    channels, x source, log flags, axis limits, and an optional secondary
+    (right) Y axis for ``y2_keys``.
+
+    One ``plotxy`` call plots the whole primary y-set via grouped range
+    syntax (``(x,y1):(x,y2):…`` — pairs need not be contiguous columns). The
+    secondary axis uses ``layer -nr`` (new right-Y layer linked to the active
+    graph's X axis) followed by a ``plotxy`` into layer 2. Both were VERIFIED
+    live against OriginPro via COM: the secondary ``plotxy`` must reference the
+    worksheet explicitly (``[%(qzbk$)]<sheet>!``) because the graph — not the
+    book — is the active window by then, and impASC renamed the book, so
+    ``qzbk$`` (captured in the import block) holds its real short name.
+    """
+    y_indices = list(range(len(labels))) if graph.y_keys is None else list(graph.y_keys)
+    if not y_indices:
+        return ["", "// Create graph (current plot state): no channels selected -- skipped"]
+
+    # Validate channel indices up front: an out-of-range or negative index would
+    # otherwise emit a `plotxy` referencing a worksheet column that was never
+    # declared (or column 0 / a wrapped-around label), silently producing a
+    # broken .ogs. The route converts this ValueError to a 422.
+    n_ch = len(labels)
+    checked = [*y_indices, *graph.y2_keys, *([] if graph.x_key is None else [graph.x_key])]
+    out_of_range = sorted({k for k in checked if not 0 <= k < n_ch})
+    if out_of_range:
+        raise ValueError(
+            f"graph channel index out of range for {n_ch} channel(s): {out_of_range}"
+        )
+
+    y2_set = set(graph.y2_keys)
+    primary = [i for i in y_indices if i not in y2_set]
+    secondary = [i for i in y_indices if i in y2_set]
+    if not primary:
+        # Nothing to anchor a left/right split against -- render the would-be
+        # y2 set on the single default axis instead.
+        primary, secondary = y_indices, []
+
+    x_col = 1 if graph.x_key is None else _col(graph.x_key)
+    if graph.x_key is None:
+        x_label, x_lbl_unit = x_name, x_unit
+    else:
+        xi = graph.x_key
+        x_label = labels[xi] if xi < len(labels) else x_name
+        x_lbl_unit = units[xi] if xi < len(units) else ""
+
+    o: list[str] = ["", "// Create graph (current plot state)"]
+    pairs = ":".join(f"({x_col},{_col(i)})" for i in primary)
+    o.append(f"plotxy iy:={pairs} plot:=201 ogl:=[<new>];")
+    if graph.x_log:
+        o.append("layer.x.type = 1;  // Log X")
+    if graph.y_log:
+        o.append("layer.y.type = 1;  // Log Y")
+    # Only emit finite limits -- NaN/Inf would format as invalid LabTalk
+    # literals (`layer.x.from = nan;`). A non-finite bound just omits the line,
+    # letting Origin auto-scale that axis.
+    if graph.x_lim is not None and all(math.isfinite(v) for v in graph.x_lim):
+        lo, hi = graph.x_lim
+        o.append(f"layer.x.from = {lo:.10g};")
+        o.append(f"layer.x.to = {hi:.10g};")
+    if graph.y_lim is not None and all(math.isfinite(v) for v in graph.y_lim):
+        lo, hi = graph.y_lim
+        o.append(f"layer.y.from = {lo:.10g};")
+        o.append(f"layer.y.to = {hi:.10g};")
+    o.append(f'xb.text$ = "{_escape_lt(_axis_title(x_label, x_lbl_unit))}";')
+    if len(primary) == 1:
+        yi = primary[0]
+        y_unit = units[yi] if yi < len(units) else ""
+        o.append(f'yl.text$ = "{_escape_lt(_axis_title(labels[yi], y_unit))}";')
+
+    if secondary:
+        # Explicit worksheet ref: the graph is the active window here, so a bare
+        # (x,y) range would not resolve. qzbk$ (import block) holds the book's
+        # post-impASC short name; <sheet> was restored right after import.
+        pairs2 = ":".join(f"[%(qzbk$)]{sheet}!({x_col},{_col(i)})" for i in secondary)
+        o += [
+            "",
+            "// Secondary (right) Y axis for y2-assigned channels (item 26).",
+            "// New right-Y layer linked to the active graph's X, then plot the",
+            "// y2 channels into layer 2 (verified live in OriginPro via COM).",
+            "layer -nr;  // new right-Y layer, linked X",
+            f"plotxy iy:={pairs2} plot:=201 ogl:=2!;",
+            "page.active = 2;  // operate on the new right-Y layer below",
+        ]
+        if graph.y_log:
+            o.append("layer.y.type = 1;  // Log Y (right)")
+        if len(secondary) == 1:
+            yi = secondary[0]
+            y_unit = units[yi] if yi < len(units) else ""
+            # A "layer -nr" layer has no pre-made axis-title object, so use the
+            # `label -yr` command (yr.text$ / yl.text$ fail here) to title its
+            # right Y axis. Verified live in OriginPro via COM.
+            o.append(f'label -yr "{_escape_lt(_axis_title(labels[yi], y_unit))}";')
+    return o
+
+
+def format_origin_script(
+    data: DataStruct,
+    *,
+    csv_name: str = "data.csv",
+    book_name: str = "",
+    sheet_name: str = "",
+    log_x: bool = False,
+    log_y: bool = False,
+    make_graph: bool = True,
+    created: str = "",
+    book_long_name: str = "",
+    graph: GraphSpec | None = None,
+) -> tuple[str, str]:
+    """Return ``(csv_text, ogs_text)`` for ``data``. Port of exportOriginScript.
+
+    ``csv_name`` is the CSV filename the script references (``impASC``).
+    ``book_name``/``sheet_name`` default to the source filename in metadata,
+    then ``"data"``; both are sanitized to LabTalk identifiers.
+
+    ``graph`` (item 26), when given, replaces the default single-column graph
+    with a full plot-state export: selected channels, x source, log axes,
+    limits, and a secondary Y axis. Ignored when ``make_graph`` is False.
+    """
+    meta = dict(data.metadata)
+    source = _meta_get(meta, "source", "filepath", "filename", default="")
+    base = str(source).replace("\\", "/").rsplit("/", 1)[-1].rsplit(".", 1)[0]
+    book = _sanitize(book_name or base or "data")
+    sheet = _sanitize(sheet_name or book)
+
+    x_name = str(_meta_get(meta, "x_column_name", "xColumnName", default="X"))
+    x_unit = str(_meta_get(meta, "x_column_unit", "xColumnUnit", default=""))
+
+    labels = list(data.labels)
+    units = list(data.units)
+    time = np.asarray(data.time, dtype=float)
+    values = np.asarray(data.values, dtype=float)
+
+    # ── CSV: header, units, then %.10g data rows ──
+    csv_lines = [
+        ",".join([x_name, *labels]),
+        ",".join([x_unit, *units]),
+    ]
+    for r in range(values.shape[0]):
+        cells = [f"{time[r]:.10g}"]
+        cells.extend(f"{values[r, c]:.10g}" for c in range(values.shape[1]))
+        csv_lines.append(",".join(cells))
+    csv_text = "\n".join(csv_lines) + "\n"
+
+    # ── LabTalk (.ogs) script ──
+    o: list[str] = [
+        "// LabTalk script generated by quantized_matlab",
+        f"// Date: {created}",
+        "",
+        "// Import data",
+        f'newbook name:="{book}" sheet:=1;',
+        # impASC auto-detects the 2-row (name/unit) header AND renames the book +
+        # sheet to the source file -- so restore the intended names AFTER import.
+        # (The historical `options.SkipRows.Count:=2` sub-option is INVALID LabTalk
+        # in current Origin and aborts the whole import; bare impASC reads our
+        # 2-header CSV correctly and the explicit designations below re-assert
+        # names/units. See docs/origin_project_format.md.)
+        f'impASC fname:="{csv_name}";',
+        *([f'page.longname$ = "{_escape_lt(book_long_name)}";'] if book_long_name else []),
+        f'wks.name$ = "{sheet}";',
+        # A successful impASC renamed the book; capture its (post-import) short
+        # name so the item-26 secondary-axis plotxy can reference the worksheet
+        # columns while the GRAPH window -- not the book -- is active.
+        *(["string qzbk$ = page.name$;"] if (make_graph and graph is not None) else []),
+        "",
+        "// Column designations and labels",
+        "wks.col1.type = 4;  // X",
+        f'wks.col1.lname$ = "{_escape_lt(x_name)}";',
+        f'wks.col1.unit$ = "{_escape_lt(x_unit)}";',
+    ]
+    for k, label in enumerate(labels):
+        cn = k + 2
+        unit = units[k] if k < len(units) else ""
+        if _is_err_label(label):
+            o.append(f"wks.col{cn}.type = 3;  // yErr")
+        else:
+            o.append(f"wks.col{cn}.type = 1;  // Y")
+        o.append(f'wks.col{cn}.lname$ = "{_escape_lt(label)}";')
+        o.append(f'wks.col{cn}.unit$ = "{_escape_lt(unit)}";')
+
+    if make_graph:
+        if graph is not None:
+            o += _plot_state_graph(
+                graph, labels=labels, units=units, x_name=x_name, x_unit=x_unit, sheet=sheet
+            )
+        else:
+            o += ["", "// Create graph", "plotxy iy:=(1,2) plot:=201 ogl:=[<new>];"]
+            if log_x:
+                o.append("layer.x.type = 1;  // Log X")
+            if log_y:
+                o.append("layer.y.type = 1;  // Log Y")
+            x_title = x_name + (f" ({x_unit})" if x_unit else "")
+            o.append(f'xb.text$ = "{_escape_lt(x_title)}";')
+            if len(labels) == 1:
+                y_unit = units[0] if units else ""
+                y_title = labels[0] + (f" ({y_unit})" if y_unit else "")
+                o.append(f'yl.text$ = "{_escape_lt(y_title)}";')
+
+    o += ["", "// Done"]
+    ogs_text = "\n".join(o) + "\n"
+    return csv_text, ogs_text
+
+
+def format_origin_project_script(
+    items: list[tuple[DataStruct, str]],
+    *,
+    created: str = "",
+    make_graph: bool = False,
+) -> tuple[list[tuple[str, str]], str]:
+    """Multi-book export: one LabTalk ``.ogs`` importing N CSVs into N books.
+
+    ``items`` is ``[(dataset, book_name), …]`` (an empty name falls back to the
+    dataset's ``origin_book`` metadata, then ``dataN``). Returns
+    ``([(csv_name, csv_text), …], ogs_text)`` — the script recreates every
+    workbook with designations, long names, units, and the book display title
+    (``page.longname$``) when the dataset carries one.
+    """
+    if not items:
+        raise ValueError("format_origin_project_script needs at least one dataset")
+    csvs: list[tuple[str, str]] = []
+    sections: list[str] = [
+        "// LabTalk project script generated by quantized",
+        f"// Date: {created}",
+        f"// Books: {len(items)}",
+    ]
+    used: set[str] = set()
+    for i, (ds, name) in enumerate(items):
+        meta = dict(ds.metadata)
+        book = _sanitize(str(name or meta.get("origin_book", "") or f"data{i + 1}"))
+        base = book
+        n = 1
+        while book in used:
+            n += 1
+            book = f"{base}{n}"
+        used.add(book)
+        long_name = str(meta.get("origin_book_long", "") or "")
+        csv_name = f"{book}_data.csv"
+        csv_text, ogs_text = format_origin_script(
+            ds,
+            csv_name=csv_name,
+            book_name=book,
+            sheet_name=book,
+            make_graph=make_graph,
+            created=created,
+            book_long_name=long_name if long_name != book else "",
+        )
+        csvs.append((csv_name, csv_text))
+        body = ogs_text.splitlines()
+        # drop the per-script header comment lines (kept once at the top)
+        while body and body[0].startswith("//"):
+            body.pop(0)
+        sections += ["", f"// ---- Book {i + 1}: {book} ----", *body]
+    return csvs, "\n".join(sections) + "\n"