docs: the quick start tells the truth about inputs, outputs and the cutoff

A default rotation run writes seven files, not five - the two the list omitted
are most of the bytes. The input is any NXmx/EIGER master or miniCBF sweep,
which the page said only 350 lines later after twice implying Jungfraujoch
data only. The CC1/2-0.30 resolution trim moves up to the quick start, and
_image.dat's columns are finally named (ScalingResult.cpp writes a # header).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EFEJG6WBQv8th4UJFNe53N
This commit is contained in:
2026-09-02 09:18:36 +02:00
co-authored by Claude Opus 5
parent 40403d7beb
commit 40cb5cd6db
+24 -5
View File
@@ -27,8 +27,10 @@ Run it with no arguments to print the usage.
## Quick start
Four commands cover most of what people ask of `rugnux`. Each takes the **master** file of a
Jungfraujoch dataset and names its output files from `-o`:
Four commands cover most of what people ask of `rugnux`. Each takes the **master** file of the
dataset — one written by Jungfraujoch, a DECTRIS EIGER master, or an NXmx master written by another
facility's toolchain; a PILATUS miniCBF sweep works too (see [Input and output](#input-and-output))
— and names its output files from `-o`:
```
# 1. everything from the data - index, integrate, scale and merge with the defaults
@@ -50,21 +52,33 @@ that, or to lift the per-image loop's default ceiling of 16 workers per GPU.
Nothing more is needed to pick the workflow: a dataset carrying a **goniometer axis** is processed
as a rotation sweep, one without as **independent stills**, and scaling and merging run by default
in both. A run that merges — the default — leaves five files next to each other:
in both. A rotation run that merges — the default — leaves seven files next to each other:
```
myrun.mtz merged intensities + French-Wilson amplitudes, for CCP4 / phenix
myrun.cif the same, as mmCIF - the self-describing format, and what to deposit
myrun.hkl the same, as SHELX HKLF 4 - feed this to SHELXC / SHELXD / ANODE
myrun_unmerged.mtz every observation before scaling, for pointless / aimless / careless -
the largest file of the run (--no-export-unmerged skips it)
myrun_P1.mtz the same observations merged in P1, so a wrong space-group call can be
re-merged or re-refined without reprocessing (--no-p1-crosscheck skips it)
myrun_report.txt what the run determined: cell, space group, statistics, warnings
myrun_image.dat one row per image, for plotting how the crystal behaved over the sweep
```
The two MTZ extras are most of the bytes a run writes — worth knowing when sizing a scratch
directory for a campaign, and both have off switches.
Read `myrun_report.txt` first: it says which space group was chosen and on what evidence, how far
the data go, and anything that needs attention.
A few things worth knowing before reaching for more flags:
- **The written reflections stop where CC½ falls through 0.30.** Every reflection file is
resolution-trimmed automatically (`--resolution-cutoff cc-logistic`, one shell past the crossing);
`--resolution-cutoff off` keeps the full measured range, `--scaling-high-resolution` fixes the
limit by hand. A rugnux file reaching less far than another program's on the same data is usually
this default at work, not lost data.
- **Rotation data are best left de novo.** Pinning the cell and space group (recipe 4) is the
normal thing to do for **serial stills**, where the `ffbidx` indexer needs a cell; on a rotation
sweep it tends to *degrade* low-symmetry cases, so prefer recipe 1 and let the run determine both
@@ -210,11 +224,12 @@ rugnux -o myrun /path/to/dataset_master.h5
```
`-o myrun` is the prefix every output file is named from and the last argument is the **master** file
of a Jungfraujoch dataset; `-N` would set the worker-thread count, which otherwise follows the
of the dataset — any of the formats under [Input and output](#input-and-output), not only one written
by Jungfraujoch; `-N` would set the worker-thread count, which otherwise follows the
machine. Nothing is assumed about the crystal
— the goniometer axis in the file tells rugnux this is a rotation sweep, the unit cell comes from
indexing the data, the space group from its systematic absences, and the resolution limit from where
CC1/2 falls off. Progress, statistics and timing go to the terminal, and the five output files land
CC1/2 falls off. Progress, statistics and timing go to the terminal, and the output files land
next to each other.
`myrun_report.txt` is written for a person, top to bottom: it says which space group was chosen and
@@ -439,6 +454,10 @@ the lattice search.
- `<prefix>_report.txt` — the **results report**: what the run determined, in a form both a person and
a beamline script can read. Always written, next to the files above. See
[The results report](#the-results-report) below.
- `<prefix>_image.dat` — one row per processed image, whitespace-separated, with a `#` header line
naming the columns: `image_number scale_G mosaicity_deg wedge_deg cc_to_merge cc_n` — the
per-image scale, mosaicity, smoothing wedge and correlation-to-merge behind the sweep-quality
table, ready for gnuplot or numpy.
Merged statistics (⟨I/σ⟩, CC1/2, completeness, …), the error model and timing are printed to the
console. By default the written resolution is trimmed automatically where CC1/2 falls off