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 
145  KDE& operator=(const KDE& other);
146 
152  KDE& operator=(KDE&& other);
153 
158  ~KDE();
159 
167  void Train(MatType referenceSet);
168 
179  void Train(Tree* referenceTree, std::vector<size_t>* oldFromNewReferences);
180 
195  void Evaluate(MatType querySet, arma::vec& estimations);
196 
212  void Evaluate(Tree* queryTree,
213  const std::vector<size_t>& oldFromNewQueries,
214  arma::vec& estimations);
215 
226  void Evaluate(arma::vec& estimations);
227 
229  const KernelType& Kernel() const { return kernel; }
230 
232  KernelType& Kernel() { return kernel; }
233 
235  const MetricType& Metric() const { return metric; }
236 
238  MetricType& Metric() { return metric; }
239 
241  Tree* ReferenceTree() { return referenceTree; }
242 
244  double RelativeError() const { return relError; }
245 
247  void RelativeError(const double newError);
248 
250  double AbsoluteError() const { return absError; }
251 
253  void AbsoluteError(const double newError);
254 
256  bool OwnsReferenceTree() const { return ownsReferenceTree; }
257 
259  bool IsTrained() const { return trained; }
260 
262  KDEMode Mode() const { return mode; }
263 
265  KDEMode& Mode() { return mode; }
266 
268  bool MonteCarlo() const { return monteCarlo; }
269 
271  bool& MonteCarlo() { return monteCarlo; }
272 
274  double MCProb() const { return mcProb; }
275 
278  void MCProb(const double newProb);
279 
281  size_t MCInitialSampleSize() const { return initialSampleSize; }
282 
285 
287  double MCEntryCoef() const { return mcEntryCoef; }
288 
290  void MCEntryCoef(const double newCoef);
291 
293  double MCBreakCoef() const { return mcBreakCoef; }
294 
296  void MCBreakCoef(const double newCoef);
297 
299  template<typename Archive>
300  void serialize(Archive& ar, const uint32_t version);
301 
302  private:
304  KernelType kernel;
305 
307  MetricType metric;
308 
310  Tree* referenceTree;
311 
313  std::vector<size_t>* oldFromNewReferences;
314 
316  double relError;
317 
319  double absError;
320 
322  bool ownsReferenceTree;
323 
325  bool trained;
326 
328  KDEMode mode;
329 
331  bool monteCarlo;
332 
334  double mcProb;
335 
337  size_t initialSampleSize;
338 
343  double mcEntryCoef;
344 
347  double mcBreakCoef;
348 
350  static void CheckErrorValues(const double relError, const double absError);
351 
353  static void RearrangeEstimations(const std::vector<size_t>& oldFromNew,
354  arma::vec& estimations);
355 };
356 
357 } // namespace kde
358 } // namespace mlpack
359 
360 // Include implementation.
361 #include "kde_impl.hpp"
362 
363 #endif // MLPACK_METHODS_KDE_KDE_HPP
KernelType & Kernel()
Modify the kernel.
Definition: kde.hpp:232
static constexpr double relError
Relative error tolerance.
Definition: kde.hpp:35
bool & MonteCarlo()
Modify whether Monte Carlo estimations are being used or not.
Definition: kde.hpp:271
Linear algebra utility functions, generally performed on matrices or vectors.
double MCProb() const
Get Monte Carlo probability of error being bounded by relative error.
Definition: kde.hpp:274
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:259
static constexpr double mcBreakCoef
Monte Carlo break coefficient.
Definition: kde.hpp:57
const KernelType & Kernel() const
Get the kernel.
Definition: kde.hpp:229
The core includes that mlpack expects; standard C++ includes, Armadillo, cereal, and a few basic mlpa...
const MetricType & Metric() const
Get the metric.
Definition: kde.hpp:235
size_t MCInitialSampleSize() const
Get Monte Carlo initial sample size.
Definition: kde.hpp:281
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:265
KDEMode Mode() const
Get the mode of KDE.
Definition: kde.hpp:262
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:238
static constexpr double absError
Absolute error tolerance.
Definition: kde.hpp:38
double RelativeError() const
Get relative error tolerance.
Definition: kde.hpp:244
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:268
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:287
size_t & MCInitialSampleSize()
Modify Monte Carlo initial sample size.
Definition: kde.hpp:284
The standard Gaussian kernel.
double MCBreakCoef() const
Get Monte Carlo break coefficient.
Definition: kde.hpp:293
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:241
bool OwnsReferenceTree() const
Check whether reference tree is owned by the KDE model.
Definition: kde.hpp:256
double AbsoluteError() const
Get absolute error tolerance.
Definition: kde.hpp:250