Skip to main content

rsomics_composition/
proportionality.rs

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(&centered[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}