quantized-lab 0.8.0__py3-none-any.whl

quantized/__init__.py

@@ -0,0 +1,11 @@
+"""quantized — Python backend for the quantized toolbox port.
+
+Layered, enforced architecture (see CLAUDE.md):
+  - ``datastruct`` + ``io`` + ``calc`` are pure libraries (no web imports).
+  - ``routes`` are thin FastAPI adapters.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.7.0"
+__all__ = ["__version__"]

quantized/__main__.py

@@ -0,0 +1,14 @@
+"""Enable ``python -m quantized`` → runs the ``qz`` CLI.
+
+The Tauri desktop shell's dev fallback spawns the server as
+``python -m quantized --no-browser`` (so ``kill()`` reaches uvicorn directly,
+not an orphaned launcher). Keeping this module trivial means the entry point
+stays stable regardless of how ``cli.main`` evolves.
+"""
+
+from __future__ import annotations
+
+from quantized.cli import main
+
+if __name__ == "__main__":
+    main()

quantized/api.py

@@ -0,0 +1,220 @@
+"""``quantized`` headless public API — drive the analysis engine from code.
+
+ORIGIN_GAP_PLAN #9. Everything the app does to your data is a pure function you
+can call from a script, notebook, or CI job — no GUI, no server, cross-platform.
+This is the differentiator Origin structurally can't match: *analysis is code*.
+
+This module is the **blessed, stable surface**. Names here are frozen — a
+rename or removal breaks ``tests/test_public_api.py`` on purpose. The
+underlying modules (``quantized.calc.*`` / ``quantized.io.*``) may reorganize;
+import from here to stay insulated.
+
+Example — load a scan, integrate a peak, build a report, render it::
+
+    import numpy as np
+    import quantized.api as qz
+
+    data = qz.load("scan.xy")                     # any registered format -> DataStruct
+    x, y = data.time, data.column(0)
+
+    result = qz.integrate_peaks(x, y, [(28.0, 32.0)])   # net area / centroid / FWHM
+    fit = qz.fit_single_peak(x, y, 28.0, 32.0, seed_center=30.0, model="Gaussian")
+
+    report = qz.from_stats_table(
+        [{"region": "111", **result["peaks"][0]}], title="Peak integration"
+    )
+    open("report.html", "w").write(qz.to_html(report.to_dict()))
+    pdf = qz.render_figure(x, [("intensity", y)], fmt="pdf")   # publication vector
+
+Note: importing this module pulls in matplotlib (for the render helpers), so it
+is heavier than ``import quantized``; the FastAPI server never imports it.
+"""
+
+from __future__ import annotations
+
+# ── Data contract + file loading ──────────────────────────────────────────
+from quantized.calc.backgrounds import (
+    anchor_baseline,
+    footprint_correction,
+    shirley_background,
+    xrd_low_angle_background,
+)
+from quantized.calc.baseline import (
+    baseline_als,
+    baseline_modpoly,
+    baseline_rolling_ball,
+    estimate_background,
+    fit_region_background,
+)
+
+# ── Corrections ────────────────────────────────────────────────────────────
+from quantized.calc.corrections import apply_corrections
+
+# ── Publication rendering (matplotlib) ─────────────────────────────────────
+from quantized.calc.figure import render_figure
+from quantized.calc.figure_map import render_map_figure
+from quantized.calc.figure_statplots import render_statplot_figure
+
+# ── Curve & peak fitting ───────────────────────────────────────────────────
+from quantized.calc.fitting import curve_fit
+from quantized.calc.peak_batch import batch_integrate_peaks
+from quantized.calc.peak_fit import fit_single_peak
+from quantized.calc.peak_integrate import integrate_peaks
+from quantized.calc.peak_multifit import fit_multi_peak
+from quantized.calc.peaks import find_peaks_robust
+
+# ── Reporting ──────────────────────────────────────────────────────────────
+from quantized.calc.report import (
+    ReportSheet,
+    figure_block,
+    params_block,
+    section,
+    source_ref,
+    table_block,
+    text_block,
+    validate_report,
+)
+from quantized.calc.report_emit import (
+    from_anova,
+    from_batch_integrate,
+    from_curve_fit,
+    from_integrate,
+    from_multipeak_fit,
+    from_stats_table,
+)
+
+# ── Statistical plots ──────────────────────────────────────────────────────
+from quantized.calc.statplots import (
+    box_stats,
+    grouped_box_stats,
+    histogram,
+    qq_plot,
+    violin_kde,
+)
+
+# ── Statistics ─────────────────────────────────────────────────────────────
+from quantized.calc.stats import (
+    anova1,
+    descriptive_stats,
+    lin_regress,
+    pca_analysis,
+    t_test,
+)
+from quantized.calc.stats_anova2 import anova2, dunnett_test, tukey_hsd
+from quantized.calc.stats_anova_ext import anova2_unbalanced, repeated_measures_anova
+from quantized.calc.stats_dist import fit_distribution, required_n, t_test_power
+from quantized.calc.stats_multivar import (
+    correlation_matrix,
+    multiple_regression,
+    partial_correlation,
+    stepwise_regression,
+)
+from quantized.calc.stats_tests import (
+    anderson_darling,
+    friedman,
+    kruskal_wallis,
+    ks_normal,
+    ks_two_sample,
+    levene,
+    mann_whitney,
+    recommend_test,
+    shapiro_wilk,
+    sign_test,
+    wilcoxon_signed_rank,
+)
+from quantized.datastruct import DataStruct
+from quantized.io.registry import import_auto as load
+from quantized.io.report_export import (
+    format_value_error,
+    render_report,
+    to_html,
+    to_latex,
+)
+
+__all__ = [
+    # data + I/O
+    "DataStruct",
+    "load",
+    # fitting
+    "curve_fit",
+    "fit_single_peak",
+    "fit_multi_peak",
+    "find_peaks_robust",
+    "integrate_peaks",
+    "batch_integrate_peaks",
+    # baseline
+    "estimate_background",
+    "fit_region_background",
+    "baseline_als",
+    "baseline_modpoly",
+    "baseline_rolling_ball",
+    # backgrounds (GOTO #2/#3/#7 — new beyond MATLAB parity)
+    "anchor_baseline",
+    "shirley_background",
+    "xrd_low_angle_background",
+    "footprint_correction",
+    # corrections
+    "apply_corrections",
+    # statistics — core
+    "descriptive_stats",
+    "lin_regress",
+    "t_test",
+    "anova1",
+    "pca_analysis",
+    # statistics — multivariate
+    "multiple_regression",
+    "correlation_matrix",
+    "partial_correlation",
+    "stepwise_regression",
+    # statistics — designed experiments
+    "anova2",
+    "anova2_unbalanced",
+    "repeated_measures_anova",
+    "tukey_hsd",
+    "dunnett_test",
+    # statistics — nonparametric + assumptions
+    "mann_whitney",
+    "wilcoxon_signed_rank",
+    "kruskal_wallis",
+    "friedman",
+    "sign_test",
+    "shapiro_wilk",
+    "anderson_darling",
+    "levene",
+    "ks_normal",
+    "ks_two_sample",
+    "recommend_test",
+    # statistics — distributions + power
+    "fit_distribution",
+    "t_test_power",
+    "required_n",
+    # statistical plots
+    "box_stats",
+    "grouped_box_stats",
+    "violin_kde",
+    "qq_plot",
+    "histogram",
+    # reporting
+    "ReportSheet",
+    "section",
+    "text_block",
+    "table_block",
+    "params_block",
+    "figure_block",
+    "source_ref",
+    "validate_report",
+    "from_curve_fit",
+    "from_multipeak_fit",
+    "from_anova",
+    "from_stats_table",
+    "from_integrate",
+    "from_batch_integrate",
+    # export / rendering
+    "render_figure",
+    "render_map_figure",
+    "render_statplot_figure",
+    "render_report",
+    "to_latex",
+    "to_html",
+    "format_value_error",
+]

quantized/app.py

@@ -0,0 +1,206 @@
+"""FastAPI application factory for quantized.
+
+Thin transport layer only — business logic lives in ``calc/`` and ``io/``.
+Composes the per-domain routers; each router is a thin adapter.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from urllib.parse import urlparse
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from quantized import __version__
+from quantized.plugins import load_plugins
+from quantized.routes import (
+    aggregate,
+    baseline,
+    books,
+    calc,
+    corrections,
+    crystallography,
+    diffusion,
+    electrical,
+    electrochemistry,
+    export,
+    export_facets,
+    export_figures,
+    export_page,
+    fitting,
+    fitting_bumps,
+    import_template,
+    import_wizard,
+    jobs_api,
+    magnetic,
+    magnetometry,
+    optics,
+    parsers,
+    peaks,
+    plot,
+    reductions,
+    reference,
+    reflectivity,
+    report_export,
+    rsm,
+    samples,
+    semiconductor,
+    sld,
+    spectral,
+    statplots,
+    stats,
+    stats_design,
+    substrates,
+    superconductor,
+    thermal,
+    thin_film,
+    vacuum,
+    xray,
+)
+
+__all__ = ["create_app", "app"]
+
+# Built SPA (vite build → src/quantized/web/). A build artifact, gitignored;
+# present in packaged/installed runs, absent in a bare dev checkout.
+#
+# One resolution serves both cases: Path(__file__).parent always points at
+# wherever the ``quantized`` package itself lives, so a PyPI/pipx install
+# (the built wheel bundles ``web/`` alongside app.py — see
+# [tool.hatch.build.targets.wheel] artifacts in pyproject.toml and the
+# "build frontend first" step in README.md) and a dev checkout that has run
+# ``npm run build`` resolve to the same relative path with no branching.
+_WEB_DIR = Path(__file__).parent / "web"
+
+# ── Desktop-style lifecycle (client presence over /api/ws) ──────────────────
+# The SPA holds a WebSocket open; the status bar's connected dot reflects it.
+# Auto-shutdown on last-tab-close is opt-in (env QZ_AUTO_SHUTDOWN=1, for the
+# future `qz --desktop` run model) so dev/tests are never killed.
+_clients = 0
+_ever_connected = False
+_AUTO_SHUTDOWN = os.environ.get("QZ_AUTO_SHUTDOWN") == "1"
+_SHUTDOWN_GRACE_S = 1.5  # tab refresh disconnects + reconnects within ~1 s
+
+
+def _origin_allowed(origin: str) -> bool:
+    """Allow same-machine origins only (the WS upgrade bypasses CORS)."""
+    host = urlparse(origin).hostname
+    return host in {"127.0.0.1", "localhost", "::1"}
+
+
+async def _lifecycle_ws(ws: WebSocket) -> None:
+    """Client-presence socket: count live tabs; (optionally) shut down when the
+    last one drops past a refresh-safe grace window. Module-level to keep
+    create_app simple."""
+    global _clients, _ever_connected
+    origin = ws.headers.get("origin")
+    if origin and not _origin_allowed(origin):
+        await ws.close(code=1008)  # policy violation
+        return
+    await ws.accept()
+    _clients += 1
+    _ever_connected = True
+    try:
+        while True:
+            await ws.receive_text()  # idles until disconnect
+    except WebSocketDisconnect:
+        pass
+    finally:
+        _clients -= 1
+        if _AUTO_SHUTDOWN and _clients == 0:
+            asyncio.get_running_loop().create_task(_grace_check())
+
+
+async def _grace_check() -> None:
+    """Exit unless a client reconnected within the grace window."""
+    await asyncio.sleep(_SHUTDOWN_GRACE_S)
+    if _AUTO_SHUTDOWN and _ever_connected and _clients == 0:
+        os._exit(0)
+
+# Vite dev server origins (the SPA in --dev mode). Same-origin in production.
+_DEV_ORIGINS = ["http://localhost:5173", "http://127.0.0.1:5173"]
+
+
+def create_app() -> FastAPI:
+    """Build the FastAPI app and wire the domain routers."""
+    application = FastAPI(title="quantized", version=__version__)
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=_DEV_ORIGINS,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @application.get("/api/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok", "version": __version__}
+
+    application.include_router(parsers.router)
+    application.include_router(books.router)
+    application.include_router(samples.router)
+    application.include_router(import_wizard.router)
+    application.include_router(import_template.router)
+    application.include_router(plot.router)
+    application.include_router(corrections.router)
+    application.include_router(fitting.router)
+    application.include_router(fitting_bumps.router)
+    application.include_router(jobs_api.router)
+    application.include_router(baseline.router)
+    application.include_router(stats.router)
+    application.include_router(stats_design.router)
+    application.include_router(statplots.router)
+    application.include_router(reference.router)
+    application.include_router(export.router)
+    application.include_router(export_figures.router)
+    application.include_router(export_facets.router)
+    application.include_router(export_page.router)
+    application.include_router(report_export.router)
+    application.include_router(magnetometry.router)
+    application.include_router(peaks.router)
+    application.include_router(reductions.router)
+    application.include_router(reflectivity.router)
+    application.include_router(rsm.router)
+    application.include_router(xray.router)
+    application.include_router(sld.router)
+    application.include_router(spectral.router)
+    application.include_router(crystallography.router)
+    application.include_router(electrical.router)
+    application.include_router(optics.router)
+    application.include_router(vacuum.router)
+    application.include_router(thermal.router)
+    application.include_router(diffusion.router)
+    application.include_router(electrochemistry.router)
+    application.include_router(substrates.router)
+    application.include_router(semiconductor.router)
+    application.include_router(thin_film.router)
+    application.include_router(superconductor.router)
+    application.include_router(magnetic.router)
+    application.include_router(aggregate.router)
+    application.include_router(calc.router)
+
+    # Client-presence WebSocket (registered before the SPA mount so the
+    # catch-all StaticFiles route never shadows it).
+    application.websocket("/api/ws")(_lifecycle_ws)
+
+    # Load user/third-party plugins once (gap #8). Registration is isolated
+    # per-plugin and logged; a broken plugin never crashes startup. Cheap when
+    # none are installed (an empty dir scan + entry-point lookup). Fit-model /
+    # parser routes read the shared registries at request time, so plugin
+    # contributions are visible regardless of this call's position.
+    try:
+        load_plugins()
+    except Exception:  # pragma: no cover - load_plugins already isolates per-plugin
+        logging.getLogger("quantized.plugins").exception("plugin loading failed")
+
+    # Serve the built SPA at / when present (production / packaged runs). In a
+    # bare dev checkout the dir is absent and the Vite dev server serves the UI.
+    if _WEB_DIR.is_dir():
+        application.mount("/", StaticFiles(directory=_WEB_DIR, html=True), name="web")
+    return application
+
+
+app = create_app()

