From 79fd639d12a64f3b5471e048ed6d83344b955fea Mon Sep 17 00:00:00 2001 From: Ryan Curtin Date: Tue, 9 Feb 2016 10:08:08 -0500 Subject: [PATCH] Documentation fixes. --- doc/tutorials/emst/emst.txt | 3 +- .../neighbor_search/neighbor_search.txt | 82 ++++++++++++++----- doc/tutorials/range_search/range_search.txt | 42 +++++----- doc/tutorials/tutorials.txt | 16 +++- 4 files changed, 98 insertions(+), 45 deletions(-) diff --git a/doc/tutorials/emst/emst.txt b/doc/tutorials/emst/emst.txt index b2b7f11db7d..f4b42c58cca 100644 --- a/doc/tutorials/emst/emst.txt +++ b/doc/tutorials/emst/emst.txt @@ -125,7 +125,8 @@ algorithm for timing and comparison purposes, using the \c --naive option. @section dtb_emsttut The 'DualTreeBoruvka' class -The 'DualTreeBoruvka' class contains our implementation of the Dual-Tree Boruvka algorithm. +The 'DualTreeBoruvka' class contains our implementation of the Dual-Tree Boruvka +algorithm. The class has two constructors: the first takes the data set, constructs the tree (where the type of tree constructed is the TreeType template parameter), diff --git a/doc/tutorials/neighbor_search/neighbor_search.txt b/doc/tutorials/neighbor_search/neighbor_search.txt index a261689a16f..f60cca15565 100644 --- a/doc/tutorials/neighbor_search/neighbor_search.txt +++ b/doc/tutorials/neighbor_search/neighbor_search.txt @@ -42,7 +42,9 @@ A list of all the sections this tutorial contains. - \ref neighborsearch_nstut - \ref sort_policy_doc_nstut - \ref metric_type_doc_nstut + - \ref mat_type_doc_nstut - \ref tree_type_doc_nstut + - \ref traverser_type_doc_nstut - \ref further_doc_nstut @section cli_nstut Command-Line 'allknn' @@ -319,14 +321,20 @@ arguments: template< typename SortPolicy = NearestNeighborSort, typename MetricType = mlpack::metric::EuclideanDistance, - typename TreeType = mlpack::tree::BinarySpaceTree, - QueryStat > + typename MatType = arma::mat, + template class TreeType = tree::KDTree, + template class TraversalType = + TreeType, + MatType>::template DualTreeTraverser> > class NeighborSearch; @endcode By choosing different components for each of these template classes, a very -arbitrary neighbor searching object can be constructed. +arbitrary neighbor searching object can be constructed. Note that each of these +template parameters have defaults, so it is not necessary to specify each one. @subsection sort_policy_doc_nstut SortPolicy policy class @@ -379,34 +387,70 @@ Mahalanobis distance (mlpack::metric::MahalanobisDistance), which must store state (the covariance matrix). Therefore, you can write a non-static MetricType class and use it seamlessly with NeighborSearch. +For more information on the MetricType policy, see the documentation +\ref metrics "here". + +@subsection mat_type_doc_nstut MatType policy class + +The MatType template parameter specifies the type of data matrix used. This +type must implement the same operations as an Armadillo matrix, and so standard +choices are @c arma::mat and @c arma::sp_mat. + @subsection tree_type_doc_nstut TreeType policy class -The NeighborSearch class also allows a custom tree to be used. The standard -\b mlpack tree, mlpack::tree::BinarySpaceTree, is also highly extensible in its -own right, and its documentation should be consulted for more information. -Currently, the NeighborSearch tree requires a tree which only has left and right -children, and no points in nodes (only in leaves), but this support is planned -to be extended. +The NeighborSearch class allows great extensibility in the selection of the type +of tree used for search. This type must follow the typical mlpack TreeType +policy, documented \ref trees "here". + +Typical choices might include mlpack::tree::KDTree, mlpack::tree::BallTree, +mlpack::tree::StandardCoverTree, mlpack::tree::RTree, or +mlpack::tree::RStarTree. It is easily possible to make your own tree type for +use with NeighborSearch; consult the \ref trees "TreeType documentation" for +more details. -A simple usage of the TreeType policy could be to use a different type of bound -with the tree. For instance, you could use a ball bound instead of a -rectangular bound: +An example of using the NeighborSearch class with a ball tree is given below. @code // Construct a NeighborSearch object with ball bounds. NeighborSearch< NearestNeighborSort, metric::EuclideanDistance, - tree::BinarySpaceTree, - QueryStat > + arma::mat, + tree::BallTree > neighborSearch(dataset); @endcode -It is important to note that the NeighborSearch class requires use of the -QueryStat tree statistic to function properly. Therefore, if you write a custom -tree, be sure it can accept the QueryStat type. See the -mlpack::tree::BinarySpaceTree documentation for more information on tree -statistics. +@subsection traverser_type_doc_nstut TraverserType policy class + +The last template parameter the NeighborSearch class offers is the TraverserType +class. The TraverserType class holds the strategy used to traverse the trees in +either single-tree or dual-tree search mode. By default, it is set to use the +default traverser of the given @c TreeType (which is the member @c +TreeType::DualTreeTraverser). + +This class must implement the following two methods: + +@code +// Instantiate with a given RuleType. +TraverserType(RuleType& rule); + +// Traverse with two trees. +void Traverse(TreeType& queryNode, TreeType& referenceNode); +@endcode + +The RuleType class provides the following functions for use in the traverser: + +@code +// Evaluate the base case between two points. +double BaseCase(const size_t queryIndex, const size_t referenceIndex); + +// Score the two nodes to see if they can be pruned, returning DBL_MAX if they +// can be pruned. +double Score(TreeType& queryNode, TreeType& referenceNode); +@endcode + +Note also that any traverser given must satisfy the definition of a pruning +dual-tree traversal given in the paper "Tree-independent dual-tree algorithms". @section further_doc_nstut Further documentation diff --git a/doc/tutorials/range_search/range_search.txt b/doc/tutorials/range_search/range_search.txt index 2ee98fb79a9..61ad7109d3d 100644 --- a/doc/tutorials/range_search/range_search.txt +++ b/doc/tutorials/range_search/range_search.txt @@ -41,6 +41,7 @@ A list of all the sections this tutorial contains. - \ref rs_ex3_rstut - \ref rs_ext_rstut - \ref metric_type_doc_rstut + - \ref mat_type_doc_rstut - \ref tree_type_doc_rstut - \ref further_doc_rstut @@ -372,40 +373,35 @@ Mahalanobis distance (mlpack::metric::MahalanobisDistance), which must store state (the covariance matrix). Therefore, you can write a non-static MetricType class and use it seamlessly with RangeSearch. +@subsection mat_type_doc_rstut MatType policy class + +The MatType template parameter specifies the type of data matrix used. This +type must implement the same operations as an Armadillo matrix, and so standard +choices are @c arma::mat and @c arma::sp_mat. + @subsection tree_type_doc_rstut TreeType policy class -The RangeSearch class also allows a custom tree to be used. The standard -\b mlpack tree, mlpack::tree::BinarySpaceTree, is also highly extensible in its -own right, and its documentation should be consulted for more information. +The RangeSearch class also allows a custom tree to be used. The TreeType policy +is also used elsewhere in mlpack and is documented more thoroughly +\ref trees "here". -A simple usage of the TreeType policy could be to use a different type of bound -with the existing mlpack::tree::BinarySpaceTree class. For instance, you could -use a ball bound instead of a rectangular bound: +Typical choices might include mlpack::tree::KDTree (the default), +mlpack::tree::BallTree, mlpack::tree::RTree, mlpack::tree::RStarTree, +or mlpack::tree::StandardCoverTree. Below is an example that uses the +RangeSearch class with an R-tree: @code // Construct a RangeSearch object with ball bounds. RangeSearch< metric::EuclideanDistance, - tree::BinarySpaceTree, - EmptyStatistic> + arma::mat, + tree::RTree > rangeSearch(dataset); @endcode -Unlike the \ref nstutorial "NeighborSearch class", the RangeSearch class does -not make use of tree statistics; therefore, the EmptyStatistic class should be -used for the StatisticType parameter of the BinarySpaceTree (but this is not -technically necessary -- RangeSearch simply makes no use of the tree statistic). - -It is also possible to use a completely different type of tree. The example -below shows the use of the RangeSearch class with the mlpack::tree::CoverTree -class (which has the EmptyStatistic statistic type as a default, so we do not -need to specify that). - -@code -// Construct a RangeSearch object that uses cover trees. -RangeSearch - rangeSearch(dataset); -@endcode +For further information on trees, including how to write your own tree for use +with RangeSearch and other mlpack methods, see the +\ref trees "TreeType policy documentation". @section further_doc_rstut Further documentation diff --git a/doc/tutorials/tutorials.txt b/doc/tutorials/tutorials.txt index 1a4ce486eb7..167b88070db 100644 --- a/doc/tutorials/tutorials.txt +++ b/doc/tutorials/tutorials.txt @@ -21,8 +21,8 @@ start. @section method_tut Method-specific Tutorials These tutorials introduce the various methods mlpack offers, aimed at users who -simply want to use the methods mlpack offers. These tutorials start with simple -examples and progress to complex, extensible uses. +want to get started quickly. These tutorials start with simple examples and +progress to complex, extensible uses. - \ref nstutorial - \ref lrtutorial @@ -32,4 +32,16 @@ examples and progress to complex, extensible uses. - \ref fmkstutorial - \ref emst_tutorial - \ref amftutorial + +@section policy_tut Policy Class Documentation + +mlpack uses templates to achieve its genericity and flexibility. Some of the +template types used by mlpack are common across multiple machine learning +algorithms. The links below provide documentation for some of these common +types. + + - \ref metrics + - \ref kernels + - \ref trees + */