scispectrum 0.3.0__tar.gz

scispectrum-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Achiya Yosef Amrusi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scispectrum-0.3.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: scispectrum
+Version: 0.3.0
+Summary: 1D detector spectrum analysis — energy calibration, background estimation, peak detection and fitting
+Author-email: Achiya Yosef Amrusi <ahia.amrosi@mail.huji.ac.il>
+License: MIT
+Project-URL: Homepage, https://github.com/achiyaAmrusi/scispectrum
+Project-URL: Repository, https://github.com/achiyaAmrusi/scispectrum
+Project-URL: Issues, https://github.com/achiyaAmrusi/scispectrum/issues
+Keywords: gamma-ray spectroscopy,peak fitting,background estimation,detector calibration,nuclear physics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3.0,>=2.0.0
+Requires-Dist: pandas<4.0,>=2.3
+Requires-Dist: scipy>=1.14.0
+Requires-Dist: xarray>=2024.6.0
+Requires-Dist: uncertainties>=3.1
+Dynamic: license-file
+
+# scispectrum
+
+A Python package for 1D spectrum analysis, designed for physicists and scientists working with detector data such as gamma-ray, X-ray, or particle spectra.
+
+scispectrum provides a clean, extensible framework for the full spectrum analysis pipeline — from raw detector output to calibrated, fitted, background-subtracted results — with proper uncertainty propagation throughout.
+
+---
+
+## Features
+
+- **Spectrum object** with axis calibration, resolution calibration, and error propagation using the uncertainties package
+- **Domain slicing** by physical axis values (e.g. energy in keV) or channels
+- **List-mode parser** for time-channel detector data, with chunked reading for large files
+- **Domain fitting and analysis** — multiple fitting and analysis methods for a domain including sum of Gaussians fitting, find peaks, centers and fwhm
+- **Background estimation** — multiple global background extimation methods including Asymmetric Least Squares (ALS)
+- **Extensible base classes** — build your own fitting, background, or analysis procedures with a consistent interface
+- **xarray throughout** — labeled, sliceable data with named coordinates
+- **Uncertainty propagation** via the `uncertainties` library
+
+---
+
+## Installation
+
+scispectrum is not yet available on PyPI. Install directly from GitHub:
+
+```bash
+git clone https://github.com/achiyaAmrusi/pySpectrum
+cd pySpectrum
+pip install -e .
+```
+This installs the package in editable mode, so any changes you make to the source are reflected immediately.
+
+---
+
+## Quick Start
+
+### Load a spectrum from a DataFrame
+
+```python
+import pandas as pd
+from scispectrum.core import Spectrum
+
+df = pd.read_csv("my_spectrum.csv")
+spectrum = Spectrum.from_dataframe(df, channel_col="channel", counts_col="counts")
+```
+
+### Apply an energy calibration
+
+```python
+from scispectrum.calibration import AxisCalibration
+
+# Linear calibration: energy = 0.5 * channel + 1.2
+calib = AxisCalibration(lambda ch: 0.5 * ch + 1.2, name="energy_keV")
+spectrum.set_axis_calibration(calib)
+```
+
+### Slice a domain by axis values
+
+```python
+# Select the region between 1460 and 1480 keV
+domain = spectrum.domain(1460, 1480)
+```
+
+### Fit peaks
+
+```python
+from scispectrum.domain_fitting import SumOfGaussians
+
+result = SumOfGaussians.fit(domain)
+
+print(result["center"].values)   # peak centers in keV
+print(result["fwhm"].values)     # peak widths
+print(result["amplitude"].values) # peak amplitudes
+```
+
+### Estimate and subtract background
+
+```python
+from scispectrum.background import ALSBackground
+
+bg_estimator = ALSBackground(lam=1e5, p=0.001, max_iter=50)
+als_bg = bg_estimator.estimate(spectrum.axis, spectrum.counts)
+domain_subtracted = domains.subtract_background(als_bg[domain.indices])
+```
+
+### Parse raw list-mode data
+
+```python
+from scispectrum.parsers import TimeChannelParser
+
+# From a large file — processed in chunks to save memory
+spectrum = TimeChannelParser.from_file(
+    "detector_run.csv",
+    axis_calib=calib,
+    num_of_channels=2**14
+)
+
+# From an in-memory DataFrame
+spectrum = TimeChannelParser.from_dataframe(df, axis_calib=calib)
+```
+
+---
+
+## Uncertainty Propagation
+
+scispectrum propagates measurement uncertainties through arithmetic operations using the `uncertainties` library. Poisson errors are assigned automatically when parsing list-mode data.
+
+```python
+# Arithmetic preserves errors
+subtraction = spectrum_a - spectrum_b
+subtraction.counts_err  # propagated uncertainties
+```
+
+---
+
+## Extending scispectrum
+
+scispectrum is designed to be extended. Each analysis category has an abstract base class that defines the interface:
+
+### Custom fitting method
+
+```python
+from scispectrum.domain_fitting.abstract_fitting_class import PeakFit
+
+class MyFitter(PeakFit):
+    @classmethod
+    def fit(cls, domain, **kwargs):
+        # your fitting logic here
+        ...
+```
+
+### Custom background estimator
+
+```python
+from scispectrum.background.base import BackgroundEstimator
+
+class MyBackground(BackgroundEstimator):
+    def estimate(self, x, y):
+        # your background logic here
+        ...
+```
+
+All custom classes integrate seamlessly with `Domain`, `Spectrum`, and the rest of the pipeline.
+
+---
+
+## Examples
+
+Full worked examples are available in the [examples directory](https://github.com/achiyaAmrusi/pySpectrum/tree/main/examples):
+
+**Core**
+- [Loading a spectrum](./examples/Core/loading_spectrum.ipynb) — reading and constructing a `Spectrum` from data
+- [Calibration](./examples/Core/calibration.ipynb) — applying axis and resolution calibrations
+- [Domain slicing](./examples/Core/domain_example.ipynb) — creating and working with domains
+
+**Background Estimation**
+- [Background subtraction](./examples/Background/background_substraction.ipynb) — estimating and subtracting background from a domain
+
+**Domain Analysis and Fitting**
+- [Domain fitting](./examples/Domain_Analysis_and_Fitting/domain_fitting.ipynb) — fitting peaks in a single domain
+- [Full spectrum fitting](./examples/Domain_Analysis_and_Fitting/full_sepctrum_fitting.ipynb) — fitting peaks across an entire spectrum
+
+**SNR Identification**
+- [Peak domain identification](./examples/SNR%20Identification/peak_domin_identification.ipynb) — identifying signal regions automatically
+- [Complex spectrum domains](./examples/SNR%20Identification/complex_spectrum_domains.ipynb) — handling overlapping and complex peak structures
+
+**Library**
+Sample data files for running the examples are provided in the [Library directory](./examples/Library).
+
+---
+
+## Requirements
+
+- numpy>=2.0.0,<3.0
+- pandas>=2.3,<4.0
+- scipy>=1.14.0
+- xarray>=2024.6.0
+- uncertainties>=3.1
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Author
+
+Achiya Yosef Amrusi — [GitHub](https://github.com/achiyaAmrusi/pySpectrum)
+
+Contributions and feedback are welcome.
+

scispectrum-0.3.0/README.md

@@ -0,0 +1,193 @@
+# scispectrum
+
+A Python package for 1D spectrum analysis, designed for physicists and scientists working with detector data such as gamma-ray, X-ray, or particle spectra.
+
+scispectrum provides a clean, extensible framework for the full spectrum analysis pipeline — from raw detector output to calibrated, fitted, background-subtracted results — with proper uncertainty propagation throughout.
+
+---
+
+## Features
+
+- **Spectrum object** with axis calibration, resolution calibration, and error propagation using the uncertainties package
+- **Domain slicing** by physical axis values (e.g. energy in keV) or channels
+- **List-mode parser** for time-channel detector data, with chunked reading for large files
+- **Domain fitting and analysis** — multiple fitting and analysis methods for a domain including sum of Gaussians fitting, find peaks, centers and fwhm
+- **Background estimation** — multiple global background extimation methods including Asymmetric Least Squares (ALS)
+- **Extensible base classes** — build your own fitting, background, or analysis procedures with a consistent interface
+- **xarray throughout** — labeled, sliceable data with named coordinates
+- **Uncertainty propagation** via the `uncertainties` library
+
+---
+
+## Installation
+
+scispectrum is not yet available on PyPI. Install directly from GitHub:
+
+```bash
+git clone https://github.com/achiyaAmrusi/pySpectrum
+cd pySpectrum
+pip install -e .
+```
+This installs the package in editable mode, so any changes you make to the source are reflected immediately.
+
+---
+
+## Quick Start
+
+### Load a spectrum from a DataFrame
+
+```python
+import pandas as pd
+from scispectrum.core import Spectrum
+
+df = pd.read_csv("my_spectrum.csv")
+spectrum = Spectrum.from_dataframe(df, channel_col="channel", counts_col="counts")
+```
+
+### Apply an energy calibration
+
+```python
+from scispectrum.calibration import AxisCalibration
+
+# Linear calibration: energy = 0.5 * channel + 1.2
+calib = AxisCalibration(lambda ch: 0.5 * ch + 1.2, name="energy_keV")
+spectrum.set_axis_calibration(calib)
+```
+
+### Slice a domain by axis values
+
+```python
+# Select the region between 1460 and 1480 keV
+domain = spectrum.domain(1460, 1480)
+```
+
+### Fit peaks
+
+```python
+from scispectrum.domain_fitting import SumOfGaussians
+
+result = SumOfGaussians.fit(domain)
+
+print(result["center"].values)   # peak centers in keV
+print(result["fwhm"].values)     # peak widths
+print(result["amplitude"].values) # peak amplitudes
+```
+
+### Estimate and subtract background
+
+```python
+from scispectrum.background import ALSBackground
+
+bg_estimator = ALSBackground(lam=1e5, p=0.001, max_iter=50)
+als_bg = bg_estimator.estimate(spectrum.axis, spectrum.counts)
+domain_subtracted = domains.subtract_background(als_bg[domain.indices])
+```
+
+### Parse raw list-mode data
+
+```python
+from scispectrum.parsers import TimeChannelParser
+
+# From a large file — processed in chunks to save memory
+spectrum = TimeChannelParser.from_file(
+    "detector_run.csv",
+    axis_calib=calib,
+    num_of_channels=2**14
+)
+
+# From an in-memory DataFrame
+spectrum = TimeChannelParser.from_dataframe(df, axis_calib=calib)
+```
+
+---
+
+## Uncertainty Propagation
+
+scispectrum propagates measurement uncertainties through arithmetic operations using the `uncertainties` library. Poisson errors are assigned automatically when parsing list-mode data.
+
+```python
+# Arithmetic preserves errors
+subtraction = spectrum_a - spectrum_b
+subtraction.counts_err  # propagated uncertainties
+```
+
+---
+
+## Extending scispectrum
+
+scispectrum is designed to be extended. Each analysis category has an abstract base class that defines the interface:
+
+### Custom fitting method
+
+```python
+from scispectrum.domain_fitting.abstract_fitting_class import PeakFit
+
+class MyFitter(PeakFit):
+    @classmethod
+    def fit(cls, domain, **kwargs):
+        # your fitting logic here
+        ...
+```
+
+### Custom background estimator
+
+```python
+from scispectrum.background.base import BackgroundEstimator
+
+class MyBackground(BackgroundEstimator):
+    def estimate(self, x, y):
+        # your background logic here
+        ...
+```
+
+All custom classes integrate seamlessly with `Domain`, `Spectrum`, and the rest of the pipeline.
+
+---
+
+## Examples
+
+Full worked examples are available in the [examples directory](https://github.com/achiyaAmrusi/pySpectrum/tree/main/examples):
+
+**Core**
+- [Loading a spectrum](./examples/Core/loading_spectrum.ipynb) — reading and constructing a `Spectrum` from data
+- [Calibration](./examples/Core/calibration.ipynb) — applying axis and resolution calibrations
+- [Domain slicing](./examples/Core/domain_example.ipynb) — creating and working with domains
+
+**Background Estimation**
+- [Background subtraction](./examples/Background/background_substraction.ipynb) — estimating and subtracting background from a domain
+
+**Domain Analysis and Fitting**
+- [Domain fitting](./examples/Domain_Analysis_and_Fitting/domain_fitting.ipynb) — fitting peaks in a single domain
+- [Full spectrum fitting](./examples/Domain_Analysis_and_Fitting/full_sepctrum_fitting.ipynb) — fitting peaks across an entire spectrum
+
+**SNR Identification**
+- [Peak domain identification](./examples/SNR%20Identification/peak_domin_identification.ipynb) — identifying signal regions automatically
+- [Complex spectrum domains](./examples/SNR%20Identification/complex_spectrum_domains.ipynb) — handling overlapping and complex peak structures
+
+**Library**
+Sample data files for running the examples are provided in the [Library directory](./examples/Library).
+
+---
+
+## Requirements
+
+- numpy>=2.0.0,<3.0
+- pandas>=2.3,<4.0
+- scipy>=1.14.0
+- xarray>=2024.6.0
+- uncertainties>=3.1
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Author
+
+Achiya Yosef Amrusi — [GitHub](https://github.com/achiyaAmrusi/pySpectrum)
+
+Contributions and feedback are welcome.
+

scispectrum-0.3.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=74.1.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scispectrum"
+version = "0.3.0"
+description = "1D detector spectrum analysis — energy calibration, background estimation, peak detection and fitting"
+authors = [
+    { name = "Achiya Yosef Amrusi", email = "ahia.amrosi@mail.huji.ac.il" }
+]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["gamma-ray spectroscopy", "peak fitting", "background estimation", "detector calibration", "nuclear physics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=2.0.0,<3.0",
+    "pandas>=2.3,<4.0",
+    "scipy>=1.14.0",
+    "xarray>=2024.6.0",
+    "uncertainties>=3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/achiyaAmrusi/scispectrum"
+Repository = "https://github.com/achiyaAmrusi/scispectrum"
+Issues = "https://github.com/achiyaAmrusi/scispectrum/issues"

scispectrum-0.3.0/scispectrum/__init__.py

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

scispectrum-0.3.0/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-0.3.0/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-0.3.0/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