[mlpack-git] master: Improve documentation. (6c2c3ca)
gitdub at mlpack.org
gitdub at mlpack.org
Thu Jun 16 22:55:08 EDT 2016
Repository : https://github.com/mlpack/mlpack
On branch : master
Link : https://github.com/mlpack/mlpack/compare/a7e8d3bac60d6aa2717f27e0d4f6c53ff20607f5...779556fed748819a18cc898d9a6f69900740ef23
>---------------------------------------------------------------
commit 6c2c3ca83d8d955b6b6f8634d9f88df06f6e3cca
Author: MarcosPividori <marcos.pividori at gmail.com>
Date: Thu Jun 16 23:55:08 2016 -0300
Improve documentation.
>---------------------------------------------------------------
6c2c3ca83d8d955b6b6f8634d9f88df06f6e3cca
src/mlpack/methods/neighbor_search/ns_model.hpp | 64 +++++++++++++++++++++-
.../methods/neighbor_search/ns_model_impl.hpp | 26 +++++++--
2 files changed, 82 insertions(+), 8 deletions(-)
diff --git a/src/mlpack/methods/neighbor_search/ns_model.hpp b/src/mlpack/methods/neighbor_search/ns_model.hpp
index f0db0d1..0203e71 100644
--- a/src/mlpack/methods/neighbor_search/ns_model.hpp
+++ b/src/mlpack/methods/neighbor_search/ns_model.hpp
@@ -19,6 +19,9 @@
namespace mlpack {
namespace neighbor {
+/**
+ * Alias template for euclidean neighbor search.
+ */
template<typename SortPolicy,
template<typename TreeMetricType,
typename TreeStatType,
@@ -49,6 +52,10 @@ struct NSModelName<FurthestNeighborSort>
static const std::string Name() { return "furthest_neighbor_search_model"; }
};
+/**
+ * MonoSearchVisitor executes a monochromatic neighbor search on the given
+ * NSType. We don't make any difference for different instantiations of NSType.
+ */
class MonoSearchVisitor : public boost::static_visitor<void>
{
private:
@@ -65,6 +72,12 @@ class MonoSearchVisitor : public boost::static_visitor<void>
arma::mat& distances);
};
+/**
+ * BiSearchVisitor executes a bichromatic neighbor search on the given NSType.
+ * We use template specialization to differenciate those tree types that
+ * accept leafSize as a parameter. In these cases, before doing neighbor search,
+ * a query tree with proper leafSize is built from the querySet.
+ */
template<typename SortPolicy>
class BiSearchVisitor : public boost::static_visitor<void>
{
@@ -75,22 +88,27 @@ class BiSearchVisitor : public boost::static_visitor<void>
arma::mat& distances;
const size_t leafSize;
+ //! Bichromatic neighbor search on the given NSType considering the leafSize.
template<typename NSType>
void SearchLeaf(NSType* ns) const;
public:
+ //! Alias template necessary for visual c++ compiler.
template<template<typename TreeMetricType,
typename TreeStatType,
typename TreeMatType> class TreeType>
using NSTypeT = NSType<SortPolicy, TreeType>;
+ //! Default Bichromatic neighbor search on the given NSType instance.
template<template<typename TreeMetricType,
typename TreeStatType,
typename TreeMatType> class TreeType>
void operator()(NSTypeT<TreeType>* ns) const;
+ //! Bichromatic neighbor search on the given NSType specialized for KDTrees.
void operator()(NSTypeT<tree::KDTree>* ns) const;
+ //! Bichromatic neighbor search on the given NSType specialized for BallTrees.
void operator()(NSTypeT<tree::BallTree>* ns) const;
BiSearchVisitor(const arma::mat& querySet,
@@ -100,6 +118,12 @@ class BiSearchVisitor : public boost::static_visitor<void>
const size_t leafSize);
};
+/**
+ * TrainVisitor sets the reference set to a new reference set on the given
+ * NSType. We use template specialization to differenciate those tree types that
+ * accept leafSize as a parameter. In these cases, a reference tree with proper
+ * leafSize is built from the referenceSet.
+ */
template<typename SortPolicy>
class TrainVisitor : public boost::static_visitor<void>
{
@@ -107,27 +131,35 @@ class TrainVisitor : public boost::static_visitor<void>
arma::mat&& referenceSet;
size_t leafSize;
+ //! Train on the given NSType considering the leafSize.
template<typename NSType>
void TrainLeaf(NSType* ns) const;
public:
+ //! Alias template necessary for visual c++ compiler.
template<template<typename TreeMetricType,
typename TreeStatType,
typename TreeMatType> class TreeType>
using NSTypeT = NSType<SortPolicy, TreeType>;
+ //! Default Train on the given NSType instance.
template<template<typename TreeMetricType,
typename TreeStatType,
typename TreeMatType> class TreeType>
void operator()(NSTypeT<TreeType>* ns) const;
+ //! Train on the given NSType specialized for KDTrees.
void operator()(NSTypeT<tree::KDTree>* ns) const;
+ //! Train on the given NSType specialized for BallTrees.
void operator()(NSTypeT<tree::BallTree>* ns) const;
TrainVisitor(arma::mat&& referenceSet, const size_t leafSize);
};
+/**
+ * SingleModeVisitor exposes the SingleMode method of the given NSType.
+ */
class SingleModeVisitor : public boost::static_visitor<bool&>
{
public:
@@ -135,6 +167,9 @@ class SingleModeVisitor : public boost::static_visitor<bool&>
bool& operator()(NSType* ns) const;
};
+/**
+ * NaiveVisitor exposes the Naive method of the given NSType.
+ */
class NaiveVisitor : public boost::static_visitor<bool&>
{
public:
@@ -142,6 +177,9 @@ class NaiveVisitor : public boost::static_visitor<bool&>
bool& operator()(NSType *ns) const;
};
+/**
+ * ReferenceSetVisitor exposes the referenceSet of the given NSType.
+ */
class ReferenceSetVisitor : public boost::static_visitor<const arma::mat&>
{
public:
@@ -149,6 +187,9 @@ class ReferenceSetVisitor : public boost::static_visitor<const arma::mat&>
const arma::mat& operator()(NSType *ns) const;
};
+/**
+ * DeleteVisitor deletes the given NSType instance.
+ */
class DeleteVisitor : public boost::static_visitor<void>
{
public:
@@ -156,6 +197,9 @@ class DeleteVisitor : public boost::static_visitor<void>
void operator()(NSType *ns) const;
};
+/**
+ * SerializeVisitor serializes the given NSType instance.
+ */
template<typename Archive>
class SerializeVisitor : public boost::static_visitor<void>
{
@@ -170,10 +214,17 @@ class SerializeVisitor : public boost::static_visitor<void>
SerializeVisitor(Archive& ar, const std::string& name);
};
+/**
+ * The NSModel class provides an easy way to serialize a model, abstracts away
+ * the different types of trees, and also reflects the NeighborSearch API.
+ *
+ * @tparam SortPolicy The sort policy for distances; see NearestNeighborSort.
+ */
template<typename SortPolicy>
class NSModel
{
public:
+ //! Enum type to identify each accepted tree type.
enum TreeTypes
{
KD_TREE,
@@ -185,13 +236,21 @@ class NSModel
};
private:
+ //! Tree type considered for neighbor search.
TreeTypes treeType;
+
+ //! For tree types that accept the maxLeafSize parameter.
size_t leafSize;
- // For random projections.
+ //! For random projections.
bool randomBasis;
arma::mat q;
+ /**
+ * nSearch holds an instance of the NeigborSearch class for the current
+ * treeType. It is initialized every time BuildModel is executed.
+ * We access to the contained value through the visitor classes defined above.
+ */
boost::variant<NSType<SortPolicy, tree::KDTree>*,
NSType<SortPolicy, tree::StandardCoverTree>*,
NSType<SortPolicy, tree::RTree>*,
@@ -248,11 +307,12 @@ class NSModel
arma::Mat<size_t>& neighbors,
arma::mat& distances);
- //! Perform neighbor search.
+ //! Perform monochromatic neighbor search.
void Search(const size_t k,
arma::Mat<size_t>& neighbors,
arma::mat& distances);
+ //! Return a string representation of the current tree type.
std::string TreeName() const;
};
diff --git a/src/mlpack/methods/neighbor_search/ns_model_impl.hpp b/src/mlpack/methods/neighbor_search/ns_model_impl.hpp
index 8c7400e..1001ff4 100644
--- a/src/mlpack/methods/neighbor_search/ns_model_impl.hpp
+++ b/src/mlpack/methods/neighbor_search/ns_model_impl.hpp
@@ -16,6 +16,7 @@
namespace mlpack {
namespace neighbor {
+//! Save parameters for monochromatic neighbor search.
MonoSearchVisitor::MonoSearchVisitor(const size_t k,
arma::Mat<size_t>& neighbors,
arma::mat& distances) :
@@ -24,6 +25,7 @@ MonoSearchVisitor::MonoSearchVisitor(const size_t k,
distances(distances)
{}
+//! Monochromatic neighbor search on the given NSType instance.
template<typename NSType>
void MonoSearchVisitor::operator()(NSType *ns) const
{
@@ -32,6 +34,7 @@ void MonoSearchVisitor::operator()(NSType *ns) const
throw std::runtime_error("no neighbor search model initialized");
}
+//! Save parameters for bichromatic neighbor search.
template<typename SortPolicy>
BiSearchVisitor<SortPolicy>::BiSearchVisitor(const arma::mat& querySet,
const size_t k,
@@ -45,6 +48,7 @@ BiSearchVisitor<SortPolicy>::BiSearchVisitor(const arma::mat& querySet,
leafSize(leafSize)
{}
+//! Default Bichromatic neighbor search on the given NSType instance.
template<typename SortPolicy>
template<template<typename TreeMetricType,
typename TreeStatType,
@@ -56,6 +60,7 @@ void BiSearchVisitor<SortPolicy>::operator()(NSTypeT<TreeType>* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
+//! Bichromatic neighbor search on the given NSType specialized for KDTrees.
template<typename SortPolicy>
void BiSearchVisitor<SortPolicy>::operator()(NSTypeT<tree::KDTree>* ns) const
{
@@ -64,6 +69,7 @@ void BiSearchVisitor<SortPolicy>::operator()(NSTypeT<tree::KDTree>* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
+//! Bichromatic neighbor search on the given NSType specialized for BallTrees.
template<typename SortPolicy>
void BiSearchVisitor<SortPolicy>::operator()(NSTypeT<tree::BallTree>* ns) const
{
@@ -72,6 +78,7 @@ void BiSearchVisitor<SortPolicy>::operator()(NSTypeT<tree::BallTree>* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
+//! Bichromatic neighbor search on the given NSType considering the leafSize.
template<typename SortPolicy>
template<typename NSType>
void BiSearchVisitor<SortPolicy>::SearchLeaf(NSType* ns) const
@@ -99,7 +106,7 @@ void BiSearchVisitor<SortPolicy>::SearchLeaf(NSType* ns) const
ns->Search(querySet, k, neighbors, distances);
}
-
+//! Save parameters for Train.
template<typename SortPolicy>
TrainVisitor<SortPolicy>::TrainVisitor(arma::mat&& referenceSet,
const size_t leafSize) :
@@ -107,6 +114,7 @@ TrainVisitor<SortPolicy>::TrainVisitor(arma::mat&& referenceSet,
leafSize(leafSize)
{}
+//! Default Train on the given NSType instance.
template<typename SortPolicy>
template<template<typename TreeMetricType,
typename TreeStatType,
@@ -118,6 +126,7 @@ void TrainVisitor<SortPolicy>::operator()(NSTypeT<TreeType>* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
+//! Train on the given NSType specialized for KDTrees.
template<typename SortPolicy>
void TrainVisitor<SortPolicy>::operator ()(NSTypeT<tree::KDTree>* ns) const
{
@@ -126,6 +135,7 @@ void TrainVisitor<SortPolicy>::operator ()(NSTypeT<tree::KDTree>* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
+//! Train on the given NSType specialized for BallTrees.
template<typename SortPolicy>
void TrainVisitor<SortPolicy>::operator ()(NSTypeT<tree::BallTree>* ns) const
{
@@ -134,6 +144,7 @@ void TrainVisitor<SortPolicy>::operator ()(NSTypeT<tree::BallTree>* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
+//! Train on the given NSType considering the leafSize.
template<typename SortPolicy>
template<typename NSType>
void TrainVisitor<SortPolicy>::TrainLeaf(NSType* ns) const
@@ -154,7 +165,7 @@ void TrainVisitor<SortPolicy>::TrainLeaf(NSType* ns) const
}
}
-
+//! Expose the SingleMode method of the given NSType.
template<typename NSType>
bool& SingleModeVisitor::operator()(NSType* ns) const
{
@@ -163,7 +174,7 @@ bool& SingleModeVisitor::operator()(NSType* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
-
+//! Expose the Naive method of the given NSType.
template<typename NSType>
bool& NaiveVisitor::operator()(NSType* ns) const
{
@@ -172,7 +183,7 @@ bool& NaiveVisitor::operator()(NSType* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
-
+//! Expose the referenceSet of the given NSType.
template<typename NSType>
const arma::mat& ReferenceSetVisitor::operator()(NSType* ns) const
{
@@ -181,7 +192,7 @@ const arma::mat& ReferenceSetVisitor::operator()(NSType* ns) const
throw std::runtime_error("no neighbor search model initialized");
}
-
+//! Clean memory, if necessary.
template<typename NSType>
void DeleteVisitor::operator()(NSType* ns) const
{
@@ -189,7 +200,7 @@ void DeleteVisitor::operator()(NSType* ns) const
delete ns;
}
-
+//! Save parameters for serialization.
template<typename Archive>
SerializeVisitor<Archive>::SerializeVisitor(Archive& ar,
const std::string& name) :
@@ -197,6 +208,7 @@ SerializeVisitor<Archive>::SerializeVisitor(Archive& ar,
name(name)
{}
+//! Serialize the given NSType instance.
template<typename Archive>
template<typename NSType>
void SerializeVisitor<Archive>::operator()(NSType* ns) const
@@ -243,6 +255,7 @@ void NSModel<SortPolicy>::Serialize(Archive& ar,
boost::apply_visitor(s, nSearch);
}
+//! Expose the dataset.
template<typename SortPolicy>
const arma::mat& NSModel<SortPolicy>::Dataset() const
{
@@ -262,6 +275,7 @@ bool& NSModel<SortPolicy>::SingleMode()
return boost::apply_visitor(SingleModeVisitor(), nSearch);
}
+//! Expose Naive.
template<typename SortPolicy>
bool NSModel<SortPolicy>::Naive() const
{
More information about the mlpack-git
mailing list