IMP logo
IMP Reference Guide  2.18.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-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  */
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(
56  IMP::DerivativeAccumulator *accum) const override;
57 
58  unsigned int get_projection_number() const { return projection_number_; }
59 
60  void set_projection_number(unsigned int n) { projection_number_ = n; }
61 
62  //! Get transformation that best places the model on the image
63  /** The transformation places the model such that if the image is placed
64  on the xy plane with its lower left corner at the origin the model's
65  projection along the z axis will coincide with the image.
66  This transformation is that calculated from the last scoring function
67  evaluation; calling this function before the score is calculated
68  results in undefined behavior.
69  */
70  algebra::Transformation3D get_transformation(unsigned int image_number) const;
71 
72  //! Get cross correlation between the image and the best model projection
73  /** This CCC is that calculated from the last scoring function
74  evaluation; calling this function before the score is calculated
75  results in undefined behavior.
76  */
77  double get_cross_correlation_coefficient(unsigned int image_number) const;
78 
79  // write best projections from last calculation, if evaluate is true,
80  // best projections will be recalculated
81  void write_best_projections(std::string file_name, bool evaluate=false);
82 
83  //! \return Information for writing to RMF files
84  RestraintInfo *get_static_info() const override;
85 
86  //! \return Information for writing to RMF files
87  RestraintInfo *get_dynamic_info() const override;
88 
89  IMP::ModelObjectsTemp do_get_inputs() const override { return ps_; }
91 
92  private:
93  // particles to fit to the images
94  Particles ps_;
95 
96  // EM2D images
97  std::vector<internal::Image2D<> > images_;
98 
99  // Image file names (absolute paths)
100  Strings image_files_;
101 
102  // image pixel size
103  double pixel_size_;
104 
105  // estimated image resolution
106  double resolution_;
107 
108  // number of particle projections to generate for image fitting
109  unsigned int projection_number_;
110 
111  // from last score calculation
112  mutable std::vector<internal::Image2D<> > best_projections_;
113 
114  // from last calculation
115  mutable std::vector<internal::ProjectionInfo> best_projections_info_;
116  mutable IMP::algebra::Vector3Ds best_projections_axis_;
117  mutable std::vector<internal::ImageTransform> best_image_transform_;
118 
119  // Projector class instance
120  internal::Projector projector_;
121 
122  // Speed up evaluation by only periodically recalculating projections
123  bool reuse_direction_;
124 
125  // Number of the largest components to be considered for the EM image
126  unsigned int n_components_;
127 
128  mutable unsigned long counter_;
129 };
130 
131 IMPEM2D_END_NAMESPACE
132 
133 #endif /* IMPEM2D_PCA_FIT_RESTRAINT_H */
Simple 3D transformation class.
virtual RestraintInfo * get_static_info() const
Definition: Restraint.h:182
virtual RestraintInfo * get_dynamic_info() const
Definition: Restraint.h:194
#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:35
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:53