diff --git a/image_analysis/WriteReflections.cpp b/image_analysis/WriteReflections.cpp index 2a7b6a4c4..ab9453d33 100644 --- a/image_analysis/WriteReflections.cpp +++ b/image_analysis/WriteReflections.cpp @@ -272,6 +272,23 @@ void WriteMmcifReflections(const std::vector &reflections, if (twinning.moment_reflections > 0) out << "_reflns.jfjoch_second_moment_I " << Fmt(twinning.second_moment, 3) << " # /^2 (untwinned 2.00, perfect twin 1.50)\n"; + // A twin law the run identified (TwinningAnalysisResult::twin_law_operator): the standard + // PDBx loop, one row per domain, the second domain related by the operator. Only meaningful + // in the true (sub)group's file, which is the one this is - in the higher group the operator + // is a symmetry element. Merohedral: the law is a lattice operation of the crystal system. + if (!twinning.twin_law_operator.empty()) { + out << "#\n"; + out << "loop_\n"; + out << "_pdbx_reflns_twin.domain_id\n"; + out << "_pdbx_reflns_twin.crystal_id\n"; + out << "_pdbx_reflns_twin.diffrn_id\n"; + out << "_pdbx_reflns_twin.operator\n"; + out << "_pdbx_reflns_twin.fraction\n"; + out << "_pdbx_reflns_twin.type\n"; + out << "1 1 1 'h,k,l' " << Fmt(1.0 - twinning.twin_law_fraction, 3) << " merohedral\n"; + out << "2 1 1 " << CifStr(twinning.twin_law_operator) << " " << Fmt(twinning.twin_law_fraction, 3) + << " merohedral\n"; + } // Radiation-damage monitor (rotation): the relative Debye-Waller B change from the first to the last // frame (A^2). A large magnitude flags a dose-dependent resolution-scale change = radiation damage; // positive is the typical direction (high-resolution intensity fades with dose). No standard mmCIF item. diff --git a/image_analysis/scale_merge/SearchSpaceGroup.cpp b/image_analysis/scale_merge/SearchSpaceGroup.cpp index d220ae05c..3de94bdc8 100644 --- a/image_analysis/scale_merge/SearchSpaceGroup.cpp +++ b/image_analysis/scale_merge/SearchSpaceGroup.cpp @@ -1297,6 +1297,8 @@ SearchSpaceGroupResult SearchSpaceGroup( bool closure = false; std::string why; }; int refused_order = 0; + bool refused_twin_gate = false; + double refused_fraction = std::numeric_limits::quiet_NaN(); std::string refused_pg_hm, refused_why; const gemmi::SpaceGroup *refused_pg_rep = nullptr; std::vector pg_cands; @@ -1579,6 +1581,9 @@ SearchSpaceGroupResult SearchSpaceGroup( refused_order = c.order; refused_pg_hm = c.pg->representative->point_group_hm(); refused_pg_rep = c.pg->representative; + refused_twin_gate = h_refused || r_refused; + refused_fraction = h_refused ? std::max(0.0, 0.5 - h_added) + : std::numeric_limits::quiet_NaN(); if (h_refused) // Twinning by a fraction a scales every twin-related difference by (1-2a), and // |I1-I2|/(I1+I2) is uniform on [0,1] for untwinned Wilson intensities, so the @@ -1702,6 +1707,8 @@ SearchSpaceGroupResult SearchSpaceGroup( result.refused_point_group_hm = refused_pg_hm; result.refused_reason = refused_why; result.refused_point_group_representative = *refused_pg_rep; + result.refused_by_twin_gate = refused_twin_gate; + result.refused_twin_fraction = refused_fraction; } // --- Stage B: pick the space group within the point group --- diff --git a/image_analysis/scale_merge/SearchSpaceGroup.h b/image_analysis/scale_merge/SearchSpaceGroup.h index 6db1a2ed5..c9d291b04 100644 --- a/image_analysis/scale_merge/SearchSpaceGroup.h +++ b/image_analysis/scale_merge/SearchSpaceGroup.h @@ -689,6 +689,11 @@ struct SearchSpaceGroupResult { // Empty when nothing was refused. Surfaced to the user - a silent demotion is how a twin gets missed. std::string refused_point_group_hm; std::string refused_reason; + // Of the refused candidate: the twin fraction its added operators' own disagreement implies + // (0.5 - H, a lower bound; NaN where H was not measured) and whether the refusal came from a twin + // gate (the H ratio or the added-operator R) rather than from the merge chi^2. + double refused_twin_fraction = std::numeric_limits::quiet_NaN(); + bool refused_by_twin_gate = false; // The symmorphic representative of that group - the same thing point_group_representative is, and // for the same reason (a name cannot tell P321 from P312). It is what a caller hands back as // fixed_point_group to ask what merging under the refused group would give. Unset when nothing diff --git a/image_analysis/scale_merge/TwinningAnalysis.cpp b/image_analysis/scale_merge/TwinningAnalysis.cpp index 488470f84..0ed2afb25 100644 --- a/image_analysis/scale_merge/TwinningAnalysis.cpp +++ b/image_analysis/scale_merge/TwinningAnalysis.cpp @@ -565,6 +565,111 @@ namespace { } } +namespace { + // The rotations of a group, as gemmi Ops without translations (its symmorphic representative's + // proper operations). + std::vector ProperRotations(const gemmi::GroupOps& gops) { + std::vector rotations; + for (const auto& op : gops.derive_symmorphic().sym_ops) + if (op.det_rot() > 0) + rotations.push_back(gemmi::Op{op.rot, {0, 0, 0}, 'x'}); + return rotations; + } + + // The reflections a zone test can be read on: present in the group, general position, in the + // shells with signal enough (ZONE_MIN_SHELL_ISIG). Fills the resolution range read. + std::vector StrongReflections(const std::vector& p1_merged, + const gemmi::GroupOps& gops, + TwinImmuneZoneResult& result) { + std::vector usable; + for (const auto& r : p1_merged) { + const gemmi::Op::Miller h{{r.h, r.k, r.l}}; + if (UsableIntensity(r) && std::isfinite(r.sigma) && r.sigma > 0.0 + && !gops.is_systematically_absent(h) && gops.epsilon_factor_without_centering(h) == 1) + usable.push_back(&r); + } + // The shells with signal enough to read (ZONE_MIN_SHELL_ISIG), 20 equal in 1/d^2. + constexpr int n_shells = 20; + double min_s = std::numeric_limits::infinity(), max_s = 0.0; + for (const auto* r : usable) { + min_s = std::min(min_s, 1.0 / (r->d * r->d)); + max_s = std::max(max_s, 1.0 / (r->d * r->d)); + } + std::vector strong; + if (!(max_s > min_s)) + return strong; + auto shell_of = [&](const MergedReflection* r) { + const double t = (1.0 / (r->d * r->d) - min_s) / (max_s - min_s); + return std::min(n_shells - 1, std::max(0, static_cast(t * n_shells))); + }; + std::vector isig_sum(n_shells, 0.0); + std::vector isig_n(n_shells, 0); + for (const auto* r : usable) { + isig_sum[shell_of(r)] += r->I / r->sigma; + isig_n[shell_of(r)] += 1; + } + for (const auto* r : usable) { + const int b = shell_of(r); + if (isig_n[b] > 0 && isig_sum[b] / isig_n[b] >= ZONE_MIN_SHELL_ISIG) + strong.push_back(r); + } + result.d_max_A = 0.0; + result.d_min_A = std::numeric_limits::infinity(); + for (const auto* r : strong) { + result.d_max_A = std::max(result.d_max_A, r->d); + result.d_min_A = std::min(result.d_min_A, r->d); + } + return strong; + } + + // The zone of one subgroup hypothesis H (given by its rotations): the reflections centric in the + // group but not in H - the self-mates of the coset the group adds over H. + TwinImmuneZone ReadSubgroupZone(const std::vector& strong, + const gemmi::GroupOps& gops, const std::vector& rotations, + const std::vector& h_ops, + const std::array* tncs_vector) { + auto contains = [&](const std::vector& set, const gemmi::Op& op) { + return std::any_of(set.begin(), set.end(), [&](const gemmi::Op& o) { return o.rot == op.rot; }); + }; + std::vector zone; + for (const auto* r : strong) { + const gemmi::Op::Miller h{{r->h, r->k, r->l}}; + const gemmi::Op::Miller minus{{-gemmi::Op::DEN * r->h, -gemmi::Op::DEN * r->k, -gemmi::Op::DEN * r->l}}; + const bool centric_in_h = std::any_of(h_ops.begin(), h_ops.end(), [&](const gemmi::Op& op) { + return op.apply_to_hkl_without_division(h) == minus; + }); + if (gops.is_reflection_centric(h) && !centric_in_h) + zone.push_back(r); + } + TwinImmuneZone z = ReadZone(zone, tncs_vector); + for (const auto& op : rotations) + if (!contains(h_ops, op)) + z.operators += (z.operators.empty() ? "" : " ") + op.as_hkl().triplet(); + return z; + } +} + +TwinImmuneZoneResult AnalyzeTwinImmuneZone(const std::vector& p1_merged, + const gemmi::SpaceGroup& group, const gemmi::SpaceGroup& subgroup, + const std::array* tncs_vector) { + TwinImmuneZoneResult result; + result.tncs_normalised = tncs_vector != nullptr; + const gemmi::GroupOps gops = group.operations(); + const std::vector rotations = ProperRotations(gops); + const std::vector h_ops = ProperRotations(subgroup.operations()); + const auto strong = StrongReflections(p1_merged, gops, result); + if (strong.empty()) + return result; + std::vector control; + for (const auto* r : strong) + if (!gops.is_reflection_centric(gemmi::Op::Miller{{r->h, r->k, r->l}})) + control.push_back(r); + result.control = ReadZone(control, tncs_vector); + result.control.operators = "acentric"; + result.zones.push_back(ReadSubgroupZone(strong, gops, rotations, h_ops, tncs_vector)); + return result; +} + TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& p1_merged, const gemmi::SpaceGroup& group, const std::array* tncs_vector) { @@ -592,10 +697,7 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& ops.push_back(p); return ops; }; - std::vector rotations; - for (const auto& op : gops.derive_symmorphic().sym_ops) - if (op.det_rot() > 0) - rotations.push_back(gemmi::Op{op.rot, {0, 0, 0}, 'x'}); + const std::vector rotations = ProperRotations(gops); std::vector squares{gemmi::Op::identity()}; for (const auto& g : rotations) squares.push_back(g * g); @@ -619,49 +721,9 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& if (subgroups.empty()) return result; - // Reflections present in the group and in general position (epsilon 1): an axial row is fixed by - // more than one operator and follows neither distribution. - std::vector usable; - for (const auto& r : p1_merged) { - const gemmi::Op::Miller h{{r.h, r.k, r.l}}; - if (UsableIntensity(r) && std::isfinite(r.sigma) && r.sigma > 0.0 - && !gops.is_systematically_absent(h) && gops.epsilon_factor_without_centering(h) == 1) - usable.push_back(&r); - } - // The shells with signal enough to read (ZONE_MIN_SHELL_ISIG), 20 equal in 1/d^2. - constexpr int n_shells = 20; - double min_s = std::numeric_limits::infinity(), max_s = 0.0; - for (const auto* r : usable) { - min_s = std::min(min_s, 1.0 / (r->d * r->d)); - max_s = std::max(max_s, 1.0 / (r->d * r->d)); - } - if (!(max_s > min_s)) - return result; - auto shell_of = [&](const MergedReflection* r) { - const double t = (1.0 / (r->d * r->d) - min_s) / (max_s - min_s); - return std::min(n_shells - 1, std::max(0, static_cast(t * n_shells))); - }; - std::vector isig_sum(n_shells, 0.0); - std::vector isig_n(n_shells, 0); - for (const auto* r : usable) { - isig_sum[shell_of(r)] += r->I / r->sigma; - isig_n[shell_of(r)] += 1; - } - std::vector strong; - for (const auto* r : usable) { - const int b = shell_of(r); - if (isig_n[b] > 0 && isig_sum[b] / isig_n[b] >= ZONE_MIN_SHELL_ISIG) - strong.push_back(r); - } + const auto strong = StrongReflections(p1_merged, gops, result); if (strong.empty()) return result; - result.d_max_A = 0.0; - result.d_min_A = std::numeric_limits::infinity(); - for (const auto* r : strong) { - result.d_max_A = std::max(result.d_max_A, r->d); - result.d_min_A = std::min(result.d_min_A, r->d); - } - std::vector control; for (const auto* r : strong) if (!gops.is_reflection_centric(gemmi::Op::Miller{{r->h, r->k, r->l}})) @@ -671,23 +733,8 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& // Per hypothesis H, the zone: centric in the group, acentric in H - the reflections some added // operator sends to -h, i.e. the self-mates of that coset read as a twin law. - for (const auto& h_ops : subgroups) { - std::vector zone; - for (const auto* r : strong) { - const gemmi::Op::Miller h{{r->h, r->k, r->l}}; - const gemmi::Op::Miller minus{{-gemmi::Op::DEN * r->h, -gemmi::Op::DEN * r->k, -gemmi::Op::DEN * r->l}}; - const bool centric_in_h = std::any_of(h_ops.begin(), h_ops.end(), [&](const gemmi::Op& op) { - return op.apply_to_hkl_without_division(h) == minus; - }); - if (gops.is_reflection_centric(h) && !centric_in_h) - zone.push_back(r); - } - TwinImmuneZone z = ReadZone(zone, tncs_vector); - for (const auto& op : rotations) - if (!contains(h_ops, op)) - z.operators += (z.operators.empty() ? "" : " ") + op.as_hkl().triplet(); - result.zones.push_back(z); - } + for (const auto& h_ops : subgroups) + result.zones.push_back(ReadSubgroupZone(strong, gops, rotations, h_ops, tncs_vector)); return result; } diff --git a/image_analysis/scale_merge/TwinningAnalysis.h b/image_analysis/scale_merge/TwinningAnalysis.h index 259d89cdb..7165e065e 100644 --- a/image_analysis/scale_merge/TwinningAnalysis.h +++ b/image_analysis/scale_merge/TwinningAnalysis.h @@ -29,6 +29,14 @@ enum class TwinFractionSource { None, LTest, SecondMoment }; struct TwinningAnalysisResult { + // A twin law the run identified: the operator a promotion would have added, refused because its + // twin-immune zone read acentric (the operator relates unequal intensities on the very + // reflections a twin cannot touch), with the fraction the operator's own disagreement implies. + // Written as the mmCIF _pdbx_reflns_twin loop of the merge in the true (sub)group; empty when + // no law was identified. + std::string twin_law_operator; // as an hkl triplet, e.g. "k,h,-l" + double twin_law_fraction = 0.0; + int l_test_pairs = 0; double mean_abs_l = 0.0; // <|L|>: 0.5 untwinned, 0.375 perfect twin double mean_l_squared = 0.0; // : 0.333 untwinned, 0.2 perfect twin @@ -128,4 +136,10 @@ TwinImmuneZoneResult AnalyzeTwinImmuneZones(const std::vector& const gemmi::SpaceGroup& group, const std::array* tncs_vector = nullptr); +// The same for ONE hypothesis: the operators `group` adds over `subgroup` (one zone in the result, +// beside the control). Read where a promotion from the subgroup to the group is in question. +TwinImmuneZoneResult AnalyzeTwinImmuneZone(const std::vector& p1_merged, + const gemmi::SpaceGroup& group, const gemmi::SpaceGroup& subgroup, + const std::array* tncs_vector = nullptr); + std::string TwinImmuneZonesToText(const TwinImmuneZoneResult& result); diff --git a/rugnux/ResultReport.cpp b/rugnux/ResultReport.cpp index dd96d05fd..928e384a2 100644 --- a/rugnux/ResultReport.cpp +++ b/rugnux/ResultReport.cpp @@ -581,6 +581,13 @@ ReportDocument BuildReportDocument(const std::string &output_prefix, Add(s, Prose(fmt::format(" The two search merges disagreed and the higher point group was taken:\n {}.", result.space_group_arm_override))); } + if (!result.twin_zone_decision.empty()) { + Add(s, KeyText("TWIN_ZONE_DECISION", result.twin_zone_decision)); + Add(s, Prose(" A twin gate refused this promotion, and the twin-immune zone of the operators it\n" + " adds decided it (reflections a twin law cannot touch: centric if the operators\n" + " are real, acentric if they are a twin law or a pseudo-symmetry; margin 20 nats):\n" + " " + result.twin_zone_decision + ".")); + } if (refused) Add(s, Prose(fmt::format( " A promotion to {} was refused: {}.\n" @@ -1174,6 +1181,16 @@ ReportDocument BuildReportDocument(const std::string &output_prefix, " absorbed can only show there as an operator averaging unequal intensities. These\n" " numbers are not circular in that way.", true)); } + if (!result.twinning.twin_law_operator.empty()) { + Add(s, KeyText("TWIN_LAW", fmt::format("{} fraction {:.2f}", result.twinning.twin_law_operator, + result.twinning.twin_law_fraction))); + Add(s, Prose(fmt::format(" Twin law identified: operator {} at a fraction of about {:.2f} (a lower bound from\n" + " the operator's own disagreement). The mmCIF carries it as _pdbx_reflns_twin; refine\n" + " against these data in this space group with that law.", + result.twinning.twin_law_operator, result.twinning.twin_law_fraction))); + } + for (size_t i = 0; i < result.twin_law_evidence.size(); ++i) + Add(s, KeyText(fmt::format("TWIN_LAW_{}", i + 1).c_str(), result.twin_law_evidence[i])); if (result.twin_immune_zones && !result.twin_immune_zones->zones.empty()) { // Report-only evidence, one row per class of 2-folds of the adopted group. Not a decision: // the space group above was chosen without it. diff --git a/rugnux/Rugnux.cpp b/rugnux/Rugnux.cpp index e213ee9e2..ede65a3cd 100644 --- a/rugnux/Rugnux.cpp +++ b/rugnux/Rugnux.cpp @@ -1728,6 +1728,47 @@ namespace { // Asked twice, from the same numbers: in RunAllPasses, where the answer is acted on, and inside a // refined pass as soon as its own search merge is in - a pass that already knows it will be thrown // away leaves its report and its files unwritten (see the superseded flag in RunPipeline). + // The twin-immune zone of the operators `higher` adds over `lower`, read on a P1 merge, as a + // verdict: +1 the added operators are real (the zone is centric with margin), -1 they are a twin + // law or a pseudo-symmetry (acentric with margin), 0 undecided - fewer than two orders apart + // (the immunity argument holds for one coset), no zone reflections, or within the margin. + // + // The margin is the screw-axis convention (SearchSpaceGroupOptions::min_screw_absence_evidence): + // the same log-likelihood-ratio units, and the same bound of 20 nats. Read over three batteries + // the zones of genuine promotions sit at +60 nats and above and the zones behind the known + // twins at -290 nats and below, with one genuine trigonal crystal at -46 nats whose promotion + // no gate refused - so the bound is not what separates them, and a refusal a gate did fire is + // the only place the verdict is read. + int TwinZoneVerdict(const std::vector &p1_merged, const SearchSpaceGroupResult &higher, + const SearchSpaceGroupResult &lower, ProcessResult &result, + const std::array *tncs_vector = nullptr) { + constexpr double DECISIVE_NATS = 20.0; + if (!higher.point_group_representative || !lower.point_group_representative) + return 0; + if (higher.point_group_order != 2 * lower.point_group_order) + return 0; + const auto z = AnalyzeTwinImmuneZone(p1_merged, *higher.point_group_representative, + *lower.point_group_representative, tncs_vector); + if (z.zones.empty() || z.zones[0].n == 0) { + result.twin_zone_decision = fmt::format("{} over {}: no zone reflections in the shells with signal " + "({} merged reflections read) -> undecided", + higher.point_group_hm, lower.point_group_hm, p1_merged.size()); + return 0; + } + const auto &zone = z.zones[0]; + const int verdict = zone.evidence_nats <= -DECISIVE_NATS ? -1 + : zone.evidence_nats >= DECISIVE_NATS ? +1 : 0; + result.twin_zone_decision = fmt::format( + "{} over {}: operators {}; n {} <|E^2-1|> {:.3f} +- {:.3f} (control {:.3f}), evidence " + "{:+.1f} nats ({:.2f}-{:.2f} A{}) -> {}", + higher.point_group_hm, lower.point_group_hm, zone.operators, zone.n, zone.mean_abs_e2_minus_1, + zone.standard_error, z.control.mean_abs_e2_minus_1, zone.evidence_nats, z.d_max_A, z.d_min_A, + z.tncs_normalised ? ", normalised per pseudo-translation class" : "", + verdict < 0 ? "acentric, the added operators are a twin law or a pseudo-symmetry" + : verdict > 0 ? "centric, the added operators are real" : "undecided"); + return verdict; + } + std::string RefinedPassIsWorse(const ProcessResult &pass1, const ProcessResult &pass2) { constexpr double MAX_CREDIBLE_COMPLETENESS = 100.5; // rounding headroom, nothing more // How much of the signal the refined pass has to lose before the run moves back off the @@ -5456,7 +5497,7 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b rsm->SetSearchMinZeta(zeta); merged_filtered_isa = sg_opts.merge_isa; // the filtered arm's, before it is replaced sg_opts.merge_isa = result.error_model_isa; // this arm's own error model - const auto alt = SearchSpaceGroup(sm_all.merged, sg_opts); + auto alt = SearchSpaceGroup(sm_all.merged, sg_opts); // The order of the point group each arm confirmed. Read from the search, not from the // space group it went on to pick: Stage B leaves best_space_group unset when no // candidate has enough absences to be eligible, which is common on the filtered arm @@ -5524,13 +5565,49 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b logger.Warning("Space-group search: {}", msg); result.space_group_arm_override = msg; }; + // A refusal is not simply outvoted by the other arm's confirmation: the gates read + // the operators' own disagreement, which a partial twin at a fraction the other arm's + // coverage happens to hide passes there (an H3 partial twin promoted to R32 by the + // filtered arm; a P31 one to P3121 by the all-observation arm). What decides is the + // twin-immune zone of the added operators, read on the all-observation P1 merge + // (TwinZoneVerdict): acentric with margin and the refusal stands, on all observations; + // centric with margin and the higher group is taken as before; undecided and the rule + // stays as it was. + int zone_verdict = 0; if (order_of(alt) > order_of(sg_search)) { logger.Info("Space-group search: all-observation merge supports {} where the " "Lorentz-filtered one supports {} - taking the higher symmetry", alt.point_group_hm, sg_search.point_group_hm); overridden(sg_search, "Lorentz-filtered", "all-observation"); + zone_verdict = !sg_search.refused_point_group_hm.empty() + ? TwinZoneVerdict(sm_all.merged, alt, sg_search, result) : 0; + if (zone_verdict < 0) { + logger.Warning("Space-group search: the Lorentz-filtered merge's refusal of {} " + "STANDS - the twin-immune zone of its added operators reads " + "acentric; keeping {}, judged on all observations", + sg_search.refused_point_group_hm, sg_search.point_group_hm); + sg_opts.fixed_point_group = sg_search.point_group_representative; + auto lower = SearchSpaceGroup(sm_all.merged, sg_opts); + sg_opts.fixed_point_group.reset(); + lower.refused_point_group_hm = sg_search.refused_point_group_hm; + lower.refused_reason = sg_search.refused_reason + ", and its twin-immune zone reads acentric"; + lower.refused_point_group_representative = sg_search.refused_point_group_representative; + lower.refused_by_twin_gate = true; + lower.refused_twin_fraction = sg_search.refused_twin_fraction; + alt = std::move(lower); + } } - if (order_of(alt) < order_of(sg_search)) { + if (order_of(alt) < order_of(sg_search) + && !alt.refused_point_group_hm.empty() + && TwinZoneVerdict(sm_all.merged, sg_search, alt, result) < 0) { + logger.Warning("Space-group search: the all-observation merge's refusal of {} STANDS " + "- the twin-immune zone of its added operators reads acentric; keeping {}", + alt.refused_point_group_hm, alt.point_group_hm); + overridden(alt, "all-observation", "Lorentz-filtered"); + result.space_group_arm_override += " - but the refusal stands (see TWIN_ZONE_DECISION)"; + alt.refused_reason += ", and its twin-immune zone reads acentric"; + sg_search = alt; + } else if (order_of(alt) < order_of(sg_search)) { // The filtered arm found symmetry the all-observation arm did not. Discarding it // was costing real point groups: over the corpus the two arms disagree on eight // crystals and the higher one is right on all eight, because the filter removes @@ -6293,6 +6370,56 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b else for (const auto &alt : hi_search.alternatives) if (alt.centring_type() == sg.centring_type()) { hi_sg = alt; break; } + // A refusal is arbitrated by the twin-immune zone of the added operators + // (TwinZoneVerdict) where it is decisive, and only otherwise by the merge + // comparison below: that comparison reads R_meas and ISa of two merges whose + // per-frame scales have settled, and the lower group, with the same scales fitted + // against fewer equivalents, then agrees with itself the better of the two on a + // genuine promotion as much as on a twin (measured: a genuine 2 -> 222 step reading + // R_meas 0.094 -> 0.103, ISa 12.3 -> 10.9). The zone does not depend on the scales. + // Read on the adopted group's own merge: the zone reflections are centric in the + // refused group and acentric in the adopted one, so they are distinct reflections + // of this merge, at full multiplicity and production scale - where the P1 search + // merge of a weak crystal has no shell with signal enough to read a zone on. + const int zone = hi_sg.has_value() + ? TwinZoneVerdict(sm.merged, hi_search, sg_search, result, + TranslationalNCSVectorForLTest(pre_tncs)) : 0; + if (zone < 0) { + const std::string msg = fmt::format( + "Point group {} was refused ({}), and the twin-immune zone of its added " + "operators reads acentric: they relate unequal intensities on the very " + "reflections a twin law cannot touch, so the refusal stands and the " + "operator is recorded as a twin law. Keeping {}.", + sg_search.refused_point_group_hm, sg_search.refused_reason, sg.xhm()); + logger.Info("{}", msg); + stats_text << " " << msg << "\n\n"; + sg_search.refused_reason += ", and its twin-immune zone reads acentric"; + hi_sg.reset(); + } else if (zone > 0) { + const std::string msg = fmt::format( + "Point group {} was confirmed by the operator correlations and then " + "refused ({}), but the twin-immune zone of its added operators reads " + "centric - a twin law cannot produce that on the reflections it leaves " + "untouched - so {} is adopted.", + sg_search.refused_point_group_hm, sg_search.refused_reason, hi_sg->xhm()); + logger.Info("{}", msg); + stats_text << " " << msg << "\n\n"; + sg_search = hi_search; + if (hi_search.best_space_group->number != hi_sg->number) { + sg_search.alternatives.push_back(*hi_search.best_space_group); + std::erase_if(sg_search.alternatives, + [&](const gemmi::SpaceGroup &a) { return a.number == hi_sg->number; }); + } + sg_search.best_space_group = *hi_sg; + result.space_group = *hi_sg; + end_msg.space_group_name = hi_sg->xhm(); + end_msg.space_group_number = static_cast(hi_sg->number); + promoted_point_group = true; + experiment_.SetSpaceGroup(*hi_sg); + phase("Re-scaling in space group " + hi_sg->short_name()); + sm = scale_and_merge(hi_sg->short_name(), false); + hi_sg.reset(); + } if (hi_sg.has_value()) { // scale_and_merge reports the error model of whatever it merged, and the two // comparison merges are not the run's answer, so it goes back if they lose. @@ -6471,6 +6598,30 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b // flat one landing on exactly the case the flag exists for. (Assigning it before the call // would not do: the call replaces the whole struct.) result.twinning.laue_class_was_chosen_by_promotion = promoted_point_group; + // A refusal that stood on the twin-immune zone names the law: the first operator the + // refused group adds, at the fraction its own disagreement implies (a lower bound). + if (result.space_group_search && result.space_group_search->refused_point_group_representative + && result.twin_zone_decision.find("acentric, the added") != std::string::npos) { + const auto &sgs = *result.space_group_search; + const gemmi::GroupOps hi = sgs.refused_point_group_representative->operations(); + const gemmi::GroupOps lo = twin_sg->operations(); + for (const auto &op : hi.derive_symmorphic().sym_ops) { + if (op.det_rot() <= 0) continue; + const bool in_lower = std::any_of(lo.sym_ops.begin(), lo.sym_ops.end(), + [&](const gemmi::Op &o) { return o.rot == op.rot; }); + if (in_lower) continue; + result.twinning.twin_law_operator = gemmi::Op{op.rot, {0, 0, 0}, 'x'}.as_hkl().triplet(); + break; + } + // The fraction: the refused operators' own H where the H gate measured it, else the + // L-test of the merge before the search (a twin fraction that does not depend on the + // promotion), else the perfect twin every operator statistic reads as symmetry. + result.twinning.twin_law_fraction = + std::isfinite(sgs.refused_twin_fraction) ? sgs.refused_twin_fraction + : result.pre_promotion_twinning + && result.pre_promotion_twinning->twin_fraction_source != TwinFractionSource::None + ? result.pre_promotion_twinning->estimated_twin_fraction : 0.5; + } if (result.tncs.measurable) stats_text << TranslationalNCSToText(result.tncs) << "\n"; stats_text << TwinningAnalysisToText(result.twinning) << "\n"; @@ -6548,6 +6699,26 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b if (result.consensus_cell && twin_sg != nullptr) { const auto twin_ops = ReindexAmbiguityOperators(*result.consensus_cell, *twin_sg, 2.0); if (!twin_ops.empty()) { + // The merge is folded under the adopted group, and a twin law sends a reflection + // outside that group's asymmetric unit - so the pairs are formed on the merge + // expanded to P1 under the group's own operations (each reflection once per + // operation; the H statistic is a median and the correlation a ratio, so the + // repetition changes neither). + std::vector expanded; + const auto expanded_merge = [&]() -> const std::vector & { + if (expanded.empty()) { + const gemmi::GroupOps ops = twin_sg->operations(); + expanded.reserve(sm.merged.size() * ops.sym_ops.size()); + for (const auto &r : sm.merged) + for (const auto &o : ops.sym_ops) { + const auto hkl = o.apply_to_hkl({{r.h, r.k, r.l}}); + MergedReflection e = r; + e.h = hkl[0]; e.k = hkl[1]; e.l = hkl[2]; + expanded.push_back(e); + } + } + return expanded; + }; std::string laws; for (const auto &op : twin_ops) { std::string t = op.triplet(); @@ -6555,7 +6726,25 @@ ProcessResult Rugnux::RunPipeline(RugnuxObserver *observer, bool write_output, b std::replace(t.begin(), t.end(), 'y', 'k'); std::replace(t.begin(), t.end(), 'z', 'l'); laws += (laws.empty() ? "" : " ; ") + t; + // What each law reads on the merge: the disagreement H of the reflections it + // relates (Yeates (1997) Methods Enzymol. 276, 344-358: a twin of fraction a reads + // (1-2a)/2, so a >= 0.5 - H), their correlation and their intensity-weighted R. + // Report-only, so a user sees which law a twin refinement would need. + gemmi::Mat33 m; + for (int i = 0; i < 3; ++i) + for (int j = 0; j < 3; ++j) + m[j][i] = static_cast(op.rot[i][j]) / gemmi::Op::DEN; + SearchSpaceGroupOptions law_opts; + law_opts.nthreads = static_cast(std::max(1, config_.nthreads)); + if (const auto s = OperatorCorrelation(expanded_merge(), m, law_opts); s.has_value()) + result.twin_law_evidence.push_back(fmt::format( + "{}: {} pairs, H {:.3f} (twin fraction {:.2f} or more), R {:.3f}, CC {:.3f}", + t, s->n_pairs, s->h_stat, std::max(0.0, 0.5 - s->h_stat), s->r_stat, s->cc)); + else + result.twin_law_evidence.push_back(fmt::format("{}: too few pairs to read", t)); } + for (const auto &e : result.twin_law_evidence) + logger.Info("Twin law {}", e); // A model can resolve it too, but whether it does is only known once the model has // been fitted (validation step below), so the warning stands here exactly as in a run // without a model, and is withdrawn there if the model's indexing probe decided it. diff --git a/rugnux/Rugnux.h b/rugnux/Rugnux.h index 45b68f3a6..4e0d1f819 100644 --- a/rugnux/Rugnux.h +++ b/rugnux/Rugnux.h @@ -351,6 +351,12 @@ struct ProcessResult { // group was taken from one of them: what the other arm said - which gate refused the promotion, // or that it never confirmed the operators. Empty when the arms agreed. std::string space_group_arm_override; + // The twin-immune zone read for a promotion a twin gate refused (the H ratio or the added-operator + // R), and what was decided on it. Empty when no twin gate fired. + std::string twin_zone_decision; + // Per lattice twin law outside the adopted group: the operator's own H, the fraction it implies + // and its correlation, on the final merge. Report-only. + std::vector twin_law_evidence; // ---- Material for the results report (_report.txt, see rugnux/ResultReport.h) ----