scispectrum 0.3.0__py3-none-any.whl

scispectrum/__init__.py

@@ -0,0 +1,4 @@
+from .core import Spectrum, Domain
+from .io import TimeChannelParser
+from .calibration import ResolutionCalibration, AxisCalibration
+

scispectrum/background/__init__.py

@@ -0,0 +1,4 @@
+from .als import ALSBackground
+from .snip import SNIPBackground
+from .polynomial import IterativePolyFit, IterativePolyFitWithMinimum
+from .minimum_in_envelope import MinimaEnvelopeBackground

scispectrum/background/als.py

@@ -0,0 +1,81 @@
+import numpy as np
+from scipy import sparse
+from scipy.sparse.linalg import spsolve
+from scispectrum.background.base import BackgroundEstimator
+
+
+class ALSBackground(BackgroundEstimator):
+    """
+    Asymmetric Least Squares (ALS) background estimator.
+
+    Estimates a smooth background by iteratively fitting a weighted
+    smoothing spline, penalizing points above the current estimate
+    more lightly than points below it. This asymmetry drives the
+    baseline to sit beneath the signal peaks.
+
+    Parameters
+    ----------
+    lam : float
+        Smoothness penalty. Larger values produce a smoother background.
+        Typical range: 1e3 to 1e7. Default is 1e5.
+    p : float
+        Asymmetry parameter. Controls the weight given to points above
+        the current estimate. Should be small (e.g. 0.001 to 0.1) so
+        the baseline stays below peaks. Default is 0.01.
+    max_iter : int
+        Number of reweighting iterations. More iterations refine the
+        baseline but increase compute time. Default is 20.
+
+    References
+    ----------
+    Eilers, P.H.C. and Boelens, H.F.M. (2005).
+    "Baseline correction with asymmetric least squares smoothing."
+    """
+
+    def __init__(self, lam=1e5, p=0.01, max_iter=20):
+        self.lam = lam
+        self.p = p
+        self.max_iter = max_iter
+
+    def estimate(self, axis: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        """
+        Estimate the background of a spectrum using ALS.
+
+        Parameters
+        ----------
+        axis : np.ndarray
+            Axis values (not used by ALS, required by the interface).
+        counts : np.ndarray
+            Spectrum counts.
+
+        Returns
+        -------
+        np.ndarray
+            Estimated background, same shape as counts.
+        """
+        y = counts
+        n = len(y)
+
+        # Second-order difference matrix (n-2 x n) — penalizes curvature
+        # in the background estimate. D.T @ D appears in the smoothness term.
+        D = sparse.diags([1, -2, 1], [0, 1, 2], shape=(n - 2, n), dtype=float)
+        DTD = D.T @ D
+
+        # Initialize weights uniformly — all points treated equally
+        w = np.ones(n)
+
+        for _ in range(self.max_iter):
+            # Diagonal weight matrix for the current iteration
+            W = sparse.diags(w, 0)
+
+            # Solve the weighted penalized least squares system:
+            # (W + lam * D'D) z = W y
+            Z = W + self.lam * DTD
+            z = spsolve(Z.tocsc(), w * y)
+
+            # Asymmetric reweighting: points above the baseline get weight p,
+            # points below get weight 1-p. This pulls the baseline downward
+            # toward the true background, away from peaks.
+            w = np.where(y > z, self.p, 1 - self.p)
+
+        return z

scispectrum/background/base.py

@@ -0,0 +1,31 @@
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+
+class BackgroundEstimator(ABC):
+    """
+    Abstract base class for background estimation algorithms.
+
+    All auxiliary inputs (resolution calibration, convolution objects, etc.)
+    must be passed at construction time, not to estimate().
+    """
+
+    @abstractmethod
+    def estimate(self, axis: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        """
+        Estimate background for a 1D spectrum.
+
+        Parameters
+        ----------
+        axis : np.ndarray
+            Axis values (e.g. energy in keV).
+        counts : np.ndarray
+            Spectrum counts.
+
+        Returns
+        -------
+        np.ndarray
+            Estimated background, same shape as counts.
+        """
+        pass

scispectrum/background/minimum_in_envelope.py

@@ -0,0 +1,125 @@
+import numpy as np
+from scipy.ndimage import gaussian_filter1d
+from scispectrum.background.base import BackgroundEstimator
+from scispectrum.calibration import ResolutionCalibration
+
+
+class MinimaEnvelopeBackground(BackgroundEstimator):
+    """
+    Non-parametric SNR-gated minimum envelope background estimator.
+
+    In each iteration, low-SNR channels are replaced by a resolution-weighted
+    local Gaussian average; high-SNR channels (peaks) are filled from their
+    neighbours. Converges to a smooth background beneath all peaks.
+    Works well for gamma spectroscopy.
+
+    Parameters
+    ----------
+    resolution_calib : ResolutionCalibration
+        Maps axis values to FWHM in the same units.
+    conv : Convolution
+        Convolution object used to compute the local SNR map.
+    iterations : int
+        Number of estimation iterations. Default is 20.
+    window_scale : float
+        Half-window size as a multiple of sigma. Default is 5.0.
+    snr_threshold : float
+        SNR above which a channel is treated as a peak. Default is 4.0.
+    """
+
+    def __init__(
+        self,
+        resolution_calib: ResolutionCalibration,
+        conv,
+        iterations: int = 20,
+        window_scale: float = 5.0,
+        snr_threshold: float = 4.0,
+    ):
+        self.resolution_calib = resolution_calib
+        self.conv = conv
+        self.iterations = iterations
+        self.window_scale = window_scale
+        self.snr_threshold = snr_threshold
+
+    def _fill_with_local_min(self, initial_bg: np.ndarray, axis: np.ndarray) -> np.ndarray:
+        dx = axis[1] - axis[0]
+        n = len(initial_bg)
+
+        fwhm = np.array([self.resolution_calib(xi) for xi in axis])
+        radius_pts = np.maximum((self.window_scale * fwhm / dx).astype(int), 1)
+
+        left_fill = initial_bg.copy()
+        for i in range(n):
+            if left_fill[i] > 0:
+                continue
+            window = left_fill[max(0, i - radius_pts[i]):i]
+            valid = window[window > 0]
+            if len(valid):
+                left_fill[i] = np.min(valid)
+
+        right_fill = initial_bg.copy()
+        for i in range(n - 1, -1, -1):
+            if right_fill[i] > 0:
+                continue
+            window = right_fill[i + 1:min(n, i + radius_pts[i] + 1)]
+            valid = window[window > 0]
+            if len(valid):
+                right_fill[i] = np.min(valid)
+
+        filled = np.minimum(
+            np.where(left_fill > 0, left_fill, np.inf),
+            np.where(right_fill > 0, right_fill, np.inf),
+        )
+
+        valid_vals = initial_bg[initial_bg > 0]
+        fallback = np.min(valid_vals) if len(valid_vals) else 0.0
+        filled[~np.isfinite(filled)] = fallback
+
+        return filled
+
+    def estimate(self, axis: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        """
+        Estimate background using the minimum envelope method.
+
+        Parameters
+        ----------
+        axis : np.ndarray
+            Axis values.
+        counts : np.ndarray
+            Spectrum counts.
+
+        Returns
+        -------
+        np.ndarray
+            Estimated background, same shape as counts.
+        """
+        dx = axis[1] - axis[0]
+        fwhm = np.array([self.resolution_calib(xi) for xi in axis])
+        sigma_pts = np.maximum((fwhm / 2.355) / dx, 1.0)
+
+        new_bg = counts.copy()
+
+        for _ in range(self.iterations):
+            prev_bg = new_bg.copy()
+            new_bg = np.zeros_like(counts)
+
+            _, _, n_sigma = self.conv.apply(axis, prev_bg)
+
+            for i in range(len(axis)):
+                if n_sigma[i] >= self.snr_threshold:
+                    continue
+                sigma = sigma_pts[i]
+                radius = int(self.window_scale * sigma)
+                i_start = max(0, i - radius)
+                i_end = min(len(counts), i + radius + 1)
+                idx = np.arange(i_start, i_end)
+                w = np.exp(-0.5 * ((idx - i) / sigma) ** 2)
+                w /= w.sum()
+                new_bg[i] = np.sum(w * prev_bg[i_start:i_end])
+
+            new_bg = self._fill_with_local_min(new_bg, axis)
+
+            sigma_global = np.mean(sigma_pts)
+            new_bg = gaussian_filter1d(new_bg, sigma=sigma_global)
+
+        return new_bg

scispectrum/background/polynomial.py

@@ -0,0 +1,165 @@
+import numpy as np
+from typing import Callable
+from scispectrum.background.base import BackgroundEstimator
+
+
+class IterativePolyFit(BackgroundEstimator):
+    """
+    Iterative polynomial baseline correction (Gan et al. 2006).
+
+    Fits a polynomial to the spectrum, clips peaks above the fit,
+    and repeats until convergence. The final polynomial is the background.
+    Note: the background can be negative.
+
+    Parameters
+    ----------
+    degree : int
+        Polynomial degree. Default is 5.
+    max_iter : int
+        Maximum number of iterations. Default is 100.
+    tolerance : float
+        Convergence threshold (relative change in fit norm). Default is 0.001.
+    """
+
+    def __init__(self, degree=5, max_iter=100, tolerance=0.001):
+        self.degree = degree
+        self.max_iter = max_iter
+        self.tolerance = tolerance
+
+    def estimate(self, axis: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        y_work = counts.copy()
+        last_fit = np.zeros_like(counts)
+
+        for i in range(self.max_iter):
+            coeffs = np.polyfit(axis, y_work, self.degree)
+            current_fit = np.polyval(coeffs, axis)
+
+            if i > 0:
+                numerator = np.linalg.norm(current_fit - last_fit)
+                denominator = np.linalg.norm(last_fit)
+                if denominator > 0 and (numerator / denominator) < self.tolerance:
+                    break
+
+            last_fit = current_fit
+            y_work = np.minimum(y_work, current_fit)
+
+        return current_fit
+
+
+class IterativePolyFitWithMinimum(BackgroundEstimator):
+    """
+    Iterative polynomial baseline (Gan et al. 2006) with SNR-gated minimum envelope.
+
+    In low-SNR regions, the working signal is floored by the local minimum within
+    a resolution-scaled window. High-SNR regions (peaks) are filled from their
+    neighbours to avoid collapsing the baseline.
+
+    Parameters
+    ----------
+    resolution : callable
+        Maps axis values to FWHM in the same units.
+    conv : Convolution
+        Convolution object used to compute the local SNR map.
+    degree : int
+        Polynomial degree. Default is 5.
+    max_iter : int
+        Maximum iterations. Default is 100.
+    tolerance : float
+        Convergence threshold. Default is 1e-3.
+    window_scale : float
+        Half-window size as a multiple of sigma. Default is 5.0.
+    snr_threshold : float
+        SNR above which a channel is treated as a peak. Default is 4.0.
+    """
+
+    def __init__(
+        self,
+        resolution: Callable[[float], float],
+        conv,
+        degree=5,
+        max_iter=100,
+        tolerance=1e-3,
+        window_scale=5.0,
+        snr_threshold=4.0,
+    ):
+        self.resolution = resolution
+        self.conv = conv
+        self.degree = degree
+        self.max_iter = max_iter
+        self.tolerance = tolerance
+        self.window_scale = window_scale
+        self.snr_threshold = snr_threshold
+
+    def _fill_with_side_min(self, bg: np.ndarray) -> np.ndarray:
+        n = len(bg)
+
+        left_vals = np.full(n, np.nan)
+        last_val = np.nan
+        for i in range(n):
+            if bg[i] > 0:
+                last_val = bg[i]
+            left_vals[i] = last_val
+
+        right_vals = np.full(n, np.nan)
+        last_val = np.nan
+        for i in range(n - 1, -1, -1):
+            if bg[i] > 0:
+                last_val = bg[i]
+            right_vals[i] = last_val
+
+        filled = bg.copy()
+        for i in range(n):
+            if bg[i] > 0:
+                continue
+            l, r = left_vals[i], right_vals[i]
+            if np.isfinite(l) and np.isfinite(r):
+                filled[i] = min(l, r)
+            elif np.isfinite(l):
+                filled[i] = l
+            elif np.isfinite(r):
+                filled[i] = r
+            else:
+                filled[i] = 0.0
+
+        return filled
+
+    def _estimate_minimum_vector(self, axis: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        dx = axis[1] - axis[0]
+        _, _, n_sigma = self.conv.apply(axis, counts)
+
+        fwhm = np.array([self.resolution(xi) for xi in axis])
+        sigma_pts = np.maximum((fwhm / 2.355) / dx, 1.0)
+
+        bg_min = np.zeros_like(counts)
+        for i in range(len(axis)):
+            if np.abs(n_sigma[i]) < self.snr_threshold:
+                sigma = sigma_pts[i]
+                radius = int(self.window_scale * sigma)
+                i_start = max(0, i - radius)
+                i_end = min(len(counts), i + radius + 1)
+                bg_min[i] = np.min(counts[i_start:i_end])
+
+        return self._fill_with_side_min(bg_min)
+
+    def estimate(self, axis: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        counts = counts.astype(float)
+        y_min = self._estimate_minimum_vector(axis, counts)
+
+        y_work = counts.copy()
+        last_fit = np.zeros_like(counts)
+
+        for i in range(self.max_iter):
+            coeffs = np.polyfit(axis, y_work, self.degree)
+            current_fit = np.polyval(coeffs, axis)
+
+            if i > 0:
+                num = np.linalg.norm(current_fit - last_fit)
+                den = np.linalg.norm(last_fit)
+                if den > 0 and (num / den) < self.tolerance:
+                    break
+
+            last_fit = current_fit
+            y_work = np.minimum(y_work, current_fit)
+            y_work = np.maximum(y_work, y_min)
+
+        return current_fit

scispectrum/background/snip.py

@@ -0,0 +1,65 @@
+import numpy as np
+from typing import Callable
+from scispectrum.utils.smoothing import adaptive_gaussian_smoothing
+from scispectrum.background.base import BackgroundEstimator
+from .snip_utils import ll_transform, inv_ll_transform
+
+
+class SNIPBackground(BackgroundEstimator):
+    """
+    Classical SNIP background estimation (Ryan, 1988).
+
+    Parameters
+    ----------
+    iterations : int
+        Number of SNIP clipping iterations.
+    resolution : callable
+        Maps axis values to FWHM in the same units.
+        Required when smooth=True (the default).
+    smooth : bool
+        If True, apply resolution-adaptive Gaussian smoothing before SNIP.
+        Default is True.
+    """
+
+    def __init__(self, iterations: int, resolution: Callable[[np.ndarray], np.ndarray] = None, smooth: bool = True):
+        self.iterations = int(iterations)
+        self.resolution = resolution
+        self.smooth = smooth
+
+    def estimate(self, axis: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        """
+        Estimate background using SNIP.
+
+        Parameters
+        ----------
+        axis : np.ndarray
+            Axis values.
+        counts : np.ndarray
+            Spectrum counts.
+
+        Returns
+        -------
+        np.ndarray
+            Estimated background, same shape as counts.
+        """
+        return self._sinp(axis, counts)
+
+    def _sinp(self, x: np.ndarray, y: np.ndarray) -> np.ndarray:
+        if self.smooth:
+            if self.resolution is None:
+                raise ValueError("resolution must be provided at construction when smooth=True.")
+            y = np.asarray(y, dtype=float)
+            z = ll_transform(y)
+            z = adaptive_gaussian_smoothing(x, z, resolution=self.resolution)
+        else:
+            y = np.asarray(y, dtype=float)
+            z = ll_transform(y)
+
+        n = len(z)
+        for k in range(1, self.iterations + 1):
+            z_new = z.copy()
+            for i in range(k, n - k):
+                z_new[i] = min(z[i], 0.5 * (z[i - k] + z[i + k]))
+            z = z_new
+
+        return inv_ll_transform(z)

scispectrum/background/snip_utils.py

@@ -0,0 +1,10 @@
+import numpy as np
+
+
+def ll_transform(y):
+    return np.log(np.log(y + 1.0) + 1.0)
+
+
+def inv_ll_transform(y):
+    return np.exp(np.exp(y) - 1.0) - 1.0
+

scispectrum/calibration/__init__.py

@@ -0,0 +1,7 @@
+"""
+module for energy and fwhm calibration
+This module is quite lacking
+"""
+from .resolution import ResolutionCalibration
+from .axis import AxisCalibration
+from .models import BaseCalibrationModel

scispectrum/calibration/axis.py

@@ -0,0 +1,60 @@
+from typing import Callable
+import numpy as np
+
+class AxisCalibration:
+    """
+    Generic calibration for a spectrum axis.
+
+    Parameters
+    ----------
+    func : Callable[[np.ndarray], np.ndarray]
+        Function mapping raw channels -> physical values.
+    name : str, optional
+        Name of the axis (e.g., "energy", "time", "wavelength").
+    """
+    def __init__(self, func: Callable[[np.ndarray], np.ndarray], name: str = "axis"):
+        if not callable(func):
+            raise TypeError("mapping must be callable")
+        self.func = func
+        self.name = name
+
+    def __call__(self, channels)-> np.ndarray:
+        """Return the axis values at a given channels."""
+        return self.func(channels)
+
+    def apply(self, channels) -> np.ndarray:
+        return self.func(channels)
+
+    @classmethod
+    def from_array(cls, axis: np.ndarray, name: str = "axis") -> "AxisCalibration":
+        """
+        Create an AxisCalibration from a pre-computed physical axis array.
+
+        The calibration is built using linear interpolation over the array,
+        so channels are assumed to be integer indices 0, 1, 2, ...
+
+        Parameters
+        ----------
+        axis : np.ndarray
+            Pre-computed physical axis values (e.g. energy in keV).
+            Must have the same length as the spectrum counts array.
+        name : str, optional
+            Name of the axis. Default is "axis".
+
+        Returns
+        -------
+        AxisCalibration
+
+        Examples
+        --------
+        >>> axis = np.array([1460.0, 1461.5, 1463.0])
+        >>> calib = AxisCalibration.from_array(axis, name="energy_keV")
+        >>> calib.apply(np.array([0, 1, 2]))
+        array([1460. , 1461.5, 1463. ])
+        """
+        if not isinstance(axis, np.ndarray) or axis.ndim != 1:
+            raise TypeError("axis must be a 1D numpy array")
+
+        channels = np.arange(len(axis))
+        func = lambda ch: np.interp(ch, channels, axis)
+        return cls(func=func, name=name)