nullcal 0.2.0__tar.gz → 0.2.1__tar.gz

{nullcal-0.2.0 → nullcal-0.2.1}/.github/workflows/codeql.yml

@@ -22,13 +22,13 @@ jobs:
               uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
 
             - name: Initialize CodeQL
-              uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+              uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
               with:
                   languages: python
                   queries: security-and-quality
 
             - name: Autobuild
-              uses: github/codeql-action/autobuild@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+              uses: github/codeql-action/autobuild@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
 
             - name: Perform CodeQL Analysis
-              uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+              uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4

{nullcal-0.2.0 → nullcal-0.2.1}/.github/workflows/draft_release.yml

@@ -22,7 +22,7 @@ jobs:
 
             - name: Generate changelog
               id: changelog
-              uses: orhun/git-cliff-action@3d96a18cc4ec17e9dc69ddcc424ccafaf1f78ce2 # v4.9.0
+              uses: orhun/git-cliff-action@a9a95522b26fe6403f7bb24031f21fb573d0f5ff # v4.9.1
               with:
                   config: cliff.toml
                   args: --unreleased --verbose

{nullcal-0.2.0 → nullcal-0.2.1}/.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
 
             - name: Generate changelog
               id: changelog
-              uses: orhun/git-cliff-action@3d96a18cc4ec17e9dc69ddcc424ccafaf1f78ce2 # v4.9.0
+              uses: orhun/git-cliff-action@a9a95522b26fe6403f7bb24031f21fb573d0f5ff # v4.9.1
               with:
                   config: cliff.toml
                   args: --current --verbose

{nullcal-0.2.0 → nullcal-0.2.1}/.github/workflows/scheduled_release.yml

@@ -31,7 +31,7 @@ jobs:
 
             - name: Check for new commits
               id: check_commits
-              uses: isaac-cf-wong/detect-git-changes-action@10d1e3ac7c5ee0997d7b370e9929cacac9c87013 # v0.0.19
+              uses: isaac-cf-wong/detect-git-changes-action@a8b0d224a4fdff017607079f83f01f013b9d66a6 # v0.0.20
               with:
                   use-latest-tag: true
 

{nullcal-0.2.0 → nullcal-0.2.1}/.github/workflows/support_floor_update.yml

@@ -22,7 +22,7 @@ jobs:
 
             - name: Apply support policy (spec0, from pyproject tool table)
               id: policy
-              uses: isaac-cf-wong/dependency-support-policy-action@74dfcfcc079cd22b26713242940f65ba2b3c70c7 # v0.2.9
+              uses: isaac-cf-wong/dependency-support-policy-action@dfc24273d70d9730ede96b5fdef09a8d7887cf04 # v0.2.10
               with:
                   mode: update
 

{nullcal-0.2.0 → nullcal-0.2.1}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
           - id: check-json
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.16.8
+      rev: v0.16.9
       hooks:
           - id: ruff
             args: [--fix, --config=pyproject.toml]
@@ -29,13 +29,13 @@ repos:
           - id: taplo-format
 
     - repo: https://github.com/crate-ci/typos
-      rev: v1.50.2
+      rev: v1.50.3
       hooks:
           - id: typos
             args: []
 
     - repo: https://github.com/rbubley/mirrors-prettier
-      rev: v3.9.8
+      rev: v3.9.9
       hooks:
           - id: prettier
             exclude: ^tests/e2e/diagnostics/likelihood_agreement\.json$
@@ -54,7 +54,7 @@ repos:
           - id: actionlint
 
     - repo: https://github.com/astral-sh/uv-pre-commit
-      rev: 0.12.17
+      rev: 0.12.20
       hooks:
           # Update the uv lockfile
           - id: uv-lock

