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 <boost/variant.hpp>
26 #include "kde.hpp"
27 
28 namespace mlpack {
29 namespace kde {
30 
32 template<typename KernelType,
33  template<typename TreeMetricType,
34  typename TreeStatType,
35  typename TreeMatType> class TreeType>
36 using KDEType = KDE<KernelType,
38  arma::mat,
39  TreeType,
41  kde::KDEStat,
42  arma::mat>::template DualTreeTraverser,
44  kde::KDEStat,
45  arma::mat>::template SingleTreeTraverser>;
46 
52 {
53  private:
54  // SFINAE check if Normalizer function is present.
55  HAS_MEM_FUNC(Normalizer, HasNormalizer);
56 
57  public:
59  template<typename KernelType>
60  static void ApplyNormalizer(
61  KernelType& /* kernel */,
62  const size_t /* dimension */,
63  arma::vec& /* estimations */,
64  const typename std::enable_if<
65  !HasNormalizer<KernelType, double(KernelType::*)(size_t)>::value>::
66  type* = 0)
67  { return; }
68 
70  template<typename KernelType>
71  static void ApplyNormalizer(
72  KernelType& kernel,
73  const size_t dimension,
74  arma::vec& estimations,
75  const typename std::enable_if<
76  HasNormalizer<KernelType, double(KernelType::*)(size_t)>::value>::
77  type* = 0)
78  {
79  estimations /= kernel.Normalizer(dimension);
80  }
81 };
82 
87 class DualMonoKDE : public boost::static_visitor<void>
88 {
89  private:
91  arma::vec& estimations;
92 
93  public:
95  template<typename KernelType,
96  template<typename TreeMetricType,
97  typename TreeStatType,
98  typename TreeMatType> class TreeType>
100 
102  template<typename KernelType,
103  template<typename TreeMetricType,
104  typename TreeStatType,
105  typename TreeMatType> class TreeType>
106  void operator()(KDETypeT<KernelType, TreeType>* kde) const;
107 
108  // TODO Implement specific cases where a leaf size can be selected.
109 
111  DualMonoKDE(arma::vec& estimations);
112 };
113 
118 class DualBiKDE : public boost::static_visitor<void>
119 {
120  private:
122  const size_t dimension;
123 
125  const arma::mat& querySet;
126 
128  arma::vec& estimations;
129 
130  public:
132  template<typename KernelType,
133  template<typename TreeMetricType,
134  typename TreeStatType,
135  typename TreeMatType> class TreeType>
137 
139  template<typename KernelType,
140  template<typename TreeMetricType,
141  typename TreeStatType,
142  typename TreeMatType> class TreeType>
143  void operator()(KDETypeT<KernelType, TreeType>* kde) const;
144 
145  // TODO Implement specific cases where a leaf size can be selected.
146 
148  DualBiKDE(arma::mat&& querySet, arma::vec& estimations);
149 };
150 
154 class TrainVisitor : public boost::static_visitor<void>
155 {
156  private:
158  arma::mat&& referenceSet;
159 
160  public:
162  template<typename KernelType,
163  template<typename TreeMetricType,
164  typename TreeStatType,
165  typename TreeMatType> class TreeType>
166  void operator()(KDEType<KernelType, TreeType>* kde) const;
167 
168  // TODO Implement specific cases where a leaf size can be selected.
169 
171  TrainVisitor(arma::mat&& referenceSet);
172 };
173 
177 class BandwidthVisitor : public boost::static_visitor<void>
178 {
179  private:
181  const double bandwidth;
182 
183  public:
185  template<typename KernelType,
186  template<typename TreeMetricType,
187  typename TreeStatType,
188  typename TreeMatType> class TreeType>
189  void operator()(KDEType<KernelType, TreeType>* kde) const;
190 
192  BandwidthVisitor(const double bandwidth);
193 };
194 
198 class RelErrorVisitor : public boost::static_visitor<void>
199 {
200  private:
202  const double relError;
203 
204  public:
206  template<typename KernelType,
207  template<typename TreeMetricType,
208  typename TreeStatType,
209  typename TreeMatType> class TreeType>
210  void operator()(KDEType<KernelType, TreeType>* kde) const;
211 
213  RelErrorVisitor(const double relError);
214 };
215 
219 class AbsErrorVisitor : public boost::static_visitor<void>
220 {
221  private:
223  const double absError;
224 
225  public:
227  template<typename KernelType,
228  template<typename TreeMetricType,
229  typename TreeStatType,
230  typename TreeMatType> class TreeType>
231  void operator()(KDEType<KernelType, TreeType>* kde) const;
232 
234  AbsErrorVisitor(const double absError);
235 };
236 
240 class MonteCarloVisitor : public boost::static_visitor<void>
241 {
242  private:
244  const bool monteCarlo;
245 
246  public:
248  template<typename KernelType,
249  template<typename TreeMetricType,
250  typename TreeStatType,
251  typename TreeMatType> class TreeType>
252  void operator()(KDEType<KernelType, TreeType>* kde) const;
253 
255  MonteCarloVisitor(const bool monteCarlo);
256 };
257 
261 class MCProbabilityVisitor : public boost::static_visitor<void>
262 {
263  private:
265  const double probability;
266 
267  public:
269  template<typename KernelType,
270  template<typename TreeMetricType,
271  typename TreeStatType,
272  typename TreeMatType> class TreeType>
273  void operator()(KDEType<KernelType, TreeType>* kde) const;
274 
276  MCProbabilityVisitor(const double probability);
277 };
278 
283 class MCSampleSizeVisitor : public boost::static_visitor<void>
284 {
285  private:
287  const size_t sampleSize;
288 
289  public:
291  template<typename KernelType,
292  template<typename TreeMetricType,
293  typename TreeStatType,
294  typename TreeMatType> class TreeType>
295  void operator()(KDEType<KernelType, TreeType>* kde) const;
296 
298  MCSampleSizeVisitor(const size_t sampleSize);
299 };
300 
304 class MCEntryCoefVisitor : public boost::static_visitor<void>
305 {
306  private:
308  const double entryCoef;
309 
310  public:
312  template<typename KernelType,
313  template<typename TreeMetricType,
314  typename TreeStatType,
315  typename TreeMatType> class TreeType>
316  void operator()(KDEType<KernelType, TreeType>* kde) const;
317 
319  MCEntryCoefVisitor(const double entryCoef);
320 };
321 
325 class MCBreakCoefVisitor : public boost::static_visitor<void>
326 {
327  private:
329  const double breakCoef;
330 
331  public:
333  template<typename KernelType,
334  template<typename TreeMetricType,
335  typename TreeStatType,
336  typename TreeMatType> class TreeType>
337  void operator()(KDEType<KernelType, TreeType>* kde) const;
338 
340  MCBreakCoefVisitor(const double breakCoef);
341 };
342 
346 class ModeVisitor : public boost::static_visitor<KDEMode&>
347 {
348  public:
350  template<typename KDEType>
351  KDEMode& operator()(KDEType* kde) const;
352 };
353 
354 class DeleteVisitor : public boost::static_visitor<void>
355 {
356  public:
358  template<typename KDEType>
359  void operator()(KDEType* kde) const;
360 };
361 
362 class KDEModel
363 {
364  public:
366  {
371  R_TREE
372  };
373 
375  {
380  TRIANGULAR_KERNEL
381  };
382 
383  private:
385  double bandwidth;
386 
388  double relError;
389 
391  double absError;
392 
394  KernelTypes kernelType;
395 
397  TreeTypes treeType;
398 
400  bool monteCarlo;
401 
404  double mcProb;
405 
407  size_t initialSampleSize;
408 
410  double mcEntryCoef;
411 
413  double mcBreakCoef;
414 
419  boost::variant<KDEType<kernel::GaussianKernel, tree::KDTree>*,
444 
445  public:
470  KDEModel(const double bandwidth = 1.0,
471  const double relError = KDEDefaultParams::relError,
472  const double absError = KDEDefaultParams::absError,
473  const KernelTypes kernelType = KernelTypes::GAUSSIAN_KERNEL,
474  const TreeTypes treeType = TreeTypes::KD_TREE,
475  const bool monteCarlo = KDEDefaultParams::mode,
476  const double mcProb = KDEDefaultParams::mcProb,
477  const size_t initialSampleSize = KDEDefaultParams::initialSampleSize,
478  const double mcEntryCoef = KDEDefaultParams::mcEntryCoef,
479  const double mcBreakCoef = KDEDefaultParams::mcBreakCoef);
480 
482  KDEModel(const KDEModel& other);
483 
485  KDEModel(KDEModel&& other);
486 
494  KDEModel& operator=(KDEModel other);
495 
497  ~KDEModel();
498 
500  template<typename Archive>
501  void serialize(Archive& ar, const unsigned int version);
502 
504  double Bandwidth() const { return bandwidth; }
505 
507  void Bandwidth(const double newBandwidth);
508 
510  double RelativeError() const { return relError; }
511 
513  void RelativeError(const double newRelError);
514 
516  double AbsoluteError() const { return absError; }
517 
519  void AbsoluteError(const double newAbsError);
520 
522  TreeTypes TreeType() const { return treeType; }
523 
525  TreeTypes& TreeType() { return treeType; }
526 
528  KernelTypes KernelType() const { return kernelType; }
529 
531  KernelTypes& KernelType() { return kernelType; }
532 
534  bool MonteCarlo() const { return monteCarlo; }
535 
537  void MonteCarlo(const bool newMonteCarlo);
538 
540  double MCProbability() const { return mcProb; }
541 
543  void MCProbability(const double newMCProb);
544 
546  size_t MCInitialSampleSize() const { return initialSampleSize; }
547 
549  void MCInitialSampleSize(const size_t newSampleSize);
550 
552  double MCEntryCoefficient() const { return mcEntryCoef; }
553 
555  void MCEntryCoefficient(const double newEntryCoef);
556 
558  double MCBreakCoefficient() const { return mcBreakCoef; }
559 
561  void MCBreakCoefficient(const double newBreakCoef);
562 
564  KDEMode Mode() const;
565 
567  KDEMode& Mode();
568 
577  void BuildModel(arma::mat&& referenceSet);
578 
590  void Evaluate(arma::mat&& querySet, arma::vec& estimations);
591 
600  void Evaluate(arma::vec& estimations);
601 
602 
603  private:
605  void CleanMemory();
606 };
607 
608 } // namespace kde
609 } // namespace mlpack
610 
613 
614 #include "kde_model_impl.hpp"
615 
616 #endif
KDE< KernelType, metric::EuclideanDistance, arma::mat, TreeType, TreeType< metric::EuclideanDistance, kde::KDEStat, arma::mat >::template DualTreeTraverser, TreeType< metric::EuclideanDistance, kde::KDEStat, arma::mat >::template SingleTreeTraverser > KDEType
Alias template.
Definition: kde_model.hpp:45
double Bandwidth() const
Get the bandwidth of the kernel.
Definition: kde_model.hpp:504
static constexpr double relError
Relative error tolerance.
Definition: kde.hpp:35
BOOST_TEMPLATE_CLASS_VERSION(template<>, mlpack::kde::KDEModel, 1)
Set the serialization version of the KDEModel class.
double RelativeError() const
Get the relative error tolerance.
Definition: kde_model.hpp:510
AbsErrorVisitor modifies absolute error tolerance for a KDEType.
Definition: kde_model.hpp:219
Linear algebra utility functions, generally performed on matrices or vectors.
Definition: add_to_po.hpp:21
KDEMode
KDEMode represents the ways in which KDE algorithm can be executed.
Definition: kde.hpp:25
BandwidthVisitor modifies the bandwidth of a KDEType kernel.
Definition: kde_model.hpp:177
double MCEntryCoefficient() const
Get Monte Carlo entry coefficient.
Definition: kde_model.hpp:552
DualBiKDE computes a Kernel Density Estimation on the given KDEType.
Definition: kde_model.hpp:118
static constexpr double mcBreakCoef
Monte Carlo break coefficient.
Definition: kde.hpp:57
KernelTypes & KernelType()
Modify the kernel type of the model.
Definition: kde_model.hpp:531
TreeTypes TreeType() const
Get the tree type of the model.
Definition: kde_model.hpp:522
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:534
static constexpr double absError
Absolute error tolerance.
Definition: kde.hpp:38
ModeVisitor exposes the Mode() method of the KDEType.
Definition: kde_model.hpp:346
void CleanMemory()
Delete any unique pointers that are held by the CLI 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:558
MCSampleSizeVisitor sets the Monte Carlo intial sample size for a given KDEType.
Definition: kde_model.hpp:283
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: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:60
MCBreakCoefVisitor sets the Monte Carlo break coefficient.
Definition: kde_model.hpp:325
double AbsoluteError() const
Get the absolute error tolerance.
Definition: kde_model.hpp:516
static constexpr size_t initialSampleSize
Initial sample size for Monte Carlo estimations.
Definition: kde.hpp:51
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:525
MCProbabilityVisitor sets the Monte Carlo probability for a given KDEType.
Definition: kde_model.hpp:261
DualMonoKDE computes a Kernel Density Estimation on the given KDEType.
Definition: kde_model.hpp:87
static constexpr double mcProb
Probability of a Monte Carlo estimation to be bounded by the relative error tolerance.
Definition: kde.hpp:48
MonteCarloVisitor activates or deactivates Monte Carlo for a given KDEType.
Definition: kde_model.hpp:240
TrainVisitor trains a given KDEType using a reference set.
Definition: kde_model.hpp:154
KernelNormalizer holds a set of methods to normalize estimations applying in each case the appropiate...
Definition: kde_model.hpp:51
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:528
MCEntryCoefVisitor sets the Monte Carlo entry coefficient.
Definition: kde_model.hpp:304
double MCProbability() const
Get Monte Carlo probability of error being bounded by relative error.
Definition: kde_model.hpp:540
size_t MCInitialSampleSize() const
Get the initial sample size for Monte Carlo estimations.
Definition: kde_model.hpp:546
RelErrorVisitor modifies relative error tolerance for a KDEType.
Definition: kde_model.hpp:198