v1.0.0-rc.160 (#70)

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: #70

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

image_analysis/bragg_integration/BraggIntegrationEngineCPU.cpp

@@ -7,6 +7,7 @@
 #include <cmath>
 #include <cstdint>
 #include <limits>
+#include <vector>
 
 #include "../../common/CompressedImage.h"
 #include "../../common/JFJochException.h"
@@ -56,6 +57,12 @@ std::vector<Reflection> BraggIntegrationEngineCPU::RunImpl(const Sampler &img,
     const int W = static_cast<int>(xpixel), H = static_cast<int>(ypixel);
     const bool do_clip = apply_bkg_clip && mode != IntegratorMode::BoxSum;
 
+    // Symmetric trimmed-mean background fraction (BraggIntegrationSettings, rugnux --background-trim):
+    // replaces the r2..r3 ring MEAN with an f-trimmed mean, robust to the high-side contamination
+    // (neighbour wings, tails) that biases the plain mean up and makes it over-subtract weak high-angle
+    // reflections. Already forced to 0 for broadband/stills by the base ctor (they keep the clip below).
+    const double bkg_trim_frac = bkg_trim;
+
     auto grid_idx = [this](int dx, int dy) { return (dy + R) * G + (dx + R); };
 
     // --- Reflection mask: mark the r2 signal disk of every predicted reflection so a neighbour's
@@ -82,6 +89,7 @@ std::vector<Reflection> BraggIntegrationEngineCPU::RunImpl(const Sampler &img,
     };
     std::vector<Rough> rough(npredicted);
     double inv_d2_min = std::numeric_limits<double>::max(), inv_d2_max = 0.0;
+    std::vector<int32_t> bkg_vals;   // reused per reflection for the trimmed-mean background (idea 1)
 
     for (size_t i = 0; i < npredicted; ++i) {
         const auto &r = predicted[i];
@@ -94,6 +102,7 @@ std::vector<Reflection> BraggIntegrationEngineCPU::RunImpl(const Sampler &img,
         int64_t I_sum = 0, I_sum_x = 0, I_sum_y = 0, n_inner = 0, n_inner_valid = 0;
         double bkg_sum = 0.0;
         int n_bkg = 0;
+        bkg_vals.clear();
         for (int y = y0; y <= y1; ++y)
             for (int x = x0; x <= x1; ++x) {
                 const double d2 = (x - r.predicted_x) * (x - r.predicted_x) + (y - r.predicted_y) * (y - r.predicted_y);
@@ -109,15 +118,28 @@ std::vector<Reflection> BraggIntegrationEngineCPU::RunImpl(const Sampler &img,
                     if (refl_mask[y * W + x]) continue;
                     if (!valid(px)) continue;
                     bkg_sum += static_cast<double>(px);
+                    if (bkg_trim_frac > 0.0) bkg_vals.push_back(px);
                     ++n_bkg;
                 }
             }
 
         if (n_inner_valid == n_inner && n_bkg > 5) {
             out.bkg = bkg_sum / n_bkg;
-            // One high-outlier sigma-clip pass on the background ring (stills-only): reject pixels
-            // above mean + 3*sqrt(mean) to strip a bandwidth-streaked neighbour that biases the mean.
-            if (do_clip) {
+            if (bkg_trim_frac > 0.0 && bkg_vals.size() > 5) {
+                // Symmetric trimmed mean over the background ring (idea 1): drop the lowest and highest
+                // bkg_trim_frac of the pixels, average the rest. Robust to the high-side contamination
+                // that biases the plain ring mean and makes it over-subtract at high resolution.
+                std::sort(bkg_vals.begin(), bkg_vals.end());
+                const size_t lo = static_cast<size_t>(bkg_vals.size() * bkg_trim_frac);
+                const size_t hi = bkg_vals.size() - lo;
+                if (hi > lo) {
+                    double s = 0.0;
+                    for (size_t t = lo; t < hi; ++t) s += bkg_vals[t];
+                    out.bkg = s / static_cast<double>(hi - lo);
+                }
+            } else if (do_clip) {
+                // One high-outlier sigma-clip pass on the background ring (stills-only): reject pixels
+                // above mean + 3*sqrt(mean) to strip a bandwidth-streaked neighbour that biases the mean.
                 const double thr = out.bkg + 3.0 * std::sqrt(std::max(out.bkg, 1.0));
                 double s = 0.0;
                 int n = 0;
@@ -323,8 +345,11 @@ std::vector<Reflection> BraggIntegrationEngineCPU::RunImpl(const Sampler &img,
             I = rh.I;
             sigma = rh.sigma;
         }
+        // Carry the Pass-A box-sum intensity-weighted centroid (observed spot position) through the
+        // profile path too - post-refinement uses it as the observed position (beam-centre / distance).
         results[i] = {static_cast<float>(I), static_cast<float>(sigma),
-                      static_cast<float>(rh.bkg), 0.0f, 0.0f, true, false};
+                      static_cast<float>(rh.bkg),
+                      static_cast<float>(rh.obs_x), static_cast<float>(rh.obs_y), true, rh.has_obs};
     }
 
     return Finalize(predicted, npredicted, results, image_number);