nullcal 0.3.3__tar.gz → 0.4.0__tar.gz

{nullcal-0.3.3 → nullcal-0.4.0}/.github/workflows/codeql.yml

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

{nullcal-0.3.3 → nullcal-0.4.0}/.github/workflows/scheduled_release.yml

@@ -29,11 +29,17 @@ jobs:
               with:
                   fetch-depth: 0
 
-            - name: Check for new commits
+            # Release only when something that reaches the built package changed
+            # since the latest tag: its sources, packaging config, readme, license
+            # or dynamic metadata files. Dev-dependency bumps, lock-file
+            # maintenance, CI, tests and docs do not count. Add more files to
+            # count with `paths`, or leave some out with `exclude-paths`.
+            - name: Check for package changes
               id: check_commits
-              uses: isaac-cf-wong/detect-git-changes-action@7a2a8da1d825e42f95f1f088760332b18604e781 # v0.0.23
+              uses: isaac-cf-wong/detect-git-changes-action@fd41a9c5553a9148e8f78399855fd19e04801501 # v0.2.0
               with:
                   use-latest-tag: true
+                  preset: python
 
     ci:
         needs: check_new_commits

{nullcal-0.3.3 → nullcal-0.4.0}/.github/workflows/semantic_pull_request.yml

@@ -15,6 +15,6 @@ jobs:
         permissions:
             pull-requests: read
         steps:
-            - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6
+            - uses: amannn/action-semantic-pull-request@2252a14e810aa9b85c2d560bd7070c802206ecf6 # v6
               env:
                   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{nullcal-0.3.3 → nullcal-0.4.0}/.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@67550aa285814b2b526b89871215604b36a1110f # v0.2.14
+              uses: isaac-cf-wong/dependency-support-policy-action@b6cbe3a70e072d31c537978451edbbcbd3401ec9 # v0.3.0
               with:
                   mode: update
 

{nullcal-0.3.3 → nullcal-0.4.0}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
           - id: check-json
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.17.3
+      rev: v0.17.4
       hooks:
           - id: ruff
             args: [--fix, --config=pyproject.toml]
@@ -29,7 +29,7 @@ repos:
           - id: taplo-format
 
     - repo: https://github.com/crate-ci/typos
-      rev: v1.51.1
+      rev: v1.52.0
       hooks:
           - id: typos
             args: []
@@ -54,7 +54,7 @@ repos:
           - id: actionlint
 
     - repo: https://github.com/astral-sh/uv-pre-commit
-      rev: 0.13.5
+      rev: 0.13.7
       hooks:
           # Update the uv lockfile
           - id: uv-lock

{nullcal-0.3.3 → nullcal-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nullcal
-Version: 0.3.3
+Version: 0.4.0
 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.3.3 → nullcal-0.4.0}/pyproject.toml

@@ -53,16 +53,16 @@ Tracker = "https://github.com/Leuven-Gravity-Institute/nullcal/issues"
 
 [dependency-groups]
 dev = [
-  "ruff>=0.17.2",
-  "prek>=0.5.7",
+  "ruff>=0.17.4",
+  "prek>=0.5.10",
   "pytest-github-actions-annotate-failures>=0.4.2",
   "pytest-cov>=7.1.0",
   "pytest-mock>=3.17.0",
-  "pytest>=9.1.1",
+  "pytest>=9.2.0",
 ]
 
-docs = ["zensical>=0.0.72", "mkdocstrings-python>=2.0.10"]
-build = ["hatch>=1.18.1"]
+docs = ["zensical>=0.1.0", "mkdocstrings-python>=2.0.10"]
+build = ["hatch>=1.18.2"]
 release = ["git-cliff>=2.14.2"]
 
 [tool.dependency-support-policy]

{nullcal-0.3.3 → nullcal-0.4.0}/scripts/spline_resolution_study.py

@@ -289,7 +289,7 @@ detector relative to 21 knots.
 
 ## Provenance and limitations
 
-- Claim `submitted_basis_misses_requirement` -> result `submitted-10` -> run
+- Claim `submitted_basis_not_demonstrated_over_20_2000_hz` -> result `submitted-10` -> run
   `2026-09-15-spline-resolution-study` in `run.json`.
 - Claim `recommended_basis_resolves_bump_over_20_2000_hz` -> result `qnm-dense-19` -> the same
   run snapshot.

nullcal-0.4.0/src/nullcal/studies/bootstrap.py

