mlpack  master
Public Types | Public Member Functions | Private Attributes | List of all members
mlpack::range::RangeSearch< MetricType, MatType, TreeType > Class Template Reference

The RangeSearch class is a template class for performing range searches. More...

Public Types

typedef TreeType< MetricType, RangeSearchStat, MatType > Tree
 Convenience typedef. More...
 

Public Member Functions

 RangeSearch (const MatType &referenceSet, const bool naive=false, const bool singleMode=false, const MetricType metric=MetricType())
 Initialize the RangeSearch object with a given reference dataset (this is the dataset which is searched). More...
 
 RangeSearch (MatType &&referenceSet, const bool naive=false, const bool singleMode=false, const MetricType metric=MetricType())
 Initialize the RangeSearch object with the given reference dataset (this is the dataset which is searched), taking ownership of the matrix. More...
 
 RangeSearch (Tree *referenceTree, const bool singleMode=false, const MetricType metric=MetricType())
 Initialize the RangeSearch object with the given pre-constructed reference tree (this is the tree built on the reference set, which is the set that is searched). More...
 
 RangeSearch (const bool naive=false, const bool singleMode=false, const MetricType metric=MetricType())
 Initialize the RangeSearch object without any reference data. More...
 
 RangeSearch (const RangeSearch &other)
 Construct the RangeSearch model as a copy of the given model. More...
 
 RangeSearch (RangeSearch &&other)
 Construct the RangeSearch model by taking ownership of the given model. More...
 
 ~RangeSearch ()
 Destroy the RangeSearch object. More...
 
size_t BaseCases () const
 Get the number of base cases during the last search. More...
 
bool Naive () const
 Get whether naive search is being used. More...
 
bool & Naive ()
 Modify whether naive search is being used. More...
 
RangeSearchoperator= (const RangeSearch &other)
 Copy the given RangeSearch model. More...
 
RangeSearchoperator= (RangeSearch &&other)
 Take ownership of the given RangeSearch model. More...
 
const MatType & ReferenceSet () const
 Return the reference set. More...
 
TreeReferenceTree ()
 Return the reference tree (or NULL if in naive mode). More...
 
size_t Scores () const
 Get the number of scores during the last search. More...
 
void Search (const MatType &querySet, const math::Range &range, std::vector< std::vector< size_t >> &neighbors, std::vector< std::vector< double >> &distances)
 Search for all reference points in the given range for each point in the query set, returning the results in the neighbors and distances objects. More...
 
void Search (Tree *queryTree, const math::Range &range, std::vector< std::vector< size_t >> &neighbors, std::vector< std::vector< double >> &distances)
 Given a pre-built query tree, search for all reference points in the given range for each point in the query set, returning the results in the neighbors and distances objects. More...
 
void Search (const math::Range &range, std::vector< std::vector< size_t >> &neighbors, std::vector< std::vector< double >> &distances)
 Search for all points in the given range for each point in the reference set (which was passed to the constructor), returning the results in the neighbors and distances objects. More...
 
template<typename Archive >
void Serialize (Archive &ar, const unsigned int version)
 Serialize the model. More...
 
bool SingleMode () const
 Get whether single-tree search is being used. More...
 
bool & SingleMode ()
 Modify whether single-tree search is being used. More...
 
void Train (const MatType &referenceSet)
 Set the reference set to a new reference set, and build a tree if necessary. More...
 
void Train (MatType &&referenceSet)
 Set the reference set to a new reference set, taking ownership of the set. More...
 
void Train (Tree *referenceTree)
 Set the reference tree to a new reference tree. More...
 

Private Attributes

size_t baseCases
 The total number of base cases during the last search. More...
 
MetricType metric
 Instantiated distance metric. More...
 
bool naive
 If true, O(n^2) naive computation is used. More...
 
std::vector< size_t > oldFromNewReferences
 Mappings to old reference indices (used when this object builds trees). More...
 
const MatType * referenceSet
 Reference set (data should be accessed using this). More...
 
TreereferenceTree
 Reference tree. More...
 
size_t scores
 The total number of scores during the last search. More...
 
bool setOwner
 If true, we own the reference set. More...
 
bool singleMode
 If true, single-tree computation is used. More...
 
bool treeOwner
 If true, this object is responsible for deleting the trees. More...
 

Detailed Description

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
class mlpack::range::RangeSearch< MetricType, MatType, TreeType >

The RangeSearch class is a template class for performing range searches.

