mlpack 3.4.2
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
28namespace mlpack {
29namespace kde {
30
32template<typename KernelType,
33 template<typename TreeMetricType,
34 typename TreeStatType,
35 typename TreeMatType> class TreeType>
36using KDEType = KDE<KernelType,
38 arma::mat,
39 TreeType,
42 arma::mat>::template DualTreeTraverser,
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
87class 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
118class 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
154class 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
177class 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
198class 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
219class 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
240class 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
261class 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
283class 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
304class 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
325class 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
346class ModeVisitor : public boost::static_visitor<KDEMode&>
347{
348 public:
350 template<typename KDEType>
352};
353
354class DeleteVisitor : public boost::static_visitor<void>
355{
356 public:
358 template<typename KDEType>
359 void operator()(KDEType* kde) const;
360};
361
363{
364 public:
366 {
371 R_TREE
372 };
373
375 {
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
486
495
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
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
AbsErrorVisitor modifies absolute error tolerance for a KDEType.
Definition: kde_model.hpp:220
AbsErrorVisitor(const double absError)
AbsErrorVisitor constructor.
BandwidthVisitor modifies the bandwidth of a KDEType kernel.
Definition: kde_model.hpp:178
BandwidthVisitor(const double bandwidth)
BandwidthVisitor constructor.
void operator()(KDEType *kde) const
Delete KDEType instance.
DualBiKDE computes a Kernel Density Estimation on the given KDEType.
Definition: kde_model.hpp:119
DualBiKDE(arma::mat &&querySet, arma::vec &estimations)
DualBiKDE constructor. Takes ownership of the given querySet.
DualMonoKDE computes a Kernel Density Estimation on the given KDEType.
Definition: kde_model.hpp:88
DualMonoKDE(arma::vec &estimations)
DualMonoKDE constructor.
double MCEntryCoefficient() const
Get Monte Carlo entry coefficient.
Definition: kde_model.hpp:552
KernelTypes KernelType() const
Get the kernel type of the model.
Definition: kde_model.hpp:528
KDEModel & operator=(KDEModel other)
Copy the given model.
KDEMode & Mode()
Modify the mode of the model.
KDEModel(const double bandwidth=1.0, const double relError=KDEDefaultParams::relError, const double absError=KDEDefaultParams::absError, const KernelTypes kernelType=KernelTypes::GAUSSIAN_KERNEL, const TreeTypes treeType=TreeTypes::KD_TREE, const bool monteCarlo=KDEDefaultParams::mode, const double mcProb=KDEDefaultParams::mcProb, const size_t initialSampleSize=KDEDefaultParams::initialSampleSize, const double mcEntryCoef=KDEDefaultParams::mcEntryCoef, const double mcBreakCoef=KDEDefaultParams::mcBreakCoef)
Initialize KDEModel.
void RelativeError(const double newRelError)
Modify the relative error tolerance.
double RelativeError() const
Get the relative error tolerance.
Definition: kde_model.hpp:510
void MonteCarlo(const bool newMonteCarlo)
Modify whether the model is using Monte Carlo estimations or not.
void MCBreakCoefficient(const double newBreakCoef)
Modify Monte Carlo break coefficient.
void AbsoluteError(const double newAbsError)
Modify the absolute error tolerance.
KernelTypes & KernelType()
Modify the kernel type of the model.
Definition: kde_model.hpp:531
double MCProbability() const
Get Monte Carlo probability of error being bounded by relative error.
Definition: kde_model.hpp:540
TreeTypes & TreeType()
Modify the tree type of the model.
Definition: kde_model.hpp:525
void serialize(Archive &ar, const unsigned int version)
Serialize the KDE model.
KDEMode Mode() const
Get the mode of the model.
void BuildModel(arma::mat &&referenceSet)
Build the KDE model with the given parameters and then trains it with the given reference data.
void Bandwidth(const double newBandwidth)
Modify the bandwidth of the kernel.
void MCEntryCoefficient(const double newEntryCoef)
Modify Monte Carlo entry coefficient.
void Evaluate(arma::vec &estimations)
Perform kernel density estimation on the reference set.
size_t MCInitialSampleSize() const
Get the initial sample size for Monte Carlo estimations.
Definition: kde_model.hpp:546
double MCBreakCoefficient() const
Get Monte Carlo break coefficient.
Definition: kde_model.hpp:558
bool MonteCarlo() const
Get whether the model is using Monte Carlo estimations or not.
Definition: kde_model.hpp:534
double AbsoluteError() const
Get the absolute error tolerance.
Definition: kde_model.hpp:516
~KDEModel()
Destroy the KDEModel object.
TreeTypes TreeType() const
Get the tree type of the model.
Definition: kde_model.hpp:522
KDEModel(const KDEModel &other)
Copy constructor of the given model.
KDEModel(KDEModel &&other)
Move constructor of the given model. Takes ownership of the model.
void MCProbability(const double newMCProb)
Modify Monte Carlo probability of error being bounded by relative error.
double Bandwidth() const
Get the bandwidth of the kernel.
Definition: kde_model.hpp:504
void MCInitialSampleSize(const size_t newSampleSize)
Modify the initial sample size for Monte Carlo estimations.
void Evaluate(arma::mat &&querySet, arma::vec &estimations)
Perform kernel density estimation on the given query set.
Extra data for each node in the tree for the task of kernel density estimation.
Definition: kde_stat.hpp:25
The KDE class is a template class for performing Kernel Density Estimations.
Definition: kde.hpp:89
KernelNormalizer holds a set of methods to normalize estimations applying in each case the appropiate...
Definition: kde_model.hpp:52
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
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
MCBreakCoefVisitor sets the Monte Carlo break coefficient.
Definition: kde_model.hpp:326
MCBreakCoefVisitor(const double breakCoef)
MCBreakCoefVisitor constructor.
MCEntryCoefVisitor sets the Monte Carlo entry coefficient.
Definition: kde_model.hpp:305
MCEntryCoefVisitor(const double entryCoef)
MCEntryCoefVisitor constructor.
MCProbabilityVisitor sets the Monte Carlo probability for a given KDEType.
Definition: kde_model.hpp:262
MCProbabilityVisitor(const double probability)
MCProbabilityVisitor constructor.
MCSampleSizeVisitor sets the Monte Carlo intial sample size for a given KDEType.
Definition: kde_model.hpp:284
MCSampleSizeVisitor(const size_t sampleSize)
MCSampleSizeVisitor constructor.
ModeVisitor exposes the Mode() method of the KDEType.
Definition: kde_model.hpp:347
KDEMode & operator()(KDEType *kde) const
Return mode of KDEType instance.
MonteCarloVisitor activates or deactivates Monte Carlo for a given KDEType.
Definition: kde_model.hpp:241
MonteCarloVisitor(const bool monteCarlo)
MonteCarloVisitor constructor.
RelErrorVisitor modifies relative error tolerance for a KDEType.
Definition: kde_model.hpp:199
RelErrorVisitor(const double relError)
RelErrorVisitor constructor.
TrainVisitor trains a given KDEType using a reference set.
Definition: kde_model.hpp:155
TrainVisitor(arma::mat &&referenceSet)
TrainVisitor constructor. Takes ownership of the given referenceSet.
Include all of the base components required to write mlpack methods, and the main mlpack Doxygen docu...
BOOST_TEMPLATE_CLASS_VERSION(template<>, mlpack::kde::KDEModel, 1)
Set the serialization version of the KDEModel class.
KDEMode
KDEMode represents the ways in which KDE algorithm can be executed.
Definition: kde.hpp:26
LMetric< 2, true > EuclideanDistance
The Euclidean (L2) distance.
Definition: lmetric.hpp:112
Linear algebra utility functions, generally performed on matrices or vectors.
Definition: cv.hpp:1
static constexpr KDEMode mode
KDE algorithm mode.
Definition: kde.hpp:41
static constexpr double absError
Absolute error tolerance.
Definition: kde.hpp:38
static constexpr double mcProb
Probability of a Monte Carlo estimation to be bounded by the relative error tolerance.
Definition: kde.hpp:48
static constexpr double mcBreakCoef
Monte Carlo break coefficient.
Definition: kde.hpp:57
static constexpr double mcEntryCoef
Monte Carlo entry coefficient.
Definition: kde.hpp:54
static constexpr size_t initialSampleSize
Initial sample size for Monte Carlo estimations.
Definition: kde.hpp:51
static constexpr double relError
Relative error tolerance.
Definition: kde.hpp:35