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/LoadReferenceMtzFreeFlagsTest.cpp

@@ -0,0 +1,96 @@
+// 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 <filesystem>
+#include <map>
+#include <tuple>
+#include <vector>
+
+#include <gemmi/mtz.hpp>
+
+#include "../image_analysis/LoadFCalcFromMtz.h"
+
+namespace {
+    // Write a small P4(3)2(1)2 MTZ with an IMEAN column and a FreeR_flag column whose free reflections
+    // carry `free_value` (and the rest its complement). ~1 in 10 reflections is flagged free.
+    std::string WriteMtzWithFreeR(const std::string& path, int free_value) {
+        gemmi::Mtz mtz(true);
+        mtz.spacegroup = gemmi::find_spacegroup_by_number(96);
+        mtz.set_cell_for_all(gemmi::UnitCell(78.0, 78.0, 37.0, 90.0, 90.0, 90.0));
+        mtz.add_dataset("test");
+        mtz.add_column("IMEAN", 'J', -1, -1, false);
+        mtz.add_column("FreeR_flag", 'I', -1, -1, false);
+        std::vector<float> data;
+        int nref = 0;
+        for (int h = 1; h <= 10; ++h)
+            for (int k = 1; k <= 10; ++k)
+                for (int l = 1; l <= 6; ++l) {
+                    const bool is_free = ((h * 7 + k * 13 + l * 17) % 10 == 0);
+                    const int flag = is_free ? free_value : (free_value == 0 ? 1 : 0);
+                    data.insert(data.end(), {static_cast<float>(h), static_cast<float>(k),
+                                             static_cast<float>(l), 100.0f, static_cast<float>(flag)});
+                    ++nref;
+                }
+        mtz.nreflections = nref;
+        mtz.data = std::move(data);
+        mtz.write_to_file(path);
+        return path;
+    }
+
+    bool ExpectedFree(int h, int k, int l) { return (h * 7 + k * 13 + l * 17) % 10 == 0; }
+}
+
+TEST_CASE("LoadReferenceMtz imports FreeR (CCP4 convention: test set = 0)", "[reference_mtz]") {
+    const auto path = (std::filesystem::temp_directory_path() / "rugnux_freer_ccp4.mtz").string();
+    WriteMtzWithFreeR(path, /*free_value=*/0);
+    const auto ref = LoadReferenceMtz(path);
+    std::filesystem::remove(path);
+
+    REQUIRE(ref.has_free_flags);
+    CHECK(ref.n_free > 0);
+    CHECK(ref.n_free < static_cast<int>(ref.reflections.size()) / 2);   // free is the minority
+    for (const auto& r : ref.reflections)
+        CHECK(r.rfree_flag == ExpectedFree(r.h, r.k, r.l));
+}
+
+TEST_CASE("LoadReferenceMtz imports FreeR (phenix convention: test set = 1) via the complement", "[reference_mtz]") {
+    // Here flag 0 is the majority (work), so the loader must take the complement and treat 1 as free.
+    const auto path = (std::filesystem::temp_directory_path() / "rugnux_freer_phenix.mtz").string();
+    WriteMtzWithFreeR(path, /*free_value=*/1);
+    const auto ref = LoadReferenceMtz(path);
+    std::filesystem::remove(path);
+
+    REQUIRE(ref.has_free_flags);
+    CHECK(ref.n_free > 0);
+    CHECK(ref.n_free < static_cast<int>(ref.reflections.size()) / 2);
+    for (const auto& r : ref.reflections)
+        CHECK(r.rfree_flag == ExpectedFree(r.h, r.k, r.l));
+}
+
+TEST_CASE("LoadReferenceMtz without a FreeR column reports no free flags", "[reference_mtz]") {
+    const auto path = (std::filesystem::temp_directory_path() / "rugnux_no_freer.mtz").string();
+    gemmi::Mtz mtz(true);
+    mtz.spacegroup = gemmi::find_spacegroup_by_number(96);
+    mtz.set_cell_for_all(gemmi::UnitCell(78.0, 78.0, 37.0, 90.0, 90.0, 90.0));
+    mtz.add_dataset("test");
+    mtz.add_column("IMEAN", 'J', -1, -1, false);
+    std::vector<float> data;
+    int nref = 0;
+    for (int h = 1; h <= 6; ++h)
+        for (int k = 1; k <= 6; ++k)
+            for (int l = 1; l <= 4; ++l) {
+                data.insert(data.end(), {static_cast<float>(h), static_cast<float>(k),
+                                         static_cast<float>(l), 100.0f});
+                ++nref;
+            }
+    mtz.nreflections = nref;
+    mtz.data = std::move(data);
+    mtz.write_to_file(path);
+    const auto ref = LoadReferenceMtz(path);
+    std::filesystem::remove(path);
+
+    CHECK_FALSE(ref.has_free_flags);
+    CHECK(ref.n_free == 0);
+}