leonarski_fandClaude Opus 5
b34f7b09a3
_image.dat carried the per-image scaling table before _plot.txt existed, and the two were written from the same ScalingResult with six columns between them. Drop it: the writer, its call site and its documentation entries go, and _plot.txt gains the one column of the old file that was not already there and is not dead - cc_n, the number of observations cc_to_merge was taken over, without which that correlation cannot be read at the sparse end of a sweep. The old file's wedge_deg is NOT carried over: image_scale_wedge_deg is only ever reset, never assigned, so that column was nan on every run that ever wrote it. _plot.txt is now written on a stills run too - it is the only per-image scaling table there is, and the columns a sweep would fill come out nan - while the picture stays rotation-only, as only the rotation pre-scan builds the projection it draws. "merged" reads nan rather than 0 where no merge stands behind the run, so --no-merge no longer looks like a sweep every frame of which was thrown out. The picture's contrast now comes from the background instead of the peaks: the ramp saturates at eight times the median measured pixel, where it used to saturate at the brightest 0.1 % as the preview and the viewer do. That percentile belongs to the Bragg spots, so the background - which is what a shadow is read off, being a place where it is MISSING - sat in the first few per cent of the scale and rendered as a flat white. The median is pure background whatever the crystal, and eight times it falls between the 94th and the 99th percentile of the projection on every set measured. Two times the median, the first value tried, falls at the 73rd to 90th instead and floods the inner half of the detector to a flat indigo, hiding the deficit at the other end of the scale. The colours are untouched - they are the viewer's, from common/ColorScale.h - and only the intensity mapping moves. Processing is unchanged: p.hkl and p.mtz are byte-identical before and after on a rotation sweep, and the wall clock does not move. rugnux_stills_ab.py reads scale_G from _plot.txt instead of the retired file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013nW6FNRP1bBJJ8pfHiByAT
8.9 KiB
Rugnux
rugnux is the offline crystallographic data-analysis tool of Jungfraujoch — the
data-processing half of the system (see Naming for where the name comes from).
It takes an existing HDF5 dataset, runs the full analysis pipeline — spot finding, indexing,
geometry refinement, Bragg integration and (optionally) scaling and merging — and writes the
results to a _process.h5 file, plus reflection files (.mtz/.cif/.hkl) when merging is
requested.
It runs the same analysis code as the online and interactive tools, just driven from the command line over a file rather than a live detector stream.
rugnux {<options>} <input.h5>
Run it with no arguments to print the usage.
Note.
rugnuxis under very active development. This page describes the tool and its options at a high level; the authoritative, always-current list of options is the program's own usage message — runrugnuxwith no arguments.
:local:
:depth: 2
Quick start
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, marCCD or SMV sweep works too (see What Rugnux reads)
— and names its output files from -o:
# 1. everything from the data - index, integrate, scale and merge with the defaults
rugnux -o myrun dataset_master.h5
# 2. with a reference dataset of the same crystal form: it fixes the space group and the cell,
# resolves the indexing ambiguity, and hands over its R-free set
rugnux -o myrun -z reference.mtz dataset_master.h5
# 3. with a known structure: R-work / R-free and sigma_A-weighted 2mFo-DFc / mFo-DFc maps
rugnux -o myrun --model model.pdb dataset_master.h5
# 4. with the space group and the cell pinned (-S takes either spelling: P43212 or 96)
rugnux -o myrun -S P43212 -C 79,79,38,90,90,90 dataset_master.h5
Parallelism needs no asking for: a run already uses the machine's threads. -N is there to limit
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 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_plot.txt 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 CC1/2 falls through 0.30. Every reflection file is
resolution-trimmed automatically (
--resolution-cutoff cc-logistic, one shell past the crossing);--resolution-cutoff offkeeps the full measured range,--scaling-high-resolutionfixes 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
ffbidxindexer needs a cell; on a rotation sweep it tends to degrade low-symmetry cases, so prefer recipe 1 and let the run determine both (see Rotation data).-Stakes a Hermann-Mauguin symbol (P43212) or a space-group number (96), whichever is to hand. - Anomalous data are there without
-A. A rotation merge always keeps the Bijvoet split: a default run's.mtzcarriesI(+)/I(-)besideIMEAN, and its.hklthe ±hkl mates —FRIEDELS_LAW= TRUEin the report says how the statistics were counted, not that the signal was averaged away. What-Achanges is the counting basis and the error model: each hand becomes a merged observation of its own, so multiplicity, completeness and ⟨I/σ⟩ are counted anomalously and the sigmas are refitted on the Bijvoet-separated merge. Reach for it for anomalous statistics; the signal itself is in the file either way. (Stills merges carry no split by default — there-Ais what creates one.) - A model names the enantiomorph. Where the data accept the model — it is tested against a
null of the same model in random orientations, and
MODEL_FIT=in the report says the verdict —--modelsettles which of P41212 and P43212 the merged reflections are labelled with — a choice no merged intensity can make. It is a label and nothing more: the two groups have the same rotation operations, so no reflection moves, and in particular I(+) and I(-) are left exactly as measured. Whether the model agrees with the data about the hand is then a real question, and the anomalous difference map answers it — a run says so when the density at the model's atoms comes out inverted. -zand--modeloverlap but are not the same. A reference MTZ steers the processing from the start; a model scores the merge and settles the frame it is written in — where the data accept it; a model they reject changes nothing. Either resolves an indexing ambiguity, which on serial data decides whether the merged intensities are usable at all.--scaling-high-resolution <d>, where the resolution is already known, sharpens both the space-group search and the error model.- A run wants memory in proportion to what it integrates, not to the detector: 2.5-14 GB of host RAM and 3-7 GB on the card over the datasets measured, both peaking in scaling and merging. Installing Rugnux ▸ Memory has the table and the two flags that lower it.
- Everything else is in Running Rugnux and the full Command-line options.
The rest of the manual
One page per job, so the answer needed is near the top of a short page:
- What Rugnux does — the pipeline from images to merged reflections, in order. Read this one first.
- Installing Rugnux — packages, the release archive, GPU drivers, building from source, hardware.
- What Rugnux reads — will it open your data: NXmx / EIGER masters, PILATUS miniCBF, marCCD and SMV sweeps, one sweep per input.
- Running Rugnux — a first run in detail, rotation and serial data, and every file a run writes.
- Rugnux with other programs — the reflection-file conventions, the unmerged export, and worked command lines for phenix, REFMAC, POINTLESS / AIMLESS, careless and Phaser.
- The results report — the
KEY= valueinterface, sweep quality and the anisotropy section. - Advanced usage — reference data and the indexing ambiguity, model validation, re-merging, and the full command-line option tables.
- Detector calibration — the geometry from a calibrant's powder rings
(
--mode calibration). - CPU/GPU data analysis — the algorithms behind all of it.
Where it fits among the three analysis tools
| Tool | Mode | Driven by | Output |
|---|---|---|---|
jfjoch_broker |
Online, real-time streaming analysis on FPGA + GPU | HTTP/REST + ZeroMQ | Live results and statistics, images streamed to jfjoch_writer |
jfjoch_viewer |
Interactive, on-screen exploration | Qt desktop application | On screen; a processing job can write the same files as rugnux |
rugnux |
Offline batch processing of a stored dataset | Command-line interface | _process.h5, and .mtz/.cif/.hkl when merging |
Use rugnux to re-analyse data after acquisition, to experiment with processing
parameters, or to produce merged intensities for downstream structure solution.