lsst.meas.modelfit  15.0-3-g150fc43+8
Mixture.h
Go to the documentation of this file.
1 // -*- lsst-c++ -*-
2 /*
3  * LSST Data Management System
4  * Copyright 2008-2013 LSST Corporation.
5  *
6  * This product includes software developed by the
7  * LSST Project (http://www.lsst.org/).
8  *
9  * This program is free software: you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation, either version 3 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the LSST License Statement and
20  * the GNU General Public License along with this program. If not,
21  * see <http://www.lsstcorp.org/LegalNotices/>.
22  */
23 
24 #ifndef LSST_MEAS_MODELFIT_Mixture_h_INCLUDED
25 #define LSST_MEAS_MODELFIT_Mixture_h_INCLUDED
26 
27 #include <limits>
28 
29 #include "Eigen/Cholesky"
30 #include "Eigen/StdVector"
31 
32 #include "ndarray.h"
33 
34 #include "lsst/base.h"
35 #include "lsst/afw/math/Random.h"
38 #include "lsst/afw/table/io/python.h" // for declarePersistableFacade
39 
40 
41 namespace lsst { namespace meas { namespace modelfit {
42 
47 public:
48 
50  int getDimension() const { return _mu.size(); }
51 
54 
56  Vector getMu() const { return _mu; }
58  void setMu(Vector const & mu) { _mu = mu; }
60 
62 
70  Matrix getSigma() const { return _sigmaLLT.reconstructedMatrix(); }
71  void setSigma(Matrix const & sigma);
73 
75  MixtureComponent project(int dim) const;
76 
78  MixtureComponent project(int dim1, int dim2) const;
79 
81  explicit MixtureComponent(int dim);
82 
84  MixtureComponent(Scalar weight_, Vector const & mu, Matrix const & sigma);
85 
87 
88  friend std::ostream & operator<<(std::ostream & os, MixtureComponent const & self) {
89  self._stream(os);
90  return os;
91  }
92 
93 private:
94 
95  friend class Mixture;
96 
97  void _stream(std::ostream & os, int offset=0) const;
98 
99  Scalar _sqrtDet;
100  Vector _mu;
101  Eigen::LLT<Matrix> _sigmaLLT;
102 };
103 
111 public:
112 
113  int getDimension() const { return _dim; }
114 
115  virtual void restrictMu(Vector & mu) const {}
116 
117  virtual void restrictSigma(Matrix & sigma) const {}
118 
120 
121  explicit MixtureUpdateRestriction(int dim) : _dim(dim) {}
122 
123 private:
124  int _dim;
125 };
126 
128 public:
129 
133  typedef ComponentList::iterator iterator;
134  typedef ComponentList::const_iterator const_iterator;
135 
137 
145  iterator begin() { return _components.begin(); }
146  iterator end() { return _components.end(); }
147 
148  const_iterator begin() const { return _components.begin(); }
149  const_iterator end() const { return _components.end(); }
150 
151  Component & operator[](std::size_t i) { return _components[i]; }
152  Component const & operator[](std::size_t i) const { return _components[i]; }
154 
156  std::size_t size() const { return _components.size(); }
157 
159  virtual int getComponentCount() const { return size(); }
160 
162  PTR(Mixture) project(int dim) const;
163 
165  PTR(Mixture) project(int dim1, int dim2) const;
166 
168  int getDimension() const { return _dim; }
169 
171  void normalize();
172 
174  void shift(int dim, Scalar offset);
175 
183  std::size_t clip(Scalar threshold=0.0);
184 
186  Scalar getDegreesOfFreedom() const { return _df; }
187 
189  void setDegreesOfFreedom(Scalar df=std::numeric_limits<Scalar>::infinity());
190 
196  template <typename Derived>
197  Scalar evaluate(Component const & component, Eigen::MatrixBase<Derived> const & x) const {
198  Scalar z = _computeZ(component, x);
199  return component.weight * _evaluate(z) / component._sqrtDet;
200  }
201 
207  template <typename Derived>
208  Scalar evaluate(Eigen::MatrixBase<Derived> const & x) const {
209  Scalar p = 0.0;
210  for (const_iterator i = begin(); i != end(); ++i) {
211  p += evaluate(*i, x);
212  }
213  return p;
214  }
215 
222  void evaluate(
223  ndarray::Array<Scalar const,2,1> const & x,
224  ndarray::Array<Scalar,1,0> const & p
225  ) const;
226 
233  void evaluateComponents(
234  ndarray::Array<Scalar const,2,1> const & x,
235  ndarray::Array<Scalar,2,1> const & p
236  ) const;
237 
245  void evaluateDerivatives(
246  ndarray::Array<Scalar const,1,1> const & x,
247  ndarray::Array<Scalar,1,1> const & gradient,
248  ndarray::Array<Scalar,2,1> const & hessian
249  ) const;
250 
257  void draw(afw::math::Random & rng, ndarray::Array<Scalar,2,1> const & x) const;
258 
281  void updateEM(
282  ndarray::Array<Scalar const,2,1> const & x,
283  ndarray::Array<Scalar const,1,0> const & w,
284  Scalar tau1=0.0, Scalar tau2=0.5
285  );
286 
297  void updateEM(
298  ndarray::Array<Scalar const,2,1> const & x,
299  ndarray::Array<Scalar const,1,0> const & w,
300  UpdateRestriction const & restriction,
301  Scalar tau1=0.0, Scalar tau2=0.5
302  );
303 
313  void updateEM(
314  ndarray::Array<Scalar const,2,1> const & x,
315  UpdateRestriction const & restriction,
316  Scalar tau1=0.0, Scalar tau2=0.5
317  );
318 
320  virtual PTR(Mixture) clone() const;
321 
332  explicit Mixture(int dim, ComponentList & components, Scalar df=std::numeric_limits<Scalar>::infinity());
333 
334  friend std::ostream & operator<<(std::ostream & os, Mixture const & self) {
335  self._stream(os);
336  return os;
337  }
338 
339  virtual bool isPersistable() const { return true; }
340 
341 protected:
342 
343  virtual std::string getPythonModule() const { return "lsst.meas.modelfit"; }
344 
345  virtual std::string getPersistenceName() const;
346 
347  virtual void write(OutputArchiveHandle & handle) const;
348 
349 private:
350 
351  template <typename Derived>
352  Scalar _computeZ(Component const & component, Eigen::MatrixBase<Derived> const & x) const {
353  _workspace = x - component._mu;
354  component._sigmaLLT.matrixL().solveInPlace(_workspace);
355  return _workspace.squaredNorm();
356  }
357 
358  // Helper function used in updateEM
359  void updateDampedSigma(int k, Matrix const & sigma, double tau1, double tau2);
360 
361  Scalar _evaluate(Scalar z) const;
362 
363  void _stream(std::ostream & os) const;
364 
365  bool _isGaussian;
366  int _dim;
367  Scalar _df;
368  Scalar _norm;
369  mutable Vector _workspace;
370  ComponentList _components;
371 };
372 
373 }}} // namespace lsst::meas::modelfit
374 
375 #endif // !LSST_MEAS_MODELFIT_Mixture_h_INCLUDED
table::Key< table::Array< int > > components
Component const & operator[](std::size_t i) const
Iterator and indexed access to components.
Definition: Mixture.h:152
Scalar getDegreesOfFreedom() const
Get the number of degrees of freedom in the component Student&#39;s T distributions (inf=Gaussian) ...
Definition: Mixture.h:186
Component & operator[](std::size_t i)
Iterator and indexed access to components.
Definition: Mixture.h:151
std::vector< Component > ComponentList
Definition: Mixture.h:132
ComponentList::iterator iterator
Definition: Mixture.h:133
MixtureComponent(int dim)
Default-construct a mixture component with weight=1, mu=0, sigma=identity.
MixtureUpdateRestriction UpdateRestriction
Definition: Mixture.h:131
MixtureComponent Component
Definition: Mixture.h:130
std::size_t size() const
Return the number of components.
Definition: Mixture.h:156
double Scalar
Typedefs to be used for probability and parameter values.
Definition: common.h:44
#define PTR(...)
MixtureComponent & operator=(MixtureComponent const &other)
ItemVariant const * other
double z
int getDimension() const
Return the number of dimensions.
Definition: Mixture.h:50
virtual bool isPersistable() const
Definition: Mixture.h:339
Vector getMu() const
Get/set the location parameter (mean/median/mode) of this component.
Definition: Mixture.h:57
afw::table::Key< double > sigma
STL class.
A weighted Student&#39;s T or Gaussian distribution used as a component in a Mixture. ...
Definition: Mixture.h:46
Helper class used to define restrictions to the form of the component parameters in Mixture::updateEM...
Definition: Mixture.h:110
Scalar evaluate(Component const &component, Eigen::MatrixBase< Derived > const &x) const
Evaluate the probability density at the given point for the given component distribution.
Definition: Mixture.h:197
Scalar evaluate(Eigen::MatrixBase< Derived > const &x) const
Evaluate the mixture distribution probability density function (PDF) at the given points...
Definition: Mixture.h:208
double w
int end
Eigen::Matrix< Scalar, Eigen::Dynamic, Eigen::Dynamic > Matrix
Typedefs to be used for probability and parameter values.
Definition: common.h:45
int getDimension() const
Return the number of dimensions.
Definition: Mixture.h:168
Eigen::Matrix< Scalar, Eigen::Dynamic, 1 > Vector
Typedefs to be used for probability and parameter values.
Definition: common.h:46
MixtureComponent project(int dim) const
Project the distribution onto the given dimension (marginalize over all others)
const_iterator begin() const
Iterator and indexed access to components.
Definition: Mixture.h:148
virtual int getComponentCount() const
Return the number of components.
Definition: Mixture.h:159
double x
ComponentList::const_iterator const_iterator
Definition: Mixture.h:134
Scalar weight
Weight of this distribution in the mixture.
Definition: Mixture.h:53
friend std::ostream & operator<<(std::ostream &os, Mixture const &self)
Definition: Mixture.h:334
virtual void restrictSigma(Matrix &sigma) const
Definition: Mixture.h:117
virtual std::string getPythonModule() const
Definition: Mixture.h:343
void setSigma(Matrix const &sigma)
Get/set the shape/size parameter.
const_iterator end() const
Iterator and indexed access to components.
Definition: Mixture.h:149
iterator end()
Iterator and indexed access to components.
Definition: Mixture.h:146
std::ostream * os
Matrix getSigma() const
Get/set the shape/size parameter.
Definition: Mixture.h:70
STL class.
clone
iterator begin()
Iterator and indexed access to components.
Definition: Mixture.h:145
friend std::ostream & operator<<(std::ostream &os, MixtureComponent const &self)
Definition: Mixture.h:88
virtual void restrictMu(Vector &mu) const
Definition: Mixture.h:115
void setMu(Vector const &mu)
Get/set the location parameter (mean/median/mode) of this component.
Definition: Mixture.h:58