quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/batch_fit.py

@@ -0,0 +1,148 @@
+"""Run the same curve fit across many datasets. Port of fitting.batchFit.
+
+Pure calc layer. Fits one model to each dataset and collects the per-dataset
+parameters / errors / fit statistics into a summary for trend analysis (e.g.
+fitted τ vs temperature). Reuses the bounded ``curve_fit``; optional per-dataset
+auto-guess via a registered model name, x-range restriction, and 1/y or 1/y²
+weighting — all matching the MATLAB original.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.datastruct import DataStruct
+
+from .fit_autoguess import auto_guess
+from .fit_models import FIT_MODELS
+from .fitting import curve_fit
+
+__all__ = ["batch_fit"]
+
+_EPS = float(np.finfo(float).eps)
+ModelFn = Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+
+
+def _extract_xy(
+    ds: DataStruct | tuple[Any, Any] | list[Any], channel: int
+) -> tuple[NDArray[np.float64], NDArray[np.float64], dict[str, Any] | None]:
+    """(x, y, metadata) from a DataStruct or an (x, y) pair."""
+    if isinstance(ds, DataStruct):
+        x = np.asarray(ds.time, dtype=float).ravel()
+        values = np.asarray(ds.values, dtype=float)
+        if values.ndim == 2:
+            ch = min(channel, values.shape[1] - 1)
+            y = values[:, ch]
+        else:
+            y = values.ravel()
+        return x, np.asarray(y, dtype=float).ravel(), dict(ds.metadata)
+    if isinstance(ds, (tuple, list)) and len(ds) >= 2:
+        return (
+            np.asarray(ds[0], dtype=float).ravel(),
+            np.asarray(ds[1], dtype=float).ravel(),
+            None,
+        )
+    return np.empty(0), np.empty(0), None
+
+
+def batch_fit(
+    datasets: list[Any],
+    model_fcn: ModelFn,
+    p0: Sequence[float],
+    *,
+    lower: Sequence[float] | None = None,
+    upper: Sequence[float] | None = None,
+    fixed: Sequence[bool] | None = None,
+    channel: int = 0,
+    model_name: str = "",
+    meta_field: str = "",
+    x_range: Sequence[float] | None = None,
+    weights: str = "none",
+) -> dict[str, Any]:
+    """Fit ``model_fcn`` to every dataset; return a per-dataset summary.
+
+    Port of fitting.batchFit. Each dataset is a ``DataStruct`` or an ``(x, y)``
+    pair. ``model_name`` (if registered) drives per-dataset auto-guess and the
+    output ``paramNames``. ``weights`` ∈ {``none``, ``1/y``, ``1/y2``}. Returns a
+    dict with ``params``/``errors`` (N×M), ``R2``/``chiSqRed``/``RMSE``/``AIC``/
+    ``exitFlags``/``metaValues`` (length N, NaN where a fit was skipped/failed),
+    ``paramNames``, ``modelName``, ``nDatasets``, ``converged``.
+    """
+    if weights not in ("none", "1/y", "1/y2"):
+        raise ValueError(f'weights must be "none", "1/y", or "1/y2", got "{weights}"')
+    n = len(datasets)
+    m = len(p0)
+    nan = float("nan")
+    params = np.full((n, m), nan)
+    errors = np.full((n, m), nan)
+    r2 = [nan] * n
+    chi_sq_red = [nan] * n
+    rmse = [nan] * n
+    aic = [nan] * n
+    exit_flags = [0] * n
+    meta_values = [nan] * n
+
+    for i in range(n):
+        x_data, y_data, meta = _extract_xy(datasets[i], channel)
+        if x_data.size < m + 1:
+            continue
+
+        if x_range is not None and len(x_range) == 2:
+            mask = (x_data >= x_range[0]) & (x_data <= x_range[1])
+            x_data, y_data = x_data[mask], y_data[mask]
+
+        w: NDArray[np.float64] | None = None
+        if weights == "1/y":
+            w = 1.0 / np.maximum(np.abs(y_data), _EPS)
+        elif weights == "1/y2":
+            w = 1.0 / np.maximum(y_data**2, _EPS)
+
+        p0i: Sequence[float] = p0
+        if model_name:
+            try:
+                p0i = auto_guess(model_name, x_data, y_data)
+            except Exception:  # noqa: BLE001 — fall back to the provided p0
+                p0i = p0
+
+        if meta_field and meta is not None:
+            val = meta.get(meta_field)
+            if isinstance(val, (int, float)) and not isinstance(val, bool):
+                meta_values[i] = float(val)
+
+        try:
+            r = curve_fit(x_data, y_data, model_fcn, p0i, lower=lower, upper=upper,
+                          fixed=fixed, weights=w)
+        except Exception:  # noqa: BLE001 — a failed fit leaves the NaN row (like MATLAB)
+            continue
+
+        params[i, :] = np.asarray(r["params"], dtype=float)
+        errors[i, :] = np.asarray(r["errors"], dtype=float)
+        r2[i] = float(r["R2"])
+        chi_sq_red[i] = float(r["chiSqRed"])
+        rmse[i] = float(r["RMSE"])
+        aic[i] = float(r["AIC"])
+        exit_flags[i] = int(r["exitFlag"])
+
+    if model_name and model_name in FIT_MODELS:
+        param_names = list(FIT_MODELS[model_name]["paramNames"])
+    else:
+        param_names = [f"p{j + 1}" for j in range(m)]
+
+    return {
+        "params": params,
+        "errors": errors,
+        "R2": r2,
+        "chiSqRed": chi_sq_red,
+        "RMSE": rmse,
+        "AIC": aic,
+        "exitFlags": exit_flags,
+        "paramNames": param_names,
+        "modelName": model_name,
+        "metaValues": meta_values,
+        "nDatasets": n,
+        "converged": [flag == 1 for flag in exit_flags],
+    }

quantized/calc/constants.py

@@ -0,0 +1,27 @@
+"""Fundamental physical constants (CODATA 2018, SI units). Port of calc.constants."""
+
+from __future__ import annotations
+
+import math
+
+__all__ = ["constants"]
+
+
+def constants() -> dict[str, float]:
+    """Return a dict of fundamental physical constants (CODATA 2018, SI)."""
+    return {
+        "h": 6.62607015e-34,  # Planck constant (J*s)
+        "hbar": 1.054571817e-34,  # reduced Planck constant (J*s)
+        "c": 2.99792458e8,  # speed of light (m/s)
+        "e": 1.602176634e-19,  # elementary charge (C)
+        "kB": 1.380649e-23,  # Boltzmann constant (J/K)
+        "NA": 6.02214076e23,  # Avogadro number (1/mol)
+        "mu0": 4 * math.pi * 1e-7,  # vacuum permeability (H/m)
+        "eps0": 8.8541878128e-12,  # vacuum permittivity (F/m)
+        "muB": 9.2740100783e-24,  # Bohr magneton (J/T)
+        "r_e": 2.8179403262e-15,  # classical electron radius (m)
+        "m_e": 9.1093837015e-31,  # electron mass (kg)
+        "R": 8.314462618,  # molar gas constant (J/mol/K)
+        "F": 96485.33212,  # Faraday constant (C/mol)
+        "Phi0": 2.067833848e-15,  # magnetic flux quantum (Wb)
+    }

quantized/calc/corrections.py

@@ -0,0 +1,192 @@
+"""Correction pipeline for a dataset. Port of bosonPlotter.applyCorrections.
+
+Pure calc layer. Applies, in order: trim -> x-offset -> beam-footprint scale
+(GOTO #7b) -> background subtraction (+ y-offset, or neutron R-scale; an
+anchor-point baseline (GOTO #2) beats the polynomial/slope forms) -> optional
+reference-background subtraction -> magnetometry unit conversion -> smoothing
+-> normalization -> derivative. Composes the already-ported processing/units
+helpers; operates on a DataStruct + a params dict mirroring the MATLAB
+``params`` struct (the GOTO additions are new keys, absent from MATLAB).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+
+from ..datastruct import DataStruct
+from .backgrounds import anchor_baseline, footprint_factor
+from .processing import (
+    cumulative_integral,
+    derivative,
+    log_derivative,
+    normalize,
+    smooth_data,
+)
+from .units import convert_units
+
+__all__ = ["apply_corrections"]
+
+
+def _matlab_round(x: float) -> int:
+    return int(math.copysign(math.floor(abs(x) + 0.5), x))
+
+
+def _interp_zero_fill(
+    bgx: np.ndarray, bgy: np.ndarray, xnew: np.ndarray, method: str
+) -> np.ndarray:
+    """interp1(bgx, bgy, xnew, method, 0): interpolate with 0 outside the range."""
+    if method == "linear":
+        return np.asarray(np.interp(xnew, bgx, bgy, left=0.0, right=0.0), dtype=float)
+    from scipy.interpolate import CubicSpline, PchipInterpolator
+
+    order = np.argsort(bgx)
+    bx, by = bgx[order], bgy[order]
+    if method == "spline":
+        out = CubicSpline(bx, by, bc_type="not-a-knot", extrapolate=False)(xnew)
+    else:  # pchip
+        out = PchipInterpolator(bx, by, extrapolate=False)(xnew)
+    return np.asarray(np.nan_to_num(out, nan=0.0), dtype=float)
+
+
+def apply_corrections(
+    data: DataStruct,
+    params: dict[str, Any],
+    *,
+    bg_dataset: DataStruct | None = None,
+    bg_interp: str = "linear",
+) -> DataStruct:
+    """Apply the correction pipeline to ``data``. Port of bosonPlotter.applyCorrections.
+
+    ``params`` keys (all optional, with sensible defaults): xOff, yOff, bgSlope,
+    bgInt, bgPoly, xTrimMin, xTrimMax, isNeutron, isMag, fieldUnit, momentUnit,
+    sampleMass, sampleVolume, smoothEnabled, smoothWindow, smoothMethod,
+    normMethod, derivativeMode. GOTO additions (new, beyond MATLAB parity):
+    bgAnchors + bgAnchorMethod (anchor-point baseline subtraction, #2) and
+    footprintW + footprintL + footprintTwoTheta (XRR/NR beam-footprint scale,
+    #7b — skips channels labelled ``dq``, like the neutron R-scale). Returns a
+    new DataStruct.
+    """
+    time = np.asarray(data.time, dtype=float).copy()
+    values = np.asarray(data.values, dtype=float).copy()
+    labels = list(data.labels)
+
+    # 1. Trim on x.
+    x_min = params.get("xTrimMin", float("nan"))
+    x_max = params.get("xTrimMax", float("nan"))
+    if not (math.isnan(x_min) and math.isnan(x_max)):
+        mask = np.ones(time.size, dtype=bool)
+        if not math.isnan(x_min):
+            mask &= time >= x_min
+        if not math.isnan(x_max):
+            mask &= time <= x_max
+        time = time[mask]
+        values = values[mask, :]
+
+    # 2. X offset.
+    time = time - params.get("xOff", 0.0)
+
+    # 2b. XRR/NR beam-footprint scale (GOTO #7b): divide by the illuminated
+    # fraction below the spill-over angle, unity above. Applied before any
+    # background handling (it corrects the RAW measured intensity); skips
+    # resolution channels labelled "dq" like the neutron R-scale below.
+    fp_w = params.get("footprintW", 0.0)
+    fp_l = params.get("footprintL", 0.0)
+    if fp_w > 0 and fp_l > 0:
+        theta = time / 2.0 if params.get("footprintTwoTheta", False) else time
+        factor = footprint_factor(theta, beam_width=fp_w, sample_length=fp_l)
+        for k in range(values.shape[1]):
+            if labels[k].lower() != "dq":
+                values[:, k] = values[:, k] / factor
+
+    # 3. Neutron R-scale, or background subtraction + y-offset.
+    y_off = params.get("yOff", 0.0)
+    if params.get("isNeutron", False):
+        for k in range(values.shape[1]):
+            if labels[k].lower() != "dq":
+                values[:, k] = values[:, k] * y_off
+    else:
+        # An anchor-point baseline (GOTO #2) beats the polynomial/slope forms.
+        bg_anchors = params.get("bgAnchors")
+        anchor_bg = (
+            anchor_baseline(
+                time,
+                values[:, 0] if values.shape[1] else time,
+                bg_anchors,
+                method=str(params.get("bgAnchorMethod", "pchip")),
+            )
+            if bg_anchors is not None and len(bg_anchors) >= 2
+            else None
+        )
+        bg_poly = params.get("bgPoly")
+        poly_coeffs = (
+            np.asarray(bg_poly, dtype=float)
+            if bg_poly is not None and len(bg_poly) > 2
+            else None
+        )
+        for k in range(values.shape[1]):
+            if anchor_bg is not None:
+                y_bg = anchor_bg
+            elif poly_coeffs is not None:
+                y_bg = np.polyval(poly_coeffs, time)
+            else:
+                y_bg = params.get("bgSlope", 0.0) * time + params.get("bgInt", 0.0)
+            values[:, k] = values[:, k] - y_bg - y_off
+
+    # 4. Optional reference-background dataset subtraction.
+    if bg_dataset is not None:
+        bgx = np.asarray(bg_dataset.time, dtype=float)
+        bgy = np.asarray(bg_dataset.values, dtype=float)[:, 0]
+        bg_vals = _interp_zero_fill(bgx, bgy, time, bg_interp)
+        for k in range(values.shape[1]):
+            values[:, k] = values[:, k] - bg_vals
+
+    # 5. Magnetometry unit conversion.
+    if params.get("isMag", False):
+        f_unit = params.get("fieldUnit", "")
+        if f_unit and f_unit != "Oe (raw)":
+            target = f_unit.replace(" (raw)", "")
+            time = np.asarray(convert_units(time, "Oe", target)[0], dtype=float)
+        m_unit = params.get("momentUnit", "")
+        if m_unit == "emu/g" and params.get("sampleMass", 0.0) > 0:
+            values = values / params["sampleMass"]
+        elif m_unit in ("emu/cm³", "kA/m") and params.get("sampleVolume", 0.0) > 0:
+            values = values / params["sampleVolume"]
+        elif m_unit == "A·m²":
+            values = values * 1e-3
+
+    # 6. Smoothing.
+    if params.get("smoothEnabled", False):
+        win = max(1, _matlab_round(params.get("smoothWindow", 5)))
+        values = smooth_data(values, method=str(params["smoothMethod"]).lower(), window=win)
+
+    # 7. Normalization.
+    norm = params.get("normMethod", "None")
+    if norm == "Range [0,1]":
+        values = normalize(values, method="range")
+    elif norm == "Peak (max=1)":
+        values = normalize(values, method="peak")
+    elif norm == "Z-score":
+        values = normalize(values, method="zscore")
+    elif norm == "Area (integral=1)":
+        for k in range(values.shape[1]):
+            area = float(np.trapezoid(values[:, k], time))
+            if area != 0:
+                values[:, k] = values[:, k] / area
+
+    # 8. Derivative / integral transforms.
+    deriv = params.get("derivativeMode", "None")
+    if deriv == "dY/dX":
+        values = derivative(time, values, order=1)
+    elif deriv == "d²Y/dX²":
+        values = derivative(time, values, order=2)
+    elif deriv == "∫Y dx":
+        values = cumulative_integral(time, values)
+    elif deriv == "dlog/dlog":
+        values = log_derivative(time, values)
+
+    return DataStruct.create(
+        time, values, labels=labels, units=list(data.units), metadata=dict(data.metadata)
+    )