Merge branch 'rc187-ack' into rc186-merge2

common/ColorScale.h

@@ -34,6 +34,7 @@ enum class ColorScaleSpecial {
 };
 
 class ColorScale {
+    // Viridis, Magma and Inferno are Matplotlib's colormaps, sampled. Following Hunter (2007) Comput. Sci. Eng. 9, 90-95
     const std::vector<rgb> viridis_colormap = {
             {68, 1, 84}, {71, 44, 123}, {59, 81, 139}, {44, 113, 142}, {33, 144, 141},
             {39, 173, 129}, {92, 200, 99}, {170, 220, 50}, {253, 231, 37}

docs/CPU_DATA_ANALYSIS.md

@@ -112,5 +112,15 @@ The methods draw on, and in places reimplement, solutions from:
 - R. J. Read, "Pushing the boundaries of molecular replacement with maximum likelihood", *Acta Cryst.* **D57** (2001), 1373-1382; A. J. McCoy, R. W. Grosse-Kunstleve, L. C. Storoni & R. J. Read, "Likelihood-enhanced fast translation functions", *Acta Cryst.* **D61** (2005), 458-464; A. J. McCoy et al., "Phaser crystallographic software", *J. Appl. Cryst.* **40** (2007), 658-674; A. J. McCoy et al., *Proc. Natl. Acad. Sci. USA* **114** (2017), 3637-3641 (the likelihood target, the solution criterion and the expected gain of molecular replacement, §14.10).
 - R. D. Oeffner, T. Croll, C. Millán et al., "Putting AlphaFold models to work with phenix.process_predicted_model and ISOLDE", *Acta Cryst.* **D78** (2022), 1303-1314, and J. Jumper et al., "Highly accurate protein structure prediction with AlphaFold", *Nature* **596** (2021), 583-589 (preparing a predicted model for molecular replacement, §14.10).
 
+- E. A. Cornish & R. A. Fisher, "Moments and cumulants in the specification of distributions", *Rev. Int. Stat. Inst.* **5** (1938), 307-320 (the Poisson quantile of the adaptive spot-finding threshold beyond the summation limit).
+- R. W. Grosse-Kunstleve, "Algorithms for deriving crystallographic space-group information", *Acta Cryst.* **A55** (1999), 383-395 (from Le Page's two-folds to a conventional cell, centring and change of basis, §13.1).
+- T. C. Huang, H. Toraya, T. N. Blanton & Y. Wu, "X-ray powder diffraction analysis of silver behenate, a possible low-angle diffraction standard", *J. Appl. Cryst.* **26** (1993), 180-184 (the silver behenate calibrant cell, §7.6).
+- P. Trueb, C. Dejoie, M. Kobas et al., "Bunch mode specific rate corrections for PILATUS3 detectors", *J. Synchrotron Rad.* **22** (2015), 701-707 (the count-rate correction clips an over-range pixel to the cutoff, §1.7).
+- D. Liebschner, P. V. Afonine, M. L. Baker et al., "Macromolecular structure determination using X-rays, neutrons and electrons: recent developments in Phenix", *Acta Cryst.* **D75** (2019), 861-877 (phenix.xtriage, the model of the twinning test, §13.2).
+- V. Luzzati, "Traitement statistique des erreurs dans la détermination des structures cristallines", *Acta Cryst.* **5** (1952), 802-810 (the fall-off of $\sigma_A$ with resolution for a model's coordinate error, Luzzati's $D$, in the likelihood of a placement, §14.10).
+- D. Liebschner, P. V. Afonine, A. G. Urzhumtsev & P. D. Adams, "Implementation of the riding hydrogen model in CCTBX to support the next generation of X-ray and neutron joint refinement in Phenix", *Methods Enzymol.* **634** (2020), 177-199 (the riding hydrogens, placed by GEMMI's code, §15.2).
+- D. L. Theobald, "Rapid calculation of RMSDs using a quaternion-based characteristic polynomial", *Acta Cryst.* **A61** (2005), 478-480, and P. Liu, D. K. Agrafiotis & D. L. Theobald, *J. Comput. Chem.* **31** (2010), 1561-1563 (the QCP superposition behind the NCS rms criterion, via GEMMI, §15.5).
+- S. S. Oren & D. G. Luenberger, "Self-scaling variable metric (SSVM) algorithms. Part I", *Management Sci.* **20** (1974), 845-862, and D. F. Shanno & K.-H. Phua, "Matrix conditioning and nonlinear optimization", *Math. Program.* **14** (1978), 149-160 (the rescaling of the L-BFGS initial inverse Hessian by the latest pair, §15.6).
+
 (list is not exhaustive; the full citations, with DOIs, are in [ACKNOWLEDGEMENT.md](ACKNOWLEDGEMENT.md))
 

image_analysis/SensorAbsorption.h

@@ -32,7 +32,8 @@
 // untilted detector. On a tilted one the correction acquires an azimuthal dependence at fixed
 // resolution, which is the only part of it that is not degenerate with an overall Wilson B.
 //
-// Attenuation coefficients: NIST X-Ray Mass Attenuation Coefficients (Hubbell & Seltzer), total
+// Attenuation coefficients: NIST X-Ray Mass Attenuation Coefficients, Hubbell & Seltzer (1995) NIST
+// Standard Reference Database 126, total
 // mu/rho with coherent scattering. Photoelectric absorption dominates over the whole range used
 // here, and because the correction is a RATIO of two absorbed fractions the photoelectric branching
 // ratio cancels exactly; only the attenuation length enters. Coherent scattering, which attenuates

image_analysis/bragg_integration/BraggIntegrationEngineCPU.cpp

@@ -246,7 +246,8 @@ std::vector<Reflection> BraggIntegrationEngineCPU::RunImpl(const Sampler &img,
         const auto &r = predicted[i];
         const BraggPanel &pn = panels[i];
         // This reflection's stencil: the r1 signal disk, and the r2..r3 ring elongated radially by
-        // the analytic smear.
+        // the analytic smear. The three-ring region follows CrystFEL, White et al. (2012) J. Appl.
+        // Cryst. 45, 335-341
         const BraggStencil st = MakeBraggStencil(pn, stencil);
         const Box box = box_of(r, st);
         const int x0 = box.x0, x1 = box.x1, y0 = box.y0, y1 = box.y1;

image_analysis/bragg_integration/BraggIntegrationEngineGPU.cu

@@ -241,7 +241,8 @@ __global__ void boxsum(const float *px_x, const float *px_y, const BraggPanel *p
         const BraggStencilDist d = BraggStencilDistances(st, (float) x - cx, (float) y - cy);
         // The window is the bounding box of the outer ellipse, so nearly half of it is neither the
         // signal disk nor the background ring. Reading the pixel only once it is known to be wanted
-        // keeps those slots from fetching a cache line for nothing.
+        // keeps those slots from fetching a cache line for nothing. The r1 disk / r2..r3 ring region
+        // follows CrystFEL, White et al. (2012) J. Appl. Cryst. 45, 335-341
         if (BraggStencilInSignal(st, (float) x - cx, (float) y - cy, d.signal, p.r1_sq)) {
             // A pixel a nearer neighbour owns carries that neighbour's flux; see the CPU engine.
             ++l_nd;

image_analysis/geom_refinement/PostRefine.h

@@ -30,6 +30,8 @@
 //   * the positional detector<->reciprocal residual at each partial's observed spot -> pins the distance.
 // Where there are more reflections than the fit's caps, the strongest by I/sigma are the ones kept;
 // inside the fit every reflection carries the same weight.
+// Following MOSFLM's post-refinement, Powell (1999) Acta Cryst. D55, 1690-1695, and Leslie & Powell (2007)
+// Evolving Methods for Macromolecular Crystallography, NATO Sci. Ser. II 245, 41-51
 
 // How far one step of the joint fit may move the distance or a cell length, relative (see STEP_BOUND in
 // PostRefine.cpp, where it is explained).

image_analysis/scale_merge/CentreOfSymmetry.cpp

@@ -98,7 +98,8 @@ namespace {
     }
 }
 
-// Following Howells, Phillips & Rogers (1950) Acta Cryst. 3, 210-214 (N(z)), and Padilla & Yeates
+// Following Wilson (1949) Acta Cryst. 2, 318-321 (the acentric and centric intensity distributions),
+// Howells, Phillips & Rogers (1950) Acta Cryst. 3, 210-214 (N(z)), and Padilla & Yeates
 // (2003) Acta Cryst. D59, 1124-1130 (the L-test, read here against its centric value 2/pi).
 CentreOfSymmetryResult AnalyzeCentreOfSymmetry(const std::vector<MergedReflection>& merged,
                                                const gemmi::SpaceGroup& space_group, size_t nthreads) {

image_analysis/scale_merge/StillsPartialityRefine.h

@@ -39,6 +39,7 @@
 // `image_scale_corr` in place; the existing MergeOnTheFly then consumes the improved corrections. The
 // width of the Gaussian partiality is the run's, measured once from the intensity-weighted excitation
 // errors (MeasureRunWidth).
+// Following Uervirojnangkoorn et al. (2015) eLife 4, e05421 (PRIME) and Sauter et al. (2014) Acta Cryst. D70, 3299-3309
 class StillsPartialityRefine {
 public:
     struct Settings {

image_analysis/structure_refinement/MolecularReplacement.h

@@ -63,6 +63,8 @@ SearchModel PrepareSearchModel(const RugnuxModel &model);
 // linkage on the symmetrised PAE until every two clusters are a mean PAE_DOMAIN_A apart; clusters of at least
 // DOMAIN_MIN_RESIDUES, largest first, each a list of positions in the prediction. Empty where the matrix does
 // not match the model.
+// The models, their pLDDT and PAE following Jumper et al. (2021) Nature 596, 583-589, and Varadi et al. (2022)
+// Nucleic Acids Res. 50, D439-D444 (the AlphaFold DB)
 std::vector<std::vector<int>> PaeDomains(const std::vector<std::vector<double>> &pae, const SearchModel &model);
 // The search model of one domain: the residues of `model` at those positions, recentred.
 SearchModel DomainModel(const SearchModel &model, const std::vector<int> &residues);

image_analysis/structure_refinement/Refinement.cpp

@@ -2653,6 +2653,9 @@ RefinementResult RefineOnce(const gemmi::Structure &placed, const std::vector<Me
         };
         const double w_max = w0 * settings.max_weight;
 
+        // NCS restraints kept where R-free keeps them, the copies' B factors refined independently: following
+        // Kleywegt (1996) Acta Cryst. D52, 842-857, Uson et al. (1999) Acta Cryst. D55, 1158-1167, and Headd et al.
+        // (2014) Acta Cryst. D70, 1346-1356
         // 1. The weights from the placed model: the ladder's rungs, tighter geometry first, each with the B factors
         //    held and refined at their own balanced weight; where there are copies, each rung without NCS restraints
         //    and then with them - those with them at the B factors' weight the rungs without chose, which NCS does

image_analysis/structure_refinement/RefinementADP.h

@@ -54,7 +54,8 @@ std::vector<gemmi::TlsGroup> TlsBodiesToGroups(const gemmi::Model &model, const
 //   U23 of the difference in a frame whose z is n, as SHELXL's RIGU restrains them;
 // - similarity, for the same pairs: |U_i - U_j|^2 (Frobenius) / sigma^2, sigma 0.04 A^2 (SHELXL's SIMU);
 // - near isotropy, for an atom in no pair (a water, an ion): |U - tr(U)/3 I|^2 / sigma^2, sigma 0.1 A^2 (ISOR).
-// Following Hirshfeld (1976) Acta Cryst. A32, 239-244, and Thorn, Dittrich & Sheldrick (2012) Acta Cryst. A68, 448-451
+// Following Hirshfeld (1976) Acta Cryst. A32, 239-244, Thorn, Dittrich & Sheldrick (2012) Acta Cryst. A68, 448-451
+// (RIGU), and Sheldrick (2015) Acta Cryst. C71, 3-8 (SIMU and ISOR)
 struct URestraints {
     static constexpr double SIGMA_RIGID = 0.004, SIGMA_SIMILAR = 0.04, SIGMA_ISOTROPIC = 0.1;
     std::vector<std::pair<int, int>> pairs;

image_analysis/structure_refinement/RefinementXray.h

@@ -133,7 +133,8 @@ private:
 // beta fitted by maximum likelihood to the free reflections as the whole spread of Fo about D Fc, D then fitted to
 // the working reflections with the variance epsilon beta + 2 sigma^2 (acentric; + sigma^2 centric), which is also
 // the variance of a reflection in the target. `fmodel` is k_total (F + fmask), without D.
-// Following Lunin & Skovoroda (1995) Acta Cryst. A51, 880-887, and Murshudov et al. (2011) Acta Cryst. D67, 355-367
+// Following Lunin & Skovoroda (1995) Acta Cryst. A51, 880-887, Lunin, Afonine & Urzhumtsev (2002) Acta Cryst. A58,
+// 270-282 (the parameters estimated on the free reflections), and Murshudov et al. (2011) Acta Cryst. D67, 355-367
 void EstimateLikelihoodParameters(const RefinementReflections &refl, const std::vector<std::complex<float>> &fmodel,
                                   XrayRowModel &rows, size_t nthreads = 1);
 
@@ -151,7 +152,8 @@ std::vector<std::complex<float>> TwinnedModel(const RefinementReflections &refl,
 // twinned amplitudes took a fraction of 0.16 for unrelated partners of one model at R-free 0.31, the average of two
 // predictions being the better prediction. Reflections that are their own mate under every law say nothing and are
 // left out. With one law the fraction is at most 1/2. `f` is F at every row, `rows` gives k_total and fmask.
-// Following Yeates (1997) Methods Enzymol. 276, 344-358 (the twinned intensity), refined as Murshudov et al. (2011)
+// Following Yeates (1997) Methods Enzymol. 276, 344-358 (the twinned intensity), refined beside the model as
+// Herbst-Irmer & Sheldrick (1998) Acta Cryst. B54, 443-449 (SHELXL's BASF) and Murshudov et al. (2011)
 // Acta Cryst. D67, 355-367 refine the fractions, by least squares
 constexpr size_t TWIN_FRACTION_SHELL = 500;
 std::vector<float> FitTwinFractions(const RefinementReflections &refl, const XrayRowModel &rows,