diff --git a/docs/RUGNUX_INTEGRATION.md b/docs/RUGNUX_INTEGRATION.md index 3033d38c6..0bcf2b6c6 100644 --- a/docs/RUGNUX_INTEGRATION.md +++ b/docs/RUGNUX_INTEGRATION.md @@ -63,6 +63,23 @@ and the wavelength, on a dataset of its own behind the reserved `HKL_base` — s the file is given the right edge. The Bijvoet columns are present on any rotation merge, with or without `-A`; a stills merge has no Bijvoet split and the file then stops after `F SIGF FreeR_flag`. +There is deliberately **no `DANO`/`SIGDANO`** pair, the anomalous difference columns a CCP4 merged +file usually carries. They are a restatement rather than a measurement: checked column against +column on a `ctruncate` file, `DANO` is `F(+) − F(-)` to the last bit and `SIGDANO` is +`√(σ(+)² + σ(−)²)` to the last bit, on every reflection — the quadrature sum is the convention +whether or not the two mates came from one scale model, and no correlation correction is applied by +anybody. Every program in the phasing routes below reads the Bijvoet columns directly and forms the +difference itself, and CCP4's own phasing engines prefer them: `bp3` and `afro` want `F+/SF+/F-/SF-` +and tell a user holding `F`/`DANO` to convert *to* that form, and `mtz2sca` ranks `I(+/-)` over +`F(+/-)` over `F/DANO`. Where the pair is genuinely wanted — `fft`'s anomalous-difference Fourier +takes a `DANO` label and has no other spelling — one command makes it, with the `ISYM` column that +belongs beside it: + +``` +ctruncate -hklin myrun.mtz -hklout myrun_ct.mtz \ + -colin '/*/*/[IMEAN,SIGIMEAN]' -colano '/*/*/[I(+),SIGI(+),I(-),SIGI(-)]' +``` + ## The unmerged export `_unmerged.mtz` holds every integrated observation, before scaling and merging, in the column @@ -134,20 +151,51 @@ independently determined orientation matrix agrees with rugnux's to well under a The reflection files are inputs to other suites, and the handover has a few conventions worth one line each. These are the minimum commands that get each program running on rugnux output. -**phenix.** The merged files carry both the mean intensity and the Bijvoet pairs, and phenix -refuses to choose between two equally usable intensity arrays — `Sorry: Multiple equally suitable -arrays of observed xray data found.` (from the mmCIF the message at least lists the choices; from -the MTZ it names none, which is where a user is genuinely stuck). It is one behaviour surfacing in -both formats; only the label vocabulary differs, following each format's own column names — the -MTZ label fails on the mmCIF with `Sorry: No matching array`: +**phenix.** The merged files carry both the mean intensity and the Bijvoet pairs, and a phenix +program that has not said which it wants stops on the pair of them — from the MTZ and from the +mmCIF alike, each listing its own format's labels: ``` -phenix.xtriage myrun.mtz xray_data.obs_labels=IMEAN,SIGIMEAN -phenix.xtriage myrun.cif xray_data.obs_labels=intensity_meas +Sorry: Multiple equally suitable arrays of observed xray data found. + +Possible choices: + myrun.mtz:IMEAN,SIGIMEAN + myrun.mtz:I(+),SIGI(+),I(-),SIGI(-) +``` + +Two things are worth knowing before reading that as a fault in the file. The tie is between the two +**intensity** arrays and nothing else: iotbx scores `F`/`SIGF` and `F(+)`/`F(-)` below them, so they +are never in the running and writing amplitudes as well as intensities is not what causes this. And +**ctruncate's own output ties in the same place** — put any merged data through CCP4's truncate step +and phenix asks the same question of the result, because a mean intensity array and an anomalous one +score equally whenever the calling program has expressed no preference. The only file change that +removes the tie is dropping one of the two, and dropping the Bijvoet columns would take the anomalous +signal — and the whole [SHELX route](#experimental-phasing-with-shelx) — with it. + +So the answer is a label. The parameter name differs by program, which is the part that catches +people out: + +``` +phenix.xtriage myrun.mtz xray_data.obs_labels=IMEAN +phenix.xtriage myrun.mtz "xray_data.obs_labels=I(+)" # the Bijvoet array instead phenix.refine model.pdb myrun.mtz miller_array.labels.name=IMEAN ``` -(phenix.refine takes a different parameter name for the same choice.) +`IMEAN` on its own is enough — the match is on a substring — and `IMEAN,SIGIMEAN` and the +fully-qualified `scaling.input.xray_data.obs_labels=` work equally. Quote the anomalous one: the +parentheses are shell syntax otherwise. The same behaviour appears on the mmCIF in that format's own +vocabulary, and a label from one format does not work on the other (`Sorry: No matching array`): + +``` +phenix.xtriage myrun.cif xray_data.obs_labels=intensity_meas +phenix.xtriage myrun.cif xray_data.obs_labels=pdbx_I_plus +``` + +**A program that states a preference needs none of this.** `phenix.hyss`, `phenix.find_peaks_holes`, +`phenix.molprobity` and the data import behind `phenix.autosol` ask for anomalous data by preference, +which breaks the tie for them. `phenix.hyss myrun.mtz n_sites=6 scattering_type=S` opens the file +with no labels given, reports `Miller array info: myrun.mtz:I(+),SIGI(+),I(-),SIGI(-)`, and forms the +anomalous differences itself. **The R-free convention.** `FreeR_flag` is **0 = work, 1 = free** (the phenix/CNS convention; 5 % free by default). phenix.refine detects that on its own. **REFMAC5 does not**: its default