1use rayon::prelude::*;
2
3use crate::{CompositionError, LabeledMatrix, Result};
4
5#[derive(Clone, Debug, PartialEq)]
6pub struct VlrMatrix {
7 components: Vec<String>,
8 values: Vec<f64>,
9}
10
11impl VlrMatrix {
12 #[must_use]
13 pub fn components(&self) -> &[String] {
14 &self.components
15 }
16
17 #[must_use]
18 pub fn values(&self) -> &[f64] {
19 &self.values
20 }
21
22 #[must_use]
23 pub fn get(&self, left: usize, right: usize) -> Option<f64> {
24 let width = self.components.len();
25 self.values.get(left.checked_mul(width)? + right).copied()
26 }
27}
28
29pub fn vlr(
30 matrix: &LabeledMatrix,
31 left: &str,
32 right: &str,
33 ddof: usize,
34 robust: bool,
35) -> Result<f64> {
36 let left = component_index(matrix, left)?;
37 let right = component_index(matrix, right)?;
38 let mut differences = Vec::with_capacity(matrix.sample_count());
39 for (row_index, row) in matrix.rows().enumerate() {
40 let x = row[left];
41 let y = row[right];
42 if robust && (x == 0.0 || y == 0.0 || x.is_nan() || y.is_nan()) {
43 continue;
44 }
45 for (column, value) in [(left, x), (right, y)] {
46 if !value.is_finite() || value <= 0.0 {
47 return Err(CompositionError::InvalidComponent {
48 sample: matrix.samples()[row_index].clone(),
49 component: matrix.components()[column].clone(),
50 value,
51 requirement: if robust {
52 "positive, finite, zero, or NaN-missing"
53 } else {
54 "strictly positive and finite"
55 },
56 });
57 }
58 }
59 differences.push(x.ln() - y.ln());
60 }
61 variance(&differences, ddof).ok_or(CompositionError::NoDegreesOfFreedom {
62 ddof,
63 observations: differences.len(),
64 })
65}
66
67pub fn pairwise_vlr(matrix: &LabeledMatrix, ddof: usize) -> Result<VlrMatrix> {
68 pairwise_vlr_with_limit(matrix, ddof, crate::DEFAULT_MAX_DENSE_CELLS)
69}
70
71pub fn pairwise_vlr_with_limit(
72 matrix: &LabeledMatrix,
73 ddof: usize,
74 maximum_cells: usize,
75) -> Result<VlrMatrix> {
76 if matrix.sample_count() <= ddof {
77 return Err(CompositionError::NoDegreesOfFreedom {
78 ddof,
79 observations: matrix.sample_count(),
80 });
81 }
82 let samples = matrix.sample_count();
83 let components = matrix.component_count();
84 let mut values = crate::limits::dense_vec(
85 "pairwise VLR matrix",
86 components,
87 components,
88 maximum_cells,
89 0.0,
90 )?;
91 let mut centered = vec![0.0; samples * components];
92 for column in 0..components {
93 let mut mean = 0.0;
94 for row in 0..samples {
95 let value = matrix.values()[row * components + column];
96 if !value.is_finite() || value <= 0.0 {
97 return Err(CompositionError::InvalidComponent {
98 sample: matrix.samples()[row].clone(),
99 component: matrix.components()[column].clone(),
100 value,
101 requirement: "strictly positive and finite",
102 });
103 }
104 let logged = value.ln();
105 centered[column * samples + row] = logged;
106 mean += logged;
107 }
108 mean /= samples as f64;
109 for row in 0..samples {
110 centered[column * samples + row] -= mean;
111 }
112 }
113 let denominator = (samples - ddof) as f64;
114 let variances: Vec<f64> = centered
115 .par_chunks(samples)
116 .map(|column| column.iter().map(|value| value * value).sum::<f64>() / denominator)
117 .collect();
118 values
119 .par_chunks_mut(components)
120 .enumerate()
121 .for_each(|(left, row)| {
122 for right in 0..components {
123 if left == right {
124 continue;
125 }
126 let covariance: f64 = centered[left * samples..(left + 1) * samples]
127 .iter()
128 .zip(¢ered[right * samples..(right + 1) * samples])
129 .map(|(&x, &y)| x * y)
130 .sum::<f64>()
131 / denominator;
132 row[right] = (variances[left] + variances[right] - 2.0 * covariance).max(0.0);
133 }
134 });
135 Ok(VlrMatrix {
136 components: matrix.components().to_vec(),
137 values,
138 })
139}
140
141fn component_index(matrix: &LabeledMatrix, component: &str) -> Result<usize> {
142 matrix
143 .components()
144 .iter()
145 .position(|candidate| candidate == component)
146 .ok_or_else(|| CompositionError::UnknownComponent(component.to_owned()))
147}
148
149fn variance(values: &[f64], ddof: usize) -> Option<f64> {
150 if values.len() <= ddof {
151 return None;
152 }
153 let mean = values.iter().sum::<f64>() / values.len() as f64;
154 Some(
155 values
156 .iter()
157 .map(|value| (value - mean).powi(2))
158 .sum::<f64>()
159 / (values.len() - ddof) as f64,
160 )
161}
162
163#[cfg(test)]
164mod tests {
165 use super::*;
166
167 #[test]
168 fn pairwise_matches_skbio_example() {
169 let values = [[1.0, 2.0, 2.0], [2.0, 3.0, 3.0], [2.0, 6.0, 12.0]]
170 .into_iter()
171 .flatten()
172 .map(f64::exp)
173 .collect();
174 let matrix = LabeledMatrix::new(
175 ["s1", "s2", "s3"].map(str::to_owned).to_vec(),
176 ["a", "b", "c"].map(str::to_owned).to_vec(),
177 values,
178 )
179 .unwrap();
180 let result = pairwise_vlr(&matrix, 1).unwrap();
181 let expected = [0.0, 3.0, 27.0, 3.0, 0.0, 12.0, 27.0, 12.0, 0.0];
182 for (&actual, expected) in result.values().iter().zip(expected) {
183 assert!((actual - expected).abs() < 1e-10, "{actual} != {expected}");
184 }
185 }
186
187 #[test]
188 fn robust_pair_masks_zeros_and_missing() {
189 let matrix = LabeledMatrix::new(
190 ["s1", "s2", "s3", "s4"].map(str::to_owned).to_vec(),
191 vec!["a".into(), "b".into()],
192 vec![1.0, 2.0, 0.0, 4.0, f64::NAN, 2.0, 3.0, 6.0],
193 )
194 .unwrap();
195 assert!(vlr(&matrix, "a", "b", 1, true).unwrap().abs() < 1e-15);
196 assert!(vlr(&matrix, "a", "b", 1, false).is_err());
197 }
198
199 #[test]
200 fn pairwise_limit_fails_before_working_storage() {
201 let matrix = LabeledMatrix::new(
202 vec!["s1".into(), "s2".into()],
203 vec!["a".into(), "b".into()],
204 vec![1.0, 2.0, 2.0, 3.0],
205 )
206 .unwrap();
207 assert!(matches!(
208 pairwise_vlr_with_limit(&matrix, 1, 3),
209 Err(CompositionError::DenseMatrixTooLarge { .. })
210 ));
211 }
212}