mlpack 3.4.2
kde.hpp
Go to the documentation of this file.
1
13#ifndef MLPACK_METHODS_KDE_KDE_HPP
14#define MLPACK_METHODS_KDE_KDE_HPP
15
16#include <mlpack/prereqs.hpp>
18
19#include "kde_stat.hpp"
20
21namespace mlpack {
22namespace kde {
23
26{
29};
30
33{
35 static constexpr double relError = 0.05;
36
38 static constexpr double absError = 0;
39
42
44 static constexpr bool monteCarlo = false;
45
48 static constexpr double mcProb = 0.95;
49
51 static constexpr size_t initialSampleSize = 100;
52
54 static constexpr double mcEntryCoef = 3;
55
57 static constexpr double mcBreakCoef = 0.4;
58};
59
74template<typename KernelType = kernel::GaussianKernel,
75 typename MetricType = mlpack::metric::EuclideanDistance,
76 typename MatType = arma::mat,
77 template<typename TreeMetricType,
78 typename TreeStatType,
79 typename TreeMatType> class TreeType = tree::KDTree,
80 template<typename RuleType> class DualTreeTraversalType =
81 TreeType<MetricType,
83 MatType>::template DualTreeTraverser,
84 template<typename RuleType> class SingleTreeTraversalType =
85 TreeType<MetricType,
87 MatType>::template SingleTreeTraverser>
88class KDE
89{
90 public:
92 typedef TreeType<MetricType, kde::KDEStat, MatType> Tree;
93
114 KDE(const double relError = KDEDefaultParams::relError,
115 const double absError = KDEDefaultParams::absError,
116 KernelType kernel = KernelType(),
117 const KDEMode mode = KDEDefaultParams::mode,
118 MetricType metric = MetricType(),
119 const bool monteCarlo = KDEDefaultParams::monteCarlo,
120 const double mcProb = KDEDefaultParams::mcProb,
121 const size_t initialSampleSize = KDEDefaultParams::initialSampleSize,
122 const double mcEntryCoef = KDEDefaultParams::mcEntryCoef,
123 const double mcBreakCoef = KDEDefaultParams::mcBreakCoef);
124
131 KDE(const KDE& other);
132
138 KDE(KDE&& other);
139
148
154
162 void Train(MatType referenceSet);
163
174 void Train(Tree* referenceTree, std::vector<size_t>* oldFromNewReferences);
175
190 void Evaluate(MatType querySet, arma::vec& estimations);
191
207 void Evaluate(Tree* queryTree,
208 const std::vector<size_t>& oldFromNewQueries,
209 arma::vec& estimations);
210
221 void Evaluate(arma::vec& estimations);
222
224 const KernelType& Kernel() const { return kernel; }
225
227 KernelType& Kernel() { return kernel; }
228
230 const MetricType& Metric() const { return metric; }
231
233 MetricType& Metric() { return metric; }
234
236 Tree* ReferenceTree() { return referenceTree; }
237
239 double RelativeError() const { return relError; }
240
242 void RelativeError(const double newError);
243
245 double AbsoluteError() const { return absError; }
246
248 void AbsoluteError(const double newError);
249
251 bool OwnsReferenceTree() const { return ownsReferenceTree; }
252
254 bool IsTrained() const { return trained; }
255
257 KDEMode Mode() const { return mode; }
258
260 KDEMode& Mode() { return mode; }
261
263 bool MonteCarlo() const { return monteCarlo; }
264
266 bool& MonteCarlo() { return monteCarlo; }
267
269 double MCProb() const { return mcProb; }
270
273 void MCProb(const double newProb);
274
276 size_t MCInitialSampleSize() const { return initialSampleSize; }
277
279 size_t& MCInitialSampleSize() { return initialSampleSize; }
280
282 double MCEntryCoef() const { return mcEntryCoef; }
283
285 void MCEntryCoef(const double newCoef);
286
288 double MCBreakCoef() const { return mcBreakCoef; }
289
291 void MCBreakCoef(const double newCoef);
292
294 template<typename Archive>
295 void serialize(Archive& ar, const unsigned int version);
296
297 private:
299 KernelType kernel;
300
302 MetricType metric;
303
305 Tree* referenceTree;
306
308 std::vector<size_t>* oldFromNewReferences;
309
311 double relError;
312
314 double absError;
315
317 bool ownsReferenceTree;
318
320 bool trained;
321
323 KDEMode mode;
324
326 bool monteCarlo;
327
329 double mcProb;
330
332 size_t initialSampleSize;
333
338 double mcEntryCoef;
339
342 double mcBreakCoef;
343
345 static void CheckErrorValues(const double relError, const double absError);
346
348 static void RearrangeEstimations(const std::vector<size_t>& oldFromNew,
349 arma::vec& estimations);
350};
351
352} // namespace kde
353} // namespace mlpack
354
356/* TODO FIX
357Cannot use BOOST_TEMPLATE_CLASS_VERSION because of the problem stated in
358https://stackoverflow.com/questions/8942912/how-to-pass-multi-argument-templates
359-to-macros
360*/
361
362namespace boost {
363namespace serialization{
364
365template<typename KernelType,
366 typename MetricType,
367 typename MatType,
368 template<typename TreeMetricType,
369 typename TreeStatType,
370 typename TreeMatType> class TreeType,
371 template<typename RuleType> class DualTreeTraversalType,
372 template<typename RuleType> class SingleTreeTraversalType>
373struct version<mlpack::kde::KDE<KernelType,
374 MetricType,
375 MatType,
376 TreeType,
377 DualTreeTraversalType,
378 SingleTreeTraversalType>>
379{
380 typedef mpl::int_<1> type;
381 typedef mpl::integral_c_tag tag;
382 BOOST_STATIC_CONSTANT(int, value = version::type::value);
383 BOOST_MPL_ASSERT((boost::mpl::less<boost::mpl::int_<1>,
384 boost::mpl::int_<256>>));
385};
386
387} // namespace serialization.
388} // namespace boost.
389
390// Include implementation.
391#include "kde_impl.hpp"
392
393#endif // MLPACK_METHODS_KDE_KDE_HPP
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
Tree * ReferenceTree()
Get the reference tree.
Definition: kde.hpp:236
KDE(const KDE &other)
Construct KDE object as a copy of the given model.
double MCEntryCoef() const
Get Monte Carlo entry coefficient.
Definition: kde.hpp:282
KernelType & Kernel()
Modify the kernel.
Definition: kde.hpp:227
void MCProb(const double newProb)
Modify Monte Carlo probability of error being bounded by relative error.
KDEMode & Mode()
Modify the mode of KDE.
Definition: kde.hpp:260
void Train(MatType referenceSet)
Trains the KDE model.
const MetricType & Metric() const
Get the metric.
Definition: kde.hpp:230
double RelativeError() const
Get relative error tolerance.
Definition: kde.hpp:239
double MCBreakCoef() const
Get Monte Carlo break coefficient.
Definition: kde.hpp:288
KDE(const double relError=KDEDefaultParams::relError, const double absError=KDEDefaultParams::absError, KernelType kernel=KernelType(), const KDEMode mode=KDEDefaultParams::mode, MetricType metric=MetricType(), const bool monteCarlo=KDEDefaultParams::monteCarlo, const double mcProb=KDEDefaultParams::mcProb, const size_t initialSampleSize=KDEDefaultParams::initialSampleSize, const double mcEntryCoef=KDEDefaultParams::mcEntryCoef, const double mcBreakCoef=KDEDefaultParams::mcBreakCoef)
Initialize KDE object using custom instantiated Metric and Kernel objects.
void RelativeError(const double newError)
Modify relative error tolerance (0 <= newError <= 1).
bool & MonteCarlo()
Modify whether Monte Carlo estimations are being used or not.
Definition: kde.hpp:266
double MCProb() const
Get Monte Carlo probability of error being bounded by relative error.
Definition: kde.hpp:269
bool OwnsReferenceTree() const
Check whether reference tree is owned by the KDE model.
Definition: kde.hpp:251
bool IsTrained() const
Check whether KDE model is trained or not.
Definition: kde.hpp:254
KDE & operator=(KDE other)
Copy a KDE model.
~KDE()
Destroy the KDE object.
void serialize(Archive &ar, const unsigned int version)
Serialize the model.
KDEMode Mode() const
Get the mode of KDE.
Definition: kde.hpp:257
TreeType< MetricType, kde::KDEStat, MatType > Tree
Convenience typedef.
Definition: kde.hpp:92
void Evaluate(arma::vec &estimations)
Estimate density of each point in the reference set given the data of the reference set.
MetricType & Metric()
Modify the metric.
Definition: kde.hpp:233
size_t MCInitialSampleSize() const
Get Monte Carlo initial sample size.
Definition: kde.hpp:276
const KernelType & Kernel() const
Get the kernel.
Definition: kde.hpp:224
void Evaluate(MatType querySet, arma::vec &estimations)
Estimate density of each point in the query set given the data of the reference set.
bool MonteCarlo() const
Get whether Monte Carlo estimations are being used or not.
Definition: kde.hpp:263
void MCEntryCoef(const double newCoef)
Modify Monte Carlo entry coefficient. (newCoef >= 1).
void Evaluate(Tree *queryTree, const std::vector< size_t > &oldFromNewQueries, arma::vec &estimations)
Estimate density of each point in the query set given the data of an already created query tree.
double AbsoluteError() const
Get absolute error tolerance.
Definition: kde.hpp:245
void AbsoluteError(const double newError)
Modify absolute error tolerance (0 <= newError).
KDE(KDE &&other)
Construct KDE object taking ownership of the given model.
size_t & MCInitialSampleSize()
Modify Monte Carlo initial sample size.
Definition: kde.hpp:279
void MCBreakCoef(const double newCoef)
Modify Monte Carlo break coefficient. (0 < newCoef <= 1).
void Train(Tree *referenceTree, std::vector< size_t > *oldFromNewReferences)
Trains the KDE model.
The standard Gaussian kernel.
Set the serialization version of the adaboost class.
Definition: adaboost.hpp:198
KDEMode
KDEMode represents the ways in which KDE algorithm can be executed.
Definition: kde.hpp:26
@ SINGLE_TREE_MODE
Definition: kde.hpp:28
@ DUAL_TREE_MODE
Definition: kde.hpp:27
LMetric< 2, true > EuclideanDistance
The Euclidean (L2) distance.
Definition: lmetric.hpp:112
BinarySpaceTree< MetricType, StatisticType, MatType, bound::HRectBound, MidpointSplit > KDTree
The standard midpoint-split kd-tree.
Definition: typedef.hpp:63
Linear algebra utility functions, generally performed on matrices or vectors.
Definition: cv.hpp:1
The core includes that mlpack expects; standard C++ includes and Armadillo.
KDEDefaultParams contains the default input parameter values for KDE.
Definition: kde.hpp:33
static constexpr KDEMode mode
KDE algorithm mode.
Definition: kde.hpp:41
static constexpr bool monteCarlo
Whether to use Monte Carlo estimations when possible.
Definition: kde.hpp:44
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