It is implemented in the style of a generalized tree-independent dual-tree algorithm; for more details on the actual algorithm, see the RangeSearchRules class.

Template Parameters
MetricTypeMetric to use for range search calculations.
MatTypeType of data to use.
TreeTypeType of tree to use; must satisfy the TreeType policy API.

Definition at line 42 of file range_search.hpp.

Member Typedef Documentation

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
typedef TreeType<MetricType, RangeSearchStat, MatType> mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Tree

Convenience typedef.

Definition at line 46 of file range_search.hpp.

Constructor & Destructor Documentation

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
mlpack::range::RangeSearch< MetricType, MatType, TreeType >::RangeSearch ( const MatType &  referenceSet,
const bool  naive = false,
const bool  singleMode = false,
const MetricType  metric = MetricType() 
)

Initialize the RangeSearch object with a given reference dataset (this is the dataset which is searched).

Optionally, perform the computation in naive mode or single-tree mode. Additionally, an instantiated metric can be given, for cases where the distance metric holds data.

This method will copy the matrices to internal copies, which are rearranged during tree-building. You can avoid this extra copy by pre-constructing the trees and passing them using a different constructor.

Parameters
referenceSetReference dataset.
naiveWhether the computation should be done in O(n^2) naive mode.
singleModeWhether single-tree computation should be used (as opposed to dual-tree computation).
metricInstantiated distance metric.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
mlpack::range::RangeSearch< MetricType, MatType, TreeType >::RangeSearch ( MatType &&  referenceSet,
const bool  naive = false,
const bool  singleMode = false,
const MetricType  metric = MetricType() 
)

Initialize the RangeSearch object with the given reference dataset (this is the dataset which is searched), taking ownership of the matrix.

Optionally, perform the computation in naive mode or single-tree mode. Additionally, an instantiated metric can be given, for cases where the distance metric holds data.

This method will not copy the data matrix, but will take ownership of it, and depending on the type of tree used, may rearrange the points. If you would rather a copy be made, consider using the constructor that takes a const reference to the data instead.

Parameters
referenceSetSet of reference points.
naiveIf true, brute force naive search will be used (as opposed to dual-tree search). This overrides singleMode (if it is set to true).
singleModeIf true, single-tree search will be used (as opposed to dual-tree search).
metricAn optional instance of the MetricType class.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
mlpack::range::RangeSearch< MetricType, MatType, TreeType >::RangeSearch ( Tree referenceTree,
const bool  singleMode = false,
const MetricType  metric = MetricType() 
)

Initialize the RangeSearch object with the given pre-constructed reference tree (this is the tree built on the reference set, which is the set that is searched).

Optionally, choose to use single-tree mode, which will not build a tree on query points. Naive mode is not available as an option for this constructor. Additionally, an instantiated distance metric can be given, for cases where the distance metric holds data.

There is no copying of the data matrices in this constructor (because tree-building is not necessary), so this is the constructor to use when copies absolutely must be avoided.

Note
Because tree-building (at least with BinarySpaceTree) modifies the ordering of a matrix, be aware that mapping of the points back to their original indices is not done when this constructor is used.
Parameters
referenceTreePre-built tree for reference points.
referenceSetSet of reference points corresponding to referenceTree.
singleModeWhether single-tree computation should be used (as opposed to dual-tree computation).
metricInstantiated distance metric.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
mlpack::range::RangeSearch< MetricType, MatType, TreeType >::RangeSearch ( const bool  naive = false,
const bool  singleMode = false,
const MetricType  metric = MetricType() 
)

Initialize the RangeSearch object without any reference data.

If the monochromatic Search() is called before a reference set is set with Train(), no results will be returned (since the reference set is empty).

Parameters
naiveWhether to use naive search.
singleModeWhether single-tree computation should be used (as opposed to dual-tree computation).
metricInstantiated metric.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
mlpack::range::RangeSearch< MetricType, MatType, TreeType >::RangeSearch ( const RangeSearch< MetricType, MatType, TreeType > &  other)

Construct the RangeSearch model as a copy of the given model.

Note that this may be computationally intensive!

Parameters
otherRangeSearch model to copy.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
mlpack::range::RangeSearch< MetricType, MatType, TreeType >::RangeSearch ( RangeSearch< MetricType, MatType, TreeType > &&  other)

Construct the RangeSearch model by taking ownership of the given model.

Parameters
otherRangeSearch model to take ownership of.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
mlpack::range::RangeSearch< MetricType, MatType, TreeType >::~RangeSearch ( )

Destroy the RangeSearch object.

