IMP logo
IMP Reference Guide  2.15.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-2021 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 //! Calculates the value of the EM fitting term.
26 /** \note The function returns scalefac*(1-ccc)
27  to support minimization optimization. The ccc value (cross
28  correlation coefficient) is calculated by the
29  cross_correlation_coefficient function.
30  \param[in] data DensityMap class containing the EM map. note:
31  correct RMSD and mean MUST be in the header!
32  \param[in] model_map SampledDensityMap class prepared to contain the
33  simulated EM map for the model.
34  \param[in] scalefactor scale factor to apply to the value of the cross
35  correlation term
36  \param[in] recalc_rms determines whether the RMS of both maps
37  should be recalculated prior to the correlation calculation.
38  False is faster, but potentially inaccurate
39  \param[in] resample if true, the model density map is resampled
40  \param[in] norm_factors if set these precalculated terms are used
41  for normalization
42  \return the value of the cross correlation term: scalefac*(1-ccc)
43  \see cross_correlation_coefficient
44  */
45 IMPEMEXPORT
46 double get_coarse_cc_score(DensityMap *data, SampledDensityMap *model_map,
47  double scalefactor, bool recalc_rms = true,
48  bool resample = true,
49  FloatPair norm_factors = FloatPair(0., 0.));
50 
51 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
52 //! Computes the derivatives of the cross correlation term at each voxel.
53 /** \param[in] em_map the target density map.
54  \param[in] model_map the density map of the model
55  \param[in] model_ps the particles sampled in model_map
56  \param[in] mass_key the key of the mass attribute of the particles
57  \param[in] scalefac scale factor to apply to the value of the cross
58  correlation term
59  \return a vector of derivatives
60  \note: The function assumes that correct RMS are calculated for the
61  densities
62  */
63 IMPEMEXPORT
64 algebra::Vector3Ds get_coarse_cc_derivatives(const DensityMap *em_map,
65  const DensityMap *model_map,
66  const Particles &model_ps,
67  const FloatKey &mass_key,
68  KernelParameters *kernel_params,
69  double scalefac,
70  const algebra::Vector3Ds &dv);
71 #endif
72 
73 //! Calculates the cross correlation coefficient between two maps
74 /** Cross correlation coefficient between the em density and the density of a
75  model. The function applied is:
76  \f$\frac{\sum_{i=1}^{N}{{td}_i}{{md}_i}-{N}
77  {{mean}_{td}}
78  {{mean}_{md}}}
79  {N\sigma_{{td}}\sigma_{{md}}}\f$, such that \f$N\f$ is the number of
80  voxels, \f${td}\f$ is the target density,
81  \f${tm}\f$ is the model density,
82  \param[in] grid1 The first 3D grid
83  \param[in] grid2 The second 3D grid
84  \param[in] grid2_voxel_data_threshold voxels with value lower
85  than threshold
86  in grid2 are not summed (avoid calculating correlation on
87  voxels below the threshold
88  \param[in] allow_padding determines whether the two maps should be padded
89  to have the same size before the calculation is performed.
90  If set to false and the grids are not of the same size,
91  the function will throw an exception.
92  \param[in] norm_factors if set these precalculated terms are used
93  for normalization
94  \return the cross correlation coefficient value between two density maps
95  \note This is not the local CC function
96  \todo check that the mean is always subtracted from the em-density.
97  The problem is that we divide by nvox*d1_mean*d2_mean, but if we
98  use voxel_data_threshold that does not consist of the entire map
99  this would be wrong. Fix it.
100  */
101 IMPEMEXPORT
102 double get_coarse_cc_coefficient(const DensityMap *grid1,
103  const DensityMap *grid2,
104  double grid2_voxel_data_threshold,
105  bool allow_padding = false,
106  FloatPair norm_factors = FloatPair(0., 0.));
107 
108 //! Local cross correlation function
109 IMPEMEXPORT
110 double get_coarse_cc_local_coefficient(const DensityMap *em_map,
111  DensityMap *model_map,
112  double voxel_data_threshold);
113 
114 
115 //! Responsible for performing coarse fitting between two density objects.
116 /**
117  \note Do not use this class as an example for writing new code!
118  The design (a class with no storage, and only static methods)
119  is not ideal. A better implementation would just be a collection
120  of free functions, not in a class; see above.
121  */
122 class IMPEMEXPORT CoarseCC : public IMP::Object {
123 
124  public:
125  IMPEM_DEPRECATED_OBJECT_DECL(2.15)
126  CoarseCC() : Object("CoarseCC%1%") {
127  IMPEM_DEPRECATED_OBJECT_DEF(2.15, "Use free functions instead");
128  }
129 
130  IMPEM_DEPRECATED_METHOD_DECL(2.15)
131  static float calc_score(DensityMap *data, SampledDensityMap *model_map,
132  float scalefactor, bool recalc_rms = true,
133  bool resample = true,
134  FloatPair norm_factors = FloatPair(0., 0.));
135 
136 #if !defined(IMP_DOXYGEN) && !defined(SWIG)
137  IMPEM_DEPRECATED_METHOD_DECL(2.15)
138  static algebra::Vector3Ds calc_derivatives(const DensityMap *em_map,
139  const DensityMap *model_map,
140  const Particles &model_ps,
141  const FloatKey &mass_key,
142  KernelParameters *kernel_params,
143  const float &scalefac,
144  const algebra::Vector3Ds &dv);
145 #endif
146 
147  IMPEM_DEPRECATED_METHOD_DECL(2.15)
148  static double cross_correlation_coefficient(const DensityMap *grid1,
149  const DensityMap *grid2,
150  float grid2_voxel_data_threshold,
151  bool allow_padding = false,
152  FloatPair norm_factors =
153  FloatPair(0., 0.));
154 
155  IMPEM_DEPRECATED_METHOD_DECL(2.15)
156  static float local_cross_correlation_coefficient(const DensityMap *em_map,
157  DensityMap *model_map,
158  float voxel_data_threshold);
159 
161 };
162 
163 IMPEM_END_NAMESPACE
164 
165 #endif /* IMPEM_COARSE_CC_H */
Key< 0 > FloatKey
The type used to identify float attributes in the Particles.
Definition: base_types.h:32
Definitions for EMBED.
double get_coarse_cc_coefficient(const DensityMap *grid1, const DensityMap *grid2, double grid2_voxel_data_threshold, bool allow_padding=false, FloatPair norm_factors=FloatPair(0., 0.))
Calculates the cross correlation coefficient between two maps.
Calculates and stores Gaussian kernel parameters.
Vector< VectorD< 3 > > Vector3Ds
Definition: VectorD.h:423
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
std::pair< double, double > FloatPair
A generic pair of floats.
Definition: types.h:27
masking tools
Represent a molecule as shells of distance from the surface.
double get_coarse_cc_score(DensityMap *data, SampledDensityMap *model_map, double scalefactor, bool recalc_rms=true, bool resample=true, FloatPair norm_factors=FloatPair(0., 0.))
Calculates the value of the EM fitting term.
An approximation of the exponential function.
Responsible for performing coarse fitting between two density objects.
Definition: CoarseCC.h:122
Class for handling density maps.
Class for handling density maps.
Definition: DensityMap.h:93
Class for sampling a density map from particles.
Common base class for heavy weight IMP objects.
Definition: Object.h:106
Refine a particle into a list of particles.
functionality for defining rigid bodies
double get_coarse_cc_local_coefficient(const DensityMap *em_map, DensityMap *model_map, double voxel_data_threshold)
Local cross correlation function.
Object(std::string name)
Construct an object with the given name.
Sampled density map.