quantized/calc/__init__.py

@@ -0,0 +1,8 @@
+"""Pure calculation library: corrections, fitting, calculators, stats, plotting math.
+
+Pure layer — MUST NOT import fastapi / pydantic / starlette / quantized.routes
+(enforced by tests/test_repo_integrity.py). This is where parity with the
+MATLAB toolbox lives.
+"""
+
+from __future__ import annotations

quantized/calc/_clipfit.py

@@ -0,0 +1,76 @@
+"""Shared Lieber-Mahadevan-Jansen iterative clip-fit loop (MAIN #8c).
+
+:func:`quantized.calc.baseline.baseline_modpoly` and
+:func:`quantized.calc.backgrounds.xrd_low_angle_background` run the same
+iterative clip discipline (Lieber & Mahadevan-Jansen, Appl. Spectrosc. 57,
+1363 (2003)): fit a model to the working signal, clamp the signal to
+``min(signal, fit)``, and refit until the RMS change relative to the data
+range drops below tolerance. Only the model fit differs between the two —
+a polynomial in normalized sample index vs a linear least-squares solve on
+a hyperbolic basis — so the loop lives here ONCE, parameterized by the fit
+callable. The operation sequence (clip, RMS, ``rms / y_range < tol``
+convergence test, 1-based iteration count) is verbatim from both callers:
+``baseline_modpoly`` is golden-parity-tested against frozen MATLAB output,
+so this loop must stay bit-identical.
+
+Pure layer: ndarray in -> results out. No fastapi/pydantic imports.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import NamedTuple
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = ["ClipFitResult", "_iterative_clip_fit"]
+
+# One model fit over the current working signal: returns ``(coeffs, fit)``
+# where ``fit`` is the model evaluated on the full grid.
+FitFn = Callable[[NDArray[np.float64]], tuple[NDArray[np.float64], NDArray[np.float64]]]
+
+
+class ClipFitResult(NamedTuple):
+    """Final state of the clip-fit loop."""
+
+    coeffs: NDArray[np.float64]
+    fit: NDArray[np.float64]
+    n_iter: int
+    converged: bool
+
+
+def _iterative_clip_fit(
+    y: NDArray[np.float64],
+    fit_fn: FitFn,
+    *,
+    max_iter: int,
+    tol: float,
+    y_range: float,
+    init: tuple[NDArray[np.float64], NDArray[np.float64]],
+) -> ClipFitResult:
+    """Iteratively fit and clip the working signal to ``min(signal, fit)``.
+
+    Each iteration fits ``fit_fn`` to the working copy of ``y``, clamps the
+    copy to ``min(copy, fit)``, and stops (``converged=True``) once the RMS
+    of the clip step falls below ``tol * y_range``. ``init`` supplies the
+    ``(coeffs, fit)`` returned when the loop body never runs (``max_iter``
+    < 1) — callers preserve their exact pre-refactor initial state through
+    it (``baseline_modpoly`` a pre-loop polynomial fit,
+    ``xrd_low_angle_background`` zeros).
+    """
+    coeffs, fit = init
+    y_work = y.copy()
+    converged = False
+    n_iter = 0
+    for it in range(1, max_iter + 1):
+        n_iter = it
+        coeffs, fit = fit_fn(y_work)
+        y_new = np.asarray(np.minimum(y_work, fit), dtype=float)
+        rms = math.sqrt(float(np.mean((y_new - y_work) ** 2)))
+        y_work = y_new
+        if rms / y_range < tol:
+            converged = True
+            break
+    return ClipFitResult(coeffs, fit, n_iter, converged)