From 805c3a14c39bb085569f643da5d81e7da39749c4 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 08:04:28 +0100 Subject: [PATCH] Refinement: the free set decides the weights and the displacement model only The free set now decides only the X-ray weights of the positions and the B factors, the NCS restraints' sigma, the displacement model (isotropic / TLS cuts / U per atom), the reading of the model's TLS groups, and whether the refinement displaces the model as given. Each of these takes a candidate over the incumbent only where both free measures agree: its -ln L of the free reflections lower and its R-free not higher by more than the standard error of the incumbent's, R_free / sqrt(2 N_free) (Tickle, Laskowski & Moss 2000), in place of the fixed R-free tie of 0.001 (which alone decided most choices). The approach of requiring free measures to agree follows PDB-REDO (Joosten et al. 2012, 2014). Every other decision now uses the work-set target - w (-ln L work) + E_geometry (with NCS at its sigma), plus w_B (-ln L work) + E_B where B is refined - at the weights the two candidates share, a step taken where it lowers that by more than 1e-4 relative and the geometry stays within bounds where it was: the trajectory's steps (which now end where the last step taken ended, not at the best step on the free set), the final ladder's step, the step after the displacement choice, the second round, the solvent build's rounds, the side-chain field's kept test and the population's child. A candidate at other weights is not compared on a target that changed with them (the positions and B minimise separate targets, whose sum a weight change can raise while it lowers each) and is left to the free-set rule. The placement's rigid bodies and B per residue are kept where they lower -ln L work. Each weight trial now records -ln L work and the restraint sums (RefinementWeightTrial::nll_work, e_geometry, e_b) and logs its target. Not changed: the twin-law choice (a paired free-set z against its null, a model hypothesis test with its own standard error), MR and model validation. No k-fold cross-validation yet for free sets under 500 reflections. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7 --- .../structure_refinement/Refinement.cpp | 255 ++++++++++-------- .../structure_refinement/Refinement.h | 3 + 2 files changed, 152 insertions(+), 106 deletions(-) diff --git a/image_analysis/structure_refinement/Refinement.cpp b/image_analysis/structure_refinement/Refinement.cpp index ac0ffc781..db574ae51 100644 --- a/image_analysis/structure_refinement/Refinement.cpp +++ b/image_analysis/structure_refinement/Refinement.cpp @@ -91,8 +91,16 @@ constexpr double REPULSION_MARGIN = 0.5; // A: pairs this much beyond their co constexpr double MAX_RMSD_BONDS = 0.02, MAX_RMSD_ANGLES = 2.0; // The minimiser's iterations per macro-cycle where the solvent build refines the solvent alone. constexpr int SOLVENT_ITERATIONS = 10; -// R-free differences smaller than this do not decide between two weights: the tighter geometry is taken. -constexpr double R_FREE_TIE = 0.001; +// The free set decides the weights and the displacement model alone, and only where both of its measures agree: a +// candidate is preferred to the incumbent where its -ln L of the free reflections is lower and its R-free not higher +// by more than the standard error of the incumbent's, R_free / sqrt(2 N_free). +// Following Tickle, Laskowski & Moss (2000) Acta Cryst. D56, 442-450 (the standard error of R-free), as PDB-REDO +// decides on more than one free measure, Joosten, Long, Murshudov & Perrakis (2014) IUCrJ 1, 213-220 +bool FreeSetPrefers(double r_free, double nll_free, double r_free_b, double nll_free_b, int n_free) { + return nll_free < nll_free_b && r_free < r_free_b + r_free_b / std::sqrt(2.0 * n_free); +} +// 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 // after it from the model the one before ended with. // The minimiser (RefinementMinimiser): a solve stops where an iteration lowers the target by less than this, @@ -1564,9 +1572,10 @@ void RefinePlacement(Context &ctx, bool group_b, RefinementResult &result) { if (body.size() >= 50) bodies.push_back(body); } - // Each step is kept only where it lowers R-free beyond the tie: a deposited model was refined atom by atom - // already, and moving its chains or shifting its B factors residue by residue then only makes it worse. - RFactors before = ctx.Refit(); + // Each step is kept only where it lowers the -ln L of the working reflections, the target it minimised (the free + // set decides the weights and the displacement model alone). + ctx.Refit(); + double before = ctx.Score().nll_work; if (!bodies.empty()) { const std::vector pos0 = ctx.Positions(); std::vector q(6 * bodies.size(), 0.0); @@ -1577,13 +1586,15 @@ void RefinePlacement(Context &ctx, bool group_b, RefinementResult &result) { const CancelCheck cancel_check(ctx); ceres::Solve(cancel_check.Options(30), problem, q.data(), &summary); rb->Place(q.data()); - const RFactors after = ctx.Refit(); - if (after.r_free < before.r_free - R_FREE_TIE) { + ctx.Refit(); + const double after = ctx.Score().nll_work; + if (after < before) { result.rigid_bodies = static_cast(bodies.size()); before = after; } else { ctx.SetPositions(pos0); - before = ctx.Refit(); + ctx.Refit(); + before = ctx.Score().nll_work; } } if (group_b) { @@ -1596,7 +1607,8 @@ void RefinePlacement(Context &ctx, bool group_b, RefinementResult &result) { const CancelCheck cancel_check(ctx); ceres::Solve(cancel_check.Options(30), problem, q.data(), &summary); gb->Place(q.data()); - result.group_b = ctx.Refit().r_free < before.r_free - R_FREE_TIE; + ctx.Refit(); + result.group_b = ctx.Score().nll_work < before; if (!result.group_b) ctx.SetB(b0); } @@ -2246,6 +2258,25 @@ struct TrialOutcome { int evaluations = 0; }; +// The work-set target's terms of the model as it stands (RefinementWeightTrial), at the last Refit()'s fit: what every +// decision but the weights' and the displacement model's is made on (WorkTarget). +void MeasureWorkTarget(Context &ctx, const RefinementTopology &topo, const NcsCopies *ncs, double ncs_sigma, + RefinementWeightTrial &t) { + const RefinementScore sc = ctx.Score(); + t.nll_work = sc.nll_work; + t.nll_free = sc.nll_free; + const std::vector> xyzb = ctx.XyzB(); + t.e_geometry = EvaluateRestraints(RestraintsNow(ctx, topo, ncs, ncs_sigma), xyzb, nullptr); + t.e_b = EvaluateRestraints(BRestraintsNow(ctx, topo), xyzb, nullptr); +} + +// The work-set target of a trial at the X-ray weights w (positions) and adp (B, 0: held), its NCS restraints at its own +// sigma: what a trial at those weights minimises, the X-ray term of the positions and the geometry, and that of the B +// factors and the B similarity where they are refined. +double WorkTarget(const RefinementWeightTrial &t, double w, double adp) { + return w * t.nll_work + t.e_geometry + (adp > 0 ? adp * t.nll_work + t.e_b : 0.0); +} + // The X-ray target's gradient on the positions, its squared norm over `refinable`, for the atoms as they are. double XrayGradientNorm(Context &ctx, const std::vector &refinable) { std::vector> g; @@ -2471,16 +2502,16 @@ TrialOutcome RunTrial(TrialSlot slot, XyzCalibrations &calibrations, const std:: t.ncs_rmsd = NcsRmsd(*ncs, ctx.XyzB()); if (hyp != nullptr) t.adp = hyp->name; - t.nll_free = ctx.Score().nll_free; - out.line = fmt::format("{}X-ray weight {:.3g}, {} {}{}: R-work {:.4f}, R-free {:.4f}{}, rmsd bonds {:.4f} A, " - "angles {:.2f} deg{}{}", + 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{}{}", std::string(tw.blur.empty() ? "" : "blurred, ") + (hyp != nullptr ? hyp->name + ", " : ""), w, kind == AdpHypothesis::Kind::Anisotropic ? "U" : kind == AdpHypothesis::Kind::Tls ? "residual B" : "B", adp_w > 0 ? fmt::format("refined at weight {:.3g}", adp_w) : std::string("held"), ncs == nullptr || ncs->Empty() ? std::string() : ncs_sigma > 0 ? fmt::format(", NCS at {:.3g} A (copies {:.3f} A apart)", ncs_sigma, t.ncs_rmsd) : fmt::format(", no NCS (copies {:.3f} A apart)", t.ncs_rmsd), - rf.r_work, rf.r_free, fmt::format(", -LL free {:.1f}", t.nll_free), + rf.r_work, rf.r_free, fmt::format(", -LL free {:.1f}", t.nll_free), WorkTarget(t, w, adp_w), t.geometry.rmsd_bonds, t.geometry.rmsd_angles, t.geometry.metal_bonds > 0 ? fmt::format(", metal bonds {:.3f} A", t.geometry.rmsd_metal) : std::string(), @@ -2859,8 +2890,8 @@ double BalancedUWeight(Context &ctx, const URestraints &restraints, const std::v // The displacements of the model as given, read where it has TLS groups whose atoms bring no U of their own: their U // from the groups, its B column taken as the total B (the U's equivalent isotropic B, as phenix.refine writes it) or as -// the residual to the groups (as REFMAC writes it), and the isotropic B as it stands - the one of the three whose -// R-free is lowest, beyond the tie in that order. `tls`: the groups, their atoms those of ctx.atoms but the hydrogens +// the residual to the groups (as REFMAC writes it), and the isotropic B as it stands - a displacement model, chosen on +// the free set (FreeSetPrefers), in that order. `tls`: the groups, their atoms those of ctx.atoms but the hydrogens // (which ride on their parents' B). Returns the R-factors of the reading kept. // Following Winn, Isupov & Murshudov (2001) Acta Cryst. D57, 122-133 (the B column total or residual to the TLS) RFactors ReadInputDisplacements(Context &ctx, const std::vector &tls, Logger &logger, RefinementResult &result) { @@ -2906,6 +2937,7 @@ RFactors ReadInputDisplacements(Context &ctx, const std::vector &tls, L readings.push_back({result.adp_input == "ANISOU" ? "ANISOU" : "isotropic", b0, aniso0}); int best = -1; std::vector rf; + std::vector nll_free; for (size_t k = 0; k < readings.size(); k++) { ctx.SetB(readings[k].b); ctx.SetAniso(readings[k].aniso); @@ -2914,9 +2946,10 @@ RFactors ReadInputDisplacements(Context &ctx, const std::vector &tls, L ctx.atoms[i]->b_iso = ctx.atoms[ctx.rider_parent[i]]->b_iso; ctx.ForgetStarts(); rf.push_back(ctx.Refit()); - logger.Info("Refinement: the model's {} TLS groups ({} atoms) read as {}: R-work {:.4f}, R-free {:.4f}", tls.size(), - tls_u.size(), readings[k].name, rf[k].r_work, rf[k].r_free); - if (best < 0 || rf[k].r_free < rf[best].r_free - R_FREE_TIE) + nll_free.push_back(ctx.Score().nll_free); + logger.Info("Refinement: the model's {} TLS groups ({} atoms) read as {}: R-work {:.4f}, R-free {:.4f}, -LL free " + "{:.1f}", tls.size(), tls_u.size(), readings[k].name, rf[k].r_work, rf[k].r_free, nll_free[k]); + if (best < 0 || FreeSetPrefers(rf[k].r_free, nll_free[k], rf[best].r_free, nll_free[best], rf[k].n_free)) best = static_cast(k); } ctx.SetB(readings[best].b); @@ -3426,10 +3459,25 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vectorran && refined->trial.within_bounds && - (!held->trial.within_bounds || refined->trial.r_free < held->trial.r_free + 2 * R_FREE_TIE)); + (refined->ran && refined->trial.within_bounds && !displaces(held->trial, refined->trial)); auto rest_b = [&](const TrialWeights &l) { return l.ncs == 0 && !first(l); }; if (refine_b && !all_ahead) run_ladder(rest_b); @@ -3552,24 +3598,17 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector from_best; // `fresh`: the first step fits the scale, the solvent and the likelihood anew (the model changed since). // `label`: the steps' name in the log. auto trajectory = [&](TrialOutcome state, bool fresh, std::vector &from_best, const char *label) { - TrialOutcome best = state; from_best.clear(); - bool state_is_best = true; - // A step taken on R-work alone is followed by one more at most: on a model refined before, R-work falls - // step after step while R-free does not, and the trajectory ends at its best anyway - a model of 490k - // atoms spent six such steps (240 s) on a round it then gave back. (On 28 refinements of 22 deposited - // models and 6 predictions the rule changed nothing.) - int since_best = 0; - for (int step = 0; step < settings.max_steps && state.ran && !ctx.Cancelled() && since_best <= 1; step++) { + for (int step = 0; step < settings.max_steps && state.ran && !ctx.Cancelled(); step++) { const double w = state.trial.weight, adp = state.trial.adp_weight, ncs_s = state.trial.ncs_sigma; std::vector trials = {{w, adp, ncs_s}}; if (step % 2 == 1 && adp > 0) { @@ -3588,27 +3627,18 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector outcomes = RunTrials(trial_slots, trials, refinable, state.pos, state.b, state.aniso, fresh && step == 0 ? nullptr : &state.fit, settings.macro_cycles, settings, ncs_p); - if (state_is_best) - from_best = outcomes; + from_best = outcomes; const int k = choose(outcomes, fmt::format("{} {}", label, step + 1).c_str()); if (k < 0) break; - const RefinementWeightTrial &t = outcomes[k].trial; // after a change of the model the first step is taken whatever it gains: it is where the change is // judged from - const bool gains = (fresh && step == 0) || displaces(t, state.trial) || - (t.within_bounds && t.r_work < state.trial.r_work - R_FREE_TIE); - if (!gains || !((fresh && step == 0) || (t.within_bounds && t.r_free < best.trial.r_free + R_FREE_TIE))) + if (!((fresh && step == 0) || advances(outcomes[k].trial, state.trial))) break; state = std::move(outcomes[k]); - state_is_best = (fresh && step == 0) || displaces(state.trial, best.trial); - since_best = state_is_best ? 0 : since_best + 1; - if (state_is_best) { - best = state; - from_best.clear(); - } + from_best.clear(); } - return best; + return state; }; if (!stopped) state = trajectory(std::move(state), false, from_best, "step"); @@ -3620,9 +3650,8 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector(std::max(settings.population, 0), trial_slots.size()); @@ -3651,7 +3680,8 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector(k); } if (best >= 0) { @@ -3686,11 +3716,11 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector(i)); TrialOutcome after = one_step(moved); - const bool kept = after.ran && after.trial.within_bounds && after.trial.r_free < unchanged.trial.r_free && - after.trial.nll_free < unchanged.trial.nll_free; - logger.Info("Side-chain field: refined from the field R-free {:.4f}, -LL free {:.1f}; from the model as it " - "was R-free {:.4f}, -LL free {:.1f}: {}", after.trial.r_free, after.trial.nll_free, - unchanged.trial.r_free, unchanged.trial.nll_free, kept ? "kept" : "not kept"); + const bool kept = after.ran && unchanged.ran && advances(after.trial, unchanged.trial); + logger.Info("Side-chain field: refined from the field R-free {:.4f}, -LL free {:.1f}, target {:.6g}; from " + "the model as it was R-free {:.4f}, -LL free {:.1f}, target {:.6g}: {}", after.trial.r_free, + after.trial.nll_free, WorkTarget(after.trial, after.trial.weight, after.trial.adp_weight), + unchanged.trial.r_free, unchanged.trial.nll_free, + WorkTarget(unchanged.trial, after.trial.weight, after.trial.adp_weight), kept ? "kept" : "not kept"); if (kept) { result.side_chain_field_kept = true; result.side_chain_field_moved = static_cast(field.moves.size()) - pruned; @@ -4132,8 +4172,8 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector trials; @@ -4156,21 +4196,21 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector= 0 && displaces(outcomes[k].trial, state.trial)) + if (k >= 0 && advances(outcomes[k].trial, state.trial)) state = std::move(outcomes[k]); } // 4. The displacement model, decided late, on the free set: from where the weights ended, TLS bodies (the // model's own groups, one per chain, the chains in TLSMD segments) with a residual B, and a U per atom at // its balanced weight and a quarter of it - each trial as long as a step, on the positions where the weights // ended, held, so that the trials differ in the displacement model alone; the model chosen then takes a - // step with the positions refined, kept where it displaces its trial (against trials a macro-cycle longer + // step with the positions refined, kept where it advances on the work-set target from its trial (against trials a macro-cycle longer // that refined the positions too, on 50 refinements of the battery R-free 0.001 lower on average and none // higher by more than 0.0015, at 78% of the evaluations). Where the geometry is out of bounds there, which // held positions cannot mend, each trial refines them too, a macro-cycle longer than a step, and no step // follows. One displaces the one before it (the first - // where the weights ended, the B factors as they are) only where its geometry is within bounds and both its - // R-free (beyond the tie) and the -ln L of the free reflections are lower: the free set is the test of the - // parameters it adds. + // where the weights ended, the B factors as they are) only where its geometry is within bounds and the free + // set prefers it (FreeSetPrefers: its -ln L of the free reflections lower, its R-free not higher beyond its + // standard error): the free set is the test of the parameters it adds. // Following Merritt (2012) Acta Cryst. D68, 468-477 (the displacement model the data support, decided by test) // The trials that would not change the choice are left out: the model's own TLS groups are tried only where // one body per chain or the finest cut lowers R-free, the cuts between those only where also the finest @@ -4298,8 +4338,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector(k); } // (the model where the weights ended keeps the displacement model a round before chose for it) @@ -4311,7 +4350,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector= 0 && hold) { // the model chosen refined on with the positions, a step from where its trial ended, kept where it - // displaces that + // advances on the work-set target from there AdpHypothesis chosen = *which[best]; chosen.bodies = state.tls; chosen.tls_b = state.tls_b; @@ -4320,7 +4359,7 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector {:.4f}{}", round, before.trial.r_free, state.trial.r_free, - kept ? "" : ", not kept"); + const bool kept = advances(state.trial, before.trial); + logger.Info("Refinement, round {}: R-free {:.4f} -> {:.4f}, target {:.6g} -> {:.6g}{}", round, + before.trial.r_free, state.trial.r_free, + WorkTarget(before.trial, state.trial.weight, state.trial.adp_weight), + WorkTarget(state.trial, state.trial.weight, state.trial.adp_weight), kept ? "" : ", not kept"); if (!kept) { state = before; result.adp_model = adp_before; break; } } - // 5. The model as given, first in order of trust: the refinement is kept where it displaces it by the rule every - // trial is held to, else the model is given back as it came (the solvent build's edits undone), so that what - // comes out is never worse on the free set than what went in - where the free set is free to the model as - // given (RefinementSettings::as_given_competes). + // 5. The model as given, first in order of trust: the refinement is kept where it displaces it on the free set + // as a weight does (displaces), else the model is given back as it came (the solvent build's edits undone), + // so that what comes out is never worse on the free set than what went in - where the free set is free to + // the model as given (RefinementSettings::as_given_competes). The work-set target cannot make this choice: + // the refinement minimised it from the model as given. if (settings.as_given_competes && state.ran && !ctx.Cancelled() && !displaces(state.trial, given.trial)) { - logger.Info("Refinement: the model as given kept (R-work {:.4f}, R-free {:.4f}), the refinement did not " - "displace it (R-work {:.4f}, R-free {:.4f})", given.trial.r_work, given.trial.r_free, - state.trial.r_work, state.trial.r_free); + logger.Info("Refinement: the model as given kept (R-work {:.4f}, R-free {:.4f}, -LL free {:.1f}), the " + "refinement did not displace it (R-work {:.4f}, R-free {:.4f}, -LL free {:.1f})", + given.trial.r_work, given.trial.r_free, given.trial.nll_free, state.trial.r_work, + state.trial.r_free, state.trial.nll_free); size_t a = 0, k = 0; for (gemmi::Chain &ch : ctx.Model().chains) for (gemmi::Residue &res : ch.residues) { diff --git a/image_analysis/structure_refinement/Refinement.h b/image_analysis/structure_refinement/Refinement.h index 5dfece5f1..b3ac73777 100644 --- a/image_analysis/structure_refinement/Refinement.h +++ b/image_analysis/structure_refinement/Refinement.h @@ -160,6 +160,9 @@ struct RefinementWeightTrial { double ncs_rmsd = NAN; // the copies' C-alpha (P) rmsd after superposition, where there are copies double r_work = 1, r_free = 1; double nll_free = NAN; // -ln L of the free reflections + // 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; GeometryStatistics geometry; bool within_bounds = false; // the geometry bounds the choice is made inside std::string adp; // the displacement model: "isotropic", "TLS ..." or "anisotropic"