ensmallen
mlpack
fast, flexible C++ machine learning library
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 
21 namespace mlpack {
22 namespace kde {
23 
25 enum KDEMode
26 {
29 };
30 
33 {
35  static constexpr double relError = 0.05;
36 
38  static constexpr double absError = 0;
39 
41  static constexpr KDEMode mode = KDEMode::DUAL_TREE_MODE;
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 
74 template<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,
86  kde::KDEStat,
87  MatType>::template SingleTreeTraverser>
88 class 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(),
118  MetricType metric = MetricType(),
120  const double mcProb = KDEDefaultParams::mcProb,
124 
131  KDE(const KDE& other);
132 
138  KDE(KDE&& other);
139 
147  KDE& operator=(KDE other);
148 
153  ~KDE();
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 
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
357 Cannot use BOOST_TEMPLATE_CLASS_VERSION because of the problem stated in
358 https://stackoverflow.com/questions/8942912/how-to-pass-multi-argument-templates
359 -to-macros
360 */
361 
362 namespace boost {
363 namespace serialization{
364 
365 template<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>
373 struct 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
KernelType & Kernel()
Modify the kernel.
Definition: kde.hpp:227
static constexpr double relError
Relative error tolerance.
Definition: kde.hpp:35
Set the serialization version of the adaboost class.
Definition: adaboost.hpp:180
bool & MonteCarlo()
Modify whether Monte Carlo estimations are being used or not.
Definition: kde.hpp:266
.hpp
Definition: add_to_po.hpp:21
double MCProb() const
Get Monte Carlo probability of error being bounded by relative error.
Definition: kde.hpp:269
KDEMode
KDEMode represents the ways in which KDE algorithm can be executed.
Definition: kde.hpp:25
bool IsTrained() const
Check whether KDE model is trained or not.
Definition: kde.hpp:254
static constexpr double mcBreakCoef
Monte Carlo break coefficient.
Definition: kde.hpp:57
const KernelType & Kernel() const
Get the kernel.
Definition: kde.hpp:224
The core includes that mlpack expects; standard C++ includes and Armadillo.
const MetricType & Metric() const
Get the metric.
Definition: kde.hpp:230
size_t MCInitialSampleSize() const
Get Monte Carlo initial sample size.
Definition: kde.hpp:276
Extra data for each node in the tree for the task of kernel density estimation.
Definition: kde_stat.hpp:24
KDEMode & Mode()
Modify the mode of KDE.
Definition: kde.hpp:260
KDEMode Mode() const
Get the mode of KDE.
Definition: kde.hpp:257
TreeType< MetricType, kde::KDEStat, MatType > Tree
Convenience typedef.
Definition: kde.hpp:92
static constexpr KDEMode mode
KDE algorithm mode.
Definition: kde.hpp:41
MetricType & Metric()
Modify the metric.
Definition: kde.hpp:233
static constexpr double absError
Absolute error tolerance.
Definition: kde.hpp:38
double RelativeError() const
Get relative error tolerance.
Definition: kde.hpp:239
The KDE class is a template class for performing Kernel Density Estimations.
Definition: kde.hpp:88
static constexpr bool monteCarlo
Whether to use Monte Carlo estimations when possible.
Definition: kde.hpp:44
bool MonteCarlo() const
Get whether Monte Carlo estimations are being used or not.
Definition: kde.hpp:263
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
KDEDefaultParams contains the default input parameter values for KDE.
Definition: kde.hpp:32
static constexpr double mcProb
Probability of a Monte Carlo estimation to be bounded by the relative error tolerance.
Definition: kde.hpp:48
double MCEntryCoef() const
Get Monte Carlo entry coefficient.
Definition: kde.hpp:282
size_t & MCInitialSampleSize()
Modify Monte Carlo initial sample size.
Definition: kde.hpp:279
The standard Gaussian kernel.
double MCBreakCoef() const
Get Monte Carlo break coefficient.
Definition: kde.hpp:288
BinarySpaceTree< MetricType, StatisticType, MatType, bound::HRectBound, MidpointSplit > KDTree
The standard midpoint-split kd-tree.
Definition: typedef.hpp:63
LMetric< 2, true > EuclideanDistance
The Euclidean (L2) distance.
Definition: lmetric.hpp:112
Tree * ReferenceTree()
Get the reference tree.
Definition: kde.hpp:236
bool OwnsReferenceTree() const
Check whether reference tree is owned by the KDE model.
Definition: kde.hpp:251
double AbsoluteError() const
Get absolute error tolerance.
Definition: kde.hpp:245