IMP logo
IMP Reference Guide  2.20.2
The Integrative Modeling Platform
FStudentT.h
Go to the documentation of this file.
1 /**
2  * \file IMP/isd/FStudentT.h
3  * \brief Joint Student's t-distribution of Function
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPISD_F_STUDENT_T_H
9 #define IMPISD_F_STUDENT_T_H
10 
11 #include <IMP/isd/isd_config.h>
12 #include <IMP/isd/distribution.h>
13 
14 IMPISD_BEGIN_NAMESPACE
15 
16 //! Joint Student's t-distribution of Function.
17 /** If a vector of values \f$F(X)\f$ is jointly distributed according to the t
18  distribution with shared center \f$F(M)\f$, scale \f$\sigma\f$, and degrees
19  of freedom \f$\nu\f$, then the vector \f$X\f$ is distributed according to
20  the F-t distribution, where \f$F\f$ is a one-to-one (strictly monotonic)
21  function.
22 
23  For a vector \f$X=\{x_1,...,x_N\}\f$ containing \f$N\f$ observations, the
24  joint F-t density is given by
25  \f[
26  p(X \mid M, \sigma, \nu) = \frac{
27  \Gamma[(N + \nu) / 2]}{\Gamma[\nu / 2]}
28  (\pi \nu)^{-N / 2} \sigma^{-N} J(X)
29  \left[1 + \frac{t(X, M, \sigma)^2}{\nu} \right]^{-(N + \nu)/2},
30  \f]
31 
32  where
33  \f[
34  J(X) = \left| \prod_{i=1}^N F'(x_i) \right|,
35  \f]
36  is a normalization factor according to the change of variables technique.
37 
38  \f[
39  t(X, M, \sigma)^2 = \frac{S_2(X) - 2 F(M) S_1(X) + N F(M)^2}{\sigma^2},
40  \f]
41 
42  and the minimally sufficient statistics are
43  \f{align*}{
44  S_1(X) &= \sum_{i=1}^N F(x_i) \
45  S_2(X) &= \sum_{i=1}^N F(x_i)^2.
46  \f}
47 
48  The degrees of freedom \f$\nu\f$ controls the heaviness of the tails. When
49  \f$\nu = 1\f$, the F-t distribution becomes the F-Cauchy distribution. For
50  very large \f$\nu\f$, the F-t distribution approaches the F-Normal
51  distribution. Set \f$J(X)\f$ values to 1 for the joint t distribution.
52 
53  \note The joint t distribution is derived by marginalizing a joint normal
54  distribution with the scaled inverse chi-square distribution as a
55  prior on the variance. The same distribution is not produced by
56  multiplying t distributions.
57  For more details, see Gelmen et al. Bayesian Data Analaysis. 3rd edition.
58 
59  \see FNormal
60  */
61 class IMPISDEXPORT FStudentT : public OneDimensionalSufficientDistribution {
62  protected:
63  virtual void do_update_sufficient_statistics(Floats FXs) override;
64  virtual void do_update_sufficient_statistics(Floats FXs, Floats JXs);
65  virtual Floats do_get_sufficient_statistics() const override;
66  virtual double do_evaluate() const override;
67 
68  public:
69  //! Create from observations vectors.
70  /** \param [in] FXs Vector of N \f$F(x)\f$ observations drawn
71  independently from the same F-t distribution.
72  \param [in] JXs Vector of N derivatives of \f$F(x)\f$ with respect to
73  \f$X\f$ vector.
74  \param [in] FM Center of F-Student t with respect to \f$F(x)\f$.
75  \param [in] sigma Scale of F-Student t with respect to \f$F(x)\f$.
76  \param [in] nu Degrees of freedom of Student t distribution.
77  \param [in] name Name.
78  */
79  FStudentT(Floats FXs, Floats JXs, double FM, double sigma, double nu,
80  std::string name = "FStudentT %1%");
81 
82  //! Create from sufficient statistics.
83  /** \param [in] sumFX Sum of observations of \f$F(x)\f$.
84  \param [in] sumFX2 Sum of observations of \f$F(x)^2\f$.
85  \param [in] N Number of observations.
86  \param [in] LogJX Log of \f$J(X)\f$.
87  \param [in] FM Center of F-t with respect to \f$F(x)\f$.
88  \param [in] sigma Scale of F-t with respect to \f$F(x)\f$.
89  \param [in] nu Degrees of freedom of Student t distribution.
90  \param [in] name Name.
91  */
92  FStudentT(double sumFX, double sumFX2, unsigned N, double LogJX,
93  double FM, double sigma, double nu,
94  std::string name = "FStudentT %1%");
95 
96  //! Update sufficient statistics with values and derivatives.
98  do_update_sufficient_statistics(FXs, JXs);
99  }
100 
101  //! Evaluate derivative of negative log-density wrt single \f$F(x_i)\f$.
102  /** \f$F(x_i)\f$ represents an element of \f$F(X)\f$. Since only the
103  sufficient statistics are stored, this value must be provided.
104  */
105  virtual double evaluate_derivative_Fx(double Fx) const;
106 
107  //! Evaluate derivative of negative log-density wrt elements of \f$F(X)\f$.
108  /** This is equivalent to though faster than running
109  evaluate_derivative_Fx() on every element of \f$F(X)\f$.
110  */
111  Floats evaluate_derivative_FX(const Floats FXs) const;
112 
113  //! Evaluate derivative of negative log-density wrt \f$\log J(X)\f$.
114  virtual double evaluate_derivative_LogJX() const;
115 
116  //! Evaluate derivative of negative log-density wrt \f$F(M)\f$.
117  virtual double evaluate_derivative_FM() const;
118 
119  //! Evaluate derivative of negative log-density wrt \f$\sigma\f$.
120  virtual double evaluate_derivative_sigma() const;
121 
122  //! Evaluate derivative of negative log-density wrt \f$\nu\f$.
123  virtual double evaluate_derivative_nu() const;
124 
125  //! Update cached intermediate values.
126  /** This method is automatically called during evaluation. If evaluating
127  derivatives after modifying parameters but before evaluation, this
128  method must be manually called.
129  */
130  void update_cached_values() const;
131 
132  void set_sumFX(double v) { sumFX_ = v; }
133  void set_sumFX2(double v) { sumFX2_ = v; }
134  void set_N(unsigned v) { N_ = v; }
135  void set_LogJX(double v) { LogJX_ = v; }
136  void set_FM(double v) { FM_ = v; }
137  void set_sigma(double v) { sigma_ = v; }
138  void set_nu(double v) { nu_ = v; }
139 
140  //! Get sufficient statistic for passed \f$J(X)\f$ values.
141  double get_sumFX() { return sumFX_; }
142  double get_sumFX2() { return sumFX2_; }
143  unsigned get_N() { return N_; }
144  double get_LogJX() { return LogJX_; }
145  double get_FM() { return FM_; }
146  double get_sigma() { return sigma_; }
147  double get_nu() { return nu_; }
148 
150 
151  private:
152  double sumFX_, sumFX2_, LogJX_, FM_, sigma_, nu_;
153  unsigned N_;
154  mutable double t2_; // square of t-statistic
155 };
157 
158 IMPISD_END_NAMESPACE
159 
160 #endif /* IMPISD_F_STUDENT_T_H */
Base class for single-variate distributions that cache sufficient statistics.
Joint Student's t-distribution of Function.
Definition: FStudentT.h:61
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
void update_sufficient_statistics(Floats FXs, Floats JXs)
Update sufficient statistics with values and derivatives.
Definition: FStudentT.h:97
double get_sumFX()
Get sufficient statistic for passed values.
Definition: FStudentT.h:141
Base class for probability distributions.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44