If trees were created, they will be deleted.

Member Function Documentation

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
size_t mlpack::range::RangeSearch< MetricType, MatType, TreeType >::BaseCases ( ) const
inline

Get the number of base cases during the last search.

Definition at line 313 of file range_search.hpp.

References mlpack::range::RangeSearch< MetricType, MatType, TreeType >::baseCases.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Naive ( ) const
inline

Get whether naive search is being used.

Definition at line 308 of file range_search.hpp.

References mlpack::range::RangeSearch< MetricType, MatType, TreeType >::naive.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool& mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Naive ( )
inline

Modify whether naive search is being used.

Definition at line 310 of file range_search.hpp.

References mlpack::range::RangeSearch< MetricType, MatType, TreeType >::naive.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
RangeSearch& mlpack::range::RangeSearch< MetricType, MatType, TreeType >::operator= ( const RangeSearch< MetricType, MatType, TreeType > &  other)

Copy the given RangeSearch model.

Parameters
otherRangeSearch model to copy.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
RangeSearch& mlpack::range::RangeSearch< MetricType, MatType, TreeType >::operator= ( RangeSearch< MetricType, MatType, TreeType > &&  other)

Take ownership of the given RangeSearch model.

Parameters
otherRangeSearch model to take ownership of.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
const MatType& mlpack::range::RangeSearch< MetricType, MatType, TreeType >::ReferenceSet ( ) const
inline

Return the reference set.

Definition at line 322 of file range_search.hpp.

References mlpack::range::RangeSearch< MetricType, MatType, TreeType >::referenceSet.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
Tree* mlpack::range::RangeSearch< MetricType, MatType, TreeType >::ReferenceTree ( )
inline

Return the reference tree (or NULL if in naive mode).

Definition at line 325 of file range_search.hpp.

References mlpack::range::RangeSearch< MetricType, MatType, TreeType >::referenceTree.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
size_t mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Scores ( ) const
inline
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
void mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Search ( const MatType &  querySet,
const math::Range range,
std::vector< std::vector< size_t >> &  neighbors,
std::vector< std::vector< double >> &  distances 
)

Search for all reference points in the given range for each point in the query set, returning the results in the neighbors and distances objects.

Each entry in the external vector corresponds to a query point. Each of these entries holds a vector which contains the indices and distances of the reference points falling into the given range.

That is:

  • neighbors.size() and distances.size() both equal the number of query points.
  • neighbors[i] contains the indices of all the points in the reference set which have distances inside the given range to query point i.
  • distances[i] contains all of the distances corresponding to the indices contained in neighbors[i].
  • neighbors[i] and distances[i] are not sorted in any particular order.
Parameters
querySetSet of query points to search with.
rangeRange of distances in which to search.
neighborsObject which will hold the list of neighbors for each point which fell into the given range, for each query point.
distancesObject which will hold the list of distances for each point which fell into the given range, for each query point.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
void mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Search ( Tree queryTree,
const math::Range range,
std::vector< std::vector< size_t >> &  neighbors,
std::vector< std::vector< double >> &  distances 
)

Given a pre-built query tree, search for all reference points in the given range for each point in the query set, returning the results in the neighbors and distances objects.

Each entry in the external vector corresponds to a query point. Each of these entries holds a vector which contains the indices and distances of the reference points falling into the given range.

That is:

  • neighbors.size() and distances.size() both equal the number of query points.
  • neighbors[i] contains the indices of all the points in the reference set which have distances inside the given range to query point i.
  • distances[i] contains all of the distances corresponding to the indices contained in neighbors[i].
  • neighbors[i] and distances[i] are not sorted in any particular order.

If either naive or singleMode are set to true, this will throw an invalid_argument exception; passing in a query tree implies dual-tree search.

If you want to use the reference tree as the query tree, instead call the overload of Search() that does not take a query set.

Parameters
queryTreeTree built on query points.
rangeRange of distances in which to search.
neighborsObject which will hold the list of neighbors for each point which fell into the given range, for each query point.
distancesObject which will hold the list of distances for each point which fell into the given range, for each query point.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
void mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Search ( const math::Range range,
std::vector< std::vector< size_t >> &  neighbors,
std::vector< std::vector< double >> &  distances 
)

Search for all points in the given range for each point in the reference set (which was passed to the constructor), returning the results in the neighbors and distances objects.

This means that the query set and the reference set are the same.

Each entry in the external vector corresponds to a query point. Each of these entries holds a vector which contains the indices and distances of the reference points falling into the given range.

