spectrl 0.1.0__py3-none-any.whl

spectrl/__init__.py

@@ -0,0 +1,221 @@
+"""spectrl — Inline Spectrum URL Encoder.
+
+Encodes a single mass spectrum into a compact, URL-safe token (spectrl1.…) so it can be
+shared with no backend. The entire spectrum lives in the token.
+
+Public API::
+
+    encode_spectrum(spec, *, lossless=False, max_len=None) -> str
+    decode_token(token) -> DecodedSpectrum
+    from_mzmlpy(spec, ref_groups=None) -> InlineSpectrum
+    top_n(spec, n) -> InlineSpectrum
+    to_fragment(token, base) -> str
+    to_query(token, base, param="d") -> str
+    to_data_uri(token) -> str
+    extract_token(url_or_uri) -> str
+"""
+
+from __future__ import annotations
+
+import warnings
+from urllib.parse import parse_qs, urlparse, urlunparse
+
+from .cv import ARRAY_CHARGE, ARRAY_INTENSITY, ARRAY_MZ, ION_MOBILITY_ARRAY_TAILS
+from .header import build_header, extract_descriptors, parse_header
+from .model import DecodedSpectrum, InlineSpectrum, SpectrlCvParam
+from .peaks import _validate_arrays, build_array_blobs, canonical_sort, compute_hash, decode_array_blobs, top_n
+from .proforma import validate_interp
+from .token import build_token, parse_token
+
+__all__ = [
+    "encode_spectrum",
+    "decode_token",
+    "from_mzmlpy",
+    "top_n",
+    "to_fragment",
+    "to_query",
+    "to_data_uri",
+    "extract_token",
+    "InlineSpectrum",
+    "DecodedSpectrum",
+    "SpectrlCvParam",
+]
+
+_SIZE_WARN = 8192  # bytes — warn past this
+_MAGIC_PREFIX = "spectrl1."
+_DATA_URI_PREFIX = "data:application/vnd.spectrl;v=1,"
+
+
+def encode_spectrum(
+    spec: InlineSpectrum,
+    *,
+    lossless: bool = False,
+    max_len: int | None = None,
+) -> str:
+    """Encode an InlineSpectrum to a spectrl1 token string.
+
+    Args:
+        spec: The spectrum to encode.
+        lossless: If True, use raw IEEE-754 + zlib (bit-exact). Default is lossy
+            MS-Numpress (recommended for URL sharing).
+        max_len: Raise OverflowError if the encoded token exceeds this byte length.
+            Use top_n() to reduce peak count, or fall back to a USI reference for
+            repository-resident spectra.
+
+    Returns:
+        A ``spectrl1.`` token string.
+
+    Raises:
+        OverflowError: If max_len is set and the encoded length exceeds it.
+        ValueError: If arrays contain NaN/Inf, or peaks are not finite.
+    """
+    spec = canonical_sort(spec)
+    _validate_arrays(spec)
+
+    if spec.interp is not None:
+        validate_interp(spec.interp)
+
+    blobs, descriptors = build_array_blobs(spec, lossless=lossless)
+
+    # Assign segment indices
+    for i, desc in enumerate(descriptors):
+        desc["seg"] = i
+
+    # Compute hash over header (without hash field) + blobs
+    header_no_hash = build_header(spec, descriptors, hash_str=None)
+    hash_str = compute_hash(header_no_hash, blobs)
+
+    # Build final header with hash
+    header_bytes = build_header(spec, descriptors, hash_str=hash_str)
+    token = build_token(header_bytes, blobs)
+
+    if len(token) > _SIZE_WARN:
+        warnings.warn(
+            f"spectrl token length {len(token)} bytes exceeds recommended maximum of {_SIZE_WARN} bytes. "
+            "Consider using top_n() to reduce peak count, or fall back to a USI reference.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    if max_len is not None and len(token) > max_len:
+        raise OverflowError(
+            f"Encoded spectrl token is {len(token)} bytes, which exceeds max_len={max_len}. "
+            "Use top_n(spec, n) to reduce peak count before encoding, "
+            "or use a USI reference for repository-resident spectra."
+        )
+
+    return token
+
+
+def decode_token(token: str) -> DecodedSpectrum:
+    """Decode a spectrl1 token string into a DecodedSpectrum.
+
+    Verifies the stored hash if present, raising ValueError on mismatch.
+
+    Args:
+        token: A ``spectrl1.`` token string.
+
+    Returns:
+        DecodedSpectrum with all metadata and peak arrays populated.
+
+    Raises:
+        ValueError: On bad magic/version or hash mismatch.
+    """
+    header_bytes, blobs = parse_token(token)
+    decoded = parse_header(header_bytes)
+
+    # Verify hash BEFORE decoding arrays (catches corruption early). The header
+    # without key 9 is recovered by byte-slicing the received bytes (not by
+    # re-encoding), so verification never depends on a canonical msgpack form.
+    if decoded.hash is not None:
+        from .header import strip_top_key
+
+        header_no_hash = strip_top_key(header_bytes, 9)
+        expected = compute_hash(header_no_hash, blobs)
+        if expected != decoded.hash:
+            raise ValueError(
+                f"spectrl token hash mismatch: stored={decoded.hash!r}, computed={expected!r}. Token may be corrupted."
+            )
+
+    descriptors = extract_descriptors(header_bytes)
+
+    # Decode peak arrays
+    arrays = decode_array_blobs(descriptors, blobs)
+
+    decoded.mz = arrays.get(ARRAY_MZ)
+    decoded.intensity = arrays.get(ARRAY_INTENSITY)
+    decoded.charge = arrays.get(ARRAY_CHARGE)
+
+    # Ion mobility: any remaining array tail in ION_MOBILITY_ARRAY_TAILS
+    for tail, arr in arrays.items():
+        if tail in ION_MOBILITY_ARRAY_TAILS.values():
+            decoded.ion_mobility = arr
+            from .cv import decode_tail
+
+            decoded.ion_mobility_type = decode_tail(tail)
+            break
+
+    return decoded
+
+
+def from_mzmlpy(spec, ref_groups: dict | None = None) -> InlineSpectrum:
+    """Convert a mzmlpy Spectrum to InlineSpectrum.
+
+    Args:
+        spec: A mzmlpy.spectra.Spectrum.
+        ref_groups: Optional dict mapping group id → mzmlpy _ParamGroup, for
+            expanding referenceableParamGroupRef elements. Build it as
+            ``{g.id: g for g in mzml.referenceable_param_groups}``.
+
+    Returns:
+        InlineSpectrum ready for encoding.
+    """
+    from .mzml import from_mzmlpy as _bridge
+
+    return _bridge(spec, ref_groups=ref_groups)
+
+
+# ─── URL binding helpers ─────────────────────────────────────────────────────
+
+
+def to_fragment(token: str, base: str) -> str:
+    """Wrap a token as a URL fragment: ``base#token``.
+
+    The fragment is never sent to the server, avoiding length limits and access logs.
+    """
+    return f"{base.rstrip('#')}#{token}"
+
+
+def to_query(token: str, base: str, param: str = "d") -> str:
+    """Wrap a token as a URL query parameter: ``base?param=token``."""
+    parsed = urlparse(base)
+    query = f"{param}={token}"
+    return urlunparse(parsed._replace(query=query))
+
+
+def to_data_uri(token: str) -> str:
+    """Wrap a token in a ``data:application/vnd.mzx;v=1,`` URI."""
+    return f"{_DATA_URI_PREFIX}{token}"
+
+
+def extract_token(url_or_uri: str) -> str:
+    """Extract a spectrl1 token from a URL fragment, query string, or data: URI.
+
+    Raises ValueError if no token is found.
+    """
+    if url_or_uri.startswith(_DATA_URI_PREFIX):
+        return url_or_uri[len(_DATA_URI_PREFIX) :]
+
+    parsed = urlparse(url_or_uri)
+
+    if parsed.fragment.startswith(_MAGIC_PREFIX):
+        return parsed.fragment
+
+    # Check query params for any value starting with spectrl1.
+    qs = parse_qs(parsed.query)
+    for vals in qs.values():
+        for v in vals:
+            if v.startswith(_MAGIC_PREFIX):
+                return v
+
+    raise ValueError(f"No spectrl1 token found in: {url_or_uri!r}")

spectrl/cli.py

@@ -0,0 +1,88 @@
+"""CLI for mzx: encode, decode, and inspect tokens."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _encode_cmd(args: argparse.Namespace) -> None:
+    import numpy as np
+
+    from . import encode_spectrum
+    from .model import InlineSpectrum, SpectrlCvParam
+
+    data = json.load(sys.stdin if args.input == "-" else open(args.input))
+    mz = np.array(data["mz"], dtype=np.float64)
+    intensity = np.array(data["intensity"], dtype=np.float64)
+
+    params = [SpectrlCvParam(**p) for p in data.get("params", [])]
+    spec = InlineSpectrum(
+        default_array_length=len(mz),
+        mz=mz,
+        intensity=intensity,
+        id=data.get("id"),
+        params=params,
+    )
+    token = encode_spectrum(spec, lossless=args.lossless, max_len=args.max_len)
+    print(token)
+
+
+def _decode_cmd(args: argparse.Namespace) -> None:
+    from . import decode_token
+
+    token = (sys.stdin.read() if args.input == "-" else open(args.input).read()).strip()
+    decoded = decode_token(token)
+    out: dict = {
+        "id": decoded.id,
+        "default_array_length": decoded.default_array_length,
+        "mz": decoded.mz.tolist() if decoded.mz is not None else None,
+        "intensity": decoded.intensity.tolist() if decoded.intensity is not None else None,
+        "charge": decoded.charge.tolist() if decoded.charge is not None else None,
+        "hash": decoded.hash,
+        "interp": decoded.interp,
+    }
+    print(json.dumps(out, indent=2))
+
+
+def _inspect_cmd(args: argparse.Namespace) -> None:
+    import msgpack
+
+    from .token import parse_token
+
+    token = (sys.stdin.read() if args.input == "-" else open(args.input).read()).strip()
+    header_bytes, blobs = parse_token(token)
+    h = msgpack.unpackb(header_bytes, raw=False)
+    print(f"Segments: 1 header + {len(blobs)} array(s)")
+    print(f"Header size: {len(header_bytes)} bytes")
+    for i, blob in enumerate(blobs):
+        print(f"Array {i} size: {len(blob)} bytes")
+    print("Header (decoded):")
+    print(json.dumps(h, indent=2, default=str))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="spectrl", description="mzx inline spectrum encoder/decoder")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    enc = sub.add_parser("encode", help="Encode a spectrum JSON to a spectrl1 token")
+    enc.add_argument("input", nargs="?", default="-", help="Input JSON file or '-' for stdin")
+    enc.add_argument("--lossless", action="store_true", help="Use lossless IEEE-754 + zlib encoding")
+    enc.add_argument("--max-len", type=int, default=None, help="Maximum token length in bytes")
+    enc.set_defaults(func=_encode_cmd)
+
+    dec = sub.add_parser("decode", help="Decode a spectrl1 token to JSON")
+    dec.add_argument("input", nargs="?", default="-", help="Token file or '-' for stdin")
+    dec.set_defaults(func=_decode_cmd)
+
+    ins = sub.add_parser("inspect", help="Inspect a spectrl1 token header as readable JSON")
+    ins.add_argument("input", nargs="?", default="-", help="Token file or '-' for stdin")
+    ins.set_defaults(func=_inspect_cmd)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

spectrl/codecs/__init__.py

@@ -0,0 +1,78 @@
+"""Codec registry keyed by compression CV accession tail integer."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+import numpy as np
+
+from ..cv import (
+    COMP_NUMLIN_ZLIB,
+    COMP_NUMPIC_ZLIB,
+    COMP_NUMSLOF_ZLIB,
+    COMP_ZLIB,
+)
+from .numpress import (
+    decode_numlin_zlib,
+    decode_numpic_zlib,
+    decode_numslof_zlib,
+    encode_numlin_zlib,
+    encode_numpic_zlib,
+    encode_numslof_zlib,
+)
+from .raw import decode_zlib_raw, encode_zlib_raw
+
+
+class Codec(Protocol):
+    def encode(self, data: np.ndarray, fp: float | None) -> bytes: ...
+    def decode(self, blob: bytes) -> np.ndarray: ...
+
+
+class _NumLinZlibCodec:
+    def encode(self, data: np.ndarray, fp: float | None) -> bytes:
+        return encode_numlin_zlib(data, fp)
+
+    def decode(self, blob: bytes) -> np.ndarray:
+        return decode_numlin_zlib(blob)
+
+
+class _NumSlofZlibCodec:
+    def encode(self, data: np.ndarray, fp: float | None) -> bytes:
+        return encode_numslof_zlib(data, fp)
+
+    def decode(self, blob: bytes) -> np.ndarray:
+        return decode_numslof_zlib(blob)
+
+
+class _NumPicZlibCodec:
+    def encode(self, data: np.ndarray, fp: float | None) -> bytes:
+        return encode_numpic_zlib(data, fp)
+
+    def decode(self, blob: bytes) -> np.ndarray:
+        return decode_numpic_zlib(blob)
+
+
+class _ZlibRawCodec:
+    def encode(self, data: np.ndarray, fp: float | None) -> bytes:
+        return encode_zlib_raw(data)
+
+    def decode(self, blob: bytes) -> np.ndarray:
+        return decode_zlib_raw(blob)
+
+
+_REGISTRY: dict[int, Codec] = {
+    COMP_NUMLIN_ZLIB: _NumLinZlibCodec(),
+    COMP_NUMSLOF_ZLIB: _NumSlofZlibCodec(),
+    COMP_NUMPIC_ZLIB: _NumPicZlibCodec(),
+    COMP_ZLIB: _ZlibRawCodec(),
+}
+
+
+def get_codec(comp_tail: int) -> Codec:
+    """Return the codec for a given compression accession tail.
+
+    Raises KeyError if the tail is not registered.
+    """
+    if comp_tail not in _REGISTRY:
+        raise KeyError(f"No codec registered for compression tail {comp_tail}.")
+    return _REGISTRY[comp_tail]

spectrl/codecs/numpress.py

@@ -0,0 +1,73 @@
+"""MS-Numpress + zlib codec wrappers over pynumpress."""
+
+import struct
+import zlib
+
+import numpy as np
+import pynumpress
+
+DEFAULT_NUMLIN_FP = 100000.0  # ~0.1 mDa precision for m/z
+# SLOF fp must satisfy: log(max_intensity + 1) * fp <= 65535 (uint16 max)
+# Use 3600.0 which handles intensities up to ~8e7; clip to safe value if data is larger.
+_SLOF_UINT16_MAX = 65535.0
+
+
+def _safe_slof_fp(data: np.ndarray, desired_fp: float) -> float:
+    """Return a slof fp that won't overflow uint16 given the array's max value."""
+    max_val = float(np.max(data)) if len(data) > 0 else 1.0
+    max_val = max(max_val, 1.0)
+    import math
+
+    max_fp = _SLOF_UINT16_MAX / (math.log(max_val + 1) + 1e-9)
+    return min(desired_fp, max_fp)
+
+
+DEFAULT_NUMSLOF_FP = 3600.0  # handles intensities up to ~8e7; adjusted dynamically if needed
+
+
+def encode_numlin_zlib(data: np.ndarray, fp: float | None = None) -> bytes:
+    """Encode array with MS-Numpress linear prediction then zlib."""
+    fp = fp if fp is not None else DEFAULT_NUMLIN_FP
+    encoded = pynumpress.encode_linear(data.astype(np.float64), fp)
+    return zlib.compress(encoded.tobytes())
+
+
+def decode_numlin_zlib(blob: bytes) -> np.ndarray:
+    """Decode MS-Numpress linear + zlib blob back to float64 array."""
+    decompressed = zlib.decompress(blob)
+    n = len(decompressed)
+    # pynumpress 0.0.9 cannot decode a single-value linear blob (12 bytes: 8-byte
+    # fixed point + one 4-byte int), though encode_linear emits exactly that. The
+    # MS-Numpress reference decodes it (dataSize == 12 → one value); do so directly
+    # to keep single-peak spectra round-trippable and cross-impl compatible.
+    if 12 <= n < 16:
+        fixed_point = struct.unpack(">d", decompressed[:8])[0]
+        first = int.from_bytes(decompressed[8:12], "little", signed=False)
+        return np.array([first / fixed_point], dtype=np.float64)
+    return np.array(pynumpress.decode_linear(np.frombuffer(decompressed, dtype=np.uint8)), dtype=np.float64)
+
+
+def encode_numslof_zlib(data: np.ndarray, fp: float | None = None) -> bytes:
+    """Encode array with MS-Numpress short logged float then zlib."""
+    desired = fp if fp is not None else DEFAULT_NUMSLOF_FP
+    safe_fp = _safe_slof_fp(data, desired)
+    encoded = pynumpress.encode_slof(data.astype(np.float64), safe_fp)
+    return zlib.compress(encoded.tobytes())
+
+
+def decode_numslof_zlib(blob: bytes) -> np.ndarray:
+    """Decode MS-Numpress slof + zlib blob back to float64 array."""
+    decompressed = zlib.decompress(blob)
+    return np.array(pynumpress.decode_slof(np.frombuffer(decompressed, dtype=np.uint8)), dtype=np.float64)
+
+
+def encode_numpic_zlib(data: np.ndarray, fp: float | None = None) -> bytes:
+    """Encode array with MS-Numpress positive integer then zlib."""
+    encoded = pynumpress.encode_pic(data.astype(np.float64))
+    return zlib.compress(encoded.tobytes())
+
+
+def decode_numpic_zlib(blob: bytes) -> np.ndarray:
+    """Decode MS-Numpress pic + zlib blob back to float64 array."""
+    decompressed = zlib.decompress(blob)
+    return np.array(pynumpress.decode_pic(np.frombuffer(decompressed, dtype=np.uint8)), dtype=np.float64)

spectrl/codecs/raw.py

@@ -0,0 +1,17 @@
+"""Lossless IEEE-754 little-endian + zlib codec."""
+
+import zlib
+
+import numpy as np
+
+
+def encode_zlib_raw(data: np.ndarray) -> bytes:
+    """Encode array as little-endian float64 + zlib."""
+    raw = data.astype("<f8").tobytes()
+    return zlib.compress(raw)
+
+
+def decode_zlib_raw(blob: bytes) -> np.ndarray:
+    """Decode zlib-compressed little-endian float64 bytes back to array."""
+    raw = zlib.decompress(blob)
+    return np.frombuffer(raw, dtype="<f8").astype(np.float64)

spectrl/cv.py

@@ -0,0 +1,117 @@
+"""CV accession ↔ integer-tail mapping using mzmlpy's StrEnum constants.
+
+Rules (§3.1):
+- Accession tails default to MS: ontology.
+- Unit tails default to UO: ontology.
+- Any other ontology uses an explicit [ontology_id, tail] pair.
+
+The tail for "MS:1000511" is 1000511; for "UO:0000031" is 31.
+"""
+
+from __future__ import annotations
+
+from mzmlpy.constants import (
+    BinaryDataArrayAccession,
+    BinaryDataTypeAccession,
+    CollisionDissociationTypeAccession,
+    CompressionTypeAccessions,
+    ScanPolarity,
+    SpectrumCombinationAccession,
+    SpectrumMSAccession,
+    SpectrumType,
+)
+
+_DEFAULT_PARAM_ONTOLOGY = "MS"
+_DEFAULT_UNIT_ONTOLOGY = "UO"
+
+
+def accession_tail(accession: str) -> int:
+    """Extract the integer tail from an accession string like 'MS:1000511' → 1000511."""
+    return int(accession.split(":")[1])
+
+
+def accession_ontology(accession: str) -> str:
+    """Extract the ontology prefix from 'MS:1000511' → 'MS'."""
+    return accession.split(":")[0]
+
+
+def encode_tail(accession: str) -> int:
+    """Encode an accession to its tail integer (assumes MS: default ontology)."""
+    return accession_tail(accession)
+
+
+def encode_unit(unit_accession: str) -> int | list:
+    """Encode a unit accession to a tail int (UO: default) or [ontology, tail] for other ontologies."""
+    onto = accession_ontology(unit_accession)
+    tail = accession_tail(unit_accession)
+    if onto == _DEFAULT_UNIT_ONTOLOGY:
+        return tail
+    return [onto, tail]
+
+
+def decode_tail(tail: int, ontology: str = _DEFAULT_PARAM_ONTOLOGY) -> str:
+    """Reconstruct an accession string from a tail integer and ontology prefix."""
+    return f"{ontology}:{tail:07d}"
+
+
+def decode_unit_tail(tail: int | list) -> str:
+    """Reconstruct a unit accession string from a tail (int = UO: default, list = [ontology, tail])."""
+    if isinstance(tail, list):
+        return f"{tail[0]}:{tail[1]:07d}"
+    return f"{_DEFAULT_UNIT_ONTOLOGY}:{tail:07d}"
+
+
+# ─── Codec compression tails (used by codecs module) ───────────────────────
+
+COMP_NUMLIN_ZLIB = accession_tail(CompressionTypeAccessions.MS_NUMPRESS_LINEAR_PREDICTION_ZLIB)
+COMP_NUMSLOF_ZLIB = accession_tail(CompressionTypeAccessions.MS_NUMPRESS_SHORT_LOGGED_FLOAT_ZLIB)
+COMP_NUMPIC_ZLIB = accession_tail(CompressionTypeAccessions.MS_NUMPRESS_POSITIVE_INTEGER_ZLIB)
+COMP_NUMLIN = accession_tail(CompressionTypeAccessions.MS_NUMPRESS_LINEAR_PREDICTION)
+COMP_NUMSLOF = accession_tail(CompressionTypeAccessions.MS_NUMPRESS_SHORT_LOGGED_FLOAT)
+COMP_NUMPIC = accession_tail(CompressionTypeAccessions.MS_NUMPRESS_POSITIVE_INTEGER)
+COMP_ZLIB = accession_tail(CompressionTypeAccessions.ZLIB_COMPRESSION)
+COMP_NONE = accession_tail(CompressionTypeAccessions.NO_COMPRESSION)
+
+# ─── Data type tails ────────────────────────────────────────────────────────
+
+TYPE_FLOAT64 = accession_tail(BinaryDataTypeAccession.FLOAT_64)
+TYPE_FLOAT32 = accession_tail(BinaryDataTypeAccession.FLOAT_32)
+TYPE_INT32 = accession_tail(BinaryDataTypeAccession.INT_32)
+TYPE_INT64 = accession_tail(BinaryDataTypeAccession.INT_64)
+
+# ─── Array type tails ───────────────────────────────────────────────────────
+
+ARRAY_MZ = accession_tail(BinaryDataArrayAccession.MZ)
+ARRAY_INTENSITY = accession_tail(BinaryDataArrayAccession.INTENSITY)
+ARRAY_CHARGE = accession_tail(BinaryDataArrayAccession.CHARGE)
+
+# Ion mobility array tails
+ION_MOBILITY_ARRAY_TAILS: dict[str, int] = {
+    acc: accession_tail(acc)
+    for acc in (
+        BinaryDataArrayAccession.RAW_ION_MOBILITY,
+        BinaryDataArrayAccession.MEAN_ION_MOBILITY_DRIFT_TIME,
+        BinaryDataArrayAccession.DECONVOLUTED_ION_MOBILITY_DRIFT_TIME,
+        BinaryDataArrayAccession.MEAN_INVERSE_REDUCED_ION_MOBILITY,
+        BinaryDataArrayAccession.MEAN_ION_MOBILITY,
+        BinaryDataArrayAccession.DECONVOLUTED_INVERSE_REDUCED_ION_MOBILITY,
+        BinaryDataArrayAccession.RAW_ION_MOBILITY_DRIFT_TIME,
+        BinaryDataArrayAccession.RAW_INVERSE_REDUCED_ION_MOBILITY,
+        BinaryDataArrayAccession.ION_MOBILITY,
+    )
+}
+
+# ─── Known accession registry for validation/tests ──────────────────────────
+
+ALL_MZX_ACCESSIONS: set[str] = set()
+for _enum in (
+    BinaryDataArrayAccession,
+    BinaryDataTypeAccession,
+    CompressionTypeAccessions,
+    ScanPolarity,
+    SpectrumCombinationAccession,
+    SpectrumMSAccession,
+    SpectrumType,
+    CollisionDissociationTypeAccession,
+):
+    ALL_MZX_ACCESSIONS.update(str(v) for v in _enum)