From a342f918fb0590fa9a085c23bea5ea495ba4112c Mon Sep 17 00:00:00 2001
From: Filip Leonarski <filip.leonarski@psi.ch>
Date: Mon, 9 Nov 2026 19:39:49 +0100
Subject: [PATCH] docs: --model never acts before the merge on serial stills

RUGNUX_MODEL_AND_REFERENCE.md still described the model as the per-crystal
indexing-ambiguity reference on stills given -C/-S; the code never uses
model intensities there (the ambiguity is resolved from the data and -z),
and the model only relabels the merged reflections afterwards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK
---
 docs/RUGNUX_MODEL_AND_REFERENCE.md | 47 ++++++++++--------------------
 1 file changed, 16 insertions(+), 31 deletions(-)

diff --git a/docs/RUGNUX_MODEL_AND_REFERENCE.md b/docs/RUGNUX_MODEL_AND_REFERENCE.md
index d1acede9d..acb60f7a6 100644
--- a/docs/RUGNUX_MODEL_AND_REFERENCE.md
+++ b/docs/RUGNUX_MODEL_AND_REFERENCE.md
@@ -35,16 +35,10 @@ the rest walks through a run step by step.
 - **A reference dataset (`-z`) and a space group or cell you give (`-S`, `-C`) are different:** they
   are taken as facts about the crystal. They fix the space group and the cell before processing,
   so with them the space group is yours, not the data's.
