feat: experimental data calibration pipeline with ROOT I/O

- Fix chi2 calculation bug in calibration.py (remove incorrect coeffs[::-1] reversal in np.polyval) - Fix broken beta_spectrum/cli.py (remove orphaned detector response add_argument calls and unused imports) - Add ExpSpectrum.apply_calibration() and EnergyCalibrator.from_am241_spectrum() - Add LivetimeDetermination class for pulser-based livetime - Add SpectrumPipeline orchestration (read→subtract→calibrate→livetime→validate) - Add ROOT I/O with PyROOT primary + uproot fallback - Add bs_exp CLI with process, livetime, export subcommands - Add exp_calibration notebook with pre-calibration visualization - Add comprehensive tests (73 passing) - Add bs_exp console script and [root] extra to pyproject.toml - Remove obsolete detector_response module and unused notebooks
2026-05-21 16:01:25 +03:00
parent caa4a77ebd
commit 5c2b12c0e6
27 changed files with 3065 additions and 773 deletions
@@ -0,0 +1,55 @@
+"""Shared fixtures for exp_data tests."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from exp_data.spectrum import ExpSpectrum
+from exp_data.calibration import CalibrationResult
+
+
+@pytest.fixture
+def synthetic_spectrum():
+    """Create a synthetic ExpSpectrum (4096 channels)."""
+    n_channels = 4096
+    energies = np.arange(n_channels, dtype=np.float64)
+    counts = np.exp(-energies / 500) * 1000 + np.random.poisson(5, n_channels)
+    return ExpSpectrum(
+        energies=energies,
+        counts=counts,
+        source="Tc99",
+        run_id="synthetic",
+    )
+
+
+@pytest.fixture
+def calibration_result():
+    """Create a synthetic CalibrationResult (linear, E = 0.4 + 0.1*ch)."""
+    coeffs = np.array([0.1, 0.4])  # polyfit order: [slope, intercept]
+    cov = np.eye(2) * 1e-6
+    return CalibrationResult(
+        coefficients=coeffs,
+        order=1,
+        chi2_per_dof=0.5,
+        n_points=2,
+        covariance=cov,
+    )
+
+
+@pytest.fixture
+def full_spectrum():
+    """Create a full ExpSpectrum with all fields populated."""
+    return ExpSpectrum(
+        energies=np.arange(4096, dtype=np.float64),
+        counts=np.exp(-np.arange(4096) / 500) * 1000 + np.random.poisson(5, 4096),
+        source="Tc99",
+        run_id="run_042",
+        date="2025-01-15",
+        dead_time=0.05,
+        live_time=3420.0,
+        metadata={
+            "calibration": {"type": "linear", "coefficients": [0.1, 0.4]},
+            "livetime": {"fraction": 0.95, "method": "pulser"},
+        },
+    )
@@ -0,0 +1,142 @@
+"""Unit tests for the LivetimeDetermination class."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from exp_data.spectrum import ExpSpectrum
+from exp_data.livetime import LivetimeDetermination, LivetimeResult
+
+
+class TestLivetimeResult:
+    def test_basic(self):
+        result = LivetimeResult(
+            live_time_fraction=0.95,
+            real_time_sec=3600.0,
+            pulser_frequency_hz=100.0,
+            observed_pulser_rate=95.0,
+            pulser_peak_center_keV=10.0,
+            pulser_peak_sigma_keV=0.5,
+            pulser_peak_chi2=1.2,
+        )
+        assert result.live_time_fraction == 0.95
+        assert result.metadata == {}
+
+    def test_metadata_populated(self):
+        result = LivetimeResult(
+            live_time_fraction=0.95,
+            real_time_sec=3600.0,
+            pulser_frequency_hz=100.0,
+            observed_pulser_rate=95.0,
+            pulser_peak_center_keV=10.0,
+            pulser_peak_sigma_keV=0.5,
+            pulser_peak_chi2=1.2,
+            metadata={"pulser_peak_channel": 100, "pulser_fit_success": True},
+        )
+        assert result.metadata["pulser_peak_channel"] == 100
+
+
+class TestLivetimeDetermination:
+    def test_from_file_requires_positive_frequency(self):
+        """Test that zero frequency raises ValueError."""
+        n_channels = 4096
+        energies = np.arange(n_channels, dtype=np.float64)
+        counts = np.ones(n_channels) * 10
+        spectrum = ExpSpectrum(energies=energies, counts=counts)
+
+        determiner = LivetimeDetermination(
+            spectrum,
+            pulser_frequency_hz=0.0,
+            real_time_sec=3600.0,
+        )
+        with pytest.raises(ValueError, match="positive"):
+            determiner.run()
+
+    def test_live_time_clamped_to_1(self):
+        """Test that live-time fraction > 1.0 is clamped to 1.0."""
+        n_channels = 4096
+        energies = np.arange(n_channels, dtype=np.float64)
+        counts = np.exp(-energies / 500) * 10  # background
+        # Add prominent pulser peak at channel 100
+        pulser_channel = 100
+        pulser_peak = 500 * np.exp(-0.5 * ((energies - pulser_channel) / 2.0) ** 2)
+        counts += pulser_peak.astype(float)
+        spectrum = ExpSpectrum(energies=energies, counts=counts)
+
+        determiner = LivetimeDetermination(
+            spectrum,
+            pulser_frequency_hz=10.0,  # low frequency -> observed rate > frequency
+            real_time_sec=0.01,  # very short time -> high observed rate
+        )
+        result = determiner.run()
+        assert result.live_time_fraction == 1.0
+
+    def test_live_time_clamped_to_0(self):
+        """Test that live-time fraction < 0 is clamped to 0."""
+        n_channels = 4096
+        energies = np.arange(n_channels, dtype=np.float64)
+        counts = np.exp(-energies / 500) * 10  # background only, no pulser peak
+        spectrum = ExpSpectrum(energies=energies, counts=counts)
+
+        determiner = LivetimeDetermination(
+            spectrum,
+            pulser_frequency_hz=100.0,
+            real_time_sec=3600.0,
+        )
+        result = determiner.run()
+        # With no pulser peak, the fitter may find a tiny spurious peak
+        # but the observed rate will be negligible -> live_time ~ 0
+        assert result.live_time_fraction >= 0.0
+        assert result.live_time_fraction <= 0.01
+
+    def test_pulser_peak_detection(self):
+        """Test that LivetimeDetermination correctly identifies a pulser peak."""
+        n_channels = 4096
+        energies = np.arange(n_channels, dtype=np.float64)
+        counts = np.exp(-energies / 500) * 10  # background
+        # Add pulser peak at channel 100 (10 keV)
+        pulser_channel = 100
+        pulser_peak = 500 * np.exp(-0.5 * ((energies - pulser_channel) / 2.0) ** 2)
+        counts += pulser_peak.astype(float)
+
+        spectrum = ExpSpectrum(
+            energies=energies,
+            counts=counts,
+            source="pulser",
+        )
+
+        determiner = LivetimeDetermination(
+            spectrum,
+            pulser_frequency_hz=100.0,
+            real_time_sec=3600.0,
+        )
+        result = determiner.run()
+
+        assert result.live_time_fraction > 0
+        assert result.live_time_fraction <= 1.0
+        assert result.pulser_peak_center_keV == pytest.approx(pulser_channel, abs=5.0)
+
+    def test_result_contains_pulser_info(self):
+        """Test that result contains pulser peak info."""
+        n_channels = 4096
+        energies = np.arange(n_channels, dtype=np.float64)
+        counts = np.exp(-energies / 500) * 10
+        pulser_channel = 100
+        pulser_peak = 500 * np.exp(-0.5 * ((energies - pulser_channel) / 2.0) ** 2)
+        counts += pulser_peak.astype(float)
+
+        spectrum = ExpSpectrum(energies=energies, counts=counts, source="pulser")
+
+        determiner = LivetimeDetermination(
+            spectrum,
+            pulser_frequency_hz=100.0,
+            real_time_sec=3600.0,
+        )
+        result = determiner.run()
+
+        assert result.pulser_peak_center_keV > 0
+        assert result.pulser_peak_sigma_keV > 0
+        assert result.pulser_peak_chi2 > 0
+        assert result.pulser_frequency_hz == 100.0
+        assert result.real_time_sec == 3600.0
@@ -0,0 +1,84 @@
+"""Unit tests for ROOT I/O (skip if no ROOT library available)."""
+
+from __future__ import annotations
+
+
+import numpy as np
+import pytest
+
+from exp_data.spectrum import ExpSpectrum
+
+
+def _has_root_io():
+    """Check if any ROOT I/O library is available."""
+    try:
+        import ROOT  # noqa: F401
+
+        return True
+    except ImportError:
+        pass
+    try:
+        import uproot  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+@pytest.fixture
+def sample_spectrum():
+    """Create a sample ExpSpectrum for testing."""
+    return ExpSpectrum(
+        energies=np.arange(100, dtype=np.float64),
+        counts=np.random.poisson(10, 100).astype(np.float64),
+        source="Tc99",
+        run_id="test_run",
+        dead_time=0.05,
+        live_time=3420.0,
+        date="2025-01-15",
+        metadata={
+            "calibration": {"type": "linear", "coefficients": [0.1, 0.4]},
+            "livetime": {"fraction": 0.95},
+        },
+    )
+
+
+@pytest.mark.skipif(
+    not _has_root_io(),
+    reason="Neither PyROOT nor uproot available",
+)
+class TestRootIOWriteRead:
+    def test_round_trip(self, sample_spectrum, tmp_path):
+        """Test write and read round-trip."""
+        from exp_data.root_io import write_spectrum, read_spectrum
+
+        root_path = tmp_path / "test.root"
+        write_spectrum(str(root_path), sample_spectrum)
+        read_back = read_spectrum(str(root_path))
+
+        np.testing.assert_array_equal(read_back.energies, sample_spectrum.energies)
+        np.testing.assert_array_equal(read_back.counts, sample_spectrum.counts)
+
+    def test_scalar_fields(self, sample_spectrum, tmp_path):
+        """Test that scalar fields survive round-trip."""
+        from exp_data.root_io import write_spectrum, read_spectrum
+
+        root_path = tmp_path / "test.root"
+        write_spectrum(str(root_path), sample_spectrum)
+        read_back = read_spectrum(str(root_path))
+
+        assert read_back.dead_time == sample_spectrum.dead_time
+        assert read_back.source == sample_spectrum.source
+        assert read_back.run_id == sample_spectrum.run_id
+
+    def test_metadata(self, sample_spectrum, tmp_path):
+        """Test that metadata survives round-trip."""
+        from exp_data.root_io import write_spectrum, read_spectrum
+
+        root_path = tmp_path / "test.root"
+        write_spectrum(str(root_path), sample_spectrum)
+        read_back = read_spectrum(str(root_path))
+
+        assert "calibration" in read_back.metadata
+        assert read_back.metadata["calibration"]["type"] == "linear"
+        assert read_back.metadata["livetime"]["fraction"] == 0.95
@@ -26,12 +26,13 @@ class TestExpSpectrumBasic:
        expected = np.sqrt([10.0, 20.0, 30.0])
        np.testing.assert_allclose(spectrum.errors, expected)

