IMP logo
IMP Reference Guide  2.10.0
The Integrative Modeling Platform
PenalizedComplexityPrior.h
Go to the documentation of this file.
1 /**
2  * \file IMP/isd/PenalizedComplexityPrior.h
3  * \brief Penalized complexity prior.
4  *
5  * Copyright 2007-2018 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPISD_PENALIZED_COMPLEXITY_PRIOR_H
9 #define IMPISD_PENALIZED_COMPLEXITY_PRIOR_H
10 
11 #include <IMP/isd/isd_config.h>
12 #include <IMP/isd/distribution.h>
13 
14 IMPISD_BEGIN_NAMESPACE
15 //! Penalized complexity prior.
16 /** Given a parameter \f$\xi\f$ of a model (distribution)
17  \f$f(x \mid \xi)\f$ with a simpler base model \f$g(x)\f$
18  (\f$f(x \mid \xi=0)\f$ if \f$\xi\f$ is a flexibility parameter), the
19  Penalized Complexity (PC) prior on \f$\xi\f$ minimizes the complexity
20  introduced by deviation from the base model. It corresponds to an
21  exponential distribution on the Kullback–Leibler divergence between the
22  flexible and base models, in terms of \f$\xi\f$.
23 
24  For ease of parameterization, a 'tail event' is defined as an upper bound
25  on an interpretable transformation \f$Q(\xi)\f$ with tail density
26  \f$\alpha\f$, such that \f$P(Q(\xi) > U) = \alpha\f$. With KL divergence
27  defined as
28 
29  \f[ \mathrm{KLD}(f(x \mid \xi) || g(x)) =
30  \int f(x \mid \xi) \log\left(\frac{f(x \mid \xi)}{g(x)}\right) dx,\f]
31 
32  KL divergence at \f$\xi\f$ normalized by KL divergence at the tail
33 
34  \f[ D(\xi) = \frac{\mathrm{KLD}(f(x \mid \xi) || g(x))}{\mathrm{KLD}(f(x \mid \xi=Q^{-1}(U)) || g(x))} ,\f]
35 
36  and
37 
38  \f[ J(\xi) = \frac{\partial D(\xi)}{\partial \xi} ,\f]
39 
40  the density of the PC prior is
41 
42  \f[p(\xi) = \frac{-\log\alpha}{2 \sqrt{D(\xi)}} \alpha^{\sqrt{D(\xi)}} |J(\xi)|.\f]
43 
44  \see NormalSigmaPCRestraint
45 
46  \note For more details, see Simpson et al. Stat Sci. (2017) 32(1): 1. arXiv: 1403.4630
47  \note The log-density with this parameterization overflows when
48  \f$D(\xi)=0\f$. The value of the PC prior at the base model is
49  unique to each case and cannot be provided by this general
50  implementation.
51  */
53  protected:
54  virtual void do_update_sufficient_statistics(Floats Dxis) IMP_OVERRIDE;
55  virtual void do_update_sufficient_statistics(Floats Dxis, Floats Jxis);
56  virtual Floats do_get_sufficient_statistics() const IMP_OVERRIDE;
57  virtual double do_evaluate() const IMP_OVERRIDE;
58 
59  public:
60  //! Create from normalized KL divergence.
61  /** \param [in] Dxi Normalized KL divergence \f$D(\xi)\f$.
62  \param [in] Jxi Derivative \f$J(\xi)\f$ of normalized KL divergence.
63  \param [in] alpha Density in tail.
64  \param [in] name Name of prior.
65  */
66  PenalizedComplexityPrior(double Dxi, double Jxi, double alpha,
67  std::string name = "PenalizedComplexityPrior %1%");
68 
69  //! Update sufficient statistics with values and derivatives.
71  do_update_sufficient_statistics(Dxis, Jxis);
72  }
73 
74  //! Evaluate derivative of negative log-density wrt \f$D(\xi)\f$.
75  double evaluate_derivative_Dxi() const;
76 
77  //! Evaluate derivative of negative log-density wrt derivative of \f$D(\xi)\f$.
78  double evaluate_derivative_Jxi() const;
79 
80  //! Evaluate derivative of negative log-density wrt alpha.
81  double evaluate_derivative_alpha() const;
82 
83  //! Evaluate derivative of negative log-density wrt parameter \f$\xi\f$.
84  /** \param [in] JJxi Second derivative of normalized KL divergence wrt \f$\xi\f$.
85  */
86  double evaluate_derivative_xi(double JJxi) const;
87 
88  //! Set normalized KL divergence \f$D(\xi)\f$.
89  void set_Dxi(double v);
90 
91  //! Set derivative of normalized KL divergence \f$D(\xi)\f$ wrt \f$\xi\f$.
92  void set_Jxi(double v);
93 
94  //! Set density in tail.
95  void set_alpha(double v);
96 
97  //! Get normalized KL divergence \f$D(\xi)\f$.
98  double get_Dxi() const;
99 
100  //! Get derivative of normalized KL divergence \f$D(\xi)\f$ wrt \f$\xi\f$.
101  double get_Jxi() const;
102 
103  //! Get density in tail.
104  double get_alpha() const;
105 
107 
108  private:
109  double sqrtDxi_, Jxi_, nloga_;
110 };
112 
113 IMPISD_END_NAMESPACE
114 
115 #endif /* IMPISD_PENALIZED_COMPLEXITY_PRIOR_H */
Base class for single-variate distributions that cache sufficient statistics.
void update_sufficient_statistics(Floats Dxis, Floats Jxis)
Update sufficient statistics with values and derivatives.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Base class for probability distributions.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.