IMP logo
IMP Reference Guide  2.19.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-2022 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$, where \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 IMPEM_END_NAMESPACE
115 
116 #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.
Vector< VectorD< 3 > > Vector3Ds
Definition: VectorD.h:427
std::pair< double, double > FloatPair
A generic pair of floats.
Definition: types.h:26
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.
Class for handling density maps.
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.
Sampled density map.