IMP logo
IMP Reference Guide  2.20.2
The Integrative Modeling Platform
Statistical.h
Go to the documentation of this file.
1 /**
2  * \file IMP/score_functor/Statistical.h
3  * \brief A Score on the distance between a pair of particles.
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPSCORE_FUNCTOR_STATISTICAL_H
9 #define IMPSCORE_FUNCTOR_STATISTICAL_H
10 
11 #include <IMP/score_functor/score_functor_config.h>
12 #include "Score.h"
13 #include <IMP/Model.h>
14 #include "internal/PMFTable.h"
15 #include <IMP/Pointer.h>
16 #include <IMP/algebra/utility.h>
17 IMPSCOREFUNCTOR_BEGIN_NAMESPACE
18 
19 /** Create a pairwise statistical potential from a file. The Keys passed
20  as a template argument are used to determine how to map the names of
21  the types as described in the loaded file to indexes. That is, if
22  atom::ResidueKey is passed as the Keys, the potential will expect a file
23  which has one line for each pair of residue names.
24 
25  The expected file format is:
26 \verbatim
27  bin_width number_a number_b [offset]
28  key_0a key_0b bin0 bin1 bin2...
29  key_1a key_1b bin0 bin1 bin2...
30 \endverbatim
31 
32  The order of the lines (after the first one) does not matter.
33  The bin_width is how much distance is allocated per bin (the distance used
34  is that between the points). number_a and number_b are the numbers of
35  particle types (number_b should only be specified if BIPARTITE is set).
36 
37  \note The values read in the file are for bins. That is, the first bin
38  is from offset to offset+width. The second is offset+width to offset+
39  2width.
40  As a result, when interpolation is used, the function achieves the
41  bin value at the center of the bin.
42 
43  \param[in] Key is an IMP::Key which maps between names and indices
44  \param[in] BIPARTITE If true, the two sets of particles being stored are
45  different (e.g. a protein atom and a ligand atom), otherwise they are
46  assumed to both be the same. Appropriate values must be provided
47  in the file.
48  \param[in] INTERPOLATE If true, even the scores without derivatives are
49  spline interpolated. If false, only the evaluation of derivatives is
50  interpolated with a spline.
51 */
52 template <class Key, bool BIPARTITE, bool INTERPOLATE, bool SPARSE = false>
53 class Statistical : public Score {
54  typedef internal::PMFTable<BIPARTITE, INTERPOLATE, SPARSE> Table;
55  PointerMember<Table> table_;
56  double threshold_;
57  IntKey key_;
58 
59  public:
60  /** \param[in] k The attribute to use for determining the particle types
61  \param[in] threshold The maximum distance to score
62  \param[in] data_file Where to load the file from.
63  */
64  Statistical(IntKey k, double threshold, TextInput data_file)
65  : table_(new Table(data_file, 0, Key())), threshold_(threshold), key_(k) {
66  IMP_USAGE_CHECK(!BIPARTITE,
67  "Constructor can only be used for non-bipartite scores.");
68  }
69  /** \param[in] k The attribute to use for determining the particle types
70  \param[in] threshold The maximum distance to score
71  \param[in] data_file Where to load the file from.
72  \param[in] shift The offset for the types of the second set of types.
73  eg, if the score is on protein and ligand atoms, the ligand atom types
74  start with the value shift.
75  */
76  Statistical(IntKey k, double threshold, TextInput data_file,
77  unsigned int shift)
78  : table_(new Table(data_file, shift, Key())),
79  threshold_(threshold),
80  key_(k) {
81  IMP_USAGE_CHECK(BIPARTITE,
82  "Constructor can only be used for bipartite scores.");
83  }
84 
85  Statistical() {}
86 
87  // depend on get_is_trivially_zero
88  double get_score(Model *m, const ParticleIndexPair &pp,
89  double distance) const {
90  if (distance >= threshold_ || distance < 0.001) {
91  return 0;
92  }
93  int pt = m->get_attribute(key_, pp[0]);
94  int lt = m->get_attribute(key_, pp[1]);
95  if (pt == -1 || lt == -1) return 0;
96  return table_->get_score(pt, lt, distance);
97  }
98  DerivativePair get_score_and_derivative(
99  Model *m, const Array<2, ParticleIndex> &pp,
100  double distance) const {
101  if (distance >= threshold_ || distance < 0.001) {
102  return DerivativePair(0, 0);
103  }
104  int pt = m->get_attribute(key_, pp[0]);
105  int lt = m->get_attribute(key_, pp[1]);
106  if (pt == -1 || lt == -1) return DerivativePair(0, 0);
107  return table_->get_score_with_derivative(pt, lt, distance);
108  }
109  double get_maximum_range(Model *, const ParticleIndexPair &) const {
110  return std::min(threshold_, table_->get_max());
111  }
112  bool get_is_trivially_zero(Model *m, const ParticleIndexPair &p,
113  double squared_distance) const {
114  return squared_distance > algebra::get_squared(get_maximum_range(m, p));
115  }
116 };
117 
118 IMPSCOREFUNCTOR_END_NAMESPACE
119 
120 #endif /* IMPSCORE_FUNCTOR_STATISTICAL_H */
Statistical(IntKey k, double threshold, TextInput data_file, unsigned int shift)
Definition: Statistical.h:76
Storage of a model, its restraints, constraints and particles.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Functions to deal with very common math operations.
A Score on the distance between a pair of particles.
std::pair< double, double > DerivativePair
A pair representing a function value with its first derivative.
Definition: types.h:22
Statistical(IntKey k, double threshold, TextInput data_file)
Definition: Statistical.h:64
A nullptr-initialized pointer to an IMP Object.
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
A functor for computing a distance based score for D particles.
Definition: Score.h:20
Type get_attribute(TypeKey attribute_key, ParticleIndex particle)
get the value of the particle attribute with the specified key