IMP logo
IMP Reference Guide  2.20.2
The Integrative Modeling Platform
em2d/Em2DRestraint.h
Go to the documentation of this file.
1 /**
2  * \file IMP/em2d/Em2DRestraint.h
3  * \brief A restraint to score the fitness of a model to a set of EM images
4  *
5  * Copyright 2007-2022 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  //! SingletonContainer to store the particles that are restrained
34  Pointer<SingletonContainer> particles_container_;
35  // mutable because it has to change to get projections while evaluating
36  // mutable ProjectionFinder finder_;
37  mutable Pointer<ProjectionFinder> finder_;
38 
39  //! Projection Masks to fast model projection
40  em2d::Images em_images_;
41  em2d::Images em_variances_;
42  unsigned int number_of_optimized_projections_;
43  bool fast_optimization_mode_;
44  bool only_coarse_registration_;
46 
47  public:
48  /**
49  * Creates the restraint. You are not done yet by creating the restraint.
50  * After creating it, you need to call the setup() function
51  */
52  Em2DRestraint(Model *m);
53 
54  /**
55  * Initializes the restraint
56  * @param score_function Scoring function to use to evaluate the similarity
57  * between particles and projections
58  * @param params All the parameters required for the restraint
59  */
60  void setup(ScoreFunction *score_function,
61  const Em2DRestraintParameters &params) {
62  params_ = params;
63  finder_ = new ProjectionFinder;
64  finder_->set_was_used(true);
65  finder_->setup(score_function, params);
66  fast_optimization_mode_ = false;
67  only_coarse_registration_ = false;
68  }
69 
70  /**
71  * Sets the particles used to compute projections.
72  * @param particles_container All the particles must be in the container
73  */
74  void set_particles(SingletonContainer *particles_container);
75 
76  /**
77  * Sets the EM images to use as restraints
78  * @param em_images The images
79  */
80  void set_images(const em2d::Images em_images);
81 
82  /*! Sets the variance images of EM images. This is useful if the
83  image is a class average
84  Note: Not all the scoring function use this
85  data
86  */
87  /**
88  * Sets the variance images for class averages. If class averages are used
89  * as restraints, it is possible to use the variance images to assign a
90  * standard deviation (error) for each of the pixels in a class average.
91  * @param variance_images
92  * @note Not all the scoring functions use the variance images
93  * @note This function is functional as is tested, but has not been tested
94  * in a real application yet.
95  */
96  void set_variance_images(const em2d::Images variance_images);
97 
98  /**
99  * Sets fast mode for computing the restraint. This mode only makes sense
100  * it the set_coarse_registration_mode option is false. This option only
101  * optimizes some coarse results (those given by the argument)
102  * to get the refined value.
103  * This option is very fast compared to a full optimization, and almost
104  * always is a good idea to use it with 1-5 results.
105  * This mode is still significantly slow compared to
106  * set_coarse_registration_mode(), but the values optimized are optimum.
107  * @param n The number of images to optimize
108  */
109  void set_fast_mode(unsigned int n);
110 
111  /**
112  * If the value provided to this function is true, restraint operates
113  * only using a coarse registration scheme (maximizing the cross correlation
114  * coefficient).
115  * This option (which is set to false by default) can speed the evaluation
116  * of the restraint by a order of magnitude, but the values obtained are
117  * not going to be less accurate. You could want to activate it at the
118  * beginning of an optimization.
119  * @param opt true if you want to use the coarse mode
120  */
122  if (opt) only_coarse_registration_ = true;
123  }
124 
125  /**
126  * Get the registration results for each of the images after finishing the
127  * optimization. Obviously, requesting the results before optimizing is an
128  * error
129  * @return A list of registration results
130  */
132  return finder_->get_registration_results();
133  }
134 
135  virtual double unprotected_evaluate(IMP::DerivativeAccumulator *accum)
136  const override;
137  virtual IMP::ModelObjectsTemp do_get_inputs() const override;
139 };
140 
142 
143 IMPEM2D_END_NAMESPACE
144 
145 #endif /* IMPEM2D_EM_2DRESTRAINT_H */
Generation of projections from models or density maps Copyright 2007-2022 IMP Inventors. All rights reserved.
projection masks Copyright 2007-2023 IMP Inventors. All rights reserved.
RegistrationResults get_registration_results() const
A container for Singletons.
#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.
IMP images for Electron Microscopy using openCV matrices Copyright 2007-2022 IMP Inventors. All rights reserved.
A smart pointer to a reference counted object.
Definition: Pointer.h:87
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Scoring functions for 2D Copyright 2007-2022 IMP Inventors. All rights reserved.
void setup(ScoreFunction *score_function, const Em2DRestraintParameters &params)
Base class for all scoring functions related to em2d.
Definition: scores2D.h:55
A shared container for Singletons.
void set_coarse_registration_mode(bool opt)
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
Coarse registration of 2D projections from a 3D volume.
Parameters used by Em2DRestraint and ProjectionFinder.
Abstract base class for all restraints.
Logging and error reporting support.
Registration results class Copyright 2007-2022 IMP Inventors. All rights reserved.
Class to perform registration of model projections to images.
virtual ModelObjectsTemp do_get_inputs() const =0
Class for adding derivatives from restraints to the model.
void set_was_used(bool tf) const
A restraint is a term in an IMP ScoringFunction.
Definition: Restraint.h:56