ExampleTree< MetricType, StatisticType, MatType > Class Template Reference

This is not an actual space tree but instead an example tree that exists to show and document all the functions that mlpack trees must implement. More...

Public Member Functions

 ExampleTree (const MatType &dataset, MetricType &metric)
 This constructor will build the tree given a dataset and an instantiated metric. More...

 
void Centroid (arma::vec &centroid) const
 Fill the given vector with the center of the node. More...

 
const ExampleTreeChild (const size_t i) const
 Return a particular child of this node. More...

 
ExampleTreeChild (const size_t i)
 Modify a particular child of this node. More...

 
size_t Descendant (const size_t i) const
 Get the index of a particular descendant point. More...

 
double FurthestDescendantDistance () const
 Get the distance from the center of the node to the furthest descendant point of this node. More...

 
double MaxDistance (const MatType &point) const
 Return the maximum distance between this node and a point. More...

 
double MaxDistance (const ExampleTree &other) const
 Return the maximum distance between this node and another node. More...

 
const MetricType & Metric () const
 Get the instantiated metric for this node. More...

 
MetricType & Metric ()
 Modify the instantiated metric for this node. More...

 
double MinDistance (const MatType &point) const
 Return the minimum distance between this node and a point. More...

 
double MinDistance (const ExampleTree &other) const
 Return the minimum distance between this node and another node. More...

 
size_t NumChildren () const
 Return the number of children of this node. More...

 
size_t NumDescendants () const
 Get the number of descendant points. More...

 
size_t NumPoints () const
 Return the number of points held in this node. More...

 
ExampleTreeParent () const
 Return the parent node (NULL if this is the root of the tree). More...

 
double ParentDistance () const
 Get the distance from the center of this node to the center of the parent node. More...

 
size_t Point (const size_t i) const
 Return the index of a particular point of this node. More...

 
math::Range RangeDistance (const MatType &point) const
 Return both the minimum and maximum distances between this node and a point as a math::Range object. More...

 
math::Range RangeDistance (const ExampleTree &other) const
 Return both the minimum and maximum distances between this node and another node as a math::Range object. More...

 
const StatisticType & Stat () const
 Get the statistic for this node. More...

 
StatisticType & Stat ()
 Modify the statistic for this node. More...

 

Detailed Description


template<typename MetricType = metric::LMetric<2, true>, typename StatisticType = EmptyStatistic, typename MatType = arma::mat>
class mlpack::tree::ExampleTree< MetricType, StatisticType, MatType >

This is not an actual space tree but instead an example tree that exists to show and document all the functions that mlpack trees must implement.

For a better overview of trees, see The TreeType policy in mlpack. Also be aware that the implementations of each of the methods in this example tree are entirely fake and do not work; this example tree exists for its API, not its implementation.

Note that trees often have different properties. These properties are known at compile-time through the mlpack::tree::TreeTraits class, and some properties may imply the existence (or non-existence) of certain functions. Refer to the TreeTraits for more documentation on that.

The three template parameters below must be template parameters to the tree, in the order given below. More template parameters are fine, but they must come after the first three.

Template Parameters
MetricTypeThis defines the space in which the tree will be built. For some trees, arbitrary metrics cannot be used, and a template metaprogramming approach should be used to issue a compile-time error if a metric cannot be used with a specific tree type. One example is the tree::BinarySpaceTree tree type, which cannot work with the metric::IPMetric class.
StatisticTypeA tree node can hold a statistic, which is sometimes useful for various dual-tree algorithms. The tree itself does not need to know anything about how the statistic works, but it needs to hold a StatisticType in each node. It can be assumed that the StatisticType class has a constructor StatisticType(const ExampleTree&).
MatTypeA tree could be built on a dense matrix or a sparse matrix. All mlpack trees should be able to support any Armadillo-compatible matrix type. When the tree is written it should be assumed that MatType has the same functionality as arma::mat.

Definition at line 56 of file example_tree.hpp.

Constructor & Destructor Documentation

◆ ExampleTree()

ExampleTree ( const MatType &  dataset,
MetricType &  metric 
)

This constructor will build the tree given a dataset and an instantiated metric.

Note that the parameter is a MatType& and not an arma::mat&. The dataset is not modified by the tree-building process (if it is, see the documentation for mlpack::tree::TreeTraits::RearrangesDataset for how to deal with that situation). The MetricType parameter is necessary even though some metrics do not hold any state. This is so that the tree does not have to worry about instantiating the metric (if the tree had to worry about this, this would almost certainly incur additional runtime complexity and a larger runtime size of the tree node objects, which is to be avoided). The metric can't be const, in case MetricType::Evaluate() is non-const.

When this constructor is finished, the entire tree will be built and ready to use. The constructor should call the constructor of the statistic for each node that is built (see tree::EmptyStatistic for more information).

Parameters
datasetThe dataset that the tree will be built on.
metricThe instantiated metric to use to build the dataset.

Member Function Documentation

◆ Centroid()

void Centroid ( arma::vec &  centroid) const

Fill the given vector with the center of the node.

Parameters
centroidVector to be filled with the center of the node.

