IMP  2.0.0
The Integrative Modeling Platform
Em2DRestraint.h
Go to the documentation of this file.
1 /**
2  * \file Em2DRestraint.h
3  * \brief A restraint to score the fitness of a model to a set of EM images
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPEM2D_EM_2DRESTRAINT_H
10 #define IMPEM2D_EM_2DRESTRAINT_H
11 
12 #include "IMP/em2d/em2d_config.h"
13 #include "IMP/em2d/project.h"
16 #include "IMP/em2d/Image.h"
17 #include "IMP/em2d/scores2D.h"
19 #include <IMP/Restraint.h>
20 #include <IMP/log.h>
21 #include <IMP/SingletonContainer.h>
22 
23 IMPEM2D_BEGIN_NAMESPACE
24 
25 /**
26  * This restraint ensures that a set of particles are similar to a set
27  * of EM images. The restraint generates projections of the model that
28  * are then compared with the EM images. The projections are generated from
29  * the radius of its particles. In the case of atoms, the radius is generated
30  * automatically. For other particles the radius has to be provided.
31 */
32 class IMPEM2DEXPORT Em2DRestraint : public Restraint
33 {
34  //! SingletonContainer to store the particles that are restrained
35  Pointer<SingletonContainer> particles_container_;
36  // mutable because it has to change to get projections while evaluating
37 // mutable ProjectionFinder finder_;
38  mutable Pointer<ProjectionFinder> finder_;
39 
40  //! Projection Masks to fast model projection
41  em2d::Images em_images_;
42  em2d::Images em_variances_;
43  unsigned int number_of_optimized_projections_;
44  bool fast_optimization_mode_;
45  bool only_coarse_registration_;
46  Em2DRestraintParameters params_;
47 public:
48 
49  /**
50  * Creates the restraint. You are not done yet by creating the restraint.
51  * After creating it, you need to call the setup() function
52  */
54 
55  /**
56  * Initializes the restraint
57  * @param score_function Scoring function to use to evalute the similarity
58  * between particles and projections
59  * @param params All the parameters required for the restraint
60  */
61  void setup(ScoreFunction *score_function,
62  const Em2DRestraintParameters &params) {
63  params_ = params;
64  finder_ = new ProjectionFinder;
65  finder_->set_was_used(true);
66  finder_->setup(score_function, params);
67  fast_optimization_mode_ = false;
68  only_coarse_registration_ = false;
69 }
70 
71  /**
72  * Sets the particles used to compute projections.
73  * @param particles_container All the particles must be in the container
74  */
75  void set_particles(SingletonContainer *particles_container);
76 
77  /**
78  * Sets the EM images to use as restraints
79  * @param em_images The images
80  */
81  void set_images(const em2d::Images em_images);
82 
83  /*! Sets the variance images of EM images. This is useful if the
84  image is a class average
85  Note: Not all the scoring function use this
86  data
87  */
88  /**
89  * Sets the variance images for class averages. If class averages are used
90  * as restraints, it is possible to use the variance images to assign a
91  * standard deviation (error) for each of the pixels in a class average.
92  * @param variance_images
93  * @note Not all the scoring functions use the variance images
94  * @note This function is functional as is tested, but has not been tested
95  * in a real application yet.
96  */
97  void set_variance_images(const em2d::Images variance_images);
98 
99  /**
100  * Sets fast mode for computing the restraint. This mode only makes sense
101  * it the set_coarse_registration_mode option is false. This option only
102  * optimizes some coarse results (those given by the argument)
103  * to get the refined value.
104  * This option is very fast compared to a full optimization, and almost
105  * always is a good idea to use it with 1-5 results.
106  * This mode is still significantly slow compared to
107  * set_coarse_registration_mode(), but the values optimized are optimum.
108  * @param n The number of images to optimize
109  */
110  void set_fast_mode(unsigned int n);
111 
112  /**
113  * If the value provided to this function is true, restraint operates
114  * only using a coarse registration scheme (maximizing the cross correlation
115  * coefficient).
116  * This option (which is set to false by default) can speed the evaluation
117  * of the restraint by a order of magnitude, but the values obtained are
118  * not going to be less accurate. You could want to activate it at the
119  * beginning of an optimization.
120  * @param opt true if you want to use the coarse mode
121  */
123  if(opt) only_coarse_registration_ = true;
124  }
125 
126  /**
127  * Get the registration results for each of the images after finishing the
128  * optimization. Obviously, requesting the results before optimizing is an
129  * error
130  * @return A list of registration results
131  */
133  return finder_->get_registration_results();
134  }
135 
137 };
138 
140 
141 IMPEM2D_END_NAMESPACE
142 
143 #endif /* IMPEM2D_EM_2DRESTRAINT_H */