quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/report_emit.py

@@ -0,0 +1,227 @@
+"""Emitters: turn calc result dicts into :class:`ReportSheet`s (#36).
+
+Each analysis already returns a plain result dict; these functions map the
+known fields into the report schema (:mod:`quantized.calc.report`) so a fit,
+peak fit, or stats test lands as a structured report that the #37/#38
+exporters and the frontend viewer render uniformly. No new math — pure
+re-shaping.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from quantized.calc.report import (
+    ReportSheet,
+    params_block,
+    section,
+    table_block,
+    text_block,
+)
+
+__all__ = [
+    "from_anova",
+    "from_batch_integrate",
+    "from_curve_fit",
+    "from_integrate",
+    "from_multipeak_fit",
+    "from_stats_table",
+]
+
+
+def _gof_table(result: Mapping[str, Any], keys: Sequence[tuple[str, str]]) -> dict[str, Any]:
+    """A two-column goodness-of-fit table from selected result keys."""
+    rows = [[label, result[key]] for label, key in keys if result.get(key) is not None]
+    return table_block(["Metric", "Value"], rows, caption="Goodness of fit")
+
+
+def from_curve_fit(
+    result: Mapping[str, Any],
+    *,
+    param_names: Sequence[str],
+    param_units: Sequence[str] | None = None,
+    title: str = "Curve fit",
+    model_name: str | None = None,
+    source_refs: Sequence[Mapping[str, Any]] | None = None,
+) -> ReportSheet:
+    """Build a report from a ``calc.fitting`` result dict.
+
+    ``result`` carries ``params`` / ``errors`` arrays (whose order matches
+    ``param_names``) plus goodness-of-fit scalars (R2, chiSqRed, RMSE, AIC).
+    """
+    params = list(result.get("params", []))
+    errors = list(result.get("errors", []) or [None] * len(params))
+    units = list(param_units) if param_units is not None else [""] * len(params)
+    if len(param_names) != len(params):
+        raise ValueError(
+            f"param_names ({len(param_names)}) must match params ({len(params)})"
+        )
+    rows = [
+        {"name": param_names[i], "value": params[i],
+         "error": errors[i] if i < len(errors) else None,
+         "unit": units[i] if i < len(units) else ""}
+        for i in range(len(params))
+    ]
+    blocks: list[dict[str, Any]] = []
+    if model_name:
+        blocks.append(text_block(f"Model: {model_name}"))
+    blocks.append(params_block(rows, caption="Fitted parameters"))
+    blocks.append(
+        _gof_table(result, [
+            ("R²", "R2"), ("Reduced χ²", "chiSqRed"),
+            ("RMSE", "RMSE"), ("AIC", "AIC"),
+            ("Free params", "nFree"), ("Points", "nPoints"),
+        ])
+    )
+    return ReportSheet(
+        title=title,
+        sections=(section("Fit results", blocks),),
+        source_refs=tuple(dict(r) for r in (source_refs or ())),
+    )
+
+
+def from_multipeak_fit(
+    result: Mapping[str, Any],
+    *,
+    title: str = "Multi-peak fit",
+    source_refs: Sequence[Mapping[str, Any]] | None = None,
+) -> ReportSheet:
+    """Build a report from a ``calc.peak_multifit`` result dict."""
+    peaks = list(result.get("peaks", []))
+    cols = ["Peak", "Model", "Center", "FWHM", "Height", "Area", "η"]
+    rows = []
+    for i, pk in enumerate(peaks, start=1):
+        rows.append([
+            i, pk.get("model", result.get("model", "")),
+            pk.get("center"), pk.get("fwhm"), pk.get("height"),
+            pk.get("area"), pk.get("eta"),
+        ])
+    blocks: list[dict[str, Any]] = [
+        table_block(cols, rows, caption=f"{len(peaks)} peak(s)"),
+        _gof_table(result, [("RMSE", "rmse"), ("Peaks", "nPeaks")]),
+    ]
+    return ReportSheet(
+        title=title,
+        sections=(section("Peak fit", blocks),),
+        source_refs=tuple(dict(r) for r in (source_refs or ())),
+    )
+
+
+# Human labels + display order for the common ANOVA-style row-dict keys.
+_STATS_COLUMNS: dict[str, str] = {
+    "source": "Source", "SS": "SS", "df": "df", "MS": "MS", "F": "F", "p": "p",
+    "group": "Group", "diff": "Difference", "statistic": "Statistic",
+    "ciLow": "CI low", "ciHigh": "CI high", "significant": "Significant",
+    "i": "i", "j": "j",
+}
+
+
+def from_stats_table(
+    records: Sequence[Mapping[str, Any]],
+    *,
+    title: str,
+    section_title: str = "Results",
+    columns: Sequence[str] | None = None,
+    caption: str | None = None,
+    source_refs: Sequence[Mapping[str, Any]] | None = None,
+) -> ReportSheet:
+    """Build a report from a list of uniform row-dicts (ANOVA, post-hoc, ...).
+
+    ``columns`` selects/orders the dict keys to show; by default it uses the
+    keys of the first record, relabeled via a small known-key map.
+    """
+    if not records:
+        raise ValueError("from_stats_table needs at least one record")
+    keys = list(columns) if columns is not None else list(records[0].keys())
+    headers = [_STATS_COLUMNS.get(k, k) for k in keys]
+    rows = [[rec.get(k) for k in keys] for rec in records]
+    return ReportSheet(
+        title=title,
+        sections=(section(section_title, [table_block(headers, rows, caption=caption)]),),
+        source_refs=tuple(dict(r) for r in (source_refs or ())),
+    )
+
+
+def from_anova(
+    result: Mapping[str, Any],
+    *,
+    title: str = "ANOVA",
+    source_refs: Sequence[Mapping[str, Any]] | None = None,
+) -> ReportSheet:
+    """Build a report from any ANOVA result dict carrying a ``table`` key."""
+    table = result.get("table")
+    if not table:
+        raise ValueError("from_anova needs a result with a non-empty 'table'")
+    return from_stats_table(
+        table, title=title, section_title="ANOVA table",
+        columns=["source", "SS", "df", "MS", "F", "p"],
+        source_refs=source_refs,
+    )
+
+
+def from_integrate(
+    result: Mapping[str, Any],
+    *,
+    title: str = "Peak integration",
+    source_refs: Sequence[Mapping[str, Any]] | None = None,
+) -> ReportSheet:
+    """Build a report from a ``calc.peak_integrate.integrate_peaks`` result."""
+    peaks = list(result.get("peaks", []))
+    if not peaks:
+        raise ValueError("from_integrate needs a result with peaks")
+    cols = ["Region", "Area", "% area", "Centroid", "Height", "Position", "FWHM"]
+    rows = []
+    for i, pk in enumerate(peaks, start=1):
+        region = pk.get("region")
+        region_str = f"{region[0]:g}–{region[1]:g}" if isinstance(region, list) else i
+        rows.append([
+            region_str, pk.get("area"), pk.get("area_pct"), pk.get("centroid"),
+            pk.get("height"), pk.get("position"), pk.get("fwhm"),
+        ])
+    caption = f"{len(peaks)} region(s), {result.get('baseline')} baseline"
+    blocks = [
+        table_block(cols, rows, caption=caption),
+        text_block(f"Total net area: {result.get('total_area')}"),
+    ]
+    return ReportSheet(
+        title=title,
+        sections=(section("Integration", blocks),),
+        source_refs=tuple(dict(r) for r in (source_refs or ())),
+    )
+
+
+def from_batch_integrate(
+    result: Mapping[str, Any],
+    *,
+    title: str = "Batch peak integration",
+    source_refs: Sequence[Mapping[str, Any]] | None = None,
+) -> ReportSheet:
+    """Build a report from a ``calc.peak_batch.batch_integrate_peaks`` result.
+
+    The area matrix (spectrum x region) becomes a trend table — one row per
+    spectrum, one column per region — plus per-spectrum alignment shift.
+    """
+    results = list(result.get("results", []))
+    regions = list(result.get("regions", []))
+    if not results or not regions:
+        raise ValueError("from_batch_integrate needs results and regions")
+    area_m = result.get("area_matrix", [])
+    region_cols = [f"{r[0]:g}–{r[1]:g}" for r in regions]
+    header = ["Spectrum", *(["Shift"] if result.get("aligned") else []), *region_cols]
+    rows = []
+    for i, row in enumerate(results):
+        cells: list[Any] = [row.get("label", i)]
+        if result.get("aligned"):
+            cells.append(row.get("shift_samples"))
+        cells.extend(area_m[i] if i < len(area_m) else [None] * len(regions))
+        rows.append(cells)
+    n_failed = result.get("n_failed", 0)
+    caption = f"{len(results)} spectra × {len(regions)} region(s)"
+    if n_failed:
+        caption += f" ({n_failed} failed)"
+    return ReportSheet(
+        title=title,
+        sections=(section("Area trends", [table_block(header, rows, caption=caption)]),),
+        source_refs=tuple(dict(r) for r in (source_refs or ())),
+    )

quantized/calc/resample.py

@@ -0,0 +1,142 @@
+"""Resample a DataStruct onto a new x-grid. Port of utilities.resampleData.
+
+Pure calc layer. Supports four grid modes (n_points / step / grid / match_dataset;
+exactly one, or none for a 500-point default) and four interpolation methods
+(linear / pchip / spline=not-a-knot / makima). Out-of-range samples are NaN unless
+``extrapolate=True``.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.interpolate import (
+    Akima1DInterpolator,
+    CubicSpline,
+    PchipInterpolator,
+    interp1d,
+)
+
+from ..datastruct import DataStruct
+
+__all__ = ["resample_data"]
+
+_METHODS = ("linear", "pchip", "spline", "makima")
+
+
+def _colon(a: float, d: float, b: float) -> NDArray[np.float64]:
+    """MATLAB ``a:d:b`` colon grid (endpoint included only if it lands exactly)."""
+    if d == 0:
+        raise ValueError("resample step must be non-zero")
+    n = int(math.floor((b - a) / d + 1e-10))
+    return np.asarray(a + np.arange(n + 1) * d, dtype=float)
+
+
+def _sanitize_xy(
+    x: NDArray[np.float64], y: NDArray[np.float64]
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Make ``(x, y)`` safe for interpolation: drop non-finite pairs, sort by x,
+    and collapse duplicate x (mean y). Mirrors MATLAB ``interp1``'s effective
+    tolerance (it ignores NaN values and accepts unsorted input). Every step is
+    guarded, so clean, strictly-increasing, finite data passes through untouched
+    — golden parity is preserved; only real-world data (NaN gaps, hysteresis /
+    unsorted sweeps, step profiles with repeated x) is repaired."""
+    finite = np.isfinite(x) & np.isfinite(y)
+    if not bool(finite.all()):
+        x, y = x[finite], y[finite]
+    if x.size > 1 and not bool(np.all(np.diff(x) > 0)):
+        order = np.argsort(x, kind="stable")
+        x, y = x[order], y[order]
+        if bool((x[1:] == x[:-1]).any()):
+            ux, inv = np.unique(x, return_inverse=True)
+            sums = np.zeros(ux.size)
+            cnts = np.zeros(ux.size)
+            np.add.at(sums, inv, y)
+            np.add.at(cnts, inv, 1.0)
+            x, y = ux, sums / cnts
+    return x, y
+
+
+def _interp_column(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    x_new: NDArray[np.float64],
+    method: str,
+    extrapolate: bool,
+) -> NDArray[np.float64]:
+    x, y = _sanitize_xy(x, y)
+    if x.size < 2:
+        # Too few finite points to interpolate — undefined everywhere.
+        return np.full(np.shape(x_new), np.nan, dtype=float)
+    if method == "linear":
+        if extrapolate:
+            fn = interp1d(x, y, kind="linear", fill_value="extrapolate", assume_sorted=True)
+            return np.asarray(fn(x_new), dtype=float)
+        return np.asarray(np.interp(x_new, x, y, left=np.nan, right=np.nan), dtype=float)
+    if method == "pchip":
+        return np.asarray(PchipInterpolator(x, y, extrapolate=extrapolate)(x_new), dtype=float)
+    if method == "spline":
+        spline = CubicSpline(x, y, bc_type="not-a-knot", extrapolate=extrapolate)
+        return np.asarray(spline(x_new), dtype=float)
+    akima = Akima1DInterpolator(x, y, method="makima", extrapolate=extrapolate)
+    return np.asarray(akima(x_new), dtype=float)
+
+
+def resample_data(
+    data: DataStruct,
+    *,
+    n_points: int | None = None,
+    step: float | None = None,
+    grid: ArrayLike | None = None,
+    match_dataset: DataStruct | None = None,
+    method: str = "makima",
+    extrapolate: bool = False,
+) -> DataStruct:
+    """Resample ``data`` onto a new x-grid, interpolating every channel.
+
+    Specify exactly one grid mode (``n_points``, ``step``, ``grid`` or
+    ``match_dataset``); with none, a 500-point linspace over the data range is
+    used. Returns a new DataStruct with ``resampled``/``resampleMethod``/
+    ``resamplePoints`` stamped into ``metadata``.
+    """
+    if method not in _METHODS:
+        raise ValueError(f"method must be one of {_METHODS}")
+    x_old = np.asarray(data.time, dtype=float).ravel()
+    y_old = np.asarray(data.values, dtype=float)
+    if y_old.ndim == 1:
+        y_old = y_old.reshape(-1, 1)
+    if x_old.size < 2:
+        raise ValueError("need at least 2 data points")
+
+    modes = sum(v is not None for v in (n_points, step, grid, match_dataset))
+    if modes > 1:
+        raise ValueError("specify only one of: n_points, step, grid, match_dataset")
+    # MATLAB min/max ignore NaN; mirror that so a NaN in the x axis doesn't
+    # collapse the auto-grid to all-NaN. No-op on clean data (golden parity).
+    if not np.isfinite(x_old).any():
+        raise ValueError("x axis has no finite values")
+    lo, hi = float(np.nanmin(x_old)), float(np.nanmax(x_old))
+    if modes == 0:
+        x_new = np.linspace(lo, hi, 500)
+    elif n_points is not None:
+        x_new = np.linspace(lo, hi, int(n_points))
+    elif step is not None:
+        x_new = _colon(lo, float(step), hi)
+    elif grid is not None:
+        x_new = np.asarray(grid, dtype=float).ravel()
+    else:  # match_dataset
+        x_new = np.asarray(match_dataset.time, dtype=float).ravel()  # type: ignore[union-attr]
+
+    y_new = np.empty((x_new.size, y_old.shape[1]))
+    for c in range(y_old.shape[1]):
+        y_new[:, c] = _interp_column(x_old, y_old[:, c], x_new, method, extrapolate)
+
+    meta = dict(data.metadata)
+    meta["resampled"] = True
+    meta["resampleMethod"] = method
+    meta["resamplePoints"] = int(x_new.size)
+    return DataStruct.create(
+        x_new, y_new, labels=data.labels, units=data.units, metadata=meta
+    )

quantized/calc/rsm.py

@@ -0,0 +1,91 @@
+"""RSM strain & relaxation analysis. Port of MATLAB ``fitting.rsmStrain``.
+
+Given the reciprocal-space peak centres of a substrate and an epitaxial film
+(from a reciprocal-space map — see ``io/xrdml`` 2D + ``calc/qspace``), compute
+the in-plane / out-of-plane strain and the relaxation.
+
+Theory (no Miller indices needed — the absolute scale cancels in the ratios):
+for a fixed (hkl), ``|Q| = 2*pi/a`` so the real-space lattice parameter is
+inversely proportional to Q. The in-plane lattice ``a_par ~ 1/Qx`` and the
+out-of-plane ``a_perp ~ 1/Qz``, hence::
+
+    eps_parallel = (a_film_par - a_sub_par) / a_sub_par = Qx_sub/Qx_film - 1
+    eps_perp     = (a_film_perp - a_sub_perp) / a_sub_perp = Qz_sub/Qz_film - 1
+
+Relaxation measures how far the film has departed from pseudomorphism
+(``Qx_film == Qx_sub``) toward its bulk (relaxed) position::
+
+    R = (Qx_film - Qx_sub) / (Qx_bulk - Qx_sub)   # 0 = strained, 1 = relaxed
+
+Returned absolute lattices use the nominal ``a = 2*pi/|Q|`` (consistent ratios).
+
+Pure calc layer — no fastapi/pydantic. Mirrors the MATLAB function's outputs.
+"""
+
+from __future__ import annotations
+
+import math
+import sys
+from typing import Any
+
+__all__ = ["rsm_strain"]
+
+# Machine epsilon floor for |Qx| (matches MATLAB's ``max(abs(Qx), eps)`` guard
+# so a symmetric reflection with Qx == 0 gives a finite nominal lattice).
+_EPS = sys.float_info.epsilon
+
+
+def rsm_strain(
+    q_sub: tuple[float, float],
+    q_film: tuple[float, float],
+    *,
+    bulk: tuple[float, float] | None = None,
+) -> dict[str, Any]:
+    """Strain + relaxation from a substrate/film peak pair in an RSM.
+
+    Args:
+        q_sub: substrate peak centre ``(Qx, Qz)`` in reciprocal space (Ang^-1).
+        q_film: film peak centre ``(Qx, Qz)`` (Ang^-1).
+        bulk: optional bulk (relaxed) film position ``(Qx, Qz)``; enables the
+            relaxation calculation. When omitted, ``relaxation`` is NaN.
+
+    Returns a dict with ``eps_parallel``, ``eps_perp``, ``a_sub_parallel``,
+    ``a_sub_perp``, ``a_film_parallel``, ``a_film_perp``, ``relaxation``.
+    ``eps_parallel`` is NaN for a symmetric reflection (``Qx == 0``: no in-plane
+    information). Raises ``ValueError`` if either ``Qz`` is zero.
+    """
+    qx_sub, qz_sub = float(q_sub[0]), float(q_sub[1])
+    qx_film, qz_film = float(q_film[0]), float(q_film[1])
+
+    if qz_sub == 0 or qz_film == 0:
+        raise ValueError(
+            f"Qz must be non-zero for both peaks (got sub={qz_sub:.4g}, film={qz_film:.4g})"
+        )
+
+    # Strain via Q ratios (no Miller indices required).
+    eps_par = math.nan if (qx_sub == 0 or qx_film == 0) else qx_sub / qx_film - 1
+    eps_perp = qz_sub / qz_film - 1
+
+    # Nominal absolute lattices (|Q| = 2*pi/a for any (hkl); consistent ratios).
+    two_pi = 2.0 * math.pi
+    a_sub_par = two_pi / max(abs(qx_sub), _EPS)
+    a_sub_perp = two_pi / abs(qz_sub)
+    a_film_par = two_pi / max(abs(qx_film), _EPS)
+    a_film_perp = two_pi / abs(qz_film)
+
+    # Relaxation (only when a bulk position is supplied).
+    relaxation = math.nan
+    if bulk is not None:
+        qx_bulk = float(bulk[0])
+        denom = qx_bulk - qx_sub
+        relaxation = math.nan if denom == 0 else (qx_film - qx_sub) / denom
+
+    return {
+        "eps_parallel": eps_par,
+        "eps_perp": eps_perp,
+        "a_sub_parallel": a_sub_par,
+        "a_sub_perp": a_sub_perp,
+        "a_film_parallel": a_film_par,
+        "a_film_perp": a_film_perp,
+        "relaxation": relaxation,
+    }