runn 0.1.1

Runn is a feature-rich, easy-to-use library for building, training, and evaluating feed-forward neural networks in Rust
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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201

use serde::{Deserialize, Serialize};

use crate::matrix::DMat;

use super::Normalization;

/// A builder for z-score normalization, standardizing input data to have zero mean and unit variance.
///
/// Z-score normalization transforms each feature by subtracting its mean and dividing by its standard deviation.
#[derive(Serialize, Deserialize, Clone)]
pub struct ZScore {
    means: Option<Vec<f32>>,
    std_devs: Option<Vec<f32>>,
}

impl ZScore {
    fn new() -> Self {
        Self {
            means: None,
            std_devs: None,
        }
    }

    fn compute_mean_std(&mut self, matrix: &DMat) {
        let (rows, cols) = (matrix.rows(), matrix.cols());
        let mut means = vec![0.0; cols];
        let mut std_devs = vec![0.0; cols];

        // Calculate means
        (0..cols).for_each(|j| {
            let mut sum = 0.0;
            for i in 0..rows {
                sum += matrix.at(i, j);
            }
            means[j] = sum / rows as f32;
        });

        // Calculate standard deviations
        for j in 0..cols {
            let mut sum = 0.0;
            for i in 0..rows {
                let diff = matrix.at(i, j) - means[j];
                sum += diff * diff;
            }
            std_devs[j] = (sum / rows as f32).sqrt();
        }

        self.means = Some(means);
        self.std_devs = Some(std_devs);
    }
}

impl Default for ZScore {
    fn default() -> Self {
        Self::new()
    }
}

#[typetag::serde]
impl Normalization for ZScore {
    fn normalize(&mut self, matrix: &mut DMat) -> Result<(), String> {
        if self.means.is_none() || self.std_devs.is_none() {
            self.compute_mean_std(matrix);
        }

        let (rows, cols) = (matrix.rows(), matrix.cols());

        let means = self.means.as_ref().ok_or_else(|| "Means not initialized".to_string())?;
        let std_devs = self
            .std_devs
            .as_ref()
            .ok_or_else(|| "Standard deviations not initialized".to_string())?;

        if means.len() != cols || std_devs.len() != cols {
            return Err("Matrix column size does not match the initialized mean/std dev sizes.".to_string());
        }

        for i in 0..rows {
            for j in 0..cols {
                let val = matrix.at(i, j);
                let mean = means[j];
                let std_dev = std_devs[j];

                if std_dev.abs() < f32::EPSILON {
                    matrix.set(i, j, 0.0); // If standard deviation is zero, set to 0
                } else {
                    matrix.set(i, j, (val - mean) / std_dev); // Normalize value
                }
            }
        }
        Ok(())
    }

    fn denormalize(&self, matrix: &mut DMat) -> Result<(), String> {
        let (rows, cols) = (matrix.rows(), matrix.cols());

        let means = self.means.as_ref().ok_or_else(|| "Means not initialized".to_string())?;
        let std_devs = self
            .std_devs
            .as_ref()
            .ok_or_else(|| "Standard deviations not initialized".to_string())?;

        if means.len() != cols || std_devs.len() != cols {
            return Err("Matrix column size does not match the initialized mean/std dev sizes.".to_string());
        }

        for i in 0..rows {
            for j in 0..cols {
                let val = matrix.at(i, j);
                let mean = means[j];
                let std_dev = std_devs[j];

                if std_dev.abs() < f32::EPSILON {
                    matrix.set(i, j, mean); // If std dev is zero, set to mean
                } else {
                    matrix.set(i, j, val * std_dev + mean); // Denormalize value
                }
            }
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::matrix::DMat; // Import DenseMatrix

    // Test for Z-Score normalization and denormalization
    #[test]
    fn test_z_score_normalization() {
        let matrix_data = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
        let mut matrix = DMat::new(3, 3, &matrix_data);

        // Z-Score Normalization
        let mut z_score = ZScore::default();
        z_score.normalize(&mut matrix).unwrap();

        // After normalization, the mean of each column should be close to 0 and std dev close to 1
        for j in 0..matrix.cols() {
            let mut sum = 0.0;
            let mut sum_sq = 0.0;
            for i in 0..matrix.rows() {
                let val = matrix.at(i, j);
                sum += val;
                sum_sq += val * val;
            }

            let mean = sum / matrix.rows() as f32;
            let std_dev = (sum_sq / matrix.rows() as f32 - mean * mean).sqrt();

            // Assert that the mean is close to 0 and standard deviation close to 1
            assert!((mean).abs() < 0.1); // Mean should be close to 0
            assert!((std_dev - 1.0).abs() < 0.1); // Std dev should be close to 1
        }

        // Denormalization
        z_score.denormalize(&mut matrix).unwrap();

        // Ensure the denormalized values match the original matrix
        let original = [vec![1.0, 2.0, 3.0], vec![4.0, 5.0, 6.0], vec![7.0, 8.0, 9.0]];

        // Compare denormalized matrix with the original matrix
        (0..matrix.rows()).for_each(|i| {
            for j in 0..matrix.cols() {
                assert!((matrix.at(i, j) - original[i][j]).abs() < f32::EPSILON);
            }
        });
    }

    #[test]
    fn test_z_score_denormalization() {
        let matrix_data = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
        let mut matrix = DMat::new(3, 3, &matrix_data);

        // Z-Score Normalization
        let mut z_score = ZScore::default();
        z_score.normalize(&mut matrix).unwrap();

        // Denormalization
        z_score.denormalize(&mut matrix).unwrap();

        // Ensure the denormalized values match the original matrix
        let original = [vec![1.0, 2.0, 3.0], vec![4.0, 5.0, 6.0], vec![7.0, 8.0, 9.0]];

        // Compare denormalized matrix with the original matrix
        (0..matrix.rows()).for_each(|i| {
            for j in 0..matrix.cols() {
                assert!((matrix.at(i, j) - original[i][j]).abs() < f32::EPSILON);
            }
        });
    }

    #[test]
    fn test_z_score_empty_matrix() {
        let mut matrix = DMat::new(0, 0, &[]); // Empty matrix
        let mut z_score = ZScore::default();
        assert!(z_score.normalize(&mut matrix).is_ok());
        assert!(z_score.denormalize(&mut matrix).is_ok());
    }
}