IMP  2.1.0
The Integrative Modeling Platform
rigid_fitting.h
Go to the documentation of this file.
1 /**
2  * \file IMP/em/rigid_fitting.h
3  * \brief preforms rigid fitting between a set of particles and a density map
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPEM_RIGID_FITTING_H
9 #define IMPEM_RIGID_FITTING_H
10 
11 #include <IMP/core/MonteCarlo.h>
13 #include <IMP/RestraintSet.h>
15 #include <IMP/kernel/Particle.h>
16 #include <IMP/kernel/Model.h>
17 #include "DensityMap.h"
18 #include "FitRestraint.h"
19 #include <IMP/em/em_config.h>
20 #include <IMP/OptimizerState.h>
21 #include <IMP/core/rigid_bodies.h>
22 #include <IMP/ScoreState.h>
23 #include <algorithm>
24 IMPEM_BEGIN_NAMESPACE
25 
26 
27 //! A simple list of fitting solutions.
28 /**
29  \see local_rigid_fitting_around_point
30  \see local_rigid_fitting_around_points
31  \see local_rigid_fitting_grid_search
32  \see compute_fitting_scores
33  */
34 class IMPEMEXPORT FittingSolutions {
35 typedef std::pair<algebra::Transformation3D,Float> FittingSolution;
36 struct sort_by_cc
37 {
38  bool operator()(const FittingSolution &s1, const FittingSolution & s2) const
39  {
40  return s1.second < s2.second;
41  }
42 };
43 public:
45  //! Get the number of solutions in the set
46  inline int get_number_of_solutions() const {return fs_.size();}
47  //! Get the score of the i'th solution
48  /**
49  \return the i'th transformation, or throw an exception
50  if the index is out of range
51  */
52  inline algebra::Transformation3D get_transformation(unsigned int i) const {
53  IMP_USAGE_CHECK(i<fs_.size(),"The index requested ("<<
54  i<<") in get_transformation is our of range ("<<
55  fs_.size()<<")"<<std::endl);
56  return fs_[i].first;
57  }
58  //! Get the score of the i'th solution
59  /**
60  \return the i'th score, or throw an exception
61  if the index is out of range
62  */
63  inline Float get_score(unsigned int i) const {
64  IMP_USAGE_CHECK(i<fs_.size(),"The index requested ("<<
65  i<<") in get_transformation is out of range ("<<
66  fs_.size()<<")"<<std::endl);
67  return fs_[i].second;
68  }
69  void set_score(unsigned int i,Float score) {
70  IMP_USAGE_CHECK(i<fs_.size(),"The index requested ("<<
71  i<<") in get_transformation is out of range ("<<
72  fs_.size()<<")"<<std::endl);
73  fs_[i].second=score;
74  }
75  //! Add a solution to the fitting solution set
76  void add_solution(const algebra::Transformation3D &t,Float score);
77  //! Sort solutions by cross-correlation scores
78  void sort(bool reverse=false);
79  //! Multiply each transformation (T) by t,
80  //!such that the new transformation are T*t
82  for(unsigned int i=0;i<fs_.size();i++) fs_[i].first=fs_[i].first*t;
83  }
84  inline algebra::Transformation3Ds get_transformations() const {
86  for(unsigned int i=0;i<fs_.size();i++) all_ts.push_back(fs_[i].first);
87  return all_ts;
88  }
89  void show(std::ostream& out=std::cout) const {
90  for(std::vector<FittingSolution>::const_iterator it = fs_.begin();
91  it != fs_.end(); it++) {
92  out<<"("<<it->first<<" , "<<it->second<<")"<<std::endl;
93  }
94  }
95 protected:
96  std::vector<FittingSolution> fs_;
97 };
99 
100 //! Local rigid fitting of a rigid body around a center point
101 /**
102 \brief Fit a set of particles to a density map around an anchor point.
103  The fitting is assessed using the cross-correaltion score.
104  The optimization is a standard MC/CG procedure.
105  The function returns a list of solutions sortedo the cross-correlation
106  score.
107 \note The returned cross-correlation score is 1-cc, as we usually want to
108  minimize a scroing function. Thus a score of 1 means no-correlation
109  and a score of 0. is perfect correlation.
110 \note The input rigid body should be also IMP::atom::Hierarchy
111 \param[in] p The rigid body to fit
112 \param[in] refiner Refiner to yield rigid body members
113 \param[in] weight_key The weight key of the particles in the rigid body
114 \param[in] dmap The density map to fit to
115 \param[in] anchor_centroid The point to fit the particles around
116 \param[in] display_log If provided, then intermediate states
117  in during the optimization procedure are printed
118 \param[in] number_of_optimization_runs number of Monte Carlo optimizations
119 \param[in] number_of_mc_steps number of steps in a Monte Carlo optimization
120 \param[in] number_of_cg_steps number of Conjugate Gradients steps in
121  a Monte Carlo step
122 \param[in] max_translation maximum translation step in a MC optimization step
123 \param[in] max_rotation maximum rotation step in a single MC optimization step
124 \param[in] fast if true the density map of the rigid body is not resampled
125  but transformed at each iteration of the optimization
126 \return the refined fitting solutions
127 */
129  kernel::Particle *p, Refiner *refiner,
130  const FloatKey &weight_key,
131  DensityMap *dmap, const algebra::Vector3D &anchor_centroid,
132  OptimizerStates display_log,
133  Int number_of_optimization_runs = 5, Int number_of_mc_steps = 10,
134  Int number_of_cg_steps=100,
135  Float max_translation=2., Float max_rotation=.3,bool fast=false);
136 
137 //! Local rigid fitting of a rigid body
138 /**
139 \brief Fit a set of particles to a density map around their centroid.
140  The fitting is assessed using the cross-correaltion score.
141  The optimization is a standard MC/CG procedure.
142  The function returns a list of solutions sortedo the cross-correlation
143  score.
144 \note The returned cross-correlation score is 1-cc, as we usually want to
145  minimize a scroing function. Thus a score of 1 means no-correlation
146  and a score of 0. is perfect correlation.
147 \note The input rigid body should be also IMP::atom::Hierarchy
148 \param[in] p The root of the hierarchy to fit
149 \param[in] refiner The refiner to get the leaves of the particle
150 \param[in] weight_key The weight key of the particles in the rigid body
151 \param[in] dmap The density map to fit to
152 \param[in] display_log If provided, then intermediate states
153  in during the optimization procedure are printed
154 \param[in] number_of_optimization_runs number of Monte Carlo optimizations
155 \param[in] number_of_mc_steps number of steps in a Monte Carlo optimization
156 \param[in] number_of_cg_steps number of Conjugate Gradients steps in
157  a Monte Carlo step
158 \param[in] max_translation maximum translation step in a MC optimization step
159 \param[in] max_rotation maximum rotation step in radians in a single
160  MC optimization step
161 \param[in] fast if true the density map of the rigid body is not resampled
162  but transformed at each iteration of the optimization
163 \return the refined fitting solutions
164 */
165 
167  kernel::Particle *p, Refiner *refiner,
168  const FloatKey &weight_key,
169  DensityMap *dmap,
170  OptimizerStates display_log,
171  Int number_of_optimization_runs = 5, Int number_of_mc_steps = 10,
172  Int number_of_cg_steps=100,
173  Float max_translation=2., Float max_rotation=.3,
174  bool fast=true) {
175  IMP_LOG_VERBOSE("Start: local_rigid_fitting\n");
176  algebra::Vector3D rb_cen=
178  IMP_LOG_VERBOSE("centroid is:"<<rb_cen<<"\n");
180  p, refiner,weight_key, dmap,
181  rb_cen,display_log,
182  number_of_optimization_runs, number_of_mc_steps,
183  number_of_cg_steps, max_translation, max_rotation,fast);
184 }
185 
186 
187 //! Local rigid fitting of a rigid body around a set of center points
188 /**
189 \brief Fit a set of particles to a density map around each of the input points.
190  The function apply local_rigid_fitting_around_point around each center.
191 \note The input rigid body should be also IMP::atom::Hierarchy
192 \param[in] p The rigid body to fit
193 \param[in] refiner Refiner to yield rigid body members
194 \param[in] wei_key The weight key of the particles in the rigid body
195 \param[in] dmap The density map to fit to
196 \param[in] anchor_centroids The points to fit the particles around
197 \param[in] display_log If provided, then intermediate states
198  in during the optimization procedure are printed
199 \param[in] number_of_optimization_runs number of Monte Carlo optimizations
200 \param[in] number_of_mc_steps number of steps in a Monte Carlo optimization
201 \param[in] number_of_cg_steps number of Conjugate Gradients steps in
202  a Monte Carlo step
203 \param[in] max_translation maximum translation step in a MC optimization step
204 \param[in] max_rotation maximum rotation step in a single MC optimization step
205 \return the refined fitting solutions
206 */
207 IMPEMEXPORT FittingSolutions local_rigid_fitting_around_points(
208  kernel::Particle *p,Refiner *refiner,
209  const FloatKey &wei_key,
210  DensityMap *dmap, const algebra::Vector3Ds &anchor_centroids,
211  OptimizerStates display_log,
212  Int number_of_optimization_runs = 5, Int number_of_mc_steps = 10,
213  Int number_of_cg_steps=100,
214  Float max_translation=2., Float max_rotation=.3);
215 
216 
217 //! Local grid search rigid fitting
218 /**
219 \brief Fit a set of particles to a density map around their centroid.
220  The fitting is assessed using the cross-correaltion score.
221  The optimization is a grid search
222 \note The transformations are not clustered.
223 \note The returned cross-correlation score is 1-cc, as we usually want to
224  minimize a scroing function. Thus a score of 1 means no-correlation
225  and a score of 0. is perfect correlation.
226 \param[in] ps The particles to be fitted (treated rigid)
227 \param[in] wei_key The weight key of the particles in the rigid body
228 \param[in] dmap The density map to fit to
229 \param[in] max_voxels_translation Sample translations within
230  -max_voxel_translation to max_voxel_translation
231 \param[in] translation_step The translation sampling step
232 \param[in] max_angle_in_radians Sample rotations with +- max_angle_in_radians
233  around the current rotation
234 \param[in] number_of_rotations The number of rotations to sample
235 \return the refined fitting solutions
236 */
237 IMPEMEXPORT FittingSolutions local_rigid_fitting_grid_search(
238  const kernel::ParticlesTemp &ps,
239  const FloatKey &wei_key,
240  DensityMap *dmap,
241  Int max_voxels_translation=2,
242  Int translation_step=1,
243  Float max_angle_in_radians = 0.174,
244  Int number_of_rotations = 100);
245 
246 
247 //! Compute fitting scores for a given set of rigid transformations
248 /**
249 \brief Score how well a set of particles fit to the map in various
250  rigid transformations.
251 \param[in] ps The particles to be fitted (treated rigid)
252 \param[in] em_map The density map to fit to
253 \param[in] wei_key The weight key of the particles in the rigid body
254 \param[in] fast_version If fast_version is used the sampled density map of the
255  input particles (ps) is not resampled for each
256  transformation but instead the corresponding grid
257  is rotated. This option significantly improves the
258  running times but the returned scores are less accurate
259 \param[in] transformations A set of rigid transformations
260 \param[in] fast_version if true the density map of each transformation
261  is interpolated
262 \param[in] local_score if true a local cross correlation score is used
263 \return The scored fitting solutions
264 \note the function assumes the density map holds its density
265  */
266 IMPEMEXPORT FittingSolutions
268  DensityMap *em_map,
269  const algebra::Transformation3Ds &transformations,
270  bool fast_version=false, bool local_score=false,
271  const FloatKey &wei_key=atom::Mass::get_mass_key());
272 
273 
274 //! Compute fitting scores for a given set of rigid transformations
275 /**
276 \brief Score how well a rigid body fits to the map
277 \param[in] em_map The density map to fit to
278 \param[in] rb The rigid body
279 \param[in] refiner The rigid body refiner
280 \param[in] transformations Transformations of the rigid body
281 \return The scored fitting solutions
282 \note the function assumes the density map holds its density
283  */
285  DensityMap *em_map,
286  core::RigidBody rb,Refiner *refiner,
287  const algebra::Transformation3Ds& transformations) {
288  return compute_fitting_scores(refiner->get_refined(rb),em_map,
289  transformations,true);
290 }
291 
292 
293 
294 //! Compute fitting scores for a given set of rigid transformations
295 /**
296 \brief Scores how well a set of particles fit a map
297 \param[in] ps The particles to be fitted
298 \param[in] em_map The density map to fit to
299 \param[in] wei_key The weight key of the particles in the rigid body
300 \note the function assumes the density map holds its density
301  */
303  DensityMap *em_map,
304  FloatKey wei_key=atom::Mass::get_mass_key());
305 
306 
307 IMPEM_END_NAMESPACE
308 #endif /* IMPEM_RIGID_FITTING_H */
Simple 3D transformation class.
Simple conjugate gradients optimizer.
Calculate score based on fit to EM map.
virtual const ParticlesTemp get_refined(Particle *a) const =0
Refine the passed particle into a set of particles.
Import IMP/kernel/RestraintSet.h in the namespace.
algebra::Transformation3D get_transformation(unsigned int i) const
Get the score of the i&#39;th solution.
Definition: rigid_fitting.h:52
Simple Monte Carlo optimizer.
FittingSolutions local_rigid_fitting_grid_search(const kernel::ParticlesTemp &ps, const FloatKey &wei_key, DensityMap *dmap, Int max_voxels_translation=2, Int translation_step=1, Float max_angle_in_radians=0.174, Int number_of_rotations=100)
Local grid search rigid fitting.
#define IMP_VALUES(Name, PluralName)
Define the type for storing sets of values.
A simple list of fitting solutions.
Definition: rigid_fitting.h:34
algebra::Vector3D get_centroid(const XYZs &ps)
Get the centroid.
FittingSolutions compute_fitting_scores(const kernel::ParticlesTemp &ps, DensityMap *em_map, const algebra::Transformation3Ds &transformations, bool fast_version=false, bool local_score=false, const FloatKey &wei_key=atom::Mass::get_mass_key())
Compute fitting scores for a given set of rigid transformations.
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Class for handling density maps.
Class for handling density maps.
Definition: DensityMap.h:98
functionality for defining rigid bodies
Float compute_fitting_score(const kernel::ParticlesTemp &ps, DensityMap *em_map, FloatKey wei_key=atom::Mass::get_mass_key())
Compute fitting scores for a given set of rigid transformations.
Import IMP/kernel/ScoreState.h in the namespace.
Class to handle individual model particles.
Storage of a model, its restraints, constraints and particles.
Classes to handle individual model particles.
Simple 3D transformation class.
IMP::base::Vector< IMP::base::Pointer< OptimizerState > > OptimizerStates
void show(Hierarchy h, std::ostream &out=std::cout)
Print out a molecular hierarchy.
double Float
Basic floating-point value (could be float, double...)
Definition: base/types.h:20
void multiply(const algebra::Transformation3D &t)
Definition: rigid_fitting.h:81
int Int
Basic integer value.
Definition: base/types.h:35
Import IMP/kernel/OptimizerState.h in the namespace.
FittingSolutions local_rigid_fitting_around_points(kernel::Particle *p, Refiner *refiner, const FloatKey &wei_key, DensityMap *dmap, const algebra::Vector3Ds &anchor_centroids, OptimizerStates display_log, Int number_of_optimization_runs=5, Int number_of_mc_steps=10, Int number_of_cg_steps=100, Float max_translation=2., Float max_rotation=.3)
Local rigid fitting of a rigid body around a set of center points.
A decorator for a rigid body.
Definition: rigid_bodies.h:75
FittingSolutions local_rigid_fitting_around_point(kernel::Particle *p, Refiner *refiner, const FloatKey &weight_key, DensityMap *dmap, const algebra::Vector3D &anchor_centroid, OptimizerStates display_log, Int number_of_optimization_runs=5, Int number_of_mc_steps=10, Int number_of_cg_steps=100, Float max_translation=2., Float max_rotation=.3, bool fast=false)
Local rigid fitting of a rigid body around a center point.
Abstract class to implement hierarchical methods.
int get_number_of_solutions() const
Get the number of solutions in the set.
Definition: rigid_fitting.h:46
#define IMP_LOG_VERBOSE(expr)
FittingSolutions local_rigid_fitting(kernel::Particle *p, Refiner *refiner, const FloatKey &weight_key, DensityMap *dmap, OptimizerStates display_log, Int number_of_optimization_runs=5, Int number_of_mc_steps=10, Int number_of_cg_steps=100, Float max_translation=2., Float max_rotation=.3, bool fast=true)
Local rigid fitting of a rigid body.
Float get_score(unsigned int i) const
Get the score of the i&#39;th solution.
Definition: rigid_fitting.h:63