@@ -0,0 +1,126 @@
+"""Source-cluster quantile uncertainty utilities."""
+
+import warnings
+from dataclasses import dataclass
+from numbers import Integral, Real
+
+import numpy as np
+from numpy.typing import ArrayLike
+from scipy.stats import DegenerateDataWarning, bootstrap
+
+_MIN_RESAMPLES = 2
+_MIN_SOURCE_COUNT = 3
+_SOURCE_MATRIX_NDIM = 2
+
+
+@dataclass(frozen=True)
+class SourceBlockQuantileBound:
+    """A nominal one-sided BCa result and its resampling distribution."""
+
+    estimate: float
+    upper_bound: float
+    standard_error: float
+    bootstrap_distribution: tuple[float, ...]
+    support_saturated: bool
+
+
+def _probability(value: float, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real) or not np.isfinite(value) or not 0 < value < 1:
+        raise ValueError(f"{name} must be a finite probability strictly between zero and one")
+    return float(value)
+
+
+def source_block_quantile_upper(
+    values: ArrayLike,
+    *,
+    quantile: float = 0.95,
+    confidence_level: float = 0.95,
+    resamples: int = 9999,
+    seed: int = 0,
+) -> SourceBlockQuantileBound:
+    """Return a pointwise BCa upper bound for a pooled repeated-source quantile.
+
+    ``values`` has shape (independent sources, repeats per source). A resample
+    selects complete source rows, retaining all repeats, and the acceleration
+    jackknife deletes one complete source. The quantile uses NumPy's ``linear``
+    convention over the pooled values. At least three sources and one repeat
+    are required; unequal-sized clusters or non-finite/missing values are not
+    accepted, including masks nested in row sequences. Input dtypes must be
+    integer or floating point, excluding boolean/string/object arrays. Sources,
+    rather than individual repeats, must be independent.
+
+    This delegates BCa to ``scipy.stats.bootstrap`` with ``alternative='less'``
+    (https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.bootstrap.html).
+    It does not clamp the upper bound above the observed estimate. Degenerate
+    or non-finite intervals raise ValueError, with no percentile fallback.
+    The returned nominal level is not evidence of empirical coverage for a
+    non-smooth quantile, nor a simultaneous confidence band across many calls.
+    ``support_saturated`` flags an endpoint at the largest bootstrap estimate;
+    it does not establish coverage or universally invalidate a discrete-data
+    interval. Callers must assess resampling precision and sampling-model validity.
+    """
+    quantile = _probability(quantile, "quantile")
+    confidence_level = _probability(confidence_level, "confidence_level")
+    if isinstance(resamples, bool) or not isinstance(resamples, Integral) or resamples < _MIN_RESAMPLES:
+        raise ValueError("resamples must be an integer of at least two")
+    if isinstance(seed, bool) or not isinstance(seed, Integral) or seed < 0:
+        raise ValueError("seed must be a nonnegative integer")
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", UserWarning)
+            warnings.simplefilter("error", RuntimeWarning)
+            masked = np.ma.asarray(values)
+            if np.ma.is_masked(masked):
+                raise ValueError("values must not contain masked entries")
+            raw = np.asarray(masked)
+            if raw.dtype.kind not in "iuf":
+                raise ValueError("values must have a real integer or floating-point dtype")
+            matrix = np.asarray(raw, dtype=np.float64)
+    except (TypeError, ValueError, UserWarning, RuntimeWarning) as exc:
+        raise ValueError("values must be a finite real source-by-repeat matrix without masked entries") from exc
+    if (
+        matrix.ndim != _SOURCE_MATRIX_NDIM
+        or matrix.shape[0] < _MIN_SOURCE_COUNT
+        or matrix.shape[1] < 1
+        or not np.all(np.isfinite(matrix))
+    ):
+        raise ValueError("values must be finite, with at least three source rows and one repeat column")
+
+    def statistic(indices: np.ndarray) -> float:
+        return float(np.quantile(matrix[indices], quantile, method="linear"))
+
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DegenerateDataWarning)
+            warnings.simplefilter("error", RuntimeWarning)
+            result = bootstrap(
+                (np.arange(matrix.shape[0]),),
+                statistic,
+                vectorized=False,
+                method="BCa",
+                alternative="less",
+                confidence_level=confidence_level,
+                n_resamples=int(resamples),
+                batch=32,
+                rng=np.random.default_rng(int(seed)),
+            )
+    except (DegenerateDataWarning, RuntimeWarning) as exc:
+        raise ValueError("BCa bound unresolved: degenerate or numerically invalid resampling distribution") from exc
+    upper_bound = float(result.confidence_interval.high)
+    standard_error = float(result.standard_error)
+    if (
+        not np.isfinite(upper_bound)
+        or not np.isfinite(standard_error)
+        or not np.all(np.isfinite(result.bootstrap_distribution))
+    ):
+        raise ValueError("BCa bound unresolved: non-finite interval or resampling distribution")
+    return SourceBlockQuantileBound(
+        estimate=float(np.quantile(matrix, quantile, method="linear")),
+        upper_bound=upper_bound,
+        standard_error=standard_error,
+        bootstrap_distribution=tuple(float(value) for value in result.bootstrap_distribution),
+        support_saturated=bool(upper_bound >= np.max(result.bootstrap_distribution)),
+    )
+
+
+__all__ = ["SourceBlockQuantileBound", "source_block_quantile_upper"]

