IMP logo
IMP Reference Guide  2.20.2
The Integrative Modeling Platform
d/PCAFitRestraint.h
Go to the documentation of this file.
1 /**
2  * \file IMP/em2d/PCAFitRestraint.h
3  * \brief fast scoring of fit between Particles in 3D and 2D class averages
4  *
5  * \authors Dina Schneidman
6  * Copyright 2007-2022 IMP Inventors. All rights reserved.
7  *
8  */
9 
10 #ifndef IMPEM2D_PCA_FIT_RESTRAINT_H
11 #define IMPEM2D_PCA_FIT_RESTRAINT_H
12 
13 #include <IMP/em2d/em2d_config.h>
14 #include <IMP/em2d/internal/Image2D.h>
15 #include <IMP/em2d/internal/Projector.h>
16 
17 #include <IMP/Restraint.h>
18 
19 IMPEM2D_BEGIN_NAMESPACE
20 
21 //! Fast scoring of Particles against electron microscopy class averages
22 /**
23  The restraint fits the particles into the 2D images by alignment of
24  principal components of each of the particles' projections with
25  principal components of the 2D class average. Therefore, the
26  particle set should comprise all subunits that are in the
27  image. The aligned projections are scored against 2D class averages
28  using the cross correlation score. This is a fast alignment and score
29  that works well for negative stain EM class averages.
30  */
31 class IMPEM2DEXPORT PCAFitRestraint : public IMP::Restraint {
32 public:
33  //! Constructor
34  /**
35  \param[in] particles The particles participating in the score, which
36  need to have XYZ, radius and mass
37  \param[in] image_files 2D class average filenames in PGM text format
38  \param[in] pixel_size Pixel size in angstroms
39  \param[in] resolution Estimated resolution of the images in angstroms
40  \param[in] projection_number Number of projections of the model
41  to generate and fit to images. The lower the number, the
42  faster the evaluation, but the lower the accuracy.
43  \param[in] reuse_direction Speed up evaluation by only periodically
44  recalculating projections
45  \param[in] n_components Number of the largest components to be
46  considered for the EM image
47  \param[in] micrographs_number Number of micrograph particles that were
48  used to generate the class averages (or zero, the default,
49  if unknown)
50  */
51  PCAFitRestraint(Particles particles,
52  const std::vector<std::string>& image_files,
53  double pixel_size, double resolution = 10.0,
54  unsigned int projection_number = 100,
55  bool reuse_direction = false,
56  unsigned int n_components = 1,
57  unsigned int micrographs_number = 0);
58 
59  double unprotected_evaluate(
60  IMP::DerivativeAccumulator *accum) const override;
61 
62  unsigned int get_projection_number() const { return projection_number_; }
63 
64  void set_projection_number(unsigned int n) { projection_number_ = n; }
65 
66  unsigned int get_micrographs_number() const { return micrographs_number_; }
67 
68  void set_micrographs_number(unsigned int n) { micrographs_number_ = n; }
69 
70  //! Get transformation that best places the model on the image
71  /** The transformation places the model such that if the image is placed
72  on the xy plane with its lower left corner at the origin the model's
73  projection along the z axis will coincide with the image.
74  This transformation is that calculated from the last scoring function
75  evaluation; calling this function before the score is calculated
76  results in undefined behavior.
77  */
78  algebra::Transformation3D get_transformation(unsigned int image_number) const;
79 
80  //! Get cross correlation between the image and the best model projection
81  /** This CCC is that calculated from the last scoring function
82  evaluation; calling this function before the score is calculated
83  results in undefined behavior.
84  */
85  double get_cross_correlation_coefficient(unsigned int image_number) const;
86 
87  // write best projections from last calculation, if evaluate is true,
88  // best projections will be recalculated
89  void write_best_projections(std::string file_name, bool evaluate=false);
90 
91  //! \return Information for writing to RMF files
92  RestraintInfo *get_static_info() const override;
93 
94  //! \return Information for writing to RMF files
95  RestraintInfo *get_dynamic_info() const override;
96 
97  IMP::ModelObjectsTemp do_get_inputs() const override { return ps_; }
99 
100  private:
101  // particles to fit to the images
102  Particles ps_;
103 
104  // EM2D images
105  std::vector<internal::Image2D<> > images_;
106 
107  // Image file names (absolute paths)
108  Strings image_files_;
109 
110  // image pixel size
111  double pixel_size_;
112 
113  // estimated image resolution
114  double resolution_;
115 
116  // number of particle projections to generate for image fitting
117  unsigned int projection_number_;
118 
119  // from last score calculation
120  mutable std::vector<internal::Image2D<> > best_projections_;
121 
122  // from last calculation
123  mutable std::vector<internal::ProjectionInfo> best_projections_info_;
124  mutable IMP::algebra::Vector3Ds best_projections_axis_;
125  mutable std::vector<internal::ImageTransform> best_image_transform_;
126 
127  // Projector class instance
128  internal::Projector projector_;
129 
130  // Speed up evaluation by only periodically recalculating projections
131  bool reuse_direction_;
132 
133  // Number of the largest components to be considered for the EM image
134  unsigned int n_components_;
135 
136  unsigned int micrographs_number_;
137  mutable unsigned long counter_;
138 };
139 
140 IMPEM2D_END_NAMESPACE
141 
142 #endif /* IMPEM2D_PCA_FIT_RESTRAINT_H */
Simple 3D transformation class.
virtual RestraintInfo * get_static_info() const
Definition: Restraint.h:178
virtual RestraintInfo * get_dynamic_info() const
Definition: Restraint.h:190
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
virtual double unprotected_evaluate(DerivativeAccumulator *da) const
Return the unweighted score for the restraint.
Fast scoring of Particles against electron microscopy class averages.
double get_cross_correlation_coefficient(Image *im1, Image *im2)
Cross correlation between two images.
Report key:value information on restraints.
Definition: RestraintInfo.h:47
Abstract base class for all restraints.
IMP::ModelObjectsTemp do_get_inputs() const override
Class for adding derivatives from restraints to the model.
A restraint is a term in an IMP ScoringFunction.
Definition: Restraint.h:56