mlpack: a scalable c++ machine learning library
mlpack  2.0.2
gaussian_distribution.hpp
Go to the documentation of this file.
1 
15 #ifndef mlpack_CORE_DISTRIBUTIONS_GAUSSIAN_DISTRIBUTION_HPP
16 #define mlpack_CORE_DISTRIBUTIONS_GAUSSIAN_DISTRIBUTION_HPP
17 
18 #include <mlpack/core.hpp>
19 
20 namespace mlpack {
21 namespace distribution {
22 
27 {
28  private:
30  arma::vec mean;
32  arma::mat covariance;
34  arma::mat covLower;
36  arma::mat invCov;
38  double logDetCov;
39 
41  static const constexpr double log2pi = 1.83787706640934533908193770912475883;
42 
43  public:
47  GaussianDistribution() { /* nothing to do */ }
48 
53  GaussianDistribution(const size_t dimension) :
54  mean(arma::zeros<arma::vec>(dimension)),
55  covariance(arma::eye<arma::mat>(dimension, dimension)),
56  covLower(arma::eye<arma::mat>(dimension, dimension)),
57  invCov(arma::eye<arma::mat>(dimension, dimension)),
58  logDetCov(0)
59  { /* Nothing to do. */ }
60 
66  GaussianDistribution(const arma::vec& mean, const arma::mat& covariance);
67 
68  // TODO(stephentu): do we want a (arma::vec&&, arma::mat&&) ctor?
69 
71  size_t Dimensionality() const { return mean.n_elem; }
72 
76  double Probability(const arma::vec& observation) const
77  {
78  return exp(LogProbability(observation));
79  }
80 
84  double LogProbability(const arma::vec& observation) const;
85 
93  void Probability(const arma::mat& x, arma::vec& probabilities) const
94  {
95  arma::vec logProbabilities;
96  LogProbability(x, logProbabilities);
97  probabilities = arma::exp(logProbabilities);
98  }
99 
100  void LogProbability(const arma::mat& x, arma::vec& logProbabilities) const;
101 
108  arma::vec Random() const;
109 
115  void Train(const arma::mat& observations);
116 
122  void Train(const arma::mat& observations,
123  const arma::vec& probabilities);
124 
128  const arma::vec& Mean() const { return mean; }
129 
133  arma::vec& Mean() { return mean; }
134 
138  const arma::mat& Covariance() const { return covariance; }
139 
143  void Covariance(const arma::mat& covariance);
144 
145  void Covariance(arma::mat&& covariance);
146 
150  template<typename Archive>
151  void Serialize(Archive& ar, const unsigned int /* version */)
152  {
153  using data::CreateNVP;
154 
155  // We just need to serialize each of the members.
156  ar & CreateNVP(mean, "mean");
157  ar & CreateNVP(covariance, "covariance");
158  ar & CreateNVP(covLower, "covLower");
159  ar & CreateNVP(invCov, "invCov");
160  ar & CreateNVP(logDetCov, "logDetCov");
161  }
162 
163  private:
169  void FactorCovariance();
170 };
171 
179 inline void GaussianDistribution::LogProbability(const arma::mat& x,
180  arma::vec& logProbabilities) const
181 {
182  // Column i of 'diffs' is the difference between x.col(i) and the mean.
183  arma::mat diffs = x - (mean * arma::ones<arma::rowvec>(x.n_cols));
184 
185  // Now, we only want to calculate the diagonal elements of (diffs' * cov^-1 *
186  // diffs). We just don't need any of the other elements. We can calculate
187  // the right hand part of the equation (instead of the left side) so that
188  // later we are referencing columns, not rows -- that is faster.
189  const arma::mat rhs = -0.5 * invCov * diffs;
190  arma::vec logExponents(diffs.n_cols); // We will now fill this.
191  for (size_t i = 0; i < diffs.n_cols; i++)
192  logExponents(i) = accu(diffs.unsafe_col(i) % rhs.unsafe_col(i));
193 
194  const size_t k = x.n_rows;
195 
196  logProbabilities = -0.5 * k * log2pi - 0.5 * logDetCov + logExponents;
197 }
198 
199 
200 } // namespace distribution
201 } // namespace mlpack
202 
203 #endif
A single multivariate Gaussian distribution.
arma::vec mean
Mean of the distribution.
Linear algebra utility functions, generally performed on matrices or vectors.
FirstShim< T > CreateNVP(T &t, const std::string &name, typename boost::enable_if< HasSerialize< T >>::type *=0)
Call this function to produce a name-value pair; this is similar to BOOST_SERIALIZATION_NVP(), but should be used for types that have a Serialize() function (or contain a type that has a Serialize() function) instead of a serialize() function.
void Probability(const arma::mat &x, arma::vec &probabilities) const
Calculates the multivariate Gaussian probability density function for each data point (column) in the...
arma::vec Random() const
Return a randomly generated observation according to the probability distribution defined by this obj...
void Train(const arma::mat &observations)
Estimate the Gaussian distribution directly from the given observations.
static const constexpr double log2pi
log(2pi)
void FactorCovariance()
This factors the covariance using arma::chol().
arma::mat covariance
Positive definite covariance of the distribution.
double LogProbability(const arma::vec &observation) const
Return the log probability of the given observation.
void Serialize(Archive &ar, const unsigned int)
Serialize the distribution.
arma::mat covLower
Lower triangular factor of cov (e.g. cov = LL^T).
double Probability(const arma::vec &observation) const
Return the probability of the given observation.
Include all of the base components required to write mlpack methods, and the main mlpack Doxygen docu...
GaussianDistribution(const size_t dimension)
Create a Gaussian distribution with zero mean and identity covariance with the given dimensionality...
arma::mat invCov
Cached inverse of covariance.
GaussianDistribution()
Default constructor, which creates a Gaussian with zero dimension.
size_t Dimensionality() const
Return the dimensionality of this distribution.
arma::vec & Mean()
Return a modifiable copy of the mean.
const arma::vec & Mean() const
Return the mean.
const arma::mat & Covariance() const
Return the covariance matrix.