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
This commit is contained in:
leonarski_fandClaude Opus 5.5 committed 2026-11-09 19:39:49 +01:00
1 parent ced02f1f78
commit a342f918fb
1 file changed
+16 -31
+16 -31
View File
@@ -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