nullcal-0.4.0/tests/studies/test_source_block_bootstrap.py

@@ -0,0 +1,155 @@
+"""References for whole-source resampling and one-sided BCa bounds."""
+
+import numpy as np
+import pytest
+from scipy.stats import bootstrap
+
+from nullcal.studies.bootstrap import SourceBlockQuantileBound, source_block_quantile_upper
+
+
+@pytest.mark.parametrize("confidence", [0.1, 0.9, 0.95])
+def test_repeated_rows_reduce_to_independent_scalar_median(confidence):
+    # Repeating each scalar an odd number of times preserves the median for
+    # every resample and every delete-one-source jackknife sample.
+    sources = np.array([-4.0, -2.0, -1.0, 0.0, 0.5, 2.0, 8.0])
+    values = np.repeat(sources[:, None], 3, axis=1)
+    reference = bootstrap(
+        (sources,),
+        np.median,
+        method="BCa",
+        alternative="less",
+        confidence_level=confidence,
+        n_resamples=256,
+        batch=32,
+        rng=np.random.default_rng(42),
+    )
+    result = source_block_quantile_upper(
+        values,
+        quantile=0.5,
+        confidence_level=confidence,
+        resamples=256,
+        seed=42,
+    )
+    assert isinstance(result, SourceBlockQuantileBound)
+    assert result.estimate == np.median(sources)
+    assert result.upper_bound == reference.confidence_interval.high
+    assert result.standard_error == reference.standard_error
+    np.testing.assert_array_equal(result.bootstrap_distribution, reference.bootstrap_distribution)
+    if confidence == 0.1:
+        assert result.upper_bound < result.estimate
+
+
+def test_bootstrap_distribution_preserves_complete_rows():
+    values = np.arange(33.0).reshape(11, 3) ** 2
+    indices = np.random.default_rng(123).integers(0, 11, size=(128, 11))
+    expected = [np.quantile(values[row].ravel(), 0.8, method="linear") for row in indices]
+    result = source_block_quantile_upper(values, quantile=0.8, resamples=128, seed=123)
+    np.testing.assert_array_equal(result.bootstrap_distribution, expected)
+    assert len(result.bootstrap_distribution) == 128
+
+
+@pytest.mark.parametrize(
+    "values",
+    [
+        [],
+        [[]],
+        np.zeros((2, 4)),
+        np.zeros((3, 0)),
+        np.zeros(4),
+        np.zeros((3, 2, 1)),
+        np.full((3, 2), np.nan),
+        np.full((3, 2), np.inf),
+        np.ones((3, 2), dtype=complex),
+    ],
+)
+def test_rejects_invalid_source_matrices(values):
+    with pytest.raises(ValueError, match="values"):
+        source_block_quantile_upper(values, resamples=32)
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {"quantile": 0},
+        {"quantile": 1},
+        {"quantile": np.nan},
+        {"quantile": True},
+        {"confidence_level": 0},
+        {"confidence_level": 1},
+        {"confidence_level": np.inf},
+        {"resamples": 0},
+        {"resamples": 1},
+        {"resamples": 2.5},
+        {"resamples": True},
+        {"seed": -1},
+        {"seed": 1.5},
+        {"seed": True},
+    ],
+)
+def test_rejects_invalid_controls(kwargs):
+    with pytest.raises(ValueError, match=next(iter(kwargs))):
+        source_block_quantile_upper(np.arange(12.0).reshape(4, 3), **kwargs)
+
+
+def test_degenerate_bca_is_unresolved():
+    with pytest.raises(ValueError, match=r"BCa.*unresolved"):
+        source_block_quantile_upper(np.ones((8, 3)), resamples=128)
+
+
+def test_bca_is_distinct_from_the_percentile_bound():
+    sources = np.arange(50.0) ** 3
+
+    def statistic(sample):
+        return np.quantile(sample, 0.8, method="linear")
+
+    reference = bootstrap(
+        (sources,),
+        statistic,
+        vectorized=False,
+        method="BCa",
+        alternative="less",
+        confidence_level=0.95,
+        n_resamples=1024,
+        batch=32,
+        rng=np.random.default_rng(741),
+    )
+    percentile = np.quantile(reference.bootstrap_distribution, 0.95, method="linear")
+    assert reference.confidence_interval.high != percentile
+    result = source_block_quantile_upper(
+        sources[:, None],
+        quantile=0.8,
+        confidence_level=0.95,
+        resamples=1024,
+        seed=741,
+    )
+    assert result.upper_bound == reference.confidence_interval.high
+    assert result.upper_bound != percentile
+    assert result.support_saturated is False
+
+
+def test_rejects_masked_values_instead_of_using_hidden_entries():
+    values = np.ma.masked_equal(np.arange(12.0).reshape(4, 3), 3.0)
+    with pytest.raises(ValueError, match="values"):
+        source_block_quantile_upper(values, resamples=128)
+
+
+@pytest.mark.parametrize("container", [list, tuple])
+def test_rejects_masked_rows_inside_a_sequence(container):
+    matrix = np.ma.masked_equal(np.arange(12.0).reshape(4, 3), 3.0)
+    values = container(matrix[row] for row in range(4))
+    with pytest.raises(ValueError, match="values"):
+        source_block_quantile_upper(values, resamples=64)
+
+
+@pytest.mark.parametrize("dtype", [str, bool, object])
+def test_rejects_non_numeric_or_boolean_matrix_types(dtype):
+    values = np.arange(12.0).reshape(4, 3).astype(dtype)
+    with pytest.raises(ValueError, match="values"):
+        source_block_quantile_upper(values, resamples=64)
+
+
+def test_reports_bootstrap_support_boundary_saturation():
+    values = np.array([0.0, 0.01, 0.02, 0.03, 100.0])[:, None]
+    result = source_block_quantile_upper(values, resamples=256, seed=5)
+    assert result.upper_bound == max(result.bootstrap_distribution)
+    assert getattr(result, "support_saturated", None) is True