{nullcal-0.2.0 → nullcal-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nullcal
-Version: 0.2.0
+Version: 0.2.1
 Summary: A package to constrain calibration errors of a closed-geometry network of gravitational-wave detectors.
 Project-URL: Source, https://github.com/Leuven-Gravity-Institute/nullcal
 Project-URL: Tracker, https://github.com/Leuven-Gravity-Institute/nullcal/issues

{nullcal-0.2.0 → nullcal-0.2.1}/docs/user-guide/quickstart.md

@@ -77,6 +77,29 @@ log_posterior = likelihood.logdensity_fn(params)
 Use `nullcal.sampler.sample_nuts` when the standard window-adapted NUTS run and
 R-hat, ESS, and divergence diagnostics are desired together.
 
+## 5. Summarize and Apply a Calibration Posterior
+
+```python
+from nullcal.calibration import posterior_median_calibration_factor
+
+# result is the output of nullcal.sampler.sample_nuts(...).
+frequencies = data.frequency_array[np.all(data.mask, axis=0)]
+factor = posterior_median_calibration_factor(
+    frequencies,
+    likelihood.knot_frequencies,
+    result.samples["amplitude"],
+    result.samples["phase"],
+)
+corrected_strain = np.asarray(data.strain).copy()
+corrected_strain[:, np.all(data.mask, axis=0)] /= np.asarray(factor)
+```
+
+The likelihood multiplies the whitened antenna response by the calibration
+factor. Correcting observed strain uses its inverse, as above. The point
+estimate evaluates the complex factor for every posterior sample at every
+frequency, then takes separate medians of its real and imaginary parts.
+Evaluating a spline from median knot values is a different estimator.
+
 ## Next Steps
 
 - See [Installation](installation.md) for environment setup

{nullcal-0.2.0 → nullcal-0.2.1}/pyproject.toml

@@ -53,7 +53,7 @@ Tracker = "https://github.com/Leuven-Gravity-Institute/nullcal/issues"
 
 [dependency-groups]
 dev = [
-  "ruff>=0.16.8",
+  "ruff>=0.16.9",
   "prek>=0.5.3",
   "pytest-github-actions-annotate-failures>=0.4.2",
   "pytest-cov>=7.1.0",
@@ -61,7 +61,7 @@ dev = [
   "pytest>=9.1.1",
 ]
 
-docs = ["zensical>=0.0.62", "mkdocstrings-python>=2.0.8"]
+docs = ["zensical>=0.0.65", "mkdocstrings-python>=2.0.9"]
 build = ["hatch>=1.18.1"]
 release = ["git-cliff>=2.14.2"]
 
@@ -84,7 +84,8 @@ parallel = true
 source = ["src"]
 
 [tool.coverage.report]
-fail_under = 55
+# Policy target: keep at least three-fifths of the package covered while retaining regression headroom.
+fail_under = 60
 omit = ["*/tests/*", "*/site-packages/*"]
 
 [tool.coverage.paths]

{nullcal-0.2.0 → nullcal-0.2.1}/src/nullcal/calibration.py

@@ -7,6 +7,12 @@ uniform log-frequency grid and also permits nonuniform knot placement.
 Importing this module enables JAX's process-wide ``jax_enable_x64`` setting.
 Calibration inference requires float64 precision, so this side effect is an
 intentional part of the module's public behavior.
+
+For a posterior point estimate, evaluate the complex calibration factor for
+each sample at each frequency, then take the componentwise median of its real
+and imaginary parts. Interpolating median knot values gives a different curve.
+The factor multiplies the antenna response; to correct observed strain, divide
+the strain by the estimated factor.
 """
 
 from __future__ import annotations
@@ -21,6 +27,7 @@ jax.config.update("jax_enable_x64", True)
 import jax.numpy as jnp  # noqa: E402
 
 MINIMUM_CUBIC_SPLINE_KNOTS = 4
+POSTERIOR_ARRAY_NDIM = 3
 
 
 def _float64(values):
@@ -109,6 +116,32 @@ def calibration_factor(frequencies, knot_frequencies, amplitude, phase):
     return (1.0 + delta_amplitude) * (2.0 + imaginary_phase) / (2.0 - imaginary_phase)
 
 
+def posterior_median_calibration_factor(frequencies, knot_frequencies, amplitudes, phases):
+    """Return the per-frequency posterior median of the complex factor.
+
+    ``amplitudes`` and ``phases`` have shape ``(sample, detector, knot)``;
+    knots may have shape ``(knot,)`` or ``(detector, knot)``. The complex median
+    is defined componentwise in real and imaginary coordinates. This evaluates
+    every posterior sample before taking the median, rather than evaluating a
+    curve from median knot values.
+    """
+    amplitudes = _float64(amplitudes)
+    phases = _float64(phases)
+    knots = _float64(knot_frequencies)
+    if amplitudes.ndim != POSTERIOR_ARRAY_NDIM or phases.shape != amplitudes.shape or amplitudes.shape[0] == 0:
+        raise ValueError("amplitudes and phases must have matching nonempty (sample, detector, knot) shapes")
+    if knots.ndim == 1:
+        knots = jnp.broadcast_to(knots, amplitudes.shape[1:])
+    if knots.shape != amplitudes.shape[1:]:
+        raise ValueError("knot_frequencies must match the detector-by-knot shape")
+
+    factors = jax.vmap(
+        jax.vmap(calibration_factor, in_axes=(None, 0, 0, 0)),
+        in_axes=(None, None, 0, 0),
+    )(frequencies, knots, amplitudes, phases)
+    return jnp.median(jnp.real(factors), axis=0) + 1j * jnp.median(jnp.imag(factors), axis=0)
+
+
 def calibration_log_prior(
     amplitude,
     phase,
@@ -185,5 +218,6 @@ __all__ = [
     "calibration_factor",
     "calibration_log_prior",
     "calibration_parameters_to_unconstrained",
+    "posterior_median_calibration_factor",
     "unconstrained_to_calibration_parameters",
 ]

nullcal-0.2.1/tests/calibration/test_posterior_summary.py

@@ -0,0 +1,23 @@
+"""Input validation for the per-frequency calibration posterior summary."""
+
+import numpy as np
+import pytest
+
+from nullcal.calibration import posterior_median_calibration_factor
+
+
+def test_posterior_median_rejects_empty_samples():
+    knots = np.geomspace(4.0, 32.0, 4)
+    empty = np.empty((0, 1, knots.size))
+
+    with pytest.raises(ValueError, match="matching nonempty"):
+        posterior_median_calibration_factor(knots, knots, empty, empty)
+
+
+def test_posterior_median_rejects_detector_by_knot_mismatch():
+    knots = np.geomspace(4.0, 32.0, 4)
+    samples = np.zeros((2, 2, knots.size))
+    one_detector_knots = knots[np.newaxis, :]
+
+    with pytest.raises(ValueError, match="detector-by-knot shape"):
+        posterior_median_calibration_factor(knots, one_detector_knots, samples, samples)

nullcal-0.2.1/tests/likelihood/test_recalibration_direction.py

@@ -0,0 +1,107 @@
+"""Zero-noise calibration-direction and posterior-summary checks."""
+
+import numpy as np
+import pytest
+
+from nullcal.calibration import calibration_factor, posterior_median_calibration_factor
+from nullcal.data import InterferometerData
+from nullcal.likelihood import RecalibrationLikelihood
+from nullcal.likelihood.recalibration_likelihood import ET_BEAM_PATTERN
+from nullcal.null_stream.null_stream import NullStream
+from nullcal.time_frequency_transform.wavelet_transforms import WaveletTransform
+
+
+@pytest.mark.parametrize("path", ["likelihood", "null_stream"])
+@pytest.mark.parametrize(
+    "correction",
+    [
+        "truth",
+        pytest.param("inverse", marks=pytest.mark.xfail(strict=True, raises=AssertionError)),
+        pytest.param("conjugate", marks=pytest.mark.xfail(strict=True, raises=AssertionError)),
+    ],
+)
+def test_exact_calibration_truth_removes_zero_noise_null_residual(path, correction, monkeypatch):
+    frequencies = np.fft.rfftfreq(64, 1.0 / 64.0)
+    mask = (frequencies >= 4.0) & (frequencies <= 32.0)
+    knots = np.geomspace(4.0, 32.0, 4)
+    amplitude = np.array([[0.08, 0.04, -0.03, 0.02], [-0.06, 0.03, 0.05, -0.02], [0.02, -0.04, 0.07, 0.01]])
+    phase = np.array([[0.06, -0.03, 0.02, 0.04], [-0.05, 0.02, 0.04, -0.03], [0.03, 0.05, -0.02, 0.01]])
+    factors = np.asarray(
+        [calibration_factor(frequencies[mask], knots, a, p) for a, p in zip(amplitude, phase, strict=True)]
+    )
+    waveforms = np.vstack(
+        (
+            np.exp(0.04j * frequencies[mask]),
+            0.7 * np.exp(-0.07j * frequencies[mask]),
+        )
+    )
+    clean_signal = ET_BEAM_PATTERN @ waveforms
+    strain = np.zeros((3, frequencies.size), dtype=np.complex128)
+    strain[:, mask] = factors * clean_signal
+    data = InterferometerData(
+        psd=np.ones((3, frequencies.size)),
+        strain=strain,
+        mask=np.broadcast_to(mask, strain.shape),
+        frequency_array=frequencies,
+        duration=1.0,
+        sampling_frequency=64.0,
+        start_time=0.0,
+        name=("ET1", "ET2", "ET3"),
+    )
+    likelihood = RecalibrationLikelihood(
+        data,
+        knots,
+        time_frequency_filter=np.ones((8, 8), dtype=bool),
+        wavelet_transform_frequency_resolution=4.0,
+    )
+
+    transform = {"truth": lambda factor: factor, "inverse": lambda factor: 1.0 / factor, "conjugate": np.conj}[
+        correction
+    ]
+    if path == "likelihood":
+        if correction != "truth":
+            original_factor = likelihood._calibration_factor
+            monkeypatch.setattr(likelihood, "_calibration_factor", lambda a, p: transform(original_factor(a, p)))
+        residual = np.asarray(likelihood._frequency_domain_null_stream(amplitude, phase))[:, mask]
+    else:
+        null_stream = NullStream(
+            data,
+            WaveletTransform(duration=1.0, sampling_frequency=64.0, frequency_resolution=4.0, nx=4.0),
+            np.ones((8, 8), dtype=bool),
+        )
+        full_factors = np.zeros_like(strain)
+        full_factors[:, mask] = transform(factors)
+        residual = np.asarray(null_stream.compute_calibrated_frequency_domain_null_stream(full_factors))[:, mask]
+
+    relative_residual = np.max(np.abs(residual)) / np.max(np.abs(strain))
+    assert relative_residual < 2e-15, f"relative residual {relative_residual:.17g} exceeds 2e-15"
+
+
+def test_posterior_median_is_taken_after_evaluating_each_factor():
+    frequencies = np.geomspace(4.0, 32.0, 17)
+    knots = np.geomspace(4.0, 32.0, 4)
+    amplitudes = np.zeros((3, 1, 4))
+    amplitudes[0, 0, 0] = 0.12
+    amplitudes[1, 0, 1] = 0.12
+    amplitudes[2, 0, 2] = 0.12
+    phases = np.zeros_like(amplitudes)
+    phases[0, 0, 1] = 0.04
+    phases[1, 0, 2] = -0.03
+    phases[2, 0, 3] = 0.05
+
+    sample_factors = np.asarray(
+        [calibration_factor(frequencies, knots, a[0], p[0]) for a, p in zip(amplitudes, phases, strict=True)]
+    )
+    expected = np.median(sample_factors.real, axis=0) + 1j * np.median(sample_factors.imag, axis=0)
+    actual = np.asarray(posterior_median_calibration_factor(frequencies, knots, amplitudes, phases))
+    median_knot_curve = np.asarray(
+        calibration_factor(
+            frequencies,
+            knots,
+            np.median(amplitudes[:, 0], axis=0),
+            np.median(phases[:, 0], axis=0),
+        )
+    )
+
+    np.testing.assert_allclose(actual[0], expected, rtol=0.0, atol=1e-15)
+    assert np.max(np.abs(actual[0] - median_knot_curve)) > 1e-3

{nullcal-0.2.0 → nullcal-0.2.1}/tests/time_frequency_transform/test_time_domain_transform.py

@@ -19,7 +19,10 @@ import numpy as np
 import pytest
 
 from nullcal.time_frequency_transform import get_shape_of_wavelet_transform, transform_wavelet_freq_time
-from nullcal.time_frequency_transform.inverse_wavelet_time_funcs import inverse_wavelet_time_helper_fast
+from nullcal.time_frequency_transform.inverse_wavelet_time_funcs import (
+    _compact_packets,
+    inverse_wavelet_time_helper_fast,
+)
 from nullcal.time_frequency_transform.transform_time_funcs import phi_vec, transform_wavelet_time_helper
 from nullcal.time_frequency_transform.wavelet_transforms import inverse_wavelet_time, transform_wavelet_time
 
@@ -59,6 +62,18 @@ def noise():
     return np.random.default_rng(20260914).normal(size=N_SAMPLES)
 
 
+@pytest.mark.unit
+def test_compact_packets_preserve_odd_row_sign_for_even_modes():
+    """Odd-row even modes enter the low and mirrored packets with opposite signs."""
+    wave = np.zeros((2, 4))
+    wave[0, 2] = 5.0
+    wave[1, 2] = 2.0
+
+    packets = np.asarray(_compact_packets(wave, n_f=4, n_t=2))
+
+    np.testing.assert_array_equal(packets[0, [2, 6]], [3.0, 7.0])
+
+
 @pytest.mark.unit
 def test_phi_vec_has_the_length_the_kernels_index(shape, phi):
     """The filter spans ``mult * 2 * n_f`` samples, the window length the kernels loop over.