Refinement: a larger displacement model must pass Hamilton's R-ratio test

In the displacement-model choice, a candidate with more displacement
parameters than the incumbent (TLS bodies over a B per atom, a U per atom over
either) now also has to lower R-work by more than its extra parameters
account for: R_small / R_large above Hamilton's critical ratio
sqrt(b / (n - m) F(b, n - m, 0.05) + 1), n the working reflections, m the
larger model's displacement parameters (the hypothesis trials hold the
positions), b the extra ones, counted unrestrained. The F point is Paulson's
normal approximation (within 0.3% of the exact value at 5/100 degrees of
freedom and closer above). Each trial records its displacement parameters.

On the 2.0-2.8 A sets where a U per atom was taken on -LL free alone, the
test now refuses it (1-1.3 working reflections per U parameter); where TLS was
taken over the B per atom it passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7
This commit is contained in:
leonarski_fandClaude Opus 5.5 committed 2026-11-18 12:36:49 +01:00
1 parent a784245627
commit e0f1cd6d92
2 files changed
+32 -1

No files matched your search

@@ -109,6 +109,29 @@ bool FreeSetPrefers(const std::vector<float> &r_terms, double nll_free, const st
const double se = n > 1 ? std::sqrt(std::max(sum2 - sum * sum / n, 0.0) * n / (n - 1)) : 0.0;
return nll_free < nll_free_b && sum < se;
}
// The upper alpha point of the F distribution with d1 and d2 degrees of freedom, by Paulson's normal approximation of
// F^(1/3) (z the normal deviate of alpha) - accurate to a few percent at the counts a displacement model has.
// Following Paulson (1942) Ann. Math. Statist. 13, 233-235
double FQuantile(double d1, double d2, double z) {
const double u = 2.0 / (9.0 * d1), v = 2.0 / (9.0 * d2), a = 1.0 - v, c = 1.0 - u;
const double q = a * a - z * z * v;
const double x = (a * c + std::sqrt(std::max(a * a * c * c - q * (c * c - z * z * u), 0.0))) / q;
return x * x * x;
}
// Of two displacement models, the one with more parameters is taken only where R-work falls by more than its extra
// parameters account for: R_small / R_large above Hamilton's ratio sqrt(b / (n - m) F(b, n - m, 0.05) + 1), n the
// working reflections, m the larger model's displacement parameters (the trials hold the positions) and b its extra
// ones - each counted unrestrained, the conservative count. True where `t` has no more parameters than `s`.
// Following Hamilton (1965) Acta Cryst. 18, 502-510, as Merritt (2012) Acta Cryst. D68, 468-477 and PDB-REDO decide
// the B model by it
bool HamiltonPasses(const RefinementWeightTrial &t, const RefinementWeightTrial &s, int n_work) {
const int b = t.adp_parameters - s.adp_parameters;
if (b <= 0)
return true;
const int dof = n_work - t.adp_parameters;
return dof > 0 && s.r_work / t.r_work > std::sqrt(b / double(dof) * FQuantile(b, dof, 1.6449) + 1.0);
}
// Every other step is taken on the work-set target (WorkTarget) where it lowers it by more than this, relative.
constexpr double TARGET_TOLERANCE = 1e-4;
// The rounds of RefineOnce's weight and displacement-model choice (4b.): the first from the model as given, each
@@ -2539,6 +2562,13 @@ TrialOutcome RunTrial(TrialSlot slot, XyzCalibrations &calibrations, const std::
t.ncs_rmsd = NcsRmsd(*ncs, ctx.XyzB());
if (hyp != nullptr)
t.adp = hyp->name;
// the displacement parameters: a B per refinable atom, the TLS bodies' 20 each beside it, or a U per atom
int atoms_b = 0;
for (int i : refinable)
atoms_b += !ctx.atoms[i]->is_hydrogen();
t.adp_parameters = kind == AdpHypothesis::Kind::Anisotropic ? 6 * static_cast<int>(u_atoms.size())
: kind == AdpHypothesis::Kind::Tls ? atoms_b + 20 * static_cast<int>(hyp->bodies.size())
: atoms_b;
MeasureWorkTarget(ctx, topo, ncs, ncs_sigma, t);
out.line = fmt::format("{}X-ray weight {:.3g}, {} {}{}: R-work {:.4f}, R-free {:.4f}{}, target {:.6g}, rmsd bonds "
"{:.4f} A, angles {:.2f} deg{}{}",
@@ -4377,7 +4407,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector<Me
continue;
logger.Info("Refinement, displacements: {}", outcomes[k].line);
result.adp_trials.push_back(t);
if (displaces(t, trial(best)))
if (displaces(t, trial(best)) && HamiltonPasses(t, trial(best), result.n_work))
best = static_cast<int>(k);
}
// (the model where the weights ended keeps the displacement model a round before chose for it, its U held by
@@ -163,6 +163,7 @@ struct RefinementWeightTrial {
// The work-set target's terms where the trial ended (RefineOnce's WorkTarget): -ln L of the working reflections,
// the restraints' sum of the geometry (with the NCS restraints at ncs_sigma) and that of the B similarity.
double nll_work = NAN, e_geometry = NAN, e_b = NAN;
int adp_parameters = 0; // the displacement model's parameters (HamiltonPasses)
std::vector<float> free_r_terms; // R-free as one term per free twin group (FreeRTerms), for paired comparisons
GeometryStatistics geometry;
bool within_bounds = false; // the geometry bounds the choice is made inside