abd-clam 0.23.1

Clustering, Learning and Approximation with 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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! Criteria used for partitioning `Cluster`s.

use distances::Number;

use crate::Cluster;

/// A criterion used to decide when to partition a `Cluster`.
///
/// # Type Parameters
///
/// - `T`: The type of the instances in the `Cluster`.
/// - `U`: The type of the distance values between instances.
pub trait PartitionCriterion<U: Number>: Send + Sync {
    /// Check whether a `Cluster` meets the criterion for partitioning.
    // TODO: Figure out how to have this not leak `Cluster` or make `Cluster` public.
    fn check(&self, c: &Cluster<U>) -> bool;
}

/// A collection of criteria used to decide when to partition a `Cluster`.
#[allow(clippy::module_name_repetitions)]
pub struct PartitionCriteria<U: Number> {
    /// The criteria used to decide when to partition a `Cluster`.
    criteria: Vec<Box<dyn PartitionCriterion<U>>>,
    /// Whether all criteria must be met for a `Cluster` to be partitioned or if any one criterion
    /// is sufficient.
    check_all: bool,
}

impl<U: Number> Default for PartitionCriteria<U> {
    fn default() -> Self {
        Self::new(true).with_min_cardinality(1)
    }
}

impl<U: Number> PartitionCriteria<U> {
    /// Create a new `PartitionCriteria` instance.
    ///
    /// # Arguments
    ///
    /// * `check_all`: if `true`, all criteria must be met for a `Cluster` to be partitioned, if
    /// `false`, any one criterion is sufficient.
    #[must_use]
    pub fn new(check_all: bool) -> Self {
        Self {
            criteria: Vec::new(),
            check_all,
        }
    }

    /// Add the `MaxDepth` criterion to the collection of criteria.
    ///
    /// # Arguments
    ///
    /// * `threshold`: the maximum depth of a `Cluster` beyond which it may not be partitioned.
    #[must_use]
    pub fn with_max_depth(mut self, threshold: usize) -> Self {
        self.criteria.push(Box::new(MaxDepth(threshold)));
        self
    }

    /// Add the `MinCardinality` criterion to the collection of criteria.
    ///
    /// # Arguments
    ///
    /// * `threshold`: the minimum cardinality of a `Cluster` below which it may not be partitioned.
    #[must_use]
    pub fn with_min_cardinality(mut self, threshold: usize) -> Self {
        self.criteria.push(Box::new(MinCardinality(threshold)));
        self
    }

    /// Add a custom criterion to the collection of criteria.
    ///
    /// # Arguments
    ///
    /// * `c`: the custom criterion to add.
    #[allow(dead_code)]
    pub(crate) fn with_custom(mut self, c: Box<dyn PartitionCriterion<U>>) -> Self {
        self.criteria.push(c);
        self
    }
}

impl<U: Number> PartitionCriterion<U> for PartitionCriteria<U> {
    fn check(&self, cluster: &Cluster<U>) -> bool {
        !cluster.is_singleton()
            && if self.check_all {
                self.criteria.iter().all(|c| c.check(cluster))
            } else {
                self.criteria.iter().any(|c| c.check(cluster))
            }
    }
}

/// The maximum depth of a `Cluster` beyond which it may not be partitioned.
#[derive(Debug, Clone)]
pub struct MaxDepth(usize);

impl<U: Number> PartitionCriterion<U> for MaxDepth {
    fn check(&self, c: &Cluster<U>) -> bool {
        c.depth() < self.0
    }
}

/// The minimum cardinality of a `Cluster` below which it may not be partitioned.
#[derive(Debug, Clone)]
pub struct MinCardinality(usize);

impl<U: Number> PartitionCriterion<U> for MinCardinality {
    fn check(&self, c: &Cluster<U>) -> bool {
        c.cardinality() > self.0
    }
}