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"