IMP logo
IMP Reference Guide  2.14.0
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-2020 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  */
48  PCAFitRestraint(Particles particles,
49  const std::vector<std::string>& image_files,
50  double pixel_size, double resolution = 10.0,
51  unsigned int projection_number = 100,
52  bool reuse_direction = false,
53  unsigned int n_components = 1);
54 
55  double unprotected_evaluate(IMP::DerivativeAccumulator *accum) const;
56 
57  unsigned int get_projection_number() const { return projection_number_; }
58 
59  void set_projection_number(unsigned int n) { projection_number_ = n; }
60 
61  //! Get transformation that best places the model on the image
62  /** The transformation places the model such that if the image is placed
63  on the xy plane with its lower left corner at the origin the model's
64  projection along the z axis will coincide with the image.
65  This transformation is that calculated from the last scoring function
66  evaluation; calling this function before the score is calculated
67  results in undefined behavior.
68  */
69  algebra::Transformation3D get_transformation(unsigned int image_number) const;
70 
71  //! Get cross correlation between the image and the best model projection
72  /** This CCC is that calculated from the last scoring function
73  evaluation; calling this function before the score is calculated
74  results in undefined behavior.
75  */
76  double get_cross_correlation_coefficient(unsigned int image_number) const;
77 
78  // write best projections from last calculation, if evaluate is true,
79  // best projections will be recalculated
80  void write_best_projections(std::string file_name, bool evaluate=false);
81 
82  //! \return Information for writing to RMF files
84 
85  //! \return Information for writing to RMF files
87 
88  IMP::ModelObjectsTemp do_get_inputs() const { return ps_; }
90 
91  private:
92  // particles to fit to the images
93  Particles ps_;
94 
95  // EM2D images
96  std::vector<internal::Image2D<> > images_;
97 
98  // Image file names (absolute paths)
99  Strings image_files_;
100 
101  // image pixel size
102  double pixel_size_;
103 
104  // estimated image resolution
105  double resolution_;
106 
107  // number of particle projections to generate for image fitting
108  unsigned int projection_number_;
109 
110  // from last score calculation
111  std::vector<internal::Image2D<> > best_projections_;
112 
113  // from last calculation
114  std::vector<internal::ProjectionInfo> best_projections_info_;
115  IMP::algebra::Vector3Ds best_projections_axis_;
116  std::vector<internal::ImageTransform> best_image_transform_;
117 
118  // Projector class instance
119  internal::Projector projector_;
120 
121  // Speed up evaluation by only periodically recalculating projections
122  bool reuse_direction_;
123 
124  // Number of the largest components to be considered for the EM image
125  unsigned int n_components_;
126 
127  mutable unsigned long counter_;
128 };
129 
130 IMPEM2D_END_NAMESPACE
131 
132 #endif /* IMPEM2D_PCA_FIT_RESTRAINT_H */
Simple 3D transformation class.
virtual RestraintInfo * get_static_info() const
Definition: Restraint.h:117
virtual RestraintInfo * get_dynamic_info() const
Definition: Restraint.h:129
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Fast scoring of Particles against electron microscopy class averages.
IMP::ModelObjectsTemp do_get_inputs() const
double get_cross_correlation_coefficient(Image *im1, Image *im2)
Cross correlation between two images.
Report key:value information on restraints.
Definition: RestraintInfo.h:35
Abstract base class for all restraints.
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.
Class for adding derivatives from restraints to the model.
A restraint is a term in an IMP ScoringFunction.
Definition: Restraint.h:54