Jungfraujoch/tests/AdaptiveThresholdTest.cpp

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only

#include <catch2/catch_all.hpp>

#include <cmath>

#include "../image_analysis/spot_finding/AdaptiveThreshold.h"

using namespace adaptive_threshold;

namespace {
    // Poisson upper tail P(X >= k) for mean mu, summed directly - an independent reference for the
    // threshold's defining property.
    double PoissonUpperTail(double mu, int k) {
        if (k <= 0)
            return 1.0;
        double pmf = std::exp(-mu);
        double cdf = pmf;
        for (int i = 1; i < k; i++) {
            pmf *= mu / i;
            cdf += pmf;
        }
        return std::max(0.0, 1.0 - cdf);
    }
}

TEST_CASE("AdaptiveThreshold_NormalQuantile", "[SpotFinding]") {
    // Textbook values of the inverse standard-normal CDF.
    CHECK(NormalQuantile(0.5) == Catch::Approx(0.0).margin(1e-9));
    CHECK(NormalQuantile(0.975) == Catch::Approx(1.959964).margin(1e-5));
    CHECK(NormalQuantile(0.99) == Catch::Approx(2.326348).margin(1e-5));
    CHECK(NormalQuantile(1.0 - 1e-6) == Catch::Approx(4.753424).margin(1e-4));

    // Symmetric about 0.5, and monotonically increasing.
    for (const double p: {1e-8, 1e-4, 0.01, 0.2, 0.45})
        CHECK(NormalQuantile(1.0 - p) == Catch::Approx(-NormalQuantile(p)).margin(1e-6));
    CHECK(NormalQuantile(0.6) > NormalQuantile(0.55));
    CHECK(NormalQuantile(1e-3) < NormalQuantile(1e-2));

    // Degenerate arguments stay finite: the finders divide a tolerated-false-pixel count by the pixel
    // count, so p can legitimately arrive at the very edge of (0, 1).
    CHECK(std::isfinite(NormalQuantile(0.0)));
    CHECK(std::isfinite(NormalQuantile(1.0)));
    CHECK(NormalQuantile(0.0) < 0.0);
    CHECK(NormalQuantile(1.0) > 0.0);
}

TEST_CASE("AdaptiveThreshold_PoissonThreshold", "[SpotFinding]") {
    const double p = 1e-5;
    const float z = static_cast<float>(NormalQuantile(1.0 - p));

    // The defining property: the returned count is the SMALLEST whose upper tail is within p.
    for (const double mu: {1e-6, 0.1, 1.0, 3.0, 10.0, 40.0, 60.0, 120.0}) {
        const int thr = static_cast<int>(PoissonThreshold(mu, p, z));
        CHECK(PoissonUpperTail(mu, thr) <= p);
        CHECK(PoissonUpperTail(mu, thr - 1) > p);
    }

    // Non-decreasing in the background level.
    float prev = 0.0f;
    for (const double mu: {1e-6, 0.01, 0.1, 0.5, 1.0, 2.0, 5.0, 20.0, 45.0}) {
        const float thr = PoissonThreshold(mu, p, z);
        CHECK(thr >= prev);
        prev = thr;
    }

    // Above the summation limit the Cornish-Fisher form takes over, and it has to stay a POISSON
    // quantile: the skewness term (z^2-1)/6 is what a plain mu + z*sqrt(mu) leaves out, and at this
    // z the Gaussian form alone lets through several times the tail asked for.
    for (const double mu: {250.0, 400.0}) {
        const float thr = PoissonThreshold(mu, p, z);
        CHECK(thr > mu + z * std::sqrt(mu));
        CHECK(PoissonUpperTail(mu, static_cast<int>(thr)) <= 2 * p);
        CHECK(PoissonUpperTail(mu, static_cast<int>(mu + z * std::sqrt(mu))) > 2 * p);
    }

    // And it joins the exact quantile smoothly at the switch - no step for a ring whose background
    // drifts across it from frame to frame.
    CHECK(std::fabs(PoissonThreshold(200.5, p, z) - PoissonThreshold(199.5, p, z)) < 2.0f);

    // A tighter operating point (smaller p) can only raise the threshold.
    CHECK(PoissonThreshold(5.0, 1e-8, static_cast<float>(NormalQuantile(1.0 - 1e-8)))
          >= PoissonThreshold(5.0, 1e-2, static_cast<float>(NormalQuantile(1.0 - 1e-2))));
}

TEST_CASE("AdaptiveThreshold_RingThreshold", "[SpotFinding]") {
    const double p = 1e-5;
    const float z = static_cast<float>(NormalQuantile(1.0 - p));

    // Never below the read-noise-aware Gaussian arm, which is what keeps an empty ring's threshold
    // off zero - a per-ring sigma alone would collapse there and flood the frame with noise spots.
    for (const float mean: {0.0f, 0.5f, 5.0f, 50.0f}) {
        for (const float sigma: {0.0f, 1.0f, 7.0f}) {
            const float gauss = mean + z * std::sqrt(sigma * sigma + READ * READ);
            CHECK(RingThreshold(mean, sigma, p, z, 1.0f) >= Catch::Approx(gauss).epsilon(1e-6));
        }
    }
    CHECK(RingThreshold(0.0f, 0.0f, p, z, 1.0f) >= z * READ);

    // Non-decreasing in the background mean and in the background scatter.
    CHECK(RingThreshold(20.0f, 4.0f, p, z, 1.0f) > RingThreshold(2.0f, 4.0f, p, z, 1.0f));
    CHECK(RingThreshold(5.0f, 9.0f, p, z, 1.0f) > RingThreshold(5.0f, 1.0f, p, z, 1.0f));

    // Where the background is countable and quiet, Poisson significance is the binding arm: a ring
    // with mean 1 and no measured scatter must still demand several photons.
    CHECK(RingThreshold(1.0f, 0.0f, p, z, 1.0f) > 1.0f + z * READ);

    // A ring whose scatter is far above Poisson (flat-field / read excess) is set by the Gaussian arm.
    CHECK(RingThreshold(10.0f, 30.0f, p, z, 1.0f) == Catch::Approx(10.0f + z * std::sqrt(900.0f + READ * READ)).epsilon(1e-6));
}

TEST_CASE("AdaptiveThreshold_RingThreshold_Gain", "[SpotFinding]") {
    const double p = 1e-5;
    const float z = static_cast<float>(NormalQuantile(1.0 - p));
    // A frame in detector units, g of them to a photon, is thresholded as its photons would be: the same
    // threshold, g times over, for the background and scatter g times over.
    for (const float g: {3.0f, 12.0f})
        for (const float mean: {0.0f, 0.05f, 1.0f, 5.0f, 300.0f})
            for (const float sigma: {0.0f, 1.0f, 7.0f})
                CHECK(RingThreshold(g * mean, g * sigma, p, z, g)
                      == Catch::Approx(g * RingThreshold(mean, sigma, p, z, 1.0f)).epsilon(1e-5));
}