That is:

  • neighbors.size() and distances.size() both equal the number of query points.
  • neighbors[i] contains the indices of all the points in the reference set which have distances inside the given range to query point i.
  • distances[i] contains all of the distances corresponding to the indices contained in neighbors[i].
  • neighbors[i] and distances[i] are not sorted in any particular order.
Parameters
queryTreeTree built on query points.
rangeRange of distances in which to search.
neighborsObject which will hold the list of neighbors for each point which fell into the given range, for each query point.
distancesObject which will hold the list of distances for each point which fell into the given range, for each query point.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
template<typename Archive >
void mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Serialize ( Archive &  ar,
const unsigned int  version 
)
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool mlpack::range::RangeSearch< MetricType, MatType, TreeType >::SingleMode ( ) const
inline

Get whether single-tree search is being used.

Definition at line 303 of file range_search.hpp.

References mlpack::range::RangeSearch< MetricType, MatType, TreeType >::singleMode.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool& mlpack::range::RangeSearch< MetricType, MatType, TreeType >::SingleMode ( )
inline

Modify whether single-tree search is being used.

Definition at line 305 of file range_search.hpp.

References mlpack::range::RangeSearch< MetricType, MatType, TreeType >::singleMode.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
void mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Train ( const MatType &  referenceSet)

Set the reference set to a new reference set, and build a tree if necessary.

This method is called 'Train()' in order to match the rest of the mlpack abstractions, even though calling this "training" is maybe a bit of a stretch.

Parameters
referenceSetNew set of reference data.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
void mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Train ( MatType &&  referenceSet)

Set the reference set to a new reference set, taking ownership of the set.

A tree is built if necessary. This method is called 'Train()' in order to match the rest of the mlpack abstractions, even though calling this "training" is maybe a bit of a stretch.

Parameters
referenceSetNew set of reference data.
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
void mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Train ( Tree referenceTree)

Set the reference tree to a new reference tree.

Member Data Documentation

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
size_t mlpack::range::RangeSearch< MetricType, MatType, TreeType >::baseCases
private

The total number of base cases during the last search.

Definition at line 350 of file range_search.hpp.

Referenced by mlpack::range::RangeSearch< MetricType, MatType, TreeType >::BaseCases().

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
MetricType mlpack::range::RangeSearch< MetricType, MatType, TreeType >::metric
private

Instantiated distance metric.

Definition at line 347 of file range_search.hpp.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool mlpack::range::RangeSearch< MetricType, MatType, TreeType >::naive
private

If true, O(n^2) naive computation is used.

Definition at line 342 of file range_search.hpp.

Referenced by mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Naive().

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
std::vector<size_t> mlpack::range::RangeSearch< MetricType, MatType, TreeType >::oldFromNewReferences
private

Mappings to old reference indices (used when this object builds trees).

Definition at line 329 of file range_search.hpp.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
const MatType* mlpack::range::RangeSearch< MetricType, MatType, TreeType >::referenceSet
private

Reference set (data should be accessed using this).

In some situations we may be the owner of this.

Definition at line 334 of file range_search.hpp.

Referenced by mlpack::range::RangeSearch< MetricType, MatType, TreeType >::ReferenceSet().

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
Tree* mlpack::range::RangeSearch< MetricType, MatType, TreeType >::referenceTree
private
template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
size_t mlpack::range::RangeSearch< MetricType, MatType, TreeType >::scores
private

The total number of scores during the last search.

Definition at line 352 of file range_search.hpp.

Referenced by mlpack::range::RangeSearch< MetricType, MatType, TreeType >::Scores().

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool mlpack::range::RangeSearch< MetricType, MatType, TreeType >::setOwner
private

If true, we own the reference set.

Definition at line 339 of file range_search.hpp.

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool mlpack::range::RangeSearch< MetricType, MatType, TreeType >::singleMode
private

If true, single-tree computation is used.

Definition at line 344 of file range_search.hpp.

Referenced by mlpack::range::RangeSearch< MetricType, MatType, TreeType >::SingleMode().

template<typename MetricType = metric::EuclideanDistance, typename MatType = arma::mat, template< typename TreeMetricType, typename TreeStatType, typename TreeMatType > class TreeType = tree::KDTree>
bool mlpack::range::RangeSearch< MetricType, MatType, TreeType >::treeOwner
private

If true, this object is responsible for deleting the trees.

Definition at line 337 of file range_search.hpp.


The documentation for this class was generated from the following file: