quantized-lab 0.8.0__py3-none-any.whl

quantized/routes/_payload.py

@@ -0,0 +1,58 @@
+"""Wire-serialization helpers for the route layer.
+
+The pure DataStruct keeps NaN/Inf (they're real in scientific data); valid wire
+JSON has no representation for them, so the HTTP boundary maps non-finite floats
+to ``null`` (which uPlot renders as a gap). Lives in routes/ — it's transport,
+not domain.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+__all__ = ["jsonify", "datastruct_payload", "to_jsonable"]
+
+
+def jsonify(arr: NDArray[np.float64]) -> list[Any]:
+    """ndarray -> JSON-safe (nested) list; non-finite floats -> ``None``."""
+    obj = arr.astype(object)
+    obj[~np.isfinite(arr)] = None
+    return obj.tolist()  # type: ignore[no-any-return]
+
+
+def to_jsonable(obj: Any) -> Any:
+    """Recursively make a calc result JSON-safe.
+
+    Calc functions return dicts/tuples that may nest ndarrays and non-finite
+    floats (real in scientific data, illegal in wire JSON). Arrays of floats go
+    through ``jsonify`` (non-finite -> ``None``); numpy scalars unwrap to Python
+    scalars; nested dicts/lists/tuples recurse. Lives in routes/ — transport.
+    """
+    if isinstance(obj, np.ndarray):
+        return jsonify(obj) if obj.dtype.kind == "f" else obj.tolist()
+    if isinstance(obj, np.generic):
+        obj = obj.item()
+    if isinstance(obj, float):
+        return obj if math.isfinite(obj) else None
+    if isinstance(obj, dict):
+        return {k: to_jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [to_jsonable(v) for v in obj]
+    return obj
+
+
+def datastruct_payload(ds: DataStruct) -> dict[str, Any]:
+    """DataStruct -> JSON-safe dict for the import response."""
+    return {
+        "time": jsonify(ds.time),
+        "values": jsonify(ds.values),
+        "labels": list(ds.labels),
+        "units": list(ds.units),
+        "metadata": dict(ds.metadata),
+    }

quantized/routes/_uploadcache.py

@@ -0,0 +1,59 @@
+"""Bounded, on-disk staging for multi-book Origin project uploads (lazy
+per-book transport, ``ORIGIN_FILE_DECODE_PLAN`` #38).
+
+``/api/parsers/upload``'s ordinary path stages the file in an ephemeral
+``tempfile.TemporaryDirectory`` that is deleted before the response returns --
+fine for a one-shot full import, but a lazy import needs the bytes to survive
+until the browser later activates a non-primary book and fetches its full
+data (``routes/books.py``). Origin project uploads are staged here instead: a
+stable temp path plus an opaque token the frontend echoes back on that fetch.
+
+Bounded to the last few uploads (LRU eviction, by unlinking the oldest staged
+file once the count is exceeded) -- this is a single-user desktop tool, not a
+multi-tenant server, so keeping a handful of recent uploads on disk is cheap
+and avoids unbounded growth from repeated re-imports.
+"""
+
+from __future__ import annotations
+
+import secrets
+import tempfile
+from collections import OrderedDict
+from pathlib import Path
+
+__all__ = ["stage_upload", "resolve_upload_token"]
+
+_MAX_STAGED = 8
+_root = Path(tempfile.gettempdir()) / "qz_origin_uploads"
+_tokens: OrderedDict[str, Path] = OrderedDict()
+
+
+def stage_upload(name: str, content: bytes) -> tuple[Path, str]:
+    """Persist ``content`` under a fresh token's own subdirectory (so same-name
+    re-uploads never collide) and return ``(path, token)``. Evicts the oldest
+    staged upload once more than ``_MAX_STAGED`` are held."""
+    _root.mkdir(parents=True, exist_ok=True)
+    token = secrets.token_hex(8)
+    staged_dir = _root / token
+    staged_dir.mkdir(parents=True, exist_ok=True)
+    dest = staged_dir / name
+    dest.write_bytes(content)
+    _tokens[token] = dest
+    _tokens.move_to_end(token)
+    while len(_tokens) > _MAX_STAGED:
+        _, old_path = _tokens.popitem(last=False)
+        old_path.unlink(missing_ok=True)
+        try:
+            old_path.parent.rmdir()
+        except OSError:
+            pass  # not empty / already gone -- best-effort cleanup only
+    return dest, token
+
+
+def resolve_upload_token(token: str) -> Path | None:
+    """The staged file path for ``token``, or ``None`` if unknown, expired
+    (evicted), or the file has since been removed out-of-band."""
+    path = _tokens.get(token)
+    if path is None or not path.is_file():
+        return None
+    return path

quantized/routes/aggregate.py

@@ -0,0 +1,46 @@
+"""Thin dataset-algebra route. Wraps ``calc.aggregate.dataset_algebra``.
+
+Combine two posted datasets pointwise on A's x-grid (B interpolated). Validate,
+call the pure golden function, serialize — no math here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.aggregate import dataset_algebra
+from quantized.datastruct import DataStruct
+from quantized.routes._payload import datastruct_payload
+
+router = APIRouter(prefix="/api/aggregate", tags=["aggregate"])
+
+
+class AlgebraRequest(BaseModel):
+    dataset_a: dict[str, Any]
+    dataset_b: dict[str, Any]
+    operation: str
+    interp_method: str = "pchip"
+    channel_a: int = 0
+    channel_b: int = 0
+
+
+@router.post("/algebra")
+def algebra(req: AlgebraRequest) -> dict[str, Any]:
+    """Combine two datasets via A+B / A-B / A*B / A/B / (A-B)/(A+B)."""
+    try:
+        a = DataStruct.from_dict(req.dataset_a)
+        b = DataStruct.from_dict(req.dataset_b)
+        out = dataset_algebra(
+            a,
+            b,
+            req.operation,
+            interp_method=req.interp_method,
+            channel_a=req.channel_a,
+            channel_b=req.channel_b,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return datastruct_payload(out)

quantized/routes/baseline.py

@@ -0,0 +1,210 @@
+"""Thin baseline routes: estimate a slowly-varying background under a signal.
+
+Wraps ``calc.baseline`` + ``calc.backgrounds``. ALS / rolling-ball / modpoly
+operate on ``y`` alone; ``estimate`` (SNIP / polynomial), Shirley, the anchor
+baseline and the XRD low-angle model need ``x`` too. Methods with iteration
+state also return an ``info`` dict (chosen window / iteration count / coeffs).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.backgrounds import (
+    anchor_baseline,
+    shirley_background,
+    xrd_low_angle_background,
+)
+from quantized.calc.baseline import (
+    baseline_als,
+    baseline_modpoly,
+    baseline_rolling_ball,
+    estimate_background,
+    fit_region_background,
+)
+from quantized.routes._payload import jsonify, to_jsonable
+
+router = APIRouter(prefix="/api/baseline", tags=["baseline"])
+
+
+class EstimateRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    method: str = "snip"
+    max_window_deg: float = 2.0
+    smooth_passes: int = 3
+    poly_degree: int = 4
+    iterative: bool = False
+    iter_max_passes: int = 3
+    iter_sigma: float = 3.0
+
+
+class ALSRequest(BaseModel):
+    y: list[float]
+    lam: float = 1e6
+    p: float = 0.01
+    max_iter: int = 20
+    tol: float = 1e-6
+
+
+class RollingBallRequest(BaseModel):
+    y: list[float]
+    radius: int = 100
+    smooth: int = -1
+
+
+class ModPolyRequest(BaseModel):
+    y: list[float]
+    order: int = 5
+    max_iter: int = 100
+    tol: float = 1e-6
+
+
+class RegionBackgroundRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    x_min: float
+    x_max: float
+    y_min: float | None = None
+    y_max: float | None = None
+    order: int = 1
+
+
+class AnchorRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    anchors: list[list[float]]  # (x, y) pairs picked on the plot
+    method: str = "pchip"
+
+
+class ShirleyRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    max_iter: int = 50
+    tol: float = 1e-6
+    edge_average: int = 1
+
+
+class XrdLowAngleRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    include_x2: bool = True
+    max_iter: int = 100
+    tol: float = 1e-6
+
+
+@router.post("/estimate")
+def estimate(req: EstimateRequest) -> dict[str, Any]:
+    """SNIP / polynomial background, optionally peak-masked and refined."""
+    try:
+        bg = estimate_background(
+            req.x,
+            req.y,
+            method=req.method,
+            max_window_deg=req.max_window_deg,
+            smooth_passes=req.smooth_passes,
+            poly_degree=req.poly_degree,
+            iterative=req.iterative,
+            iter_max_passes=req.iter_max_passes,
+            iter_sigma=req.iter_sigma,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": jsonify(bg)}
+
+
+@router.post("/als")
+def als(req: ALSRequest) -> dict[str, Any]:
+    """Asymmetric least-squares (Eilers/Whittaker) baseline."""
+    try:
+        bg = baseline_als(
+            np.asarray(req.y, dtype=float),
+            lam=req.lam,
+            p=req.p,
+            max_iter=req.max_iter,
+            tol=req.tol,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": jsonify(bg)}
+
+
+@router.post("/rollingball")
+def rollingball(req: RollingBallRequest) -> dict[str, Any]:
+    """Rolling-ball (grayscale morphological opening) baseline."""
+    try:
+        bg, info = baseline_rolling_ball(req.y, radius=req.radius, smooth=req.smooth)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": jsonify(bg), "info": to_jsonable(info)}
+
+
+@router.post("/modpoly")
+def modpoly(req: ModPolyRequest) -> dict[str, Any]:
+    """Modified-polynomial (Lieber) baseline."""
+    try:
+        bg, info = baseline_modpoly(
+            req.y, order=req.order, max_iter=req.max_iter, tol=req.tol
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": jsonify(bg), "info": to_jsonable(info)}
+
+
+@router.post("/anchor")
+def anchor(req: AnchorRequest) -> dict[str, Any]:
+    """Baseline through user-picked (x, y) anchors (GOTO #2); extrapolation
+    clamps to the end anchors."""
+    try:
+        bg = anchor_baseline(req.x, req.y, req.anchors, method=req.method)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": jsonify(bg)}
+
+
+@router.post("/shirley")
+def shirley(req: ShirleyRequest) -> dict[str, Any]:
+    """Iterative Shirley step background (GOTO #3). Non-convergence is a 422
+    (the calc raises ValueError), never a 500."""
+    try:
+        bg, info = shirley_background(
+            req.x, req.y, max_iter=req.max_iter, tol=req.tol,
+            edge_average=req.edge_average,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": jsonify(bg), "info": to_jsonable(info)}
+
+
+@router.post("/xrdlowangle")
+def xrd_low_angle(req: XrdLowAngleRequest) -> dict[str, Any]:
+    """Hyperbolic (One_on_X) low-angle air-scatter background (GOTO #7a)."""
+    try:
+        bg, info = xrd_low_angle_background(
+            req.x, req.y, include_x2=req.include_x2,
+            max_iter=req.max_iter, tol=req.tol,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"baseline": jsonify(bg), "info": to_jsonable(info)}
+
+
+@router.post("/region")
+def region(req: RegionBackgroundRequest) -> dict[str, Any]:
+    """Fit a polynomial background from a boxed x/y region (BosonPlotter
+    "Fit BG from Box"); returns coeffs + the full-range background + region stats."""
+    try:
+        result = fit_region_background(
+            req.x, req.y, req.x_min, req.x_max,
+            y_min=req.y_min, y_max=req.y_max, order=req.order,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    bg = result.pop("background")
+    out: dict[str, Any] = to_jsonable(result)
+    out["background"] = jsonify(bg)
+    return out

quantized/routes/books.py

@@ -0,0 +1,117 @@
+"""Thin route: fetch one Origin book's full data on demand (lazy per-book
+transport, ORIGIN_FILE_DECODE_PLAN #38).
+
+``/api/parsers/import``/``upload`` return the primary book's full data plus a
+lightweight inventory + preview for every OTHER book
+(``routes.parsers._import_with_books``'s default, non-``full_books`` path).
+This route is where the frontend's first activation of one of those other
+books fetches its full ``DataStruct``. A cache hit (the common case — the
+import route already parsed the whole project and primed ``_bookcache`` with
+the SAME book list) is a plain dict lookup; a miss (server restart, cache
+eviction, or a book requested well after the cache's LRU bound was exceeded)
+re-parses the source file once and re-primes the cache.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.io.origin_project import (
+    OriginProjectError,
+    drop_empty_library_books,
+    read_origin_project_all,
+)
+from quantized.routes._bookcache import cache_project_books, get_cached_book
+from quantized.routes._uploadcache import resolve_upload_token
+from quantized.routes.parsers import _allowed_roots, _book_payload
+
+router = APIRouter(prefix="/api/parsers", tags=["parsers"])
+
+
+class BookDataRequest(BaseModel):
+    book_id: str
+    # Exactly one of these — mirrors the two ways a project got imported
+    # (routes.parsers._book_source_ref): a path /import already validated, or
+    # an /upload's staged-file token (_uploadcache).
+    path: str | None = None
+    token: str | None = None
+
+
+def _resolve_book_path(raw_path: str) -> Path:
+    """The SAME realpath+commonpath containment guard as
+    ``routes.parsers.import_file`` (reusing its ``_allowed_roots``), kept
+    inline here rather than factored into a shared function that both routes
+    call: that function's own docstring notes the guard is deliberately
+    inline so static analysis (CodeQL) can see the taint→sink path sit
+    entirely within one function body — the same reasoning applies here.
+    """
+    try:
+        resolved = os.path.realpath(raw_path)
+    except (OSError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail="invalid path") from exc
+    within_allowed = False
+    for root in _allowed_roots():
+        try:
+            if os.path.commonpath((root, resolved)) == root:
+                within_allowed = True
+                break
+        except ValueError:
+            continue  # different drives (Windows) -> not under this root
+    if not within_allowed:
+        raise HTTPException(
+            status_code=403,
+            detail="path is outside the allowed roots (set QZ_DATA_ROOTS to widen)",
+        )
+    if not os.path.isfile(resolved):
+        raise HTTPException(status_code=404, detail=f"file not found: {raw_path}")
+    return Path(resolved)
+
+
+@router.post("/books/data")
+def book_data(req: BookDataRequest) -> dict[str, Any]:
+    """One book's full DataStruct payload, by the id + source reference an
+    import response's ``book_source``/lazy inventory entry gave the caller."""
+    if not req.book_id:
+        raise HTTPException(status_code=400, detail="book_id is required")
+    if bool(req.path) == bool(req.token):
+        raise HTTPException(
+            status_code=400, detail="exactly one of path or token is required"
+        )
+
+    if req.token:
+        resolved = resolve_upload_token(req.token)
+        if resolved is None:
+            raise HTTPException(
+                status_code=404,
+                detail="upload expired — re-import the file to fetch this book",
+            )
+    else:
+        assert req.path is not None
+        resolved = _resolve_book_path(req.path)
+
+    cached = get_cached_book(resolved, req.book_id)
+    if cached is not None:
+        return _book_payload(cached)
+
+    # Cache miss: re-parse once and re-prime the cache for any sibling books
+    # activated next.
+    try:
+        raw = resolved.read_bytes()
+        _primary, all_books = read_origin_project_all(resolved, raw=raw)
+    except (OriginProjectError, ValueError, KeyError, struct.error, OSError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    books = drop_empty_library_books(all_books)
+    cache_project_books(resolved, books)
+    match = next(
+        (b for b in books if str(b.metadata.get("origin_book", "")) == req.book_id),
+        None,
+    )
+    if match is None:
+        raise HTTPException(status_code=404, detail=f"book not found: {req.book_id}")
+    return _book_payload(match)

quantized/routes/calc.py

@@ -0,0 +1,56 @@
+"""Thin headless-calculator routes — an HTTP surface for the calc registry.
+
+Exposes the same discoverable, name-addressed calculator catalog as
+``calc.registry`` (the DiraCulator headless API) over HTTP: list the operations,
+describe one's parameters, or invoke one by name with a params dict. Validate →
+call the pure registry → JSON-serialize. No business logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from quantized.calc.registry import call_calculator, describe_calculator, list_calculators
+from quantized.routes._payload import to_jsonable
+
+router = APIRouter(prefix="/api/calc", tags=["calc"])
+
+
+class CallRequest(BaseModel):
+    name: str
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+def _detail(exc: Exception) -> str:
+    """Clean message text (KeyError.__str__ wraps its arg in quotes)."""
+    return str(exc.args[0]) if exc.args else str(exc)
+
+
+@router.get("/catalog")
+def catalog(domain: str | None = None) -> dict[str, Any]:
+    """List calculator operations (``{name, domain, summary}``); optionally one domain."""
+    return {"calculators": list_calculators(domain)}
+
+
+@router.get("/describe/{name}")
+def describe(name: str) -> dict[str, Any]:
+    """Describe one operation: name, domain, summary, and its signature params."""
+    try:
+        return describe_calculator(name)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=_detail(exc)) from exc
+
+
+@router.post("/call")
+def call(req: CallRequest) -> dict[str, Any]:
+    """Invoke a calculator by name with a params dict; JSON-serialize the result."""
+    try:
+        result = call_calculator(req.name, req.params)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=_detail(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=_detail(exc)) from exc
+    return {"name": req.name, "result": to_jsonable(result)}

quantized/routes/corrections.py

@@ -0,0 +1,78 @@
+"""Thin corrections route: DataStruct + params -> corrected DataStruct.
+
+Validate, call ``calc.corrections.apply_corrections`` (the pure 8-step pipeline),
+serialize. No algorithms here — the math lives in calc/. The request ``params``
+mirror the MATLAB ``correctionParams`` struct (camelCase on the wire); the typed
+model below is the API contract and is dumped back to that exact key set.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, ConfigDict, Field
+
+from quantized.calc.corrections import apply_corrections
+from quantized.datastruct import DataStruct
+from quantized.routes._payload import datastruct_payload
+
+router = APIRouter(prefix="/api/corrections", tags=["corrections"])
+
+
+class CorrectionParams(BaseModel):
+    """Correction-pipeline parameters (all optional; mirror MATLAB ``params``).
+
+    Wire names are camelCase (aliases); unset fields are dropped so the calc
+    layer falls back to its own defaults (e.g. NaN ``xTrim*`` = no trim).
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    x_off: float | None = Field(default=None, alias="xOff")
+    y_off: float | None = Field(default=None, alias="yOff")
+    bg_slope: float | None = Field(default=None, alias="bgSlope")
+    bg_int: float | None = Field(default=None, alias="bgInt")
+    bg_poly: list[float] | None = Field(default=None, alias="bgPoly")
+    x_trim_min: float | None = Field(default=None, alias="xTrimMin")
+    x_trim_max: float | None = Field(default=None, alias="xTrimMax")
+    is_neutron: bool | None = Field(default=None, alias="isNeutron")
+    is_mag: bool | None = Field(default=None, alias="isMag")
+    field_unit: str | None = Field(default=None, alias="fieldUnit")
+    moment_unit: str | None = Field(default=None, alias="momentUnit")
+    sample_mass: float | None = Field(default=None, alias="sampleMass")
+    sample_volume: float | None = Field(default=None, alias="sampleVolume")
+    smooth_enabled: bool | None = Field(default=None, alias="smoothEnabled")
+    smooth_window: int | None = Field(default=None, alias="smoothWindow")
+    smooth_method: str | None = Field(default=None, alias="smoothMethod")
+    norm_method: str | None = Field(default=None, alias="normMethod")
+    derivative_mode: str | None = Field(default=None, alias="derivativeMode")
+    # GOTO additions (new features beyond MATLAB parity):
+    # #2 anchor-point baseline subtraction ((x, y) pairs + interp method).
+    bg_anchors: list[list[float]] | None = Field(default=None, alias="bgAnchors")
+    bg_anchor_method: str | None = Field(default=None, alias="bgAnchorMethod")
+    # #7b XRR/NR beam-footprint correction (beam width / sample length share
+    # one length unit; footprintTwoTheta reads x as the detector angle 2theta).
+    footprint_w: float | None = Field(default=None, alias="footprintW")
+    footprint_l: float | None = Field(default=None, alias="footprintL")
+    footprint_two_theta: bool | None = Field(default=None, alias="footprintTwoTheta")
+
+
+class CorrectionsRequest(BaseModel):
+    dataset: dict[str, Any]
+    params: CorrectionParams = Field(default_factory=CorrectionParams)
+    bg_dataset: dict[str, Any] | None = None
+    bg_interp: str = "linear"
+
+
+@router.post("/apply")
+def apply(req: CorrectionsRequest) -> dict[str, Any]:
+    """Apply the correction pipeline to a posted DataStruct."""
+    try:
+        ds = DataStruct.from_dict(req.dataset)
+        bg = DataStruct.from_dict(req.bg_dataset) if req.bg_dataset else None
+        params = req.params.model_dump(by_alias=True, exclude_none=True)
+        out = apply_corrections(ds, params, bg_dataset=bg, bg_interp=req.bg_interp)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return datastruct_payload(out)