diff --git a/docs/RUGNUX.md b/docs/RUGNUX.md index 8b3198a35..58b0cf880 100644 --- a/docs/RUGNUX.md +++ b/docs/RUGNUX.md @@ -182,6 +182,8 @@ One page per job, so the answer needed is near the top of a short page: anisotropy section. - [Advanced usage](RUGNUX_ADVANCED.md) — reference data and the indexing ambiguity, model validation, re-merging, and the full command-line option tables. +- [Models and reference data](RUGNUX_MODEL_AND_REFERENCE.md) — every model and reference option, + and decision by decision what a model can and cannot change. - [Detector calibration](RUGNUX_CALIBRATION.md) — the geometry from a calibrant's powder rings (`--mode calibration`). - [CPU/GPU data analysis](CPU_DATA_ANALYSIS.md) — the algorithms behind all of it. diff --git a/docs/RUGNUX_ADVANCED.md b/docs/RUGNUX_ADVANCED.md index 0ac0a01f1..c70823562 100644 --- a/docs/RUGNUX_ADVANCED.md +++ b/docs/RUGNUX_ADVANCED.md @@ -147,6 +147,9 @@ determined on, CCP4 style (`k,l,h` is h'=k, k'=l, l'=h); `h,k,l` where nothing m ## Validating against a model (`rugnux --model`) +Which decisions a model can influence, and which it cannot, is set out decision by decision in +[Models and reference data](RUGNUX_MODEL_AND_REFERENCE.md). + Given an atomic model of the same structure, `--model model.pdb` scales the model structure factors to the merged amplitudes — fitting a flat bulk-solvent contribution and an overall anisotropic *B* — and reports **R-work / R-free** and the mean 2mFo−DFc density at the atom centres. diff --git a/docs/RUGNUX_MODEL_AND_REFERENCE.md b/docs/RUGNUX_MODEL_AND_REFERENCE.md new file mode 100644 index 000000000..1cc62e8c2 --- /dev/null +++ b/docs/RUGNUX_MODEL_AND_REFERENCE.md @@ -0,0 +1,333 @@ +# Models and reference data + +What Rugnux does with outside knowledge — an atomic model, a predicted model, a reference dataset, a +cell or a space group you already know — and, decision by decision, what that knowledge is and is not +allowed to change. The first section is the short version; the tables after it are the precise one; +the rest walks through a run step by step. + +```{contents} On this page +:local: +:depth: 2 +``` + +## In short + +- **Rugnux needs nothing but the images.** Indexing, the cell, the space group, the resolution cut, + scaling, merging and the error model all come from the data. Everything on this page is optional. +- **A model (`--model`, `--mr`) does not change how your data are processed.** The images are + indexed, integrated, scaled and merged the same way with or without it, and the space group is + determined before the model is used. The merged intensities and their sigmas in + `.mtz` are the same numbers either way. +- **The model can only relabel, and only if the data accept it.** It is first tested against + copies of itself placed in random orientations. A model that fits no better than those changes + nothing at all: the reflection files are byte for byte what a run without a model writes. A model + that does fit may change three *labels* in `.mtz`: the **hand** of the space group + (P4₁2₁2 against P4₃2₁2, which the intensities cannot tell apart), the **indexing** where the + lattice allows two equally valid ones, and the **axes** the files are written on. No + intensity is changed, no reflection is added or removed, and no other space group is ever taken. +- **A different space group chosen by the model goes to a separate file.** If the model prefers + another space group, or a twinned subgroup, that merge is written *beside* the answer as + `_mr.mtz`/`.cif`, with the model as placed there. `.mtz` stays the data's own + answer. +- **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":** on **serial stills** given `--model` together with + `-C` and `-S`, the model is used during integration 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)). + +## Every option that brings in a model or reference data + +| Option | What you give | What Rugnux uses it for | Can it change `.mtz`? | +|---|---|---|---| +| *(none)* | — | Everything from the data | — | +| `--model ` | An atomic model, PDB or mmCIF, gzipped or not, recognised by content: an experimental structure or a prediction | Validation after the merge (R-work/R-free, CC(model, data), maps, the placed model); a rigid-body placement checked against a null, with molecular replacement where the rigid body does not place it, and straight away for a prediction | Labels only (hand, indexing, axes), and only where the model fits. Other space groups → `_mr.*` | +| `--mr ` | The same kinds of model | As `--model`, but molecular replacement straight away, without the rigid body. `--mode mx` only, not together with `--model` | Hand label only. Other space groups → `_mr.*` | +| PAE file beside a prediction | `AF--F1-predicted_aligned_error_v.json` next to `AF--F1-model_v.cif` (read automatically, no option) | Cuts the prediction into rigid domains for molecular replacement | No (a domain alone can only confirm the answer's group) | +| `-z, --reference ` (`--reference-mtz`) | Merged data of the same crystal form: an MTZ, or a PDB structure-factor mmCIF (`-sf.cif`) | Fixes the space group (in its own setting) and the cell (softly), puts the merge on its axes, resolves the indexing ambiguity, hands over its R-free set, reports CCref on stills. Never a scale anchor | **Yes**: the space group, the axes, the indexing and the free set are the reference's | +| `--reference-column