IMP  2.0.0
The Integrative Modeling Platform
CoarseCC.h
Go to the documentation of this file.
1 /**
2  * \file IMP/em/CoarseCC.h
3  * \brief Perform coarse fitting between two density objects.
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPEM_COARSE_CC_H
10 #define IMPEM_COARSE_CC_H
11 
12 #include <IMP/em/em_config.h>
13 #include "exp.h"
14 #include "DensityMap.h"
15 #include "SampledDensityMap.h"
16 #include "SurfaceShellDensityMap.h"
17 #include "def.h"
18 #include <vector>
19 #include <IMP/core/rigid_bodies.h>
20 #include <IMP/Refiner.h>
21 #include "masking.h"
22 
23 IMPEM_BEGIN_NAMESPACE
24 
25 //! Responsible for performing coarse fitting between two density objects.
26 /** The pixels involved are derived from the positions of N particles.
27  */
28 class IMPEMEXPORT CoarseCC : public IMP::base::Object
29 {
30 
31 public:
32  CoarseCC():Object("CoarseCC%1%"){}
33  //! Calculates the value of the EM fitting term.
34  /** \note The function returns scalefac*(1-ccc)
35  to support minimization optimization. The ccc value (cross
36  correlation coefficient) is calculate by the
37  cross_correlation_coefficient function.
38  \param[in] data DensityMap class containing the EM map. note:
39  correct RMSD and mean MUST be in the header!
40  \param[in] model_map SampledDensityMap class prepared to contain the
41  simulated EM map for the model.
42  \param[in] scalefactor scale factor to apply to the value of the cross
43  correlation term
44  \param[in] recalc_rms determines wheather the RMS of both maps
45  should be recalcualted prior to the correlation calculation.
46  False is faster, but potentially innacurate
47  \param[in] resample if true, the model density map is resampled
48  \param[in] norm_factors if set these precalcualted terms are used
49  for normalization
50  \return the value of the cross correlation term: scalefac*(1-ccc)
51  \relatesalso cross_correlation_coefficient
52  */
53  static float calc_score(
54  DensityMap *data, SampledDensityMap *model_map,
55  float scalefactor,
56  bool recalc_rms=true,bool resample=true,
57  FloatPair norm_factors=FloatPair(0.,0.));
58 
59 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
60 /**
61  Computes the derivatives of the cross correlation term scalefac*(1-ccc) at each
62  voxel of the map.
63  \param[in] em_map the target density map.
64  \param[in] model_map the density map of the model
65  \param[in] model_ps the particles sampled in model_map
66  \param[in] mass_key the key of the mass attribute of the particles
67  \param[in] scalefac scale factor to apply to the value of the cross
68  correlation term
69  \return a vector of derivatives
70  \note: The function assumes that correct RMS are calculated for the densities
71 */
72  static algebra::Vector3Ds calc_derivatives(
73  const DensityMap *em_map, const DensityMap *model_map,
74  const Particles &model_ps,const FloatKey &mass_key,
75  KernelParameters *kernel_params,
76  const float &scalefac, const algebra::Vector3Ds &dv);
77 #endif
78 
79  //!Calculates the cross correlation coefficient between two maps
80  /** Cross correlation coefficient between the em density and the density of a
81  model. The function applied is:
82  \f$\frac{\sum_{i=1}^{N}{{td}_i}{{md}_i}-{N}
83  {{mean}_{td}}
84  {{mean}_{md}}}
85  {N\sigma_{{td}}\sigma_{{md}}}\f$, such that \f$N\f$ is the number of
86  voxels, \f${td}\f$ is the target density,
87  \f${tm}\f$ is the model density,
88  \param[in] grid1 The first 3D grid
89  \param[in] grid2 The second 3D grid
90  \param[in] grid2_voxel_data_threshold voxels with value lower
91  than threshold
92  in grid2 are not summed (avoid calculating correlation on
93  voxels below the threshold
94  \param[in] allow_padding determines wheather the two maps should be padded
95  to have the same size before the calcualtion is performed.
96  If set to false and the grids are not of the same size,
97  the function will throw an exception.
98  \param[in] norm_factors if set these precacluated terms are used
99  for normalization
100  \return the cross correlation coefficient value between two density maps
101  \note This is not the local CC function
102  \todo check that the mean is always subtracted from the em-density.
103  The problem is that we divide by nvox*d1_mean*d2_mean, but if we
104  use voxel_data_threshold that does not consist of the entire map
105  this would be wrong. Fix it.
106  */
107  static double cross_correlation_coefficient(
108  const DensityMap *grid1,
109  const DensityMap *grid2,
110  float grid2_voxel_data_threshold,
111  bool allow_padding=false,
112  FloatPair norm_factors=FloatPair(0.,0.));
113 
114  //! Local cross correlation function
115 static float local_cross_correlation_coefficient(const DensityMap *em_map,
116  DensityMap *model_map,
117  float voxel_data_threshold);
118 
120 };
121 
122 
123 
124 IMPEM_END_NAMESPACE
125 
126 #endif /* IMPEM_COARSE_CC_H */