nullcal-0.4.0/tests/studies/test_spline_provenance.py

@@ -0,0 +1,60 @@
+"""Check generated claim links using synthetic results, independently of plotting."""
+
+import json
+import re
+import runpy
+import sys
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+
+
+def test_readme_claim_links_resolve_to_run_claims(tmp_path, monkeypatch):
+    # Plotting is optional and irrelevant to this metadata contract.
+    plotting = ModuleType("matplotlib.pyplot")
+    package = ModuleType("matplotlib")
+    package.__path__ = []
+    package.pyplot = plotting
+    monkeypatch.setitem(sys.modules, "matplotlib", package)
+    monkeypatch.setitem(sys.modules, "matplotlib.pyplot", plotting)
+    script = Path(__file__).parents[2] / "scripts" / "spline_resolution_study.py"
+    main = runpy.run_path(script)["main"]
+    namespace = main.__globals__
+    results = [
+        {
+            "name": "submitted-10",
+            "knot_count": 10,
+            "knots_hz": [20.0 + 1980.0 * i / 9 for i in range(10)],
+            "evaluation_minimum_hz": 20.0,
+            "evaluation_maximum_hz": 512.0,
+            "max_amplitude_residual_percent": 1.5,
+            "max_phase_residual_degrees": 2.5,
+        },
+        {
+            "name": "qnm-dense-19",
+            "knot_count": 19,
+            "knots_hz": [20.0 + 1980.0 * i / 18 for i in range(19)],
+            "evaluation_minimum_hz": 20.0,
+            "evaluation_maximum_hz": 2000.0,
+            "max_amplitude_residual_percent": 0.5,
+            "max_phase_residual_degrees": 0.25,
+        },
+    ]
+    by_name = {row["name"]: row for row in results}
+    monkeypatch.setitem(namespace, "configurations", lambda: [SimpleNamespace(name=name) for name in by_name])
+    monkeypatch.setitem(namespace, "evaluate", lambda config: by_name[config.name])
+    monkeypatch.setitem(namespace, "git_metadata", lambda: ("0" * 40, False))
+    monkeypatch.setitem(namespace, "write_figure", lambda *_: None)
+    monkeypatch.setattr(sys, "argv", [str(script), "--output-directory", str(tmp_path)])
+
+    main()
+
+    run = json.loads((tmp_path / "run.json").read_text())
+    links = dict(
+        re.findall(r"^- Claim `([^`]+)` -> result `([^`]+)`", (tmp_path / "README.md").read_text(), re.MULTILINE)
+    )
+    assert set(run["claims"]) == {
+        "submitted_basis_not_demonstrated_over_20_2000_hz",
+        "recommended_basis_resolves_bump_over_20_2000_hz",
+    }
+    assert links == {key: claim["supported_by"] for key, claim in run["claims"].items()}
+    assert run["results"] == results