291 lines
68 KiB
HTML
291 lines
68 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: Approximate furthest neighbor search (mlpack_approx_kfn) tutorial</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">Approximate furthest neighbor search (mlpack_approx_kfn) tutorial </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><h1><a class="anchor" id="intro_akfntut"></a>
|
|
Introduction</h1>
|
|
<p><b>mlpack</b> implements multiple strategies for approximate furthest neighbor search in its <code>mlpack_approx_kfn</code> and <code>mlpack_kfn</code> programs (each program corresponds to different techniques). This tutorial discusses what problems these algorithms solve and how to use each of the techniques that <b>mlpack</b> implements.</p>
|
|
<p><b>mlpack</b> implements five approximate furthest neighbor search algorithms:</p>
|
|
<ul>
|
|
<li>brute-force search (in <code>mlpack_kfn</code>)</li>
|
|
<li>single-tree search (in <code>mlpack_kfn</code>)</li>
|
|
<li>dual-tree search (in <code>mlpack_kfn</code>)</li>
|
|
<li>query-dependent approximate furthest neighbor (QDAFN) (in <code>mlpack_approx_kfn</code>)</li>
|
|
<li>DrusillaSelect (in <code>mlpack_approx_kfn</code>)</li>
|
|
</ul>
|
|
<p>These methods are described in the following papers:</p>
|
|
<div class="fragment"><div class="line">@inproceedings{curtin2013tree,</div><div class="line"> title={Tree-Independent Dual-Tree Algorithms},</div><div class="line"> author={Curtin, Ryan R. and March, William B. and Ram, Parikshit and Anderson,</div><div class="line"> David V. and Gray, Alexander G. and Isbell Jr., Charles L.},</div><div class="line"> booktitle={Proceedings of The 30th International Conference on Machine</div><div class="line"> Learning (ICML <span class="stringliteral">'13)},</span></div><div class="line"><span class="stringliteral"> pages={1435--1443},</span></div><div class="line"><span class="stringliteral"> year={2013}</span></div><div class="line"><span class="stringliteral">}</span></div></div><!-- fragment --><div class="fragment"><div class="line">@incollection{pagh2015approximate,</div><div class="line"> title={Approximate furthest neighbor in high dimensions},</div><div class="line"> author={Pagh, Rasmus and Silvestri, Francesco and Sivertsen, Johan and Skala,</div><div class="line"> Matthew},</div><div class="line"> booktitle={Similarity Search and Applications},</div><div class="line"> pages={3--14},</div><div class="line"> year={2015},</div><div class="line"> publisher={Springer}</div><div class="line">}</div></div><!-- fragment --><div class="fragment"><div class="line">@incollection{curtin2016fast,</div><div class="line"> title={Fast approximate furthest neighbors with data-dependent candidate</div><div class="line"> selection},</div><div class="line"> author={Curtin, Ryan R., and Gardner, Andrew B.},</div><div class="line"> booktitle={Similarity Search and Applications},</div><div class="line"> pages={221--235},</div><div class="line"> year={2016},</div><div class="line"> publisher={Springer}</div><div class="line">}</div></div><!-- fragment --><p>The problem of furthest neighbor search is simple, and is the opposite of the much-more-studied nearest neighbor search problem. Given a set of reference points <img class="formulaInl" alt="$R$" src="form_101.png"/> (the set in which we are searching), and a set of query points <img class="formulaInl" alt="$Q$" src="form_102.png"/> (the set of points for which we want the furthest neighbor), our goal is to return the <img class="formulaInl" alt="$k$" src="form_103.png"/> furthest neighbors for each query point in <img class="formulaInl" alt="$Q$" src="form_102.png"/>:</p>
|
|
<p class="formulaDsp">
|
|
<img class="formulaDsp" alt="\[ \operatorname{k-argmax}_{p_r \in R} d(p_q, p_r). \]" src="form_104.png"/>
|
|
</p>
|
|
<p>In order to solve this problem, <b>mlpack</b> provides a number of interfaces.</p>
|
|
<ul>
|
|
<li>two <a class="el" href="akfntutorial.html#cli_akfntut">simple command-line executables</a> to calculate approximate furthest neighbors</li>
|
|
<li>a simple <a class="el" href="akfntutorial.html#cpp_qdafn_akfntut">C++ class for QDAFN</a></li>
|
|
<li>a simple <a class="el" href="akfntutorial.html#cpp_ds_akfntut">C++ class for DrusillaSelect</a></li>
|
|
<li>a simple C++ class for tree-based and brute-force search</li>
|
|
</ul>
|
|
<h1><a class="anchor" id="toc_akfntut"></a>
|
|
Table of Contents</h1>
|
|
<p>A list of all the sections this tutorial contains.</p>
|
|
<ul>
|
|
<li><a class="el" href="akfntutorial.html#intro_akfntut">Introduction</a></li>
|
|
<li><a class="el" href="akfntutorial.html#toc_akfntut">Table of Contents</a></li>
|
|
<li><a class="el" href="akfntutorial.html#which_akfntut">Which algorithm should be used?</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_akfntut">Command-line 'mlpack_approx_kfn' and 'mlpack_kfn'</a><ul>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex1_akfntut">Calculate 5 furthest neighbors with default options</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex2_akfntut">Specifying algorithm parameters for DrusillaSelect</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex3_akfntut">Using QDAFN instead of DrusillaSelect</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex4_akfntut">Printing results quality with exact distances</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex5_akfntut">Using cached exact distances for quality results</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex6_akfntut">Using tree-based approximation with mlpack_kfn</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex7_akfntut">Different algorithms with 'mlpack_kfn'</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_ex8_akfntut">Saving a model for later use</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cli_final_akfntut">Final command-line program notes</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ds_akfntut">DrusillaSelect C++ class</a><ul>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex1_ds_akfntut">Approximate furthest neighbors with defaults</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex2_ds_akfntut">Custom numbers of tables and projections</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex3_ds_akfntut">Accessing the candidate set</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex4_ds_akfntut">Retraining on a new reference set</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex5_ds_akfntut">Running on sparse data</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_qdafn_akfntut">QDAFN C++ class</a><ul>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex1_qdafn_akfntut">Approximate furthest neighbors with defaults</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex2_qdafn_akfntut">Custom numbers of tables and projections</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex3_qdafn_akfntut">Accessing the candidate set</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex4_qdafn_akfntut">Retraining on a new reference set</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex5_qdafn_akfntut">Running on sparse data</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ns_akfntut">KFN C++ class</a><ul>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex1_ns_akfntut">Simple furthest neighbors example</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex2_ns_akfntut">Retraining on a new reference set</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex3_ns_akfntut">Searching in single-tree mode</a></li>
|
|
<li><a class="el" href="akfntutorial.html#cpp_ex4_ns_akfntut">Searching in brute-force mode</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="el" href="akfntutorial.html#further_doc_akfntut">Further documentation</a></li>
|
|
</ul>
|
|
<h1><a class="anchor" id="which_akfntut"></a>
|
|
Which algorithm should be used?</h1>
|
|
<p>There are three algorithms for furthest neighbor search that <b>mlpack</b> implements, and each is suited to a different setting. Below is some basic guidance on what should be used. Note that the question of "which algorithm
|
|
should be used" is a very difficult question to answer, so the guidance below is just that—guidance—and may not be right for a particular problem.</p>
|
|
<ul>
|
|
<li><code>DrusillaSelect</code> is very fast and will perform extremely well for datasets with outliers or datasets with structure (like low-dimensional datasets embedded in high dimensions)</li>
|
|
<li><code>QDAFN</code> is a random approach and therefore should be well-suited for datasets with little to no structure</li>
|
|
<li>The tree-based approaches (the <code>KFN</code> class and the <code>mlpack_kfn</code> program) is best suited for low-dimensional datasets, and is most effective when very small levels of approximation are desired, or when exact results are desired.</li>
|
|
<li>Dual-tree search is most useful when the query set is large and structured (like for all-furthest-neighbor search).</li>
|
|
<li>Single-tree search is more useful when the query set is small.</li>
|
|
</ul>
|
|
<h1><a class="anchor" id="cli_akfntut"></a>
|
|
Command-line 'mlpack_approx_kfn' and 'mlpack_kfn'</h1>
|
|
<p><b>mlpack</b> provides two command-line programs to solve approximate furthest neighbor search:</p>
|
|
<ul>
|
|
<li><code>mlpack_approx_kfn</code>, for the QDAFN and DrusillaSelect approaches</li>
|
|
<li><code>mlpack_kfn</code>, for exact and approximate tree-based approaches</li>
|
|
</ul>
|
|
<p>These two programs allow a large number of algorithms to be used to find approximate furthest neighbors. Note that the <code>mlpack_kfn</code> program is also documented by the <a class="el" href="nstutorial.html#cli_nstut">Command-Line 'mlpack_knn'</a> section of the <a class="el" href="nstutorial.html">NeighborSearch tutorial (k-nearest-neighbors)</a> page, as it shares options with the <code>mlpack_knn</code> program.</p>
|
|
<p>Below are several examples of how the <code>mlpack_approx_kfn</code> and <code>mlpack_kfn</code> programs might be used. The first examples focus on the <code>mlpack_approx_kfn</code> program, and the last few show how <code>mlpack_kfn</code> can be used to produce approximate results.</p>
|
|
<h2><a class="anchor" id="cli_ex1_akfntut"></a>
|
|
Calculate 5 furthest neighbors with default options</h2>
|
|
<p>Here we have a query dataset <code>queries.csv</code> and a reference dataset <code>refs.csv</code> and we wish to find the 5 furthest neighbors of every query point in the reference dataset. We may do that with the <code>mlpack_approx_kfn</code> algorithm, using the default of the <code>DrusillaSelect</code> algorithm with default parameters.</p>
|
|
<div class="fragment"><div class="line">$ mlpack_approx_kfn -q queries.csv -r refs.csv -v -k 5 -n n.csv -d d.csv</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Building DrusillaSelect model...</div><div class="line">[INFO ] Model built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 5 furthest neighbors with DrusillaSelect...</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'n.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'d.csv'</span>.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: ds</div><div class="line">[INFO ] calculate_error: <span class="keyword">false</span></div><div class="line">[INFO ] distances_file: d.csv</div><div class="line">[INFO ] exact_distances_file: <span class="stringliteral">""</span></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 ] neighbors_file: n.csv</div><div class="line">[INFO ] num_projections: 5</div><div class="line">[INFO ] num_tables: 5</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] reference_file: refs.csv</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 ] drusilla_select_construct: 0.000342s</div><div class="line">[INFO ] drusilla_select_search: 0.000780s</div><div class="line">[INFO ] loading_data: 0.010689s</div><div class="line">[INFO ] saving_data: 0.005585s</div><div class="line">[INFO ] total_time: 0.018592s</div></div><!-- fragment --><p>Convenient timers for parts of the program operation are printed. The results, saved in <code>n.csv</code> and <code>d.csv</code>, indicate the furthest neighbors and distances for each query point. The row of the output file indicates the query point that the results are for. The neighbors are listed from furthest to nearest; so, the 4th element in the 3rd row of <code>d.csv</code> indicates the distance between the 3rd query point in <code>queries.csv</code> and its approximate 4th furthest neighbor. Similarly, the same element in <code>n.csv</code> indicates the index of the approximate 4th furthest neighbor (with respect to <code>refs.csv</code>).</p>
|
|
<h2><a class="anchor" id="cli_ex2_akfntut"></a>
|
|
Specifying algorithm parameters for DrusillaSelect</h2>
|
|
<p>The <code>-p</code> (<code>–num_projections</code>) and <code>-t</code> (<code>–num_tables</code>) parameters affect the running of the <code>DrusillaSelect</code> algorithm and the QDAFN algorithm. Specifically, larger values for each of these parameters will search more possible candidate furthest neighbors and produce better results (at the cost of runtime). More details on how each of these parameters works is available in the original papers, the <b>mlpack</b> source, or the documentation given by <code>–help</code>.</p>
|
|
<p>In the example below, we run <code>DrusillaSelect</code> to find 4 furthest neighbors using 10 tables and 2 points in each table. In this case we have chosen to omit the <code>-n</code> <code>n.csv</code> option, meaning that only the output candidate distances will be written to <code>d.csv</code>.</p>
|
|
<div class="fragment"><div class="line">$ mlpack_approx_kfn -q queries.csv -r refs.csv -v -k 4 -n n.csv -d d.csv -t 10 -p 2</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Building DrusillaSelect model...</div><div class="line">[INFO ] Model built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 4 furthest neighbors with DrusillaSelect...</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'n.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'d.csv'</span>.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: ds</div><div class="line">[INFO ] calculate_error: <span class="keyword">false</span></div><div class="line">[INFO ] distances_file: d.csv</div><div class="line">[INFO ] exact_distances_file: <span class="stringliteral">""</span></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: 4</div><div class="line">[INFO ] neighbors_file: n.csv</div><div class="line">[INFO ] num_projections: 2</div><div class="line">[INFO ] num_tables: 10</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] reference_file: refs.csv</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 ] drusilla_select_construct: 0.000645s</div><div class="line">[INFO ] drusilla_select_search: 0.000551s</div><div class="line">[INFO ] loading_data: 0.008518s</div><div class="line">[INFO ] saving_data: 0.003734s</div><div class="line">[INFO ] total_time: 0.014019s</div></div><!-- fragment --><h2><a class="anchor" id="cli_ex3_akfntut"></a>
|
|
Using QDAFN instead of DrusillaSelect</h2>
|
|
<p>The algorithm to be used for approximate furthest neighbor search can be specified with the <code>–algorithm</code> (<code>-a</code>) option to the <code>mlpack_approx_kfn</code> program. Below, we use the QDAFN algorithm instead of the default. We leave the <code>-p</code> and <code>-t</code> options at their defaults—even though QDAFN often requires more tables and points to get the same quality of results.</p>
|
|
<div class="fragment"><div class="line">$ mlpack_approx_kfn -q queries.csv -r refs.csv -v -k 3 -n n.csv -d d.csv -a qdafn</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Building QDAFN model...</div><div class="line">[INFO ] Model built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 3 furthest neighbors with QDAFN...</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'n.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'d.csv'</span>.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: qdafn</div><div class="line">[INFO ] calculate_error: <span class="keyword">false</span></div><div class="line">[INFO ] distances_file: d.csv</div><div class="line">[INFO ] exact_distances_file: <span class="stringliteral">""</span></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 ] neighbors_file: n.csv</div><div class="line">[INFO ] num_projections: 5</div><div class="line">[INFO ] num_tables: 5</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] reference_file: refs.csv</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 ] loading_data: 0.008380s</div><div class="line">[INFO ] qdafn_construct: 0.003399s</div><div class="line">[INFO ] qdafn_search: 0.000886s</div><div class="line">[INFO ] saving_data: 0.002253s</div><div class="line">[INFO ] total_time: 0.015465s</div></div><!-- fragment --><h2><a class="anchor" id="cli_ex4_akfntut"></a>
|
|
Printing results quality with exact distances</h2>
|
|
<p>The <code>mlpack_approx_kfn</code> program can calculate the quality of the results if the <code>–calculate_error</code> (<code>-e</code>) flag is specified. Below we use the program with its default parameters and calculate the error, which is displayed in the output. The error is only calculated for the furthest neighbor, not all k; therefore, in this example we have set <code>-k</code> to <code>1</code>.</p>
|
|
<div class="fragment"><div class="line">$ mlpack_approx_kfn -q queries.csv -r refs.csv -v -k 1 -e -q -n n.csv</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Building DrusillaSelect model...</div><div class="line">[INFO ] Model built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 1 furthest neighbors with DrusillaSelect...</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Calculating exact distances...</div><div class="line">[INFO ] 28891 node combinations were scored.</div><div class="line">[INFO ] 37735 base cases were calculated.</div><div class="line">[INFO ] Calculation complete.</div><div class="line">[INFO ] Average error: 1.08417.</div><div class="line">[INFO ] Maximum error: 1.28712.</div><div class="line">[INFO ] Minimum error: 1.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: ds</div><div class="line">[INFO ] calculate_error: <span class="keyword">true</span></div><div class="line">[INFO ] distances_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] exact_distances_file: <span class="stringliteral">""</span></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 ] neighbors_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] num_projections: 5</div><div class="line">[INFO ] num_tables: 5</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] reference_file: refs.csv</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.001476s</div><div class="line">[INFO ] drusilla_select_construct: 0.000309s</div><div class="line">[INFO ] drusilla_select_search: 0.000495s</div><div class="line">[INFO ] loading_data: 0.008462s</div><div class="line">[INFO ] total_time: 0.011670s</div><div class="line">[INFO ] tree_building: 0.000202s</div></div><!-- fragment --><p>Note that the output includes three lines indicating the error:</p>
|
|
<div class="fragment"><div class="line">[INFO ] Average error: 1.08417.</div><div class="line">[INFO ] Maximum error: 1.28712.</div><div class="line">[INFO ] Minimum error: 1.</div></div><!-- fragment --><p>In this case, a minimum error of 1 indicates an exact result, and over the entire query set the algorithm has returned a furthest neighbor candidate with maximum error 1.28712.</p>
|
|
<h2><a class="anchor" id="cli_ex5_akfntut"></a>
|
|
Using cached exact distances for quality results</h2>
|
|
<p>However, for large datasets, calculating the error may take a long time, because the exact furthest neighbors must be calculated. Therefore, if the exact furthest neighbor distances are already known, they may be passed in with the <code>–exact_distances_file</code> (<code>-x</code>) option in order to avoid the calculation. In the example below, we assume <code>exact.csv</code> contains the exact furthest neighbor distances. We run the <code>qdafn</code> algorithm in this example.</p>
|
|
<p>Note that the <code>-e</code> option must be specified for the <code>-x</code> option have any effect.</p>
|
|
<div class="fragment"><div class="line">$ mlpack_approx_kfn -q queries.csv -r refs.csv -k 1 -e -x exact.csv -n n.csv -v -a qdafn</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Building QDAFN model...</div><div class="line">[INFO ] Model built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 1 furthest neighbors with QDAFN...</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Loading <span class="stringliteral">'exact.csv'</span> as raw ASCII formatted data. Size is 1 x 1000.</div><div class="line">[INFO ] Average error: 1.06914.</div><div class="line">[INFO ] Maximum error: 1.67407.</div><div class="line">[INFO ] Minimum error: 1.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'n.csv'</span>.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: qdafn</div><div class="line">[INFO ] calculate_error: <span class="keyword">true</span></div><div class="line">[INFO ] distances_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] exact_distances_file: exact.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: 1</div><div class="line">[INFO ] neighbors_file: n.csv</div><div class="line">[INFO ] num_projections: 5</div><div class="line">[INFO ] num_tables: 5</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] reference_file: refs.csv</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 ] loading_data: 0.010348s</div><div class="line">[INFO ] qdafn_construct: 0.000318s</div><div class="line">[INFO ] qdafn_search: 0.000793s</div><div class="line">[INFO ] saving_data: 0.000259s</div><div class="line">[INFO ] total_time: 0.012254s</div></div><!-- fragment --><h2><a class="anchor" id="cli_ex6_akfntut"></a>
|
|
Using tree-based approximation with mlpack_kfn</h2>
|
|
<p>The <code>mlpack_kfn</code> algorithm allows specifying a desired approximation level with the <code>–epsilon</code> (<code>-e</code>) option. The parameter must be greater than or equal to 0 and less than 1. A setting of 0 indicates exact search.</p>
|
|
<p>The example below runs dual-tree furthest neighbor search (the default algorithm) with the approximation parameter set to 0.5.</p>
|
|
<div class="fragment"><div class="line">$ mlpack_kfn -q queries.csv -r refs.csv -v -k 3 -e 0.5 -n n.csv -d d.csv</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Loaded reference data from <span class="stringliteral">'refs.csv'</span> (3x1000).</div><div class="line">[INFO ] Building reference tree...</div><div class="line">[INFO ] Tree built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Loaded query data from <span class="stringliteral">'queries.csv'</span> (3x1000).</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 3 neighbors with dual-tree kd-tree search...</div><div class="line">[INFO ] 1611 node combinations were scored.</div><div class="line">[INFO ] 13938 base cases were calculated.</div><div class="line">[INFO ] 1611 node combinations were scored.</div><div class="line">[INFO ] 13938 base cases were calculated.</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'n.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'d.csv'</span>.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: dual_tree</div><div class="line">[INFO ] distances_file: d.csv</div><div class="line">[INFO ] epsilon: 0.5</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: 20</div><div class="line">[INFO ] naive: <span class="keyword">false</span></div><div class="line">[INFO ] neighbors_file: n.csv</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] percentage: 1</div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] random_basis: <span class="keyword">false</span></div><div class="line">[INFO ] reference_file: refs.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 ] true_distances_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] true_neighbors_file: <span class="stringliteral">""</span></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.000442s</div><div class="line">[INFO ] loading_data: 0.008060s</div><div class="line">[INFO ] saving_data: 0.002850s</div><div class="line">[INFO ] total_time: 0.012667s</div><div class="line">[INFO ] tree_building: 0.000251s</div></div><!-- fragment --><p>Note that the format of the output files <code>d.csv</code> and <code>n.csv</code> are the same as for <code>mlpack_approx_kfn</code>.</p>
|
|
<h2><a class="anchor" id="cli_ex7_akfntut"></a>
|
|
Different algorithms with 'mlpack_kfn'</h2>
|
|
<p>The <code>mlpack_kfn</code> program offers a large number of different algorithms that can be used. The <code>–algorithm</code> (<code>-a</code>) may be used to specify three main different algorithm types: <code>naive</code> (brute-force search), <code>single_tree</code> (single-tree search), <code>dual_tree</code> (dual-tree search, the default), and <code>greedy</code> ("defeatist" greedy search, which goes to one leaf node of the tree then terminates). The example below uses single-tree search to find approximate neighbors with epsilon set to 0.1.</p>
|
|
<div class="fragment"><div class="line">mlpack_kfn -q queries.csv -r refs.csv -v -k 3 -e 0.1 -n n.csv -d d.csv -a single_tree</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Loaded reference data from <span class="stringliteral">'refs.csv'</span> (3x1000).</div><div class="line">[INFO ] Building reference tree...</div><div class="line">[INFO ] Tree built.</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Loaded query data from <span class="stringliteral">'queries.csv'</span> (3x1000).</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 3 neighbors with single-tree kd-tree search...</div><div class="line">[INFO ] 13240 node combinations were scored.</div><div class="line">[INFO ] 15924 base cases were calculated.</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'n.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'d.csv'</span>.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: single_tree</div><div class="line">[INFO ] distances_file: d.csv</div><div class="line">[INFO ] epsilon: 0.1</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: 20</div><div class="line">[INFO ] naive: <span class="keyword">false</span></div><div class="line">[INFO ] neighbors_file: n.csv</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] percentage: 1</div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] random_basis: <span class="keyword">false</span></div><div class="line">[INFO ] reference_file: refs.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 ] true_distances_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] true_neighbors_file: <span class="stringliteral">""</span></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.000850s</div><div class="line">[INFO ] loading_data: 0.007858s</div><div class="line">[INFO ] saving_data: 0.003445s</div><div class="line">[INFO ] total_time: 0.013084s</div><div class="line">[INFO ] tree_building: 0.000250s</div></div><!-- fragment --><h2><a class="anchor" id="cli_ex8_akfntut"></a>
|
|
Saving a model for later use</h2>
|
|
<p>The <code>mlpack_approx_kfn</code> and <code>mlpack_kfn</code> programs both allow models to be saved and loaded for future use. The <code>–output_model_file</code> (<code>-M</code>) option allows specifying where to save a model, and the <code>–input_model_file</code> (<code>-m</code>) option allows a model to be loaded instead of trained. So, if you specify <code>–input_model_file</code> then you do not need to specify <code>–reference_file</code> (<code>-r</code>), <code>–num_projections</code> (<code>-p</code>), or <code>–num_tables</code> (<code>-t</code>).</p>
|
|
<p>The example below saves a model with 10 projections and 5 tables. Note that neither <code>–query_file</code> (<code>-q</code>) nor <code>-k</code> are specified; this run only builds the model and saves it to <code>model.bin</code>.</p>
|
|
<div class="fragment"><div class="line">$ mlpack_approx_kfn -r refs.csv -t 5 -p 10 -v -M model.bin</div><div class="line">[INFO ] Loading <span class="stringliteral">'refs.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Building DrusillaSelect model...</div><div class="line">[INFO ] Model built.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: ds</div><div class="line">[INFO ] calculate_error: <span class="keyword">false</span></div><div class="line">[INFO ] distances_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] exact_distances_file: <span class="stringliteral">""</span></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: 0</div><div class="line">[INFO ] neighbors_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] num_projections: 10</div><div class="line">[INFO ] num_tables: 5</div><div class="line">[INFO ] output_model_file: model.bin</div><div class="line">[INFO ] query_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] reference_file: refs.csv</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 ] drusilla_select_construct: 0.000321s</div><div class="line">[INFO ] loading_data: 0.004700s</div><div class="line">[INFO ] total_time: 0.007320s</div></div><!-- fragment --><p>Now, with the model saved, we can run approximate furthest neighbor search on a query set using the saved model:</p>
|
|
<div class="fragment"><div class="line">$ mlpack_approx_kfn -m model.bin -q queries.csv -k 3 -d d.csv -n n.csv -v</div><div class="line">[INFO ] Loading <span class="stringliteral">'queries.csv'</span> as CSV data. Size is 3 x 1000.</div><div class="line">[INFO ] Searching <span class="keywordflow">for</span> 3 furthest neighbors with DrusillaSelect...</div><div class="line">[INFO ] Search complete.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'n.csv'</span>.</div><div class="line">[INFO ] Saving CSV data to <span class="stringliteral">'d.csv'</span>.</div><div class="line">[INFO ] </div><div class="line">[INFO ] Execution parameters:</div><div class="line">[INFO ] algorithm: ds</div><div class="line">[INFO ] calculate_error: <span class="keyword">false</span></div><div class="line">[INFO ] distances_file: d.csv</div><div class="line">[INFO ] exact_distances_file: <span class="stringliteral">""</span></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: model.bin</div><div class="line">[INFO ] k: 3</div><div class="line">[INFO ] neighbors_file: n.csv</div><div class="line">[INFO ] num_projections: 5</div><div class="line">[INFO ] num_tables: 5</div><div class="line">[INFO ] output_model_file: <span class="stringliteral">""</span></div><div class="line">[INFO ] query_file: queries.csv</div><div class="line">[INFO ] reference_file: <span class="stringliteral">""</span></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 ] drusilla_select_search: 0.000878s</div><div class="line">[INFO ] loading_data: 0.004599s</div><div class="line">[INFO ] saving_data: 0.003006s</div><div class="line">[INFO ] total_time: 0.009234s</div></div><!-- fragment --><p>These options work in the same way for both the <code>mlpack_approx_kfn</code> and <code>mlpack_kfn</code> programs.</p>
|
|
<h2><a class="anchor" id="cli_final_akfntut"></a>
|
|
Final command-line program notes</h2>
|
|
<p>Both the <code>mlpack_kfn</code> and <code>mlpack_approx_kfn</code> programs contain numerous options not fully documented in these short examples. You can run each program with the <code>–help</code> (<code>-h</code>) option for more information.</p>
|
|
<h1><a class="anchor" id="cpp_ds_akfntut"></a>
|
|
DrusillaSelect C++ class</h1>
|
|
<p><b>mlpack</b> provides a simple <code>DrusillaSelect</code> C++ class that can be used inside of C++ programs to perform approximate furthest neighbor search. The class has only one template parameter—<code>MatType—which</code> specifies the type of matrix to be use. That means the class can be used with either dense data (of type <code>arma::mat</code>) or sparse data (of type <code>arma::sp_mat</code>).</p>
|
|
<p>The following examples show simple usage of this class.</p>
|
|
<h2><a class="anchor" id="cpp_ex1_ds_akfntut"></a>
|
|
Approximate furthest neighbors with defaults</h2>
|
|
<p>The code below builds a <code>DrusillaSelect</code> model with default options on the matrix <code>dataset</code>, then queries for the approximate furthest neighbor of every point in the <code>queries</code> matrix.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="drusilla__select_8hpp.html">mlpack/methods/approx_kfn/drusilla_select.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The query set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat queries;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with defaults.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1DrusillaSelect.html">DrusillaSelect<></a> ds(dataset);</div><div class="line"></div><div class="line"><span class="comment">// Query the model, putting output into the following two matrices.</span></div><div class="line">arma::mat distances;</div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">ds.Search(queries, 1, neighbors, distances);</div></div><!-- fragment --><p>At the end of this code, both the <code>distances</code> and <code>neighbors</code> matrices will have number of columns equal to the number of columns in the <code>queries</code> matrix. So, each column of the <code>distances</code> and <code>neighbors</code> matrices are the distances or neighbors of the corresponding column in the <code>queries</code> matrix.</p>
|
|
<h2><a class="anchor" id="cpp_ex2_ds_akfntut"></a>
|
|
Custom numbers of tables and projections</h2>
|
|
<p>The following example constructs a DrusillaSelect model with 10 tables and 5 projections. Once that is done it performs the same task as the previous example.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="drusilla__select_8hpp.html">mlpack/methods/approx_kfn/drusilla_select.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The query set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat queries;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with custom parameters.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1DrusillaSelect.html">DrusillaSelect<></a> ds(dataset, 10, 5);</div><div class="line"></div><div class="line"><span class="comment">// Query the model, putting output into the following two matrices.</span></div><div class="line">arma::mat distances;</div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">ds.Search(queries, 1, neighbors, distances);</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex3_ds_akfntut"></a>
|
|
Accessing the candidate set</h2>
|
|
<p>The <code>DrusillaSelect</code> algorithm merely scans the reference set and extracts a number of points that will be queried in a brute-force fashion when the <code>Search()</code> method is called. We can access this set with the <code>CandidateSet()</code> method. The code below prints the fifth point of the candidate set.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="drusilla__select_8hpp.html">mlpack/methods/approx_kfn/drusilla_select.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with custom parameters.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1DrusillaSelect.html">DrusillaSelect<></a> ds(dataset, 10, 5);</div><div class="line"></div><div class="line"><span class="comment">// Print the fifth point of the candidate set.</span></div><div class="line">std::cout << ds.CandidateSet().col(4).t();</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex4_ds_akfntut"></a>
|
|
Retraining on a new reference set</h2>
|
|
<p>It is possible to retrain a <code>DrusillaSelect</code> model with new parameters or with a new reference set. This is functionally equivalent to creating a new model. The example code below creates a first <code>DrusillaSelect</code> model using 3 tables and 10 projections, and then retrains this with the same reference set using 10 tables and 3 projections.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="drusilla__select_8hpp.html">mlpack/methods/approx_kfn/drusilla_select.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with initial parameters.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1DrusillaSelect.html">DrusillaSelect<></a> ds(dataset, 3, 10);</div><div class="line"></div><div class="line"><span class="comment">// Now retrain with different parameters.</span></div><div class="line">ds.Train(dataset, 10, 3);</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex5_ds_akfntut"></a>
|
|
Running on sparse data</h2>
|
|
<p>We can set the template parameter for <code>DrusillaSelect</code> to <code>arma::sp_mat</code> in order to perform furthest neighbor search on sparse data. This code below creates a <code>DrusillaSelect</code> model using 4 tables and 6 projections with sparse input data, then searches for 3 approximate furthest neighbors.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="drusilla__select_8hpp.html">mlpack/methods/approx_kfn/drusilla_select.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::sp_mat dataset;</div><div class="line"><span class="comment">// The query dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::sp_mat querySet;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model on sparse data.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1DrusillaSelect.html">DrusillaSelect<arma::sp_mat></a> ds(dataset, 4, 6);</div><div class="line"></div><div class="line"><span class="comment">// Search on query data.</span></div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">arma::mat distances;</div><div class="line">ds.Search(querySet, 3, neighbors, distances);</div></div><!-- fragment --><h1><a class="anchor" id="cpp_qdafn_akfntut"></a>
|
|
QDAFN C++ class</h1>
|
|
<p><b>mlpack</b> also provides a standalone simple <code>QDAFN</code> class for furthest neighbor search. The API for this class is virtually identical to the <code>DrusillaSelect</code> class, and also has one template parameter to specify the type of matrix to be used (dense or sparse or other).</p>
|
|
<p>The following subsections demonstrate usage of the <code>QDAFN</code> class in the same way as the previous section's examples for <code>DrusillaSelect</code>.</p>
|
|
<h2><a class="anchor" id="cpp_ex1_qdafn_akfntut"></a>
|
|
Approximate furthest neighbors with defaults</h2>
|
|
<p>The code below builds a <code>QDAFN</code> model with default options on the matrix <code>dataset</code>, then queries for the approximate furthest neighbor of every point in the <code>queries</code> matrix.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="qdafn_8hpp.html">mlpack/methods/approx_kfn/qdafn.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The query set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat queries;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with defaults.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1QDAFN.html">QDAFN<></a> qd(dataset);</div><div class="line"></div><div class="line"><span class="comment">// Query the model, putting output into the following two matrices.</span></div><div class="line">arma::mat distances;</div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">qd.Search(queries, 1, neighbors, distances);</div></div><!-- fragment --><p>At the end of this code, both the <code>distances</code> and <code>neighbors</code> matrices will have number of columns equal to the number of columns in the <code>queries</code> matrix. So, each column of the <code>distances</code> and <code>neighbors</code> matrices are the distances or neighbors of the corresponding column in the <code>queries</code> matrix.</p>
|
|
<h2><a class="anchor" id="cpp_ex2_qdafn_akfntut"></a>
|
|
Custom numbers of tables and projections</h2>
|
|
<p>The following example constructs a QDAFN model with 15 tables and 30 projections. Once that is done it performs the same task as the previous example.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="qdafn_8hpp.html">mlpack/methods/approx_kfn/qdafn.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The query set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat queries;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with custom parameters.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1QDAFN.html">QDAFN<></a> qdafn(dataset, 15, 30);</div><div class="line"></div><div class="line"><span class="comment">// Query the model, putting output into the following two matrices.</span></div><div class="line">arma::mat distances;</div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">qdafn.Search(queries, 1, neighbors, distances);</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex3_qdafn_akfntut"></a>
|
|
Accessing the candidate set</h2>
|
|
<p>The <code>QDAFN</code> algorithm scans the reference set, extracting points that have been projected onto random directions. Each random direction corresponds to a single table. The <code>QDAFN</code> class stores these points as a vector of matrices, which can be accessed with the <code>CandidateSet()</code> method. The code below prints the fifth point of the candidate set of the third table.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="qdafn_8hpp.html">mlpack/methods/approx_kfn/qdafn.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with custom parameters.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1QDAFN.html">QDAFN<></a> qdafn(dataset, 10, 5);</div><div class="line"></div><div class="line"><span class="comment">// Print the fifth point of the candidate set.</span></div><div class="line">std::cout << ds.CandidateSet(2).col(4).t();</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex4_qdafn_akfntut"></a>
|
|
Retraining on a new reference set</h2>
|
|
<p>It is possible to retrain a <code>QDAFN</code> model with new parameters or with a new reference set. This is functionally equivalent to creating a new model. The example code below creates a first <code>QDAFN</code> model using 10 tables and 40 projections, and then retrains this with the same reference set using 15 tables and 25 projections.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="qdafn_8hpp.html">mlpack/methods/approx_kfn/qdafn.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model with initial parameters.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1QDAFN.html">QDAFN<></a> qdafn(dataset, 3, 10);</div><div class="line"></div><div class="line"><span class="comment">// Now retrain with different parameters.</span></div><div class="line">qdafn.Train(dataset, 10, 3);</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex5_qdafn_akfntut"></a>
|
|
Running on sparse data</h2>
|
|
<p>We can set the template parameter for <code>QDAFN</code> to <code>arma::sp_mat</code> in order to perform furthest neighbor search on sparse data. This code below creates a <code>QDAFN</code> model using 20 tables and 60 projections with sparse input data, then searches for 3 approximate furthest neighbors.</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="qdafn_8hpp.html">mlpack/methods/approx_kfn/qdafn.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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::sp_mat dataset;</div><div class="line"><span class="comment">// The query dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::sp_mat querySet;</div><div class="line"></div><div class="line"><span class="comment">// Construct the model on sparse data.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1QDAFN.html">QDAFN<arma::sp_mat></a> qdafn(dataset, 20, 60);</div><div class="line"></div><div class="line"><span class="comment">// Search on query data.</span></div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">arma::mat distances;</div><div class="line">qdafn.Search(querySet, 3, neighbors, distances);</div></div><!-- fragment --><h1><a class="anchor" id="cpp_ns_akfntut"></a>
|
|
KFN C++ class</h1>
|
|
<p>The extensive <code>NeighborSearch</code> class also provides a way to search for approximate furthest neighbors using a different, tree-based technique. For full documentation on this class, see the <a class="el" href="nstutorial.html">NeighborSearch tutorial</a>. The <code>KFN</code> class is a convenient typedef of the <code>NeighborSearch</code> class that can be used to perform the furthest neighbors task with kd-trees.</p>
|
|
<p>In the following subsections, the <code>KFN</code> class is used in short code examples.</p>
|
|
<h2><a class="anchor" id="cpp_ex1_ns_akfntut"></a>
|
|
Simple furthest neighbors example</h2>
|
|
<p>The <code>KFN</code> class has construction semantics similar to <code>DrusillaSelect</code> and <code>QDAFN</code>. The example below constructs a <code>KFN</code> object (which will build the tree on the reference set), but note that the third parameter to the constructor allows us to specify our desired level of approximation. In this example we choose epsilon = 0.05. Then, the code searches for 3 approximate furthest neighbors.</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">// The reference dataset.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The query set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat querySet;</div><div class="line"></div><div class="line"><span class="comment">// Construct the object, performing the default dual-tree search with</span></div><div class="line"><span class="comment">// approximation level epsilon = 0.05.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1NeighborSearch.html">KFN</a> kfn(dataset, <a class="code" href="namespacemlpack_1_1neighbor.html#a77313e33f7e679dd62047c737e50be56ac74cfb269c1ee9c3a28afda6f1843d58">KFN::DUAL_TREE_MODE</a>, 0.05);</div><div class="line"></div><div class="line"><span class="comment">// Search for approximate furthest neighbors.</span></div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">arma::mat distances;</div><div class="line">kfn.Search(querySet, 3, neighbors, distances);</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex2_ns_akfntut"></a>
|
|
Retraining on a new reference set</h2>
|
|
<p>Like the <code>QDAFN</code> and <code>DrusillaSelect</code> classes, the <code>KFN</code> class is capable of retraining on a new reference set. The code below demonstrates this.</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">// The original reference set we train on.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The new reference set we retrain on.</span></div><div class="line"><span class="keyword">extern</span> arma::mat newDataset;</div><div class="line"></div><div class="line"><span class="comment">// Construct the object with approximation level 0.1.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1NeighborSearch.html">KFN</a> kfn(dataset, <a class="code" href="namespacemlpack_1_1neighbor.html#a77313e33f7e679dd62047c737e50be56ac74cfb269c1ee9c3a28afda6f1843d58">DUAL_TREE_MODE</a>, 0.1);</div><div class="line"></div><div class="line"><span class="comment">// Retrain on the new reference set.</span></div><div class="line">kfn.Train(newDataset);</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex3_ns_akfntut"></a>
|
|
Searching in single-tree mode</h2>
|
|
<p>The particular mode to be used in search can be specified in the constructor. In this example, we use single-tree search (as opposed to the default of dual-tree 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">// The reference set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The query set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat querySet;</div><div class="line"></div><div class="line"><span class="comment">// Construct the object with approximation level 0.25 and in single tree search</span></div><div class="line"><span class="comment">// mode.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1NeighborSearch.html">KFN</a> kfn(dataset, <a class="code" href="namespacemlpack_1_1neighbor.html#a77313e33f7e679dd62047c737e50be56afee89338d05b0dbb1190cc13652b19e0">SINGLE_TREE_MODE</a>, 0.25);</div><div class="line"></div><div class="line"><span class="comment">// Search for 5 approximate furthest neighbors.</span></div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">arma::mat distances;</div><div class="line">kfn.Search(querySet, 5, neighbors, distances);</div></div><!-- fragment --><h2><a class="anchor" id="cpp_ex4_ns_akfntut"></a>
|
|
Searching in brute-force mode</h2>
|
|
<p>If desired, brute-force search ("naive search") can be used to find the furthest neighbors; however, the result will not be approximate—it will be exact (since every possibility will be considered). The code below performs exact furthest neighbor search by using the <code>KFN</code> class in brute-force mode.</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">// The reference set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat dataset;</div><div class="line"><span class="comment">// The query set.</span></div><div class="line"><span class="keyword">extern</span> arma::mat querySet;</div><div class="line"></div><div class="line"><span class="comment">// Construct the object in brute-force mode. We can leave the approximation</span></div><div class="line"><span class="comment">// parameter to its default (0) since brute-force will provide exact results.</span></div><div class="line"><a class="code" href="classmlpack_1_1neighbor_1_1NeighborSearch.html">KFN</a> kfn(dataset, <a class="code" href="namespacemlpack_1_1neighbor.html#a77313e33f7e679dd62047c737e50be56a527cee74536f4be0526acc59bbe10be7">NAIVE_MODE</a>);</div><div class="line"></div><div class="line"><span class="comment">// Perform the search for 2 furthest neighbors.</span></div><div class="line">arma::Mat<size_t> neighbors;</div><div class="line">arma::mat distances;</div><div class="line">kfn.Search(querySet, 2, neighbors, distances);</div></div><!-- fragment --><h1><a class="anchor" id="further_doc_akfntut"></a>
|
|
Further documentation</h1>
|
|
<p>For further documentation on the approximate furthest neighbor facilities offered by <b>mlpack</b>, consult the following documentation:</p>
|
|
<ul>
|
|
<li><a class="el" href="nstutorial.html">NeighborSearch tutorial (k-nearest-neighbors)</a></li>
|
|
<li><a class="el" href="classmlpack_1_1neighbor_1_1QDAFN.html">QDAFN class documentation</a></li>
|
|
<li><a class="el" href="classmlpack_1_1neighbor_1_1DrusillaSelect.html">DrusillaSelect class documentation</a></li>
|
|
<li><a class="el" href="classmlpack_1_1neighbor_1_1NeighborSearch.html">NeighborSearch class documentation</a> </li>
|
|
</ul>
|
|
</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>
|