abd-clam 0.21.3

Clustered Learning of Approximate Manifolds
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

//! A `Tree` represents a hierarchy of "similar" instances from a metric-`Space`.

use distances::Number;

use crate::{Cluster, Dataset, PartitionCriteria};

/// A `Tree` represents a hierarchy of `Cluster`s, i.e. "similar" instances
/// from a metric-`Space`.
///
/// # Type Parameters
///
/// - `T`: The type of the instances in the `Tree`.
/// - `U`: The type of the distance values between instances.
/// - `D`: The type of the `Dataset` from which the `Tree` is built.
#[derive(Debug)]
pub struct Tree<T: Send + Sync + Copy, U: Number, D: Dataset<T, U>> {
    /// The dataset from which the tree is built.
    data: D,
    /// The root `Cluster` of the tree.
    root: Cluster<T, U>,
    /// The depth of the tree.
    depth: usize,
    /// The type of the instances in the tree.
    center: T,
}

impl<T: Send + Sync + Copy, U: Number, D: Dataset<T, U>> Tree<T, U, D> {
    /// Constructs a new `Tree` for a given dataset. Importantly, this does not
    /// partition the tree.
    ///
    /// # Arguments
    /// dataset: The dataset from which the tree will be built
    pub fn new(data: D, seed: Option<u64>) -> Self {
        let root = Cluster::new_root(&data, data.indices(), seed);
        let depth = root.max_leaf_depth();
        let center = root.center;
        Self {
            data,
            root,
            depth,
            center,
        }
    }

    /// Recursively partitions the root `Cluster` using the given criteria.
    ///
    /// # Arguments
    ///
    /// * `criteria`: the criteria used to decide when to partition a `Cluster`.
    ///
    /// # Returns
    ///
    /// The `Tree` after partitioning.
    #[must_use]
    pub fn partition(mut self, criteria: &PartitionCriteria<T, U>) -> Self {
        self.root = self.root.partition(&mut self.data, criteria);
        self
    }

    /// Returns a reference to the data used to build the `Tree`.
    pub const fn data(&self) -> &D {
        &self.data
    }

    /// A reference to the root `Cluster` of the tree.
    pub(crate) const fn root(&self) -> &Cluster<T, U> {
        &self.root
    }

    /// The depth of the tree.
    pub(crate) const fn depth(&self) -> usize {
        self.depth
    }

    /// The center of the tree.
    pub(crate) const fn center(&self) -> T {
        self.center
    }

    /// The cardinality of the `Tree`, i.e. the number of instances in the data.
    pub const fn cardinality(&self) -> usize {
        self.root.cardinality
    }

    /// The radius of the root of the `Tree`.
    pub const fn radius(&self) -> U {
        self.root.radius
    }

    /// Returns the indices contained in the root of the `Tree`.
    pub fn indices(&self) -> &[usize] {
        self.data.indices()
    }
}