use rayon::prelude::*;
use crate::{CompositionError, LabeledMatrix, Result};
#[derive(Clone, Debug, PartialEq)]
pub struct VlrMatrix {
components: Vec<String>,
values: Vec<f64>,
}
impl VlrMatrix {
#[must_use]
pub fn components(&self) -> &[String] {
&self.components
}
#[must_use]
pub fn values(&self) -> &[f64] {
&self.values
}
#[must_use]
pub fn get(&self, left: usize, right: usize) -> Option<f64> {
let width = self.components.len();
self.values.get(left.checked_mul(width)? + right).copied()
}
}
pub fn vlr(
matrix: &LabeledMatrix,
left: &str,
right: &str,
ddof: usize,
robust: bool,
) -> Result<f64> {
let left = component_index(matrix, left)?;
let right = component_index(matrix, right)?;
let mut differences = Vec::with_capacity(matrix.sample_count());
for (row_index, row) in matrix.rows().enumerate() {
let x = row[left];
let y = row[right];
if robust && (x == 0.0 || y == 0.0 || x.is_nan() || y.is_nan()) {
continue;
}
for (column, value) in [(left, x), (right, y)] {
if !value.is_finite() || value <= 0.0 {
return Err(CompositionError::InvalidComponent {
sample: matrix.samples()[row_index].clone(),
component: matrix.components()[column].clone(),
value,
requirement: if robust {
"positive, finite, zero, or NaN-missing"
} else {
"strictly positive and finite"
},
});
}
}
differences.push(x.ln() - y.ln());
}
variance(&differences, ddof).ok_or(CompositionError::NoDegreesOfFreedom {
ddof,
observations: differences.len(),
})
}
pub fn pairwise_vlr(matrix: &LabeledMatrix, ddof: usize) -> Result<VlrMatrix> {
pairwise_vlr_with_limit(matrix, ddof, crate::DEFAULT_MAX_DENSE_CELLS)
}
pub fn pairwise_vlr_with_limit(
matrix: &LabeledMatrix,
ddof: usize,
maximum_cells: usize,
) -> Result<VlrMatrix> {
if matrix.sample_count() <= ddof {
return Err(CompositionError::NoDegreesOfFreedom {
ddof,
observations: matrix.sample_count(),
});
}
let samples = matrix.sample_count();
let components = matrix.component_count();
let mut values = crate::limits::dense_vec(
"pairwise VLR matrix",
components,
components,
maximum_cells,
0.0,
)?;
let mut centered = vec![0.0; samples * components];
for column in 0..components {
let mut mean = 0.0;
for row in 0..samples {
let value = matrix.values()[row * components + column];
if !value.is_finite() || value <= 0.0 {
return Err(CompositionError::InvalidComponent {
sample: matrix.samples()[row].clone(),
component: matrix.components()[column].clone(),
value,
requirement: "strictly positive and finite",
});
}
let logged = value.ln();
centered[column * samples + row] = logged;
mean += logged;
}
mean /= samples as f64;
for row in 0..samples {
centered[column * samples + row] -= mean;
}
}
let denominator = (samples - ddof) as f64;
let variances: Vec<f64> = centered
.par_chunks(samples)
.map(|column| column.iter().map(|value| value * value).sum::<f64>() / denominator)
.collect();
values
.par_chunks_mut(components)
.enumerate()
.for_each(|(left, row)| {
for right in 0..components {
if left == right {
continue;
}
let covariance: f64 = centered[left * samples..(left + 1) * samples]
.iter()
.zip(¢ered[right * samples..(right + 1) * samples])
.map(|(&x, &y)| x * y)
.sum::<f64>()
/ denominator;
row[right] = (variances[left] + variances[right] - 2.0 * covariance).max(0.0);
}
});
Ok(VlrMatrix {
components: matrix.components().to_vec(),
values,
})
}
fn component_index(matrix: &LabeledMatrix, component: &str) -> Result<usize> {
matrix
.components()
.iter()
.position(|candidate| candidate == component)
.ok_or_else(|| CompositionError::UnknownComponent(component.to_owned()))
}
fn variance(values: &[f64], ddof: usize) -> Option<f64> {
if values.len() <= ddof {
return None;
}
let mean = values.iter().sum::<f64>() / values.len() as f64;
Some(
values
.iter()
.map(|value| (value - mean).powi(2))
.sum::<f64>()
/ (values.len() - ddof) as f64,
)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn pairwise_matches_skbio_example() {
let values = [[1.0, 2.0, 2.0], [2.0, 3.0, 3.0], [2.0, 6.0, 12.0]]
.into_iter()
.flatten()
.map(f64::exp)
.collect();
let matrix = LabeledMatrix::new(
["s1", "s2", "s3"].map(str::to_owned).to_vec(),
["a", "b", "c"].map(str::to_owned).to_vec(),
values,
)
.unwrap();
let result = pairwise_vlr(&matrix, 1).unwrap();
let expected = [0.0, 3.0, 27.0, 3.0, 0.0, 12.0, 27.0, 12.0, 0.0];
for (&actual, expected) in result.values().iter().zip(expected) {
assert!((actual - expected).abs() < 1e-10, "{actual} != {expected}");
}
}
#[test]
fn robust_pair_masks_zeros_and_missing() {
let matrix = LabeledMatrix::new(
["s1", "s2", "s3", "s4"].map(str::to_owned).to_vec(),
vec!["a".into(), "b".into()],
vec![1.0, 2.0, 0.0, 4.0, f64::NAN, 2.0, 3.0, 6.0],
)
.unwrap();
assert!(vlr(&matrix, "a", "b", 1, true).unwrap().abs() < 1e-15);
assert!(vlr(&matrix, "a", "b", 1, false).is_err());
}
#[test]
fn pairwise_limit_fails_before_working_storage() {
let matrix = LabeledMatrix::new(
vec!["s1".into(), "s2".into()],
vec!["a".into(), "b".into()],
vec![1.0, 2.0, 2.0, 3.0],
)
.unwrap();
assert!(matches!(
pairwise_vlr_with_limit(&matrix, 1, 3),
Err(CompositionError::DenseMatrixTooLarge { .. })
));
}
}