faasle 0.1.1

A Rust crate for evaluating distances (metrics)
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173

use ndarray::{ArrayD, Axis};

pub use crate::generic::metric::{
    Chebyshev, Cityblock, Euclidean, Hamming, Minkowski, RMSDeviation, TotalVariation,
};
pub use crate::generic::pre_metric::{GenKLDivergence, KLDivergence};
pub use crate::generic::semi_metric::{
    BhattacharyyaDist, BrayCurtis, ChiSqDist, JSDivergence, MeanAbsDeviation, MeanSqDeviation,
    SqEuclidean,
};

/// Implement this trait for a distance metric. The trait provides a method to evaluate the distance
/// between two arrays along a specified axis.
pub trait Distance<T>
where
    T: num_traits::Float,
{
    /// # Safety
    ///
    /// This method is unsafe because there are no checks to ensure that the arrays have the same
    /// shape. The caller must ensure that the arrays have the same shape.
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T>;

    /// Evaluate the distance between two arrays. The arrays must have the same shape.
    /// The distance is computed along the specified axis.
    fn evaluate(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> Result<ArrayD<T>, String> {
        if x.ndim() != y.ndim() {
            return Err("x and y must have the same number of dimensions".to_string());
        }
        if x.shape() != y.shape() {
            return Err("x and y must have the same shape".to_string());
        }
        Ok(unsafe { self.distance(x, y, axis) })
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for Euclidean {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).pow2().sum_axis(axis).sqrt()
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for SqEuclidean {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).pow2().sum_axis(axis)
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for Cityblock {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).abs().sum_axis(axis)
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float + ndarray::ScalarOperand> Distance<T> for TotalVariation {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).abs().sum_axis(axis) * T::from(0.5).unwrap()
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for Minkowski {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y)
            .abs()
            .powf(T::from(self.p).unwrap())
            .sum_axis(axis)
            .powf(T::from(1.0 / self.p).unwrap())
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for Chebyshev {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).abs().fold_axis(axis, T::zero(), |a, b| a.max(*b))
    }
}

#[doc(hidden)]
impl<T: num_traits::Float> Distance<T> for Hamming {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        ArrayD::from_shape_fn(x.raw_dim(), |idx| {
            let idx_copy = idx.clone();
            let x_idx = x.get(idx).unwrap();
            let y_idx = y.get(idx_copy).unwrap();
            match x_idx != y_idx {
                true => T::one(),
                false => T::zero(),
            }
        })
        .sum_axis(axis)
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for BrayCurtis {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        let sum_abs_diff = (x - y).abs().sum_axis(axis);
        let sum_abs_sum = (x + y).abs().sum_axis(axis);
        sum_abs_diff / sum_abs_sum
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for ChiSqDist {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        let diff_sq = (x - y).pow2();
        let sum = x + y;
        let sum_diff_sq = diff_sq / sum;
        sum_diff_sq.sum_axis(axis)
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float> Distance<T> for KLDivergence {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x * (x.ln() - y.ln())).sum_axis(axis)
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float + ndarray::ScalarOperand> Distance<T> for GenKLDivergence {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x * (x.ln() - y.ln() - T::one()) + y).sum_axis(axis)
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float + ndarray::ScalarOperand> Distance<T> for JSDivergence {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        let m = (x + y) * T::from(0.5).unwrap();
        let kl_div_x_m = (x * (x.ln() - m.ln())).sum_axis(axis);
        let kl_div_y_m = (y * (y.ln() - m.ln())).sum_axis(axis);
        (kl_div_x_m + kl_div_y_m) * T::from(0.5).unwrap()
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float + num_traits::FromPrimitive> Distance<T> for MeanAbsDeviation {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).abs().mean_axis(axis).unwrap()
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float + num_traits::FromPrimitive> Distance<T> for MeanSqDeviation {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).pow2().mean_axis(axis).unwrap()
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float + num_traits::FromPrimitive> Distance<T> for RMSDeviation {
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        (x - y).pow2().mean_axis(axis).unwrap().sqrt()
    }
}

#[doc(hidden)]
impl<T: 'static + num_traits::Float + num_traits::FromPrimitive + ndarray::ScalarOperand>
    Distance<T> for BhattacharyyaDist
{
    unsafe fn distance(&self, x: &ArrayD<T>, y: &ArrayD<T>, axis: Axis) -> ArrayD<T> {
        let ln_sqrt_sum_x_y = (x * y).sqrt().sum_axis(axis).ln();
        let sqrt_sum_x = x.sum_axis(axis).ln() * T::from(0.5).unwrap();
        let sqrt_sum_y = y.sum_axis(axis).ln() * T::from(0.5).unwrap();
        sqrt_sum_x + sqrt_sum_y - ln_sqrt_sum_x_y
    }
}