196 lines
33 KiB
HTML
196 lines
33 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.11"/>
|
|
<title>mlpack: NeighborSearch tutorial (k-nearest-neighbors)</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<script type="text/javascript">
|
|
$(document).ready(function() { init_search(); });
|
|
</script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="extra-stylesheet.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">mlpack
|
|
 <span id="projectnumber">master</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.11 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
</script>
|
|
<div id="navrow1" class="tabs">
|
|
<ul class="tablist">
|
|
<li><a href="index.html"><span>Main Page</span></a></li>
|
|
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
|
|
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
|
|
<li><a href="annotated.html"><span>Classes</span></a></li>
|
|
<li><a href="files.html"><span>Files</span></a></li>
|
|
<li>
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
alt=""/>
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
|
</span><span class="right">
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
|
</span>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
</div><!-- top -->
|
|
<div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">NeighborSearch tutorial (k-nearest-neighbors) </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><h1><a class="anchor" id="intro_nstut"></a>
|
|
Introduction</h1>
|
|
<p>Nearest-neighbors search is a common machine learning task. In this setting, we have a <b>query</b> and a <b>reference</b> dataset. For each point in the <b>query</b> dataset, we wish to know the <img class="formulaInl" alt="$k$" src="form_103.png"/> points in the <b>reference</b> dataset which are closest to the given query point.</p>
|
|
<p>Alternately, if the query and reference datasets are the same, the problem can be stated more simply: for each point in the dataset, we wish to know the <img class="formulaInl" alt="$k$" src="form_103.png"/> nearest points to that point.</p>
|
|
<p><b>mlpack</b> provides:</p>
|
|
<ul>
|
|
<li>a <a class="el" href="nstutorial.html#cli_nstut">simple command-line executable</a> to run nearest-neighbors search (and furthest-neighbors search)</li>
|
|
<li>a <a class="el" href="nstutorial.html#knn_nstut">simple C++ interface</a> to perform nearest-neighbors search (and furthest-neighbors search)</li>
|
|
<li>a <a class="el" href="nstutorial.html#neighborsearch_nstut">generic, extensible, and powerful C++ class (NeighborSearch)</a> for complex usage</li>
|
|
</ul>
|
|
<h1><a class="anchor" id="toc_nstut"></a>
|
|
Table of Contents</h1>
|
|
<p>A list of all the sections this tutorial contains.</p>
|
|
<ul>
|
|
<li><a class="el" href="nstutorial.html#intro_nstut">Introduction</a></li>
|
|
<li><a class="el" href="nstutorial.html#toc_nstut">Table of Contents</a></li>
|
|
<li><a class="el" href="nstutorial.html#cli_nstut">Command-Line 'mlpack_knn'</a><ul>
|
|
<li><a class="el" href="nstutorial.html#cli_ex1_nstut">One dataset, 5 nearest neighbors</a></li>
|
|
<li><a class="el" href="nstutorial.html#cli_ex2_nstut">Query and reference dataset, 10 nearest neighbors</a></li>
|
|
<li><a class="el" href="nstutorial.html#cli_ex3_nstut">One dataset, 3 nearest neighbors, leaf size of 15 points</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="nstutorial.html#knn_nstut">The 'KNN' class</a><ul>
|
|
<li><a class="el" href="nstutorial.html#knn_ex1_nstut">5 nearest neighbors on a single dataset</a></li>
|
|
<li><a class="el" href="nstutorial.html#knn_ex2_nstut">10 nearest neighbors on a query and reference dataset</a></li>
|
|
<li><a class="el" href="nstutorial.html#knn_ex3_nstut">Naive (exhaustive) search for 6 nearest neighbors on one dataset</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="nstutorial.html#neighborsearch_nstut">The extensible 'NeighborSearch' class</a><ul>
|
|
<li><a class="el" href="nstutorial.html#sort_policy_doc_nstut">SortPolicy policy class</a></li>
|
|
<li><a class="el" href="nstutorial.html#metric_type_doc_nstut">MetricType policy class</a></li>
|
|
<li><a class="el" href="nstutorial.html#mat_type_doc_nstut">MatType policy class</a></li>
|
|
<li><a class="el" href="nstutorial.html#tree_type_doc_nstut">TreeType policy class</a></li>
|
|
<li><a class="el" href="nstutorial.html#traverser_type_doc_nstut">TraverserType policy class</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="nstutorial.html#further_doc_nstut">Further documentation</a></li>
|
|
</ul>
|
|
<h1><a class="anchor" id="cli_nstut"></a>
|
|
Command-Line 'mlpack_knn'</h1>
|
|
<p>The simplest way to perform nearest-neighbors search in <b>mlpack</b> is to use the <code>mlpack_knn</code> executable. This program will perform nearest-neighbors search and place the resultant neighbors into one file and the resultant distances into another. The output files are organized such that the first row corresponds to the nearest neighbors of the first query point, with the first column corresponding to the nearest neighbor, and so forth.</p>
|
|
<p>Below are several examples of simple usage (and the resultant output). The <code>-v</code> option is used so that output is given. Further documentation on each individual option can be found by typing</p>
|
|
<div class="fragment"><div class="line">$ mlpack_knn --help</div></div><!-- fragment --><h2><a class="anchor" id="cli_ex1_nstut"></a>
|
|
One dataset, 5 nearest neighbors</h2>
|
|
<div class="fragment"><div class="line">$ mlpack_knn -r dataset.csv -n neighbors_out.csv -d distances_out.csv -k 5 -v</div><div class="line">[INFO ] Loading <span class="stringliteral">'dataset.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Loaded reference data from <span class="stringliteral">'dataset.csv'</span> (3 x 1000).</div><div class="line">[INFO ] Building reference tree...</div><div class="line">[INFO ] Tree built.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 5 nearest neighbors with dual-tree kd-tree search...</div><div class="line">[INFO ] 18412 node combinations were scored.</div><div class="line">[INFO ] 54543 base cases were calculated.</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'neighbors_out.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'distances_out.csv'</span>.</div><div class="line">[INFO ]</div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] distances_file: distances_out.csv</div><div class="line">[INFO ] help: <span class="keyword">false</span></div><div class="line">[INFO ] info: <span class="stringliteral">""</span></div><div class="line">[INFO ] input_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] k: 5</div><div class="line">[INFO ] leaf_size: 20</div><div class="line">[INFO ] naive: <span class="keyword">false</span></div><div class="line">[INFO ] neighbors_file: neighbors_out.csv</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] random_basis: <span class="keyword">false</span></div><div class="line">[INFO ] reference_file: dataset.csv</div><div class="line">[INFO ] seed: 0</div><div class="line">[INFO ] single_mode: <span class="keyword">false</span></div><div class="line">[INFO ] tree_type: kd</div><div class="line">[INFO ] verbose: <span class="keyword">true</span></div><div class="line">[INFO ] version: <span class="keyword">false</span></div><div class="line">[INFO ]</div><div class="line">[INFO ] Program timers:</div><div class="line">[INFO ] computing_neighbors: 0.108968s</div><div class="line">[INFO ] loading_data: 0.006495s</div><div class="line">[INFO ] saving_data: 0.003843s</div><div class="line">[INFO ] total_time: 0.126036s</div><div class="line">[INFO ] tree_building: 0.003442s</div></div><!-- fragment --><p>Convenient program timers are given for different parts of the calculation at the bottom of the output, as well as the parameters the simulation was run with. Now, if we look at the output files:</p>
|
|
<div class="fragment"><div class="line">$ head neighbors_out.csv</div><div class="line">862,344,224,43,885</div><div class="line">703,499,805,639,450</div><div class="line">867,472,972,380,601</div><div class="line">397,319,277,443,323</div><div class="line">840,827,865,38,438</div><div class="line">732,876,751,492,616</div><div class="line">563,222,569,985,940</div><div class="line">361,97,928,437,79</div><div class="line">547,695,419,961,716</div><div class="line">982,113,689,843,634</div><div class="line"></div><div class="line">$ head distances_out.csv</div><div class="line">5.986076164057e-02,7.664920518084e-02,1.116050961847e-01,1.155595474371e-01,1.169810085522e-01</div><div class="line">7.532635022982e-02,1.012564715841e-01,1.127846944644e-01,1.209584396720e-01,1.216543647014e-01</div><div class="line">7.659571546879e-02,1.014588981948e-01,1.025114621511e-01,1.128082429187e-01,1.131659758673e-01</div><div class="line">2.079405647909e-02,4.710724516732e-02,7.597622408419e-02,9.171977778898e-02,1.037033340864e-01</div><div class="line">7.082206779700e-02,9.002355499742e-02,1.044181406406e-01,1.093149568834e-01,1.139700558608e-01</div><div class="line">5.688056488896e-02,9.478072514474e-02,1.085637706630e-01,1.114177921451e-01,1.139370265105e-01</div><div class="line">7.882260880455e-02,9.454474078041e-02,9.724494179950e-02,1.023829575445e-01,1.066927013814e-01</div><div class="line">7.005321598247e-02,9.131417221561e-02,9.498248889074e-02,9.897964162308e-02,1.121202216165e-01</div><div class="line">5.295654132754e-02,5.509877761894e-02,8.108227366619e-02,9.785461174861e-02,1.043968140367e-01</div><div class="line">3.992859920333e-02,4.471418646159e-02,7.346053904990e-02,9.181982339584e-02,9.843075910782e-02</div></div><!-- fragment --><p>So, the nearest neighbor to point 0 is point 862, with a distance of 5.986076164057e-02. The second nearest neighbor to point 0 is point 344, with a distance of 7.664920518084e-02. The third nearest neighbor to point 5 is point 751, with a distance of 1.085637706630e-01.</p>
|
|
<h2><a class="anchor" id="cli_ex2_nstut"></a>
|
|
Query and reference dataset, 10 nearest neighbors</h2>
|
|
<div class="fragment"><div class="line">$ mlpack_knn -q query_dataset.csv -r reference_dataset.csv \</div><div class="line">> -n neighbors_out.csv -d distances_out.csv -k 10 -v</div><div class="line">[INFO ] Loading <span class="stringliteral">'reference_dataset.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Loaded reference data from <span class="stringliteral">'reference_dataset.csv'</span> (3 x 1000).</div><div class="line">[INFO ] Building reference tree...</div><div class="line">[INFO ] Tree built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'query_dataset.csv'</span> as CSV data. Size is 3 x 50.</div><div class="line">[INFO ] Loaded query data from <span class="stringliteral">'query_dataset.csv'</span> (3x50).</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 10 nearest neighbors with dual-tree kd-tree search...</div><div class="line">[INFO ] Building query tree...</div><div class="line">[INFO ] Tree built.</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'neighbors_out.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'distances_out.csv'</span>.</div><div class="line">[INFO ]</div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] distances_file: distances_out.csv</div><div class="line">[INFO ] help: <span class="keyword">false</span></div><div class="line">[INFO ] info: <span class="stringliteral">""</span></div><div class="line">[INFO ] input_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] k: 10</div><div class="line">[INFO ] leaf_size: 20</div><div class="line">[INFO ] naive: <span class="keyword">false</span></div><div class="line">[INFO ] neighbors_file: neighbors_out.csv</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: query_dataset.csv</div><div class="line">[INFO ] random_basis: <span class="keyword">false</span></div><div class="line">[INFO ] reference_file: reference_dataset.csv</div><div class="line">[INFO ] seed: 0</div><div class="line">[INFO ] single_mode: <span class="keyword">false</span></div><div class="line">[INFO ] tree_type: kd</div><div class="line">[INFO ] verbose: <span class="keyword">true</span></div><div class="line">[INFO ] version: <span class="keyword">false</span></div><div class="line">[INFO ]</div><div class="line">[INFO ] Program timers:</div><div class="line">[INFO ] computing_neighbors: 0.022589s</div><div class="line">[INFO ] loading_data: 0.003572s</div><div class="line">[INFO ] saving_data: 0.000755s</div><div class="line">[INFO ] total_time: 0.032197s</div><div class="line">[INFO ] tree_building: 0.002590s</div></div><!-- fragment --><h2><a class="anchor" id="cli_ex3_nstut"></a>
|
|
One dataset, 3 nearest neighbors, leaf size of 15 points</h2>
|
|
<div class="fragment"><div class="line">$ mlpack_knn -r dataset.csv -n neighbors_out.csv -d distances_out.csv -k 3 -l 15 -v</div><div class="line">[INFO ] Loading <span class="stringliteral">'dataset.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Loaded reference data from <span class="stringliteral">'dataset.csv'</span> (3 x 1000).</div><div class="line">[INFO ] Building reference tree...</div><div class="line">[INFO ] Tree built.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 3 nearest neighbors with dual-tree kd-tree search...</div><div class="line">[INFO ] 19692 node combinations were scored.</div><div class="line">[INFO ] 36263 base cases were calculated.</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'neighbors_out.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'distances_out.csv'</span>.</div><div class="line">[INFO ]</div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] distances_file: distances_out.csv</div><div class="line">[INFO ] help: <span class="keyword">false</span></div><div class="line">[INFO ] info: <span class="stringliteral">""</span></div><div class="line">[INFO ] input_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] k: 3</div><div class="line">[INFO ] leaf_size: 15</div><div class="line">[INFO ] naive: <span class="keyword">false</span></div><div class="line">[INFO ] neighbors_file: neighbors_out.csv</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] random_basis: <span class="keyword">false</span></div><div class="line">[INFO ] reference_file: dataset.csv</div><div class="line">[INFO ] seed: 0</div><div class="line">[INFO ] single_mode: <span class="keyword">false</span></div><div class="line">[INFO ] tree_type: kd</div><div class="line">[INFO ] verbose: <span class="keyword">true</span></div><div class="line">[INFO ] version: <span class="keyword">false</span></div><div class="line">[INFO ]</div><div class="line">[INFO ] Program timers:</div><div class="line">[INFO ] computing_neighbors: 0.059020s</div><div class="line">[INFO ] loading_data: 0.002791s</div><div class="line">[INFO ] saving_data: 0.002369s</div><div class="line">[INFO ] total_time: 0.069277s</div><div class="line">[INFO ] tree_building: 0.002713s</div></div><!-- fragment --><p>Further documentation on options should be found by using the –help option.</p>
|
|
<h1><a class="anchor" id="knn_nstut"></a>
|
|
The 'KNN' class</h1>
|
|
<p>The 'KNN' class is, specifically, a typedef of the more extensible NeighborSearch class, querying for nearest neighbors using the Euclidean distance.</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">typedef</span> NeighborSearch<NearestNeighborSort, metric::EuclideanDistance></div><div class="line"> <a class="code" href="namespacemlpack_1_1neighbor.html#aca865b778e506f60fd3bbcf2f34672e5">KNN</a>;</div></div><!-- fragment --><p>Using the KNN class is particularly simple; first, the object must be constructed and given a dataset. Then, the method is run, and two matrices are returned: one which holds the indices of the nearest neighbors, and one which holds the distances of the nearest neighbors. These are of the same structure as the output –neighbors_file and –distances_file for the CLI interface (see above). A handful of examples of simple usage of the KNN class are given below.</p>
|
|
<h2><a class="anchor" id="knn_ex1_nstut"></a>
|
|
5 nearest neighbors on a single dataset</h2>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="neighbor__search_8hpp.html">mlpack/methods/neighbor_search/neighbor_search.hpp</a>></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacemlpack_1_1neighbor.html">mlpack::neighbor</a>;</div><div class="line"></div><div class="line"><span class="comment">// Our dataset matrix, which is column-major.</span></div><div class="line"><span class="keyword">extern</span> arma::mat data;</div><div class="line"></div><div class="line">KNN a(data);</div><div class="line"></div><div class="line"><span class="comment">// The matrices we will store output in.</span></div><div class="line">arma::Mat<size_t> resultingNeighbors;</div><div class="line">arma::mat resultingDistances;</div><div class="line"></div><div class="line">a.Search(5, resultingNeighbors, resultingDistances);</div></div><!-- fragment --><p>The output of the search is stored in resultingNeighbors and resultingDistances.</p>
|
|
<h2><a class="anchor" id="knn_ex2_nstut"></a>
|
|
10 nearest neighbors on a query and reference dataset</h2>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="neighbor__search_8hpp.html">mlpack/methods/neighbor_search/neighbor_search.hpp</a>></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacemlpack_1_1neighbor.html">mlpack::neighbor</a>;</div><div class="line"></div><div class="line"><span class="comment">// Our dataset matrices, which are column-major.</span></div><div class="line"><span class="keyword">extern</span> arma::mat queryData, referenceData;</div><div class="line"></div><div class="line">KNN a(referenceData);</div><div class="line"></div><div class="line"><span class="comment">// The matrices we will store output in.</span></div><div class="line">arma::Mat<size_t> resultingNeighbors;</div><div class="line">arma::mat resultingDistances;</div><div class="line"></div><div class="line">a.Search(queryData, 10, resultingNeighbors, resultingDistances);</div></div><!-- fragment --><h2><a class="anchor" id="knn_ex3_nstut"></a>
|
|
Naive (exhaustive) search for 6 nearest neighbors on one dataset</h2>
|
|
<p>This example uses the O(n^2) naive search (not the tree-based search).</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="neighbor__search_8hpp.html">mlpack/methods/neighbor_search/neighbor_search.hpp</a>></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacemlpack_1_1neighbor.html">mlpack::neighbor</a>;</div><div class="line"></div><div class="line"><span class="comment">// Our dataset matrix, which is column-major.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"></div><div class="line">KNN a(dataset, <span class="keyword">true</span>);</div><div class="line"></div><div class="line"><span class="comment">// The matrices we will store output in.</span></div><div class="line">arma::Mat<size_t> resultingNeighbors;</div><div class="line">arma::mat resultingDistances;</div><div class="line"></div><div class="line">a.Search(6, resultingNeighbors, resultingDistances);</div></div><!-- fragment --><p>Needless to say, naive search can be very slow...</p>
|
|
<h1><a class="anchor" id="neighborsearch_nstut"></a>
|
|
The extensible 'NeighborSearch' class</h1>
|
|
<p>The NeighborSearch class is very extensible, having the following template arguments:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">template</span><</div><div class="line"> <span class="keyword">typename</span> SortPolicy = NearestNeighborSort,</div><div class="line"> <span class="keyword">typename</span> MetricType = <a class="code" href="namespacemlpack_1_1metric.html#a012695bde5dbf7ded7f7a180b5f3f512">mlpack::metric::EuclideanDistance</a>,</div><div class="line"> <span class="keyword">typename</span> MatType = arma::mat,</div><div class="line"> <span class="keyword">template</span><<span class="keyword">typename</span> TreeMetricType,</div><div class="line"> <span class="keyword">typename</span> TreeStatType,</div><div class="line"> <span class="keyword">typename</span> TreeMatType> <span class="keyword">class </span>TreeType = <a class="code" href="namespacemlpack_1_1tree.html#a562474c3dca60a6ac3c5168ae88bc028">tree::KDTree</a>,</div><div class="line"> <span class="keyword">template</span><<span class="keyword">typename</span> RuleType> <span class="keyword">class </span>TraversalType =</div><div class="line"> TreeType<MetricType, NeighborSearchStat<SortPolicy>,</div><div class="line"> MatType>::template DualTreeTraverser></div><div class="line">></div><div class="line"><span class="keyword">class </span>NeighborSearch;</div></div><!-- fragment --><p>By choosing different components for each of these template classes, a very 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.</p>
|
|
<h2><a class="anchor" id="sort_policy_doc_nstut"></a>
|
|
SortPolicy policy class</h2>
|
|
<p>The SortPolicy template parameter allows specification of how the NeighborSearch object will decide which points are to be searched for. The <a class="el" href="classmlpack_1_1neighbor_1_1NearestNeighborSort.html" title="This class implements the necessary methods for the SortPolicy template parameter of the NeighborSear...">mlpack::neighbor::NearestNeighborSort</a> class is a well-documented example. A custom SortPolicy class must implement the same methods which NearestNeighborSort does:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">size_t</span> SortDistance(<span class="keyword">const</span> arma::vec& list, <span class="keywordtype">double</span> newDistance);</div><div class="line"></div><div class="line"><span class="keyword">static</span> <span class="keywordtype">bool</span> IsBetter(<span class="keyword">const</span> <span class="keywordtype">double</span> value, <span class="keyword">const</span> <span class="keywordtype">double</span> ref);</div><div class="line"></div><div class="line"><span class="keyword">template</span><<span class="keyword">typename</span> TreeType></div><div class="line"><span class="keyword">static</span> <span class="keywordtype">double</span> BestNodeToNodeDistance(<span class="keyword">const</span> TreeType* queryNode,</div><div class="line"> <span class="keyword">const</span> TreeType* referenceNode);</div><div class="line"></div><div class="line"><span class="keyword">template</span><<span class="keyword">typename</span> TreeType></div><div class="line"><span class="keyword">static</span> <span class="keywordtype">double</span> BestPointToNodeDistance(<span class="keyword">const</span> arma::vec& queryPoint,</div><div class="line"> <span class="keyword">const</span> TreeType* referenceNode);</div><div class="line"></div><div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">double</span> WorstDistance();</div><div class="line"></div><div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">double</span> BestDistance();</div></div><!-- fragment --><p>The <a class="el" href="classmlpack_1_1neighbor_1_1FurthestNeighborSort.html" title="This class implements the necessary methods for the SortPolicy template parameter of the NeighborSear...">mlpack::neighbor::FurthestNeighborSort</a> class is another implementation, which is used to create the 'KFN' typedef class, which finds the furthest neighbors, as opposed to the nearest neighbors.</p>
|
|
<h2><a class="anchor" id="metric_type_doc_nstut"></a>
|
|
MetricType policy class</h2>
|
|
<p>The MetricType policy class allows the neighbor search to take place in any arbitrary metric space. The <a class="el" href="classmlpack_1_1metric_1_1LMetric.html" title="The L_p metric for arbitrary integer p, with an option to take the root. ">mlpack::metric::LMetric</a> class is a good example implementation. A MetricType class must provide the following functions:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Empty constructor is required.</span></div><div class="line">MetricType();</div><div class="line"></div><div class="line"><span class="comment">// Compute the distance between two points.</span></div><div class="line"><span class="keyword">template</span><<span class="keyword">typename</span> VecType></div><div class="line"><span class="keywordtype">double</span> Evaluate(<span class="keyword">const</span> VecType& a, <span class="keyword">const</span> VecType& b);</div></div><!-- fragment --><p>Internally, the NeighborSearch class keeps an instantiated MetricType class (which can be given in the constructor). This is useful for a metric like the Mahalanobis distance (<a class="el" href="classmlpack_1_1metric_1_1MahalanobisDistance.html" title="The Mahalanobis distance, which is essentially a stretched Euclidean distance. ">mlpack::metric::MahalanobisDistance</a>), which must store state (the covariance matrix). Therefore, you can write a non-static MetricType class and use it seamlessly with NeighborSearch.</p>
|
|
<p>For more information on the MetricType policy, see the documentation <a class="el" href="metrics.html">here</a>.</p>
|
|
<h2><a class="anchor" id="mat_type_doc_nstut"></a>
|
|
MatType policy class</h2>
|
|
<p>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 <code>arma::mat</code> and <code>arma::sp_mat</code>.</p>
|
|
<h2><a class="anchor" id="tree_type_doc_nstut"></a>
|
|
TreeType policy class</h2>
|
|
<p>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 <a class="el" href="trees.html">here</a>.</p>
|
|
<p>Typical choices might include <a class="el" href="namespacemlpack_1_1tree.html#a562474c3dca60a6ac3c5168ae88bc028" title="The standard midpoint-split kd-tree. ">mlpack::tree::KDTree</a>, <a class="el" href="namespacemlpack_1_1tree.html#abc9c69ba447c575b235eff25f14d99c7" title="A midpoint-split ball tree. ">mlpack::tree::BallTree</a>, <a class="el" href="namespacemlpack_1_1tree.html#a97bb6c0e6c1be359a95c89d21b1afd42" title="The standard cover tree, as detailed in the original cover tree paper: ">mlpack::tree::StandardCoverTree</a>, <a class="el" href="namespacemlpack_1_1tree.html#a1a47efe6afda858544988d1f7927477c" title="An implementation of the R tree that satisfies the TreeType policy API. ">mlpack::tree::RTree</a>, or <a class="el" href="namespacemlpack_1_1tree.html#a4e25f4921d1b4ca77a30bf82d5366da5" title="The R*-tree, a more recent variant of the R tree. ">mlpack::tree::RStarTree</a>. It is easily possible to make your own tree type for use with NeighborSearch; consult the <a class="el" href="trees.html">TreeType documentation</a> for more details.</p>
|
|
<p>An example of using the NeighborSearch class with a ball tree is given below.</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Construct a NeighborSearch object with ball bounds.</span></div><div class="line">NeighborSearch<</div><div class="line"> NearestNeighborSort,</div><div class="line"> <a class="code" href="namespacemlpack_1_1metric.html#a012695bde5dbf7ded7f7a180b5f3f512">metric::EuclideanDistance</a>,</div><div class="line"> arma::mat,</div><div class="line"> <a class="code" href="namespacemlpack_1_1tree.html#abc9c69ba447c575b235eff25f14d99c7">tree::BallTree</a></div><div class="line">> neighborSearch(dataset);</div></div><!-- fragment --><h2><a class="anchor" id="traverser_type_doc_nstut"></a>
|
|
TraverserType policy class</h2>
|
|
<p>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 <code>TreeType</code> (which is the member <code>TreeType::DualTreeTraverser</code>).</p>
|
|
<p>This class must implement the following two methods:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Instantiate with a given RuleType.</span></div><div class="line">TraverserType(RuleType& rule);</div><div class="line"></div><div class="line"><span class="comment">// Traverse with two trees.</span></div><div class="line"><span class="keywordtype">void</span> Traverse(TreeType& queryNode, TreeType& referenceNode);</div></div><!-- fragment --><p>The RuleType class provides the following functions for use in the traverser:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Evaluate the base case between two points.</span></div><div class="line"><span class="keywordtype">double</span> BaseCase(<span class="keyword">const</span> <span class="keywordtype">size_t</span> queryIndex, <span class="keyword">const</span> <span class="keywordtype">size_t</span> referenceIndex);</div><div class="line"></div><div class="line"><span class="comment">// Score the two nodes to see if they can be pruned, returning DBL_MAX if they</span></div><div class="line"><span class="comment">// can be pruned.</span></div><div class="line"><span class="keywordtype">double</span> Score(TreeType& queryNode, TreeType& referenceNode);</div></div><!-- fragment --><p>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".</p>
|
|
<h1><a class="anchor" id="further_doc_nstut"></a>
|
|
Further documentation</h1>
|
|
<p>For further documentation on the NeighborSearch class, consult the <a class="el" href="classmlpack_1_1neighbor_1_1NeighborSearch.html">complete API documentation</a>. </p>
|
|
</div></div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.11
|
|
</small></address>
|
|
</body>
|
|
<script type="text/javascript">
|
|
var x = document.getElementsByClassName("formulaDsp");
|
|
var i;
|
|
for (i = 0; i < x.length; i++)
|
|
{
|
|
x[i].width /= 4;
|
|
}
|
|
</script>
|
|
</html>
|