mx/Jungfraujoch
2
1
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases 71 Wiki Activity

rugnux: measure and report diffraction anisotropy

Browse Source 
rugnux now says whether a dataset's fall-off is direction-dependent, and by
how much. It corrects nothing and truncates nothing: no intensity is changed,
no reflection is dropped on a directional criterion, and the written files do
not depend on direction at all.

Two quantities, because they are not the same thing. The anisotropic deltaB is
the range of the principal components of the anisotropy tensor - a rate of
fall-off. The diffraction limit along each principal direction is where
<I/sigma(I)> in a 20 degree cone falls through 2 - where signal actually runs
out. One battery case has only 0.28 A between its directional limits and a 58x
ratio in cone <I/sigma>, so reporting either alone would miss it.

The tensor is a Laue-constrained deviatoric ADP tensor fitted on INTENSITIES
with no positivity cut, by weighted Gauss-Newton over 12 shells x 60
directions with a free constant per shell. Fitting amplitudes after a
positivity cut, which is what xtriage and ctruncate do, destroys about 40% of
the measured anisotropy - the cut keeps only the positive noise excursions in
whichever direction has died, and that is the direction carrying the signal.
Against the same 38 merged files rugnux reads 1.24x xtriage's eigenvalue
spread and 1.61x ctruncate's; on strong near-isotropic data all three agree to
a few percent, and they diverge exactly where a direction has died.

The verdict is gated three ways - not detected, detected, or cannot determine
- against the dataset's own systematic floor, measured in the tensor
directions its Laue symmetry forbids. The floor cannot be measured on merged
reflections, which have exact Laue symmetry by construction, so the floor is
taken from the unmerged observations and the verdict is "cannot determine"
without them. Triclinic has no forbidden subspace and always returns cannot
determine. A cubic crystal returns exactly zero, because that is its symmetry
and not a measurement.

A second axis reports the resolution signature: a genuine Debye-Waller
fall-off is linear through the origin in s^2, and a deficit that is flat is
something else. Magnitude alone had promoted a crystal that is 68% not a
Debye-Waller B into the top five of this battery; it now reads not detected
with the caution attached.

Following Sheriff & Hendrickson (1987) Acta Cryst. A43, 118-121 for the tensor
and Popov & Bourenkov (2003) Acta Cryst. D59, 1145-1153 for the estimator.

The directional limits are written as jfjoch_ local mmCIF items rather than
_reflns.pdbx_aniso_diffraction_limit_*, whose dictionary definition is
explicitly the ellipsoid fitted to a diffraction cut-off surface - a
construction rugnux does not perform. The generic anisotropic B tensor items
are written.

Changes no existing number; only REPORT_VERSION moves, 1 to 2.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CHMmeM1d489zvNFT7ZMN2P
This commit is contained in:
leonarski_f
2026-08-25 19:13:16 +02:00
co-authored by Claude Opus 5
parent 0f5a6e41d6
commit 80e10f51b3
13 changed files with 1842 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
image_analysis/WriteReflections.cpp
+42
View File
@@ -274,6 +274,48 @@ void WriteMmcifReflections(const std::vector<MergedReflection> &reflections,
if (std::isfinite(statistics.radiation_damage_delta_b))
out << "_reflns.jfjoch_radiation_damage_relative_B " << Fmt(statistics.radiation_damage_delta_b, 2)
<< " # relative-B first->last over the run (A^2); + = high-res fades with dose\n";
// Diffraction anisotropy. The eigen-decomposition of the anisotropy tensor has standard PDBx
// items; the eigenvalues there must be non-negative, and only the deviatoric part of the tensor
// is determined at all (its isotropic part is degenerate with the overall scale), so they are
// written relative to the weakest direction - eigenvalue_3 is 0 by construction and
// eigenvalue_1 is the anisotropic deltaB. The eigenvectors are in the PDB orthogonalisation
// convention, which is the one gemmi (and hence rugnux) uses throughout.
//
// The directional diffraction LIMITS are deliberately NOT written as
// _reflns.pdbx_aniso_diffraction_limit_*: the dictionary defines those as the semi-axes of an
// ellipsoid fitted to a diffraction cut-off surface, which is a different construction from the
// one below and one rugnux does not perform - it cuts nothing on a directional criterion. They
// go under the jfjoch local prefix with their own definition instead.
const auto &an = statistics.anisotropy;
if (an.n_reflections > 0 && an.n_cells > 0 && std::isfinite(an.delta_b)) {
out << "_reflns.pdbx_orthogonalization_convention pdb\n";
for (int i = 0; i < 3; ++i) {
out << "_reflns.pdbx_aniso_B_tensor_eigenvalue_" << (i + 1) << " "
<< Fmt(an.eigenvalue[i] - an.eigenvalue[2], 2) << "\n";
for (int j = 0; j < 3; ++j)
out << "_reflns.pdbx_aniso_B_tensor_eigenvector_" << (i + 1) << "_ortho[" << (j + 1)
<< "] " << Fmt(an.eigenvector[i][j], 4) << "\n";
}
out << "_reflns.jfjoch_aniso_delta_B " << Fmt(an.delta_b, 2)
<< " # range of the principal components (A^2), fitted on intensities\n";
if (std::isfinite(an.delta_b_linear))
out << "_reflns.jfjoch_aniso_delta_B_linear " << Fmt(an.delta_b_linear, 2)
<< " # deltaB implied by the s^2 slope alone: what a Debye-Waller B accounts for\n";
out << "_reflns.jfjoch_aniso_shape " << AnisotropyShapeCode(an.shape)
<< " # resolution signature of the directional deficit\n";
if (std::isfinite(an.floor))
out << "_reflns.jfjoch_aniso_floor " << Fmt(an.floor, 3)
<< " # deltaB this data set's own systematic error could manufacture (A^2)\n";
if (std::isfinite(an.significance))
out << "_reflns.jfjoch_aniso_significance " << Fmt(an.significance, 2)
<< " # deltaB(linear) / floor\n";
out << "_reflns.jfjoch_aniso_verdict " << AnisotropyVerdictCode(an.verdict) << "\n";
for (int i = 0; i < 3; ++i)
if (std::isfinite(an.d_min_axis[i]))
out << "_reflns.jfjoch_aniso_d_min_" << (i + 1) << " "
<< Fmt(an.d_min_axis[i], 2)
<< " # <I/sigma(I)> = 2 in a 20 deg cone about eigenvector " << (i + 1) << "\n";
}
out << "#\n";
// Per-batch relative-B curve (the radiation-damage monitor, rotation): one relative Debye-Waller B