◆ Child() [1/2]

const ExampleTree& Child ( const size_t  i) const

Return a particular child of this node.

◆ Child() [2/2]

ExampleTree& Child ( const size_t  i)

Modify a particular child of this node.

◆ Descendant()

size_t Descendant ( const size_t  i) const

Get the index of a particular descendant point.

The ordering of the descendants does not matter, as long as calling Descendant(0) through Descendant(NumDescendants() - 1) will return the indices of every unique descendant point of the node.

◆ FurthestDescendantDistance()

double FurthestDescendantDistance ( ) const

Get the distance from the center of the node to the furthest descendant point of this node.

This does not necessarily need to be the exact furthest descendant distance but instead can be an upper bound. See the definitions in The TreeType policy in mlpack for more information.

◆ MaxDistance() [1/2]

double MaxDistance ( const MatType &  point) const

Return the maximum distance between this node and a point.

It is not required that the exact maximum distance between the node and the point is returned but instead an upper bound on the maximum distance will suffice. See the definitions in The TreeType policy in mlpack for more information.

Parameters
pointPoint to return [upper bound on] maximum distance to.

◆ MaxDistance() [2/2]

double MaxDistance ( const ExampleTree< MetricType, StatisticType, MatType > &  other) const

Return the maximum distance between this node and another node.

It is not required that the exact maximum distance between the two nodes be returned but instead an upper bound on the maximum distance will suffice. See the definitions in The TreeType policy in mlpack for more information.

Parameters
nodeNode to return [upper bound on] maximum distance to.

◆ Metric() [1/2]

const MetricType& Metric ( ) const

Get the instantiated metric for this node.

◆ Metric() [2/2]

MetricType& Metric ( )

Modify the instantiated metric for this node.

◆ MinDistance() [1/2]

double MinDistance ( const MatType &  point) const

Return the minimum distance between this node and a point.

It is not required that the exact minimum distance between the node and the point is returned but instead a lower bound on the minimum distance will suffice. See the definitions in The TreeType policy in mlpack for more information.

Parameters
pointPoint to return [lower bound on] minimum distance to.

◆ MinDistance() [2/2]

double MinDistance ( const ExampleTree< MetricType, StatisticType, MatType > &  other) const

Return the minimum distance between this node and another node.

It is not required that the exact minimum distance between the two nodes be returned but instead a lower bound on the minimum distance will suffice. See the definitions in The TreeType policy in mlpack for more information.

Parameters
nodeNode to return [lower bound on] minimum distance to.

◆ NumChildren()

size_t NumChildren ( ) const

Return the number of children of this node.

◆ NumDescendants()

size_t NumDescendants ( ) const

Get the number of descendant points.

This is the number of unique points held in this node plus the number of points held in all descendant nodes. This could be calculated at build-time and cached, or could be calculated at run-time. This may be harder to calculate for trees that may hold points in multiple nodes (like cover trees and spill trees, for instance).

◆ NumPoints()

size_t NumPoints ( ) const

Return the number of points held in this node.

◆ Parent()

ExampleTree* Parent ( ) const

Return the parent node (NULL if this is the root of the tree).

◆ ParentDistance()

double ParentDistance ( ) const

Get the distance from the center of this node to the center of the parent node.

◆ Point()

size_t Point ( const size_t  i) const

Return the index of a particular point of this node.

mlpack trees do not, in general, hold the actual dataset, and instead just hold the indices of the points they contain. Thus, you might use this function in code like this:

arma::vec thirdPoint = dataset.col(treeNode.Point(2));

◆ RangeDistance() [1/2]

math::Range RangeDistance ( const MatType &  point) const

Return both the minimum and maximum distances between this node and a point as a math::Range object.

This overload is given because it is possible that, for some tree types, calculation of both at once is faster than a call to MinDistance() then MaxDistance(). It is not necessary that the minimum and maximum distances be exact; it is sufficient to return a lower bound on the minimum distance and an upper bound on the maximum distance. See the definitions in The TreeType policy in mlpack for more information.

Parameters
pointPoint to return [bounds on] minimum and maximum distances to.

◆ RangeDistance() [2/2]

math::Range RangeDistance ( const ExampleTree< MetricType, StatisticType, MatType > &  other) const

Return both the minimum and maximum distances between this node and another node as a math::Range object.

This overload is given because it is possible that, for some tree types, calculation of both at once is faster than a call to MinDistance() then MaxDistance(). It is not necessary that the minimum and maximum distances be exact; it is sufficient to return a lower bound on the minimum distance and an upper bound on the maximum distance. See the definitions in The TreeType policy in mlpack for more information.

Parameters
nodeNode to return [bounds on] minimum and maximum distances to.

◆ Stat() [1/2]

const StatisticType& Stat ( ) const

Get the statistic for this node.

◆ Stat() [2/2]

StatisticType& Stat ( )

Modify the statistic for this node.


The documentation for this class was generated from the following file:
  • /home/jenkins-mlpack/mlpack.org/_src/mlpack-3.2.1/src/mlpack/core/tree/example_tree.hpp