-    def test_zero_counts_get_error_one(self):
+    def test_zero_counts_get_zero_error(self):
+        """Zero counts produce zero error (not sqrt(1))."""
        spectrum = ExpSpectrum(
            energies=np.array([0.0, 1.0]),
            counts=np.array([0.0, 100.0]),
        )
-        assert spectrum.errors[0] == 1.0  # sqrt(1) for zero counts
+        assert spectrum.errors[0] == 0.0  # sqrt(0) = 0

    def test_shape_mismatch_raises(self):
        with pytest.raises(AssertionError):
@@ -47,12 +48,19 @@ class TestExpSpectrumBasic:
                counts=np.array([10.0, 20.0]),
            )

-    def test_negative_counts_raises(self):
-        with pytest.raises(AssertionError):
-            ExpSpectrum(
-                energies=np.array([0.0, 1.0]),
-                counts=np.array([10.0, -5.0]),
-            )
+    def test_negative_counts_allowed_for_difference_spectra(self):
+        """Negative counts are allowed — they arise in cumulative subtraction.
+
+        Difference spectra can have negative counts in channels where the true
+        count is zero and Poisson noise causes the earlier cumulative to slightly
+        exceed the later one.
+        """
+        spectrum = ExpSpectrum(
+            energies=np.array([0.0, 1.0]),
+            counts=np.array([10.0, -5.0]),
+        )
+        # Should not raise; errors use abs(counts) for negative values
+        assert spectrum.errors[1] == np.sqrt(5.0)

    def test_total_counts(self):
        spectrum = ExpSpectrum(