kde_model.hpp
Go to the documentation of this file.
1 
12 #ifndef MLPACK_METHODS_KDE_MODEL_HPP
13 #define MLPACK_METHODS_KDE_MODEL_HPP
14 
15 // Include trees.
20 
21 // Include core.
22 #include <mlpack/core.hpp>
23 
24 // Remaining includes.
25 #include "kde.hpp"
26 
27 namespace mlpack {
28 namespace kde {
29 
35 {
36  private:
37  // SFINAE check if Normalizer function is present.
38  HAS_MEM_FUNC(Normalizer, HasNormalizer);
39 
40  public:
42  template<typename KernelType>
43  static void ApplyNormalizer(
44  KernelType& /* kernel */,
45  const size_t /* dimension */,
46  arma::vec& /* estimations */,
47  const typename std::enable_if<
48  !HasNormalizer<KernelType, double(KernelType::*)(size_t)>::value>::
49  type* = 0)
50  { return; }
51 
53  template<typename KernelType>
54  static void ApplyNormalizer(
55  KernelType& kernel,
56  const size_t dimension,
57  arma::vec& estimations,
58  const typename std::enable_if<
59  HasNormalizer<KernelType, double(KernelType::*)(size_t)>::value>::
60  type* = 0)
61  {
62  estimations /= kernel.Normalizer(dimension);
63  }
64 };
65 
72 {
73  public:
77 
80  virtual KDEWrapperBase* Clone() const = 0;
81 
83  virtual ~KDEWrapperBase() { }
84 
86  virtual void Bandwidth(const double bw) = 0;
87 
89  virtual void RelativeError(const double relError) = 0;
90 
92  virtual void AbsoluteError(const double absError) = 0;
93 
95  virtual bool MonteCarlo() const = 0;
97  virtual bool& MonteCarlo() = 0;
98 
100  virtual void MCProb(const double mcProb) = 0;
101 
103  virtual size_t MCInitialSampleSize() const = 0;
105  virtual size_t& MCInitialSampleSize() = 0;
106 
108  virtual void MCEntryCoef(const double entryCoef) = 0;
109 
111  virtual void MCBreakCoef(const double breakCoef) = 0;
112 
114  virtual KDEMode Mode() const = 0;
116  virtual KDEMode& Mode() = 0;
117 
119  virtual void Train(arma::mat&& referenceSet) = 0;
120 
122  virtual void Evaluate(arma::mat&& querySet,
123  arma::vec& estimates) = 0;
124 
126  virtual void Evaluate(arma::vec& estimates) = 0;
127 };
128 
134 template<typename KernelType,
135  template<typename TreeMetricType,
136  typename TreeStatType,
137  typename TreeMatType> class TreeType>
139 {
140  public:
142  KDEWrapper(const double relError,
143  const double absError,
144  const KernelType& kernel) :
145  kde(relError, absError, kernel)
146  {
147  // Nothing left to do.
148  }
149 
152  virtual KDEWrapper* Clone() const { return new KDEWrapper(*this); }
153 
155  virtual ~KDEWrapper() { }
156 
158  virtual void Bandwidth(const double bw) { kde.Kernel() = KernelType(bw); }
159 
161  virtual void RelativeError(const double eps) { kde.RelativeError(eps); }
162 
164  virtual void AbsoluteError(const double eps) { kde.AbsoluteError(eps); }
165 
167  virtual bool MonteCarlo() const { return kde.MonteCarlo(); }
169  virtual bool& MonteCarlo() { return kde.MonteCarlo(); }
170 
172  virtual void MCProb(const double mcProb) { kde.MCProb(mcProb); }
173 
175  virtual size_t MCInitialSampleSize() const
176  {
177  return kde.MCInitialSampleSize();
178  }
180  virtual size_t& MCInitialSampleSize()
181  {
182  return kde.MCInitialSampleSize();
183  }
184 
186  virtual void MCEntryCoef(const double e) { kde.MCEntryCoef(e); }
187 
189  virtual void MCBreakCoef(const double b) { kde.MCBreakCoef(b); }
190 
192  virtual KDEMode Mode() const { return kde.Mode(); }
194  virtual KDEMode& Mode() { return kde.Mode(); }
195 
197  virtual void Train(arma::mat&& referenceSet);
198 
200  virtual void Evaluate(arma::mat&& querySet,
201  arma::vec& estimates);
202 
204  virtual void Evaluate(arma::vec& estimates);
205 
207  template<typename Archive>
208  void serialize(Archive& ar, const uint32_t /* version */)
209  {
210  ar(CEREAL_NVP(kde));
211  }
212 
213  protected:
214  typedef KDE<KernelType,
216  arma::mat,
217  TreeType> KDEType;
218 
220  KDEType kde;
221 };
222 
229 class KDEModel
230 {
231  public:
233  {
238  R_TREE
239  };
240 
242  {
247  TRIANGULAR_KERNEL
248  };
249 
250  private:
252  double bandwidth;
253 
255  double relError;
256 
258  double absError;
259 
261  KernelTypes kernelType;
262 
264  TreeTypes treeType;
265 
267  bool monteCarlo;
268 
271  double mcProb;
272 
274  size_t initialSampleSize;
275 
277  double mcEntryCoef;
278 
280  double mcBreakCoef;
281 
286  KDEWrapperBase* kdeModel;
287 
288  public:
313  KDEModel(const double bandwidth = 1.0,
314  const double relError = KDEDefaultParams::relError,
315  const double absError = KDEDefaultParams::absError,
316  const KernelTypes kernelType = KernelTypes::GAUSSIAN_KERNEL,
317  const TreeTypes treeType = TreeTypes::KD_TREE,
318  const bool monteCarlo = KDEDefaultParams::mode,
319  const double mcProb = KDEDefaultParams::mcProb,
320  const size_t initialSampleSize = KDEDefaultParams::initialSampleSize,
321  const double mcEntryCoef = KDEDefaultParams::mcEntryCoef,
322  const double mcBreakCoef = KDEDefaultParams::mcBreakCoef);
323 
325  KDEModel(const KDEModel& other);
326 
328  KDEModel(KDEModel&& other);
329 
335  KDEModel& operator=(const KDEModel& other);
336 
342  KDEModel& operator=(KDEModel&& other);
343 
345  ~KDEModel();
346 
348  template<typename Archive>
349  void serialize(Archive& ar, const uint32_t version);
350 
352  double Bandwidth() const { return bandwidth; }
353 
355  void Bandwidth(const double newBandwidth);
356 
358  double RelativeError() const { return relError; }
359 
361  void RelativeError(const double newRelError);
362 
364  double AbsoluteError() const { return absError; }
365 
367  void AbsoluteError(const double newAbsError);
368 
370  TreeTypes TreeType() const { return treeType; }
371 
373  TreeTypes& TreeType() { return treeType; }
374 
376  KernelTypes KernelType() const { return kernelType; }
377 
379  KernelTypes& KernelType() { return kernelType; }
380 
382  bool MonteCarlo() const { return monteCarlo; }
383 
385  void MonteCarlo(const bool newMonteCarlo);
386 
388  double MCProbability() const { return mcProb; }
389 
391  void MCProbability(const double newMCProb);
392 
394  size_t MCInitialSampleSize() const { return initialSampleSize; }
395 
397  void MCInitialSampleSize(const size_t newSampleSize);
398 
400  double MCEntryCoefficient() const { return mcEntryCoef; }
401 
403  void MCEntryCoefficient(const double newEntryCoef);
404 
406  double MCBreakCoefficient() const { return mcBreakCoef; }
407 
409  void MCBreakCoefficient(const double newBreakCoef);
410 
412  KDEMode Mode() const { return kdeModel->Mode(); }
413 
415  KDEMode& Mode() { return kdeModel->Mode(); }
416 
420  void InitializeModel();
421 
430  void BuildModel(arma::mat&& referenceSet);
431 
443  void Evaluate(arma::mat&& querySet, arma::vec& estimations);
444 
453  void Evaluate(arma::vec& estimations);
454 
455 
456  private:
458  void CleanMemory();
459 };
460 
461 } // namespace kde
462 } // namespace mlpack
463 
464 #include "kde_model_impl.hpp"
465 
466 #endif
virtual void MCProb(const double mcProb)
Modify the Monte Carlo probability.
Definition: kde_model.hpp:172
double Bandwidth() const
Get the bandwidth of the kernel.
Definition: kde_model.hpp:352
static constexpr double relError
Relative error tolerance.
Definition: kde.hpp:35
virtual void MCEntryCoef(const double e)
Modify the Monte Carlo entry coefficient.
Definition: kde_model.hpp:186
double RelativeError() const
Get the relative error tolerance.
Definition: kde_model.hpp:358
Linear algebra utility functions, generally performed on matrices or vectors.
KDEMode
KDEMode represents the ways in which KDE algorithm can be executed.
Definition: kde.hpp:25
KDEType kde
The instantiated KDE object that we are wrapping.
Definition: kde_model.hpp:220
double MCEntryCoefficient() const
Get Monte Carlo entry coefficient.
Definition: kde_model.hpp:400
static constexpr double mcBreakCoef
Monte Carlo break coefficient.
Definition: kde.hpp:57
virtual KDEWrapper * Clone() const
Create a new KDEWrapper that is the same as this one.
Definition: kde_model.hpp:152
virtual size_t MCInitialSampleSize() const
Get the Monte Carlo sample size.
Definition: kde_model.hpp:175
virtual KDEMode Mode() const =0
Get the search mode.
virtual ~KDEWrapper()
Destruct the KDEWrapper (nothing to do).
Definition: kde_model.hpp:155
void serialize(Archive &ar, const uint32_t)
Serialize the KDE model.
Definition: kde_model.hpp:208
virtual KDEMode Mode() const
Get the search mode.
Definition: kde_model.hpp:192
virtual size_t & MCInitialSampleSize()
Modify the Monte Carlo sample size.
Definition: kde_model.hpp:180
KernelTypes & KernelType()
Modify the kernel type of the model.
Definition: kde_model.hpp:379
TreeTypes TreeType() const
Get the tree type of the model.
Definition: kde_model.hpp:370
virtual void Bandwidth(const double bw)
Modify the bandwidth of the kernel.
Definition: kde_model.hpp:158
static constexpr KDEMode mode
KDE algorithm mode.
Definition: kde.hpp:41
bool MonteCarlo() const
Get whether the model is using Monte Carlo estimations or not.
Definition: kde_model.hpp:382
KDEWrapper is a wrapper class for all KDE types supported by KDEModel.
Definition: kde_model.hpp:138
static constexpr double absError
Absolute error tolerance.
Definition: kde.hpp:38
virtual KDEMode & Mode()
Modify the search mode.
Definition: kde_model.hpp:194
KDEMode & Mode()
Modify the mode of the model.
Definition: kde_model.hpp:415
void CleanMemory()
Delete any unique pointers that are held by the IO object.
The KDE class is a template class for performing Kernel Density Estimations.
Definition: kde.hpp:88
double MCBreakCoefficient() const
Get Monte Carlo break coefficient.
Definition: kde_model.hpp:406
KDEMode Mode() const
Get the mode of the model.
Definition: kde_model.hpp:412
Include all of the base components required to write mlpack methods, and the main mlpack Doxygen docu...
static void ApplyNormalizer(KernelType &kernel, const size_t dimension, arma::vec &estimations, const typename std::enable_if< HasNormalizer< KernelType, double(KernelType::*)(size_t)>::value >::type *=0)
Normalize kernels that have normalizer.
Definition: kde_model.hpp:54
KDEWrapperBase is a base wrapper class for holding all KDE types supported by KDEModel.
Definition: kde_model.hpp:71
static void ApplyNormalizer(KernelType &, const size_t, arma::vec &, const typename std::enable_if< !HasNormalizer< KernelType, double(KernelType::*)(size_t)>::value >::type *=0)
Normalization not needed.
Definition: kde_model.hpp:43
virtual bool MonteCarlo() const
Get whether Monte Carlo search is being used.
Definition: kde_model.hpp:167
The KDEModel provides an abstraction for the KDE class, abstracting away the KernelType and TreeType ...
Definition: kde_model.hpp:229
double AbsoluteError() const
Get the absolute error tolerance.
Definition: kde_model.hpp:364
static constexpr size_t initialSampleSize
Initial sample size for Monte Carlo estimations.
Definition: kde.hpp:51
KDE< KernelType, metric::EuclideanDistance, arma::mat, TreeType > KDEType
Definition: kde_model.hpp:217
static constexpr double mcEntryCoef
Monte Carlo entry coefficient.
Definition: kde.hpp:54
TreeTypes & TreeType()
Modify the tree type of the model.
Definition: kde_model.hpp:373
virtual void AbsoluteError(const double eps)
Modify the absolute error tolerance.
Definition: kde_model.hpp:164
static constexpr double mcProb
Probability of a Monte Carlo estimation to be bounded by the relative error tolerance.
Definition: kde.hpp:48
virtual ~KDEWrapperBase()
Destruct the KDEWrapperBase (nothing to do).
Definition: kde_model.hpp:83
KDEWrapperBase()
Create the KDEWrapperBase object.
Definition: kde_model.hpp:76
KernelNormalizer holds a set of methods to normalize estimations applying in each case the appropiate...
Definition: kde_model.hpp:34
LMetric< 2, true > EuclideanDistance
The Euclidean (L2) distance.
Definition: lmetric.hpp:112
KernelTypes KernelType() const
Get the kernel type of the model.
Definition: kde_model.hpp:376
KDEWrapper(const double relError, const double absError, const KernelType &kernel)
Create the KDEWrapper object, initializing the internally-held KDE object.
Definition: kde_model.hpp:142
virtual bool & MonteCarlo()
Modify whether Monte Carlo search is being used.
Definition: kde_model.hpp:169
double MCProbability() const
Get Monte Carlo probability of error being bounded by relative error.
Definition: kde_model.hpp:388
virtual void RelativeError(const double eps)
Modify the relative error tolerance.
Definition: kde_model.hpp:161
size_t MCInitialSampleSize() const
Get the initial sample size for Monte Carlo estimations.
Definition: kde_model.hpp:394
virtual void MCBreakCoef(const double b)
Modify the Monte Carlo break coefficient.
Definition: kde_model.hpp:189