-- **One exception to "processed the same", and only one:** on **serial stills** given `--model`
-  together with `-C` and `-S`, the model is used during integration to break the **indexing
-  ambiguity** — to choose, crystal by crystal, between the two equally valid indexings — the same job
-  a reference dataset does there (see
-  [Serial stills](#serial-stills-the-one-place-a-model-acts-before-the-merge)). Nothing else is
-  taken from it before the merge. This is deliberate: a structure of the same protein (often a cryo
-  structure) usually exists, and it settles the choice reliably. Where the lattice has no ambiguity
-  the model changes nothing. Without a model the crystals are made consistent with each other from
-  the data alone (with `-S` given), which recovers most of what the model gives; the model still
-  decides the weakest crystals better than the other crystals can.
+- **Serial stills are no exception:** the model is not used before the merge there either. The
+  per-crystal **indexing ambiguity** is resolved from the data (and against `-z` where given), see
+  [Serial stills](#serial-stills-the-indexing-ambiguity); the model only relabels the merged
+  reflections into its own indexing afterwards, as on rotation data.
 
 ## Every option that brings in a model or reference data
 
@@ -58,7 +52,7 @@ the rest walks through a run step by step.
 | `--reference-column <label>` | An MTZ column label | Which column of the reference is read | Through `-z` only |
 | `--free-flags <file>` | Merged data carrying an R-free set: an MTZ, or a structure-factor mmCIF - typically the deposited reflections of the `--model` | Its R-free set and nothing else: the model is validated and refined against it, on the model's axes, where the merge matches the file's intensities (`R_FREE_FLAGS= FILE`) | The free flags only |
 | `-S, --space-group` | A space group | Fixes it: no space-group search | **Yes**: the group is yours (a fitting model may still relabel its hand) |
-| `-C, --unit-cell` | A cell | Indexing looks for this cell (within tolerance); the FFT search range is widened to cover it; on stills the shared-geometry refinement anchors on it as a prior (without it, on the cell the frames index to), and warns, keeping it, where it puts materially fewer of a sample's spots on the lattice than the frames indexed de novo and, with `-S` and `--model`, the per-image use of the model | **Yes**: the cell, and the axis order the files are written in |
+| `-C, --unit-cell` | A cell | Indexing looks for this cell (within tolerance); the FFT search range is widened to cover it; on stills the shared-geometry refinement anchors on it as a prior (without it, on the cell the frames index to), and warns, keeping it, where it puts materially fewer of a sample's spots on the lattice than the frames indexed de novo | **Yes**: the cell, and the axis order the files are written in |
 | `--force-rotation-lattice` | Nine numbers: a lattice | Skips the first-pass indexing and uses this lattice | **Yes**: the lattice |
 | `--report-resolution <dmin>[,<dmax>]` | Another program's resolution range | A second statistics table at that range (`REFRES_*`) | No — report only |
 
@@ -108,14 +102,14 @@ these letters.
 |---|---|---|---|---|---|
 | Spot finding, beam centre, detector geometry | data | — | — | — | (a) |
 | Indexing, lattice, cell | data (de novo) | your cell / lattice | the reference's cell, softly | — | (a) |
-| Integration | data | — | — | — (stills: see below) | (a) |
+| Integration | data | — | — | — | (a) |
 | Scaling, error model, ISa | data | — | — (never a scale anchor) | — | (a) |
 | Outlier rejection, frame disposition | data | — | — | — | (a) |
 | Resolution cut | data (CC1/2 fall-off) | — | — | — (`CC_MODEL_CONFIRMED_TO_D_MIN` is reported, never used) | (a) |
 | Point group, Laue class, centring | data (space-group search) | `-S` fixes it | the reference's | — | (a) |
 | Screw axes (space group within the point group) | data | `-S` | the reference's | a different choice → `<prefix>_mr.*` only | (a) in `p.mtz`, (c) beside it |
 | Hand (enantiomorph) | not decidable: `SPACE_GROUP_ENANTIOMORPH= UNDETERMINED` | `GIVEN` | `GIVEN` | relabelled to the model's where it fits, past the anomalous veto: `ASSUMED_FROM_MODEL` | (b) |
-| Indexing ambiguity (merohedral reindex) | arbitrary on rotation (`INDEXING_AMBIGUITY_OPERATORS=`); on stills with `-S` the crystals made consistent from the data, otherwise mixed (warning) | — | resolved against the reference | resolved by the rigid-body model where its lead beats its null, rotation; per image on stills with `-C`/`-S`. Never by molecular replacement | (b) |
+| Indexing ambiguity (merohedral reindex) | arbitrary on rotation (`INDEXING_AMBIGUITY_OPERATORS=`); on stills with `-S` the crystals made consistent from the data, otherwise mixed (warning) | — | resolved against the reference | resolved by the model's fit to the merge where its lead beats its null, rotation and stills alike. Never by molecular replacement | (b) |
 | Setting (which axis is a, b, c) | standard setting | `-C`'s axis order; `-S`'s symbol | the reference's | the model's, where it fits and there is no `-z` (`SETTING_SOURCE= MODEL`) | (b) |
 | Twinning check (L-test, twin laws) | data | — | — | — | (a) |
 | Twin hypothesis `<prefix>_twin_<SG>.*` | data (when the group may have absorbed a twin law) | — | — | the model may also *ask* for this merge; written then only where the model chooses it | (a) / (c) |
@@ -134,8 +128,8 @@ these letters.
    is told apart from an **experimental structure** (`MR_MODEL_KIND=`). A model that cannot be read
    does not fail the run; the report says `MODEL_VALIDATION= NOT_PERFORMED` and carries a warning.
 2. **The data are processed without the model.** Indexing, integration, scaling, the space-group
-   search, the resolution cut, the error model, outlier rejection: none of them reads the model
-   (on serial stills with `-C`/`-S`, see the next section). The only thing the model asks for here is
+   search, the resolution cut, the error model, outlier rejection: none of them reads the model,
+   on rotation data and serial stills alike. The only thing the model asks for here is
    one extra merge: the merge in a subgroup (the twin hypothesis) where the indexed lattice's group
    was promoted by a metric re-ask, or where the model's own group has fewer rotations than the
    adopted one — so that the model can be scored there. That merge is written only if the model
@@ -190,27 +184,18 @@ In `--mode scale`, `--model` is steps 3–5 only: the rigid body, its null, and
 it may settle. There is no molecular replacement, no setting change, no twin hypothesis and no refinement, and
 `--mr` is refused.
 
-### Serial stills: the one place a model acts before the merge
+### Serial stills: the indexing ambiguity
 
 On serial stills each crystal is indexed on its own, so where the lattice admits two indexings, each
 crystal lands in one of them at random and a merge averages reflections that are not equivalent.
-That has to be settled per crystal, at integration time — by the time there is a merge, the hands
-are already mixed. A reference dataset (`-z`) is the tool for it. Without one, `--model` given
-together with `-C` and `-S` supplies the reference intensities instead: structure factors computed
-from the model, against which each crystal's intensities are correlated to choose its indexing.
+That has to be settled per crystal, before the merge. `--model` plays no part in it: intensities
+computed from a model are never used as the per-crystal reference, so a run with a model merges
+exactly what a run without one does. After the merge, the model is validated as in the steps above
+and may relabel the merged reflections into its own indexing.
 
-This is the only point at which a model affects which observations are merged together, and it is
-not gated by the null — there is no merge yet to test the model on. It chooses only between
-indexings that are equally valid for each crystal; a model that does not belong to the crystal
-carries no information to choose with, so the crystals stay mixed, as they would without a model.
-Where the lattice is only pseudo-merohedral, each crystal's own cell is weighed beside its correlation
-with the model, as far as the run's cells tell the indexings apart.
-After the merge, the model is validated as in the steps above. Without `-C` and `-S`, or on rotation
-data, the model is not used before the merge at all.
-
-Without a model or reference, a stills run given `-S` settles the same question from the data: it
+A stills run given `-S` settles the same question from the data: it
 cannot say which indexing is the true one, but it can say which crystals share one, and puts each
-crystal into the indexing in which it agrees best with all the others, its own cell again weighed
+crystal into the indexing in which it agrees best with all the others, its own cell weighed
 beside that (`INDEXING_AMBIGUITY_RESOLVED= data`). Without `-S` - the space group then
 determined by the run, after the merge - nothing resolves it, and the run warns. With a reference MTZ,
 that same resolution runs and the reference fixes the indexing the merge is written in: `AMBIGUITY_DATA_DISAGREES=` in the report counts the