diff --git a/docs/RUGNUX.md b/docs/RUGNUX.md index 086b0846e..ac87d8d39 100644 --- a/docs/RUGNUX.md +++ b/docs/RUGNUX.md @@ -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. - `_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. +- `_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