v1.0.0-rc.159 (#69)

This is an UNSTABLE release. It includes many experimental features, as well as many AI generated fixes. We recommend using rc.152 for production use.

* rugnux: Add `--model model.pdb` - score the merged data against an atomic model and compute initial maps. It reports R-work/R-free (scaling the model to the observed amplitudes with an overall scale, an anisotropic B and a flat bulk solvent - the standard few-parameter model, so a batch of maps stays directly comparable) and writes 2Fo-Fc / Fo-Fc electron-density maps (CCP4) plus a map-coefficient MTZ. The structure itself is not refined; the model is only re-fractionalised into the data cell.
* rugnux: The merged reflection output now carries French-Wilson amplitudes (|F| and its sigma) next to the intensities - MTZ `F`/`SIGF`, mmCIF `_refln.F_meas_au`, and the text HKL - computed with the correct centric/acentric Wilson prior and epsilon multiplicity, so a downstream program (e.g. phenix.refine) can refine against amplitudes. The intensity columns are unchanged.
* rugnux: R-free test-set flags are now assigned deterministically and consistently across symmetry - a Bijvoet pair I(+)/I(-) is never split between the work and free sets, and the assignment is a reproducible per-hkl hash that depends only on the reflection index, so every dataset of one crystal form gets the same ~5% free set (what a multi-dataset campaign such as PanDDA needs). On small data the fraction is floored so the test set stays large enough for a stable R-free (~500 reflections, capped at 10%); it stays flat at 5% on ordinary data. When a reference MTZ carries a `FreeR_flag` column its test set is imported instead, letting a whole campaign inherit one shared free set.
* rugnux: A reference MTZ (`--reference-mtz`) can now fix the space group and cell for rotation data too (previously rejected), without being used to scale - the rotation merge stays self-consistent. When the crystal has an indexing (merohedral) ambiguity - a lattice symmetry higher than its Laue symmetry, e.g. P3/P4/P6/C2 - the reference also resolves it: each candidate reindexing (identity plus the twin-law cosets of the metric symmetry) is scored by its intensity correlation against the reference and the data are re-merged in the best-correlating one. This is a metric-preserving relabelling of hkl (the cell is unchanged) and a no-op for a holohedral crystal such as lysozyme.
* rugnux: `--model` validation now aligns the data to the model before scoring - the observed reflections are reindexed into the model's enantiomorph when the two differ only by hand (indistinguishable from merged intensities). A merohedral indexing ambiguity is resolved against the reference MTZ when one is given (so a whole campaign shares one indexing convention); only with a model and no reference does validation fall back to fitting each candidate reindexing and keeping the lowest R-free.
* rugnux: De-novo symmetry - recover a genuine high-symmetry group whose data are imperfectly scaled. Such a merge's within-orbit chi² lands just past the self-consistency bound (each real symmetry step adds a little systematic scatter), right where a merohedral twin also lands, so the chi² ratio alone cannot separate them. The candidate is now rescued when the extra intensity-proportional systematic error it invokes stays small relative to the confirmed subgroup - a genuine symmetry step gains multiplicity without inflating the merge error model's b, whereas a twin forces non-equivalent reflections together and b balloons. Fixes cubic insulin (I23 instead of I222) with no change to any other crystal in the test battery, including the twins that must stay in their lower symmetry.
* Docs: Document the French-Wilson amplitude estimation, R-free flagging, reference-based space-group/ambiguity resolution, and model-based validation/maps in CPU_DATA_ANALYSIS.md.
* Frontend: The status-bar pill now shows a progress bar during detector calibration (previously only during measurement), and the calibration state and its button are labelled "Calibration"/"CALIBRATE" (the internal `Pedestal` state name is unchanged for back-compatibility).Reviewed-on: #69

Co-authored-by: Filip Leonarski <filip.leonarski@psi.ch>

tests/FrenchWilsonTest.cpp

@@ -0,0 +1,97 @@
+// 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 <vector>
+
+#include "../image_analysis/scale_merge/FrenchWilson.h"
+
+namespace {
+    MergedReflection Refl(int h, int k, int l, float d, float I, float sigma) {
+        MergedReflection r;
+        r.h = h; r.k = k; r.l = l; r.d = d; r.I = I; r.sigma = sigma;
+        return r;
+    }
+    // A resolution-spread of ordinary reflections so a Wilson mean can be formed per shell.
+    std::vector<MergedReflection> Background() {
+        std::vector<MergedReflection> v;
+        for (int h = 1; h <= 12; ++h)
+            for (int k = 0; k <= 12; ++k)
+                for (int l = 0; l <= 12; ++l)
+                    v.push_back(Refl(h, k, l, 40.0f / (1 + h * h + k * k + l * l), 800.0f, 20.0f));
+        return v;
+    }
+}
+
+TEST_CASE("French-Wilson: strong reflections reduce to sqrt(I)", "[french_wilson]") {
+    auto v = Background();
+    v.push_back(Refl(1, 0, 0, 25.0f, 40000.0f, 50.0f));   // I/sigma = 800, clearly strong
+    ApplyFrenchWilson(v, 1);
+    CHECK(v.back().F == Catch::Approx(std::sqrt(40000.0)).epsilon(0.02));   // ~200
+    CHECK(v.back().sigmaF >= 0.0f);
+    CHECK(std::isfinite(v.back().sigmaF));
+}
+
+TEST_CASE("French-Wilson: weak and negative intensities get a positive amplitude", "[french_wilson]") {
+    auto v = Background();
+    v.push_back(Refl(2, 0, 0, 20.0f, -40.0f, 50.0f));   // negative measured intensity
+    v.push_back(Refl(3, 0, 0, 15.0f, 10.0f, 50.0f));    // weak, I < sigma
+    ApplyFrenchWilson(v, 1);
+    const auto& neg = v[v.size() - 2];
+    const auto& weak = v.back();
+    CHECK(std::isfinite(neg.F));
+    CHECK(neg.F > 0.0f);          // Bayesian estimate is positive (naive sqrt would give 0)
+    CHECK(std::isfinite(weak.F));
+    CHECK(weak.F > 0.0f);
+}
+
+TEST_CASE("French-Wilson: amplitudes are always finite and non-negative", "[french_wilson]") {
+    std::vector<MergedReflection> v;
+    // A deliberate mix: strong, weak, negative, tiny sigma, across resolution.
+    for (int i = 0; i < 300; ++i) {
+        const float d = 20.0f / (1 + 0.05f * i);
+        const float I = (i % 7 == 0) ? -30.0f : static_cast<float>((i % 50) * 40);
+        v.push_back(Refl(1 + i, 2, 3, d, I, 25.0f));
+    }
+    ApplyFrenchWilson(v, 96);   // P4(3)2(1)2 (has centric reflections + epsilon>1 axes)
+    for (const auto& r : v) {
+        CHECK(std::isfinite(r.F));
+        CHECK(r.F >= 0.0f);
+        CHECK(std::isfinite(r.sigmaF));
+        CHECK(r.sigmaF >= 0.0f);
+    }
+}
+
+TEST_CASE("French-Wilson: centric weak reflection gets a smaller amplitude than acentric", "[french_wilson]") {
+    // At the same resolution (same Wilson mean Sigma) and the same near-zero intensity, the centric
+    // prior puts more weight near |F|=0, so the posterior <|F|> is smaller than for an acentric
+    // reflection (0.80*sqrt(Sigma) vs 0.89*sqrt(Sigma) at I=0). This pins the centric/acentric prior
+    // the right way round: if the two priors were swapped the inequality below would flip.
+    std::vector<MergedReflection> v;
+    // Uniform strong background across resolution, so every shell has ~the same Wilson mean.
+    for (int h = 1; h <= 10; ++h)
+        for (int k = 1; k <= 10; ++k)
+            for (int l = 1; l <= 6; ++l)
+                v.push_back(Refl(h, k, l, 20.0f / (0.5f + 0.1f * (h + k + l)), 1000.0f, 30.0f));
+    // Two weak (I=0) probes at the SAME resolution: (3,1,0) is centric in P4 (l=0 zone), (3,1,4) is
+    // acentric. d is set directly, so both share a shell (hence Sigma) regardless of the cell.
+    v.push_back(Refl(3, 1, 0, 5.0f, 0.0f, 10.0f));
+    v.push_back(Refl(3, 1, 4, 5.0f, 0.0f, 10.0f));
+    ApplyFrenchWilson(v, 75);   // P4
+    const auto& centric = v[v.size() - 2];
+    const auto& acentric = v.back();
+    CHECK(centric.F > 0.0f);
+    CHECK(acentric.F > 0.0f);
+    CHECK(centric.F < acentric.F);
+}
+
+TEST_CASE("French-Wilson: unusable sigma falls back to sqrt(max(I,0))", "[french_wilson]") {
+    auto v = Background();
+    v.push_back(Refl(4, 0, 0, 12.0f, 144.0f, NAN));   // no sigma
+    v.push_back(Refl(5, 0, 0, 11.0f, -5.0f, NAN));    // no sigma, negative I
+    ApplyFrenchWilson(v, 1);
+    CHECK(v[v.size() - 2].F == Catch::Approx(12.0f));   // sqrt(144)
+    CHECK(v.back().F == Catch::Approx(0.0f));           // sqrt(max(-5,0))
+}