From 2148bacb7e9ce7b680446d501dcd4a718ebb0461 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Mon, 2 Nov 2026 08:16:45 +0100 Subject: [PATCH] docs: --export-observations and --stills-window-sigmas in the option list, ISA_ASYMPTOTIC in the report keys Both options are accepted by rugnux but were missing from RUGNUX_CLI.md, which the usage text names as the list of every option. ISA_ASYMPTOTIC, which the report's own explanation mentions, had no row in RUGNUX_REPORT.md. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQqrcrEZy6XBUCMZvyT --- docs/RUGNUX_CLI.md | 2 ++ docs/RUGNUX_REPORT.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index 15dd2cc6f..56dab1a29 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -323,6 +323,7 @@ serial stills; `fft` (GPU) / `fftw` (CPU) index **de novo** and suit strong rota | `--export-unmerged` | Write `_unmerged.mtz`, an unmerged MTZ (POINTLESS column layout), for aimless / pointless. **On by default** whenever there is an output prefix. Rotation partials are summed into one full per reflection, and on a rotation merge `I`/`SIGI` are the merge's own scaled fulls, those it rejected left out. Otherwise intensities carry the deterministic per-reflection corrections and nothing else — Lorentz and polarization in `LP`, sensor efficiency in `QE`, flight path in `FLIGHT` — while the partiality is not divided out and the per-image scale is not applied. Written in `--mode mx` and `--mode scale`, and with `--no-merge`. See [The unmerged export](RUGNUX_INTEGRATION.md#the-unmerged-export) | | `--no-export-unmerged` | Do not write `_unmerged.mtz`. It is the largest file a run produces, so a run whose observations are not going to another scaling program can skip it | | `--export-unmerged-partials` | Write `_unmerged_partials.mtz`, the integrated observations unscaled, each partial as its own row (one batch per image), for a reading program that sums and scales them itself (careless). Off by default, and independent of `--export-unmerged` | +| `--export-observations` | Stills diagnostic: write `_obs.mtz`, every integrated observation of the written merge as one row - its signed excitation error, partiality, the run's rocking width, raw I/σ and background, corrections, scale, the σ the merge weighted it with, the frame's cell and orientation, and a bit for each merge test it fails (observations the merge drops included). Processing is unchanged | | `--dump-observations ` | Diagnostic: write the unmerged fulls of every rotation 3D combine to `` as text, for a comparison with XDS | ### Integration @@ -342,6 +343,7 @@ serial stills; `fft` (GPU) / `fftw` (CPU) index **de novo** and suit strong rota | `--overlap ` | What to do where two predicted reflections share signal pixels: `off` \| `reject` \| `exclude` (default `exclude`). A shared pixel belongs to the nearer centre; without this a crowded reflection reads high on a dense pattern. `exclude` drops the shared pixels from the profile fit, which renormalises itself, and keeps the reflection; `reject` instead drops the whole reflection when too little of its profile is cleanly its own. `--integrator boxsum` has no profile to renormalise, so only `reject` acts there | | `--overlap-minpk ` | Least fraction of a reflection's expected profile that must be usable for it to be kept (default 0.75, XDS `MINPK`). Governs both the fraction that must be **readable** — not masked, untrusted, in a gap or overloaded — in every profile mode, and, under `--overlap reject`, the fraction that must be cleanly its own. Under `--integrator boxsum` any unreadable pixel discards the disk outright and the reject fraction goes by disk *area*, which cuts harder | | `--flight-path ` | What the diffracted beam crosses between the sample and the detector: `air` (default) \| `helium` \| `vacuum`. A reflection arriving at angle α to the detector normal flies `D/cos α` instead of `D`, so it crosses more of the medium and reads low; the factor is `exp(D/L·(1/cos α − 1))`, with `L` the attenuation length of the medium from the NIST tabulation and `D` and λ as stated by the file — nothing in it is fitted. **Nothing in NXmx, and no field of any master file Rugnux reads, describes the medium**, so it cannot be auto-detected and is assumed; the report states which medium was assumed and what it was worth (`FLIGHT_PATH`, `FLIGHT_PATH_WILSON_B`). Nor can it be inferred from the implied transmission — in this corpus a confirmed helium station sits at 51 % implied air transmission and a confirmed air station at 63 %. In air the term is +1.5 % at α = 55° for 18 keV over 160 mm and several-fold below 5 keV, where stations use helium precisely because air is unusable; helium attenuates ~1/600 of air, and vacuum leaves intensities untouched | +| `--stills-window-sigmas ` | Stills: half-width of the prediction window in units of the run's measured rocking width - every frame predicts the reflections within `k` rocking widths of the Ewald sphere (default 2) | | `--prediction-mosaicity ` | Diagnostic: fix the rocking width (deg) the **prediction** window opens to, leaving partiality on the per-image σ_M. The two are one number by default, so a σ_M that moves takes the integrated reflection population with it | ### Geometry overrides diff --git a/docs/RUGNUX_REPORT.md b/docs/RUGNUX_REPORT.md index db497573f..234195189 100644 --- a/docs/RUGNUX_REPORT.md +++ b/docs/RUGNUX_REPORT.md @@ -252,7 +252,7 @@ The keys most scripts read, by section; the rest of this page explains the ones | `I_OVER_SIGMA`, `R_MEAS`, `CC_HALF`, `WILSON_B` | The overall merging statistics; the shell table beside them is in the comment lines. `R_MEAS` (and `R_MERGE`, `R_PIM`) rotation only, `R_SPLIT` stills only | | `SIGANO`, `CC_ANOM`, `FRIEDELS_LAW` | The anomalous signal, and whether Friedel pairs were merged (`FALSE` with `-A`) | | `ERROR_MODEL_A`, `ERROR_MODEL_B`, `ISA` | The error model in XDS's convention and ISa = 1/sqrt(a·b); `ISA= undetermined` where b is zero within its error, so 1/b would be noise. Rotation only for `ISA` | -| `ISA_LOW`, `ISA_HIGH` | Rotation data: the 95% interval of `ISA` from a bootstrap over the reflections (100 replicates, fixed draws). With `ISA= undetermined`, `ISA_LOW` alone is a lower bound: b reaches zero inside its interval, so only ISa ≥ `ISA_LOW` is measured. Both absent where there is no fit to resample (b out of reach of the data, or a on its bound) and on stills, which write no `ISA` | +| `ISA_LOW`, `ISA_HIGH` | Rotation data: the 95% interval of `ISA` from a bootstrap over the reflections (100 replicates, fixed draws). With `ISA= undetermined`, `ISA_LOW` alone is a lower bound: b reaches zero inside its interval, so only ISa ≥ `ISA_LOW` is measured. Both absent where there is no fit to resample (b out of reach of the data, or a on its bound) and on stills, which write no `ISA`. `ISA_ASYMPTOTIC` (`--developer`) is the ISa of the strong-reflection tier alone | | `ERROR_MODEL_C` | Stills only: the partiality term of the stills error model, σ² = a(σ₀² + b·I² + c·((1−p)/p)²·I²) in the same convention. A stills report writes no `ISA` ([below](#the-stills-error-model)), and `ERROR_MODEL_B= undetermined` where b is zero within its error | | `R_WORK`, `R_FREE` | Section 5: the model as placed against these data ([below](#model-validation)); the refined model's are `REFINE_R_WORK`/`REFINE_R_FREE` | | `R_FREE_FLAGS` | Section 5: the free set both are read on - `DRAWN` by this run, inherited from the `-z` `REFERENCE`, or from the `--free-flags` `FILE` |