rsomics-composition 0.1.0

Compositional-data geometry, transforms, and differential abundance
Documentation
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(&centered[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 { .. })
        ));
    }
}