[mlpack-git] master: Add an actual example. (e7ab269)

[gitdub at big.cc.gt.atl.ga.us]

Repository : https://github.com/mlpack/mlpack

On branch  : master
Link       : https://github.com/mlpack/mlpack/compare/ad4cc1bfc9b3e9897ef5340940afaa2227b03223...07f205fe90f9e6df5080c509fd36684758eb71cd

>---------------------------------------------------------------

commit e7ab269631a23f49d5d0d647314ff2c0c4cf87eb
Author: Ryan Curtin <ryan at ratml.org>
Date:   Sat Aug 29 11:40:57 2015 -0400

    Add an actual example.


>---------------------------------------------------------------

e7ab269631a23f49d5d0d647314ff2c0c4cf87eb
 doc/policies/metrics.hpp | 50 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/doc/policies/metrics.hpp b/doc/policies/metrics.hpp
index c9bdcbc..6237dd4 100644
--- a/doc/policies/metrics.hpp
+++ b/doc/policies/metrics.hpp
@@ -10,8 +10,10 @@ any valid metric.
 
 mlpack algorithms, when possible, allow the use of an arbitrary metric via the
 use of the \c MetricType template parameter.  Any metric passed as a
-\c MetricType template parameter will need to implement an \c Evaluate function
-and a default constructor.
+\c MetricType template parameter will need to have
+
+ - an \c Evaluate function
+ - a default constructor.
 
 The signature of the \c Evaluate function is straightforward:
 
@@ -54,6 +56,50 @@ class ExampleMetric
 };
 @endcode
 
+Then, this metric can easily be used inside of other mlpack algorithms.  For
+example, the code below runs range search on a random dataset with the
+\c ExampleKernel, by instantiating a \c mlpack::range::RangeSearch object that
+uses the \c ExampleKernel.  Then, the number of results are printed.  The \c
+RangeSearch class takes three template parameters: \c MetricType, \c MatType,
+and \c TreeType.  (All three have defaults, so we will just leave \c MatType and
+\c TreeType to their defaults.)
+
+ at code
+#include <mlpack/core.hpp>
+#include <mlpack/methods/range_search/range_search.hpp>
+#include "example_metric.hpp" // A file that contains ExampleKernel.
+
+using namespace mlpack;
+using namespace mlpack::range;
+using namespace std;
+
+int main()
+{
+  // Create a random dataset with 10 dimensions and 5000 points.
+  arma::mat data = arma::randu<arma::mat>(10, 5000);
+
+  // Instantiate the RangeSearch object with the ExampleKernel.
+  RangeSearch<ExampleKernel> rs(data);
+
+  // These vectors will store the results.
+  vector<vector<size_t>> neighbors;
+  vector<vector<double>> distances;
+
+  // Create a random 10-dimensional query point.
+  arma::vec query = arma::randu<arma::vec>(10);
+
+  // Find those points with distance (according to ExampleMetric) between 1 and
+  // 2 from the query point.
+  rs.Search(query, math::Range(1.0, 2.0), neighbors, distances);
+
+  // Now, print the number of points inside the desired range.  We know that
+  // neighbors and distances will have length 1, since there was only one query
+  // point.
+  cout << neighbors[0].size() << " points within the range [1.0, 2.0] of the "
+      << "query point!" << endl;
+}
+ at endcode
+
 mlpack comes with a number of pre-written metrics that satisfy the \c MetricType
 policy: