rsomics-composition 0.1.0

Compositional-data geometry, transforms, and differential abundance
Documentation
use std::collections::{HashMap, HashSet};
use std::io::{Read, Write};

use crate::{CompositionError, Result};

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum DelimitedFormat {
    Tsv,
    Csv,
}

impl DelimitedFormat {
    pub(crate) const fn delimiter(self) -> u8 {
        match self {
            Self::Tsv => b'\t',
            Self::Csv => b',',
        }
    }
}

#[derive(Clone, Debug, PartialEq)]
pub struct LabeledMatrix {
    samples: Vec<String>,
    components: Vec<String>,
    values: Vec<f64>,
}

impl LabeledMatrix {
    pub fn new(samples: Vec<String>, components: Vec<String>, values: Vec<f64>) -> Result<Self> {
        if samples.is_empty() || components.is_empty() {
            return Err(CompositionError::EmptyMatrix);
        }
        validate_identities("sample", &samples)?;
        validate_identities("component", &components)?;
        let expected =
            samples
                .len()
                .checked_mul(components.len())
                .ok_or(CompositionError::Shape {
                    samples: samples.len(),
                    components: components.len(),
                    values: values.len(),
                    expected: usize::MAX,
                })?;
        if values.len() != expected {
            return Err(CompositionError::Shape {
                samples: samples.len(),
                components: components.len(),
                values: values.len(),
                expected,
            });
        }
        Ok(Self {
            samples,
            components,
            values,
        })
    }

    pub fn read(reader: impl Read, format: DelimitedFormat) -> Result<Self> {
        let mut parser = csv::ReaderBuilder::new()
            .delimiter(format.delimiter())
            .has_headers(true)
            .flexible(true)
            .from_reader(reader);
        let header = parser
            .headers()
            .map_err(|error| CompositionError::Delimited(error.to_string()))?
            .clone();
        if header.is_empty() {
            return Err(CompositionError::MissingHeader);
        }
        if header.len() < 2 || header.get(0).is_none_or(str::is_empty) {
            return Err(CompositionError::InvalidHeader);
        }
        let components: Vec<String> = header.iter().skip(1).map(str::to_owned).collect();
        let mut samples = Vec::new();
        let mut values = Vec::new();
        for record in parser.records() {
            let record = record.map_err(|error| CompositionError::Delimited(error.to_string()))?;
            let sample = record.get(0).unwrap_or_default();
            if record.len() != components.len() + 1 {
                return Err(CompositionError::RaggedRow {
                    row: sample.to_owned(),
                    found: record.len().saturating_sub(1),
                    expected: components.len(),
                });
            }
            samples.push(sample.to_owned());
            for (component, field) in components.iter().zip(record.iter().skip(1)) {
                let value = field
                    .parse::<f64>()
                    .map_err(|_| CompositionError::InvalidNumber {
                        sample: sample.to_owned(),
                        component: component.clone(),
                        value: field.to_owned(),
                    })?;
                values.push(value);
            }
        }
        Self::new(samples, components, values)
    }

    pub fn write(&self, writer: impl Write, format: DelimitedFormat) -> Result<()> {
        let mut output = csv::WriterBuilder::new()
            .delimiter(format.delimiter())
            .from_writer(writer);
        let header = std::iter::once("sample").chain(self.components.iter().map(String::as_str));
        output
            .write_record(header)
            .map_err(|error| CompositionError::Io(error.to_string()))?;
        for (sample, row) in self.samples.iter().zip(self.rows()) {
            let mut record = Vec::with_capacity(row.len() + 1);
            record.push(sample.clone());
            record.extend(row.iter().map(ToString::to_string));
            output
                .write_record(record)
                .map_err(|error| CompositionError::Io(error.to_string()))?;
        }
        output
            .flush()
            .map_err(|error| CompositionError::Io(error.to_string()))
    }

    #[must_use]
    pub fn samples(&self) -> &[String] {
        &self.samples
    }

    #[must_use]
    pub fn components(&self) -> &[String] {
        &self.components
    }

    #[must_use]
    pub fn values(&self) -> &[f64] {
        &self.values
    }

    #[must_use]
    pub fn sample_count(&self) -> usize {
        self.samples.len()
    }

    #[must_use]
    pub fn component_count(&self) -> usize {
        self.components.len()
    }

    #[must_use]
    pub fn row(&self, index: usize) -> Option<&[f64]> {
        let width = self.component_count();
        self.values
            .get(index.checked_mul(width)?..(index + 1).checked_mul(width)?)
    }

    pub fn rows(&self) -> impl ExactSizeIterator<Item = &[f64]> {
        self.values.chunks_exact(self.component_count())
    }

    pub(crate) fn shaped(&self, components: Vec<String>, values: Vec<f64>) -> Result<Self> {
        Self::new(self.samples.clone(), components, values)
    }

    pub(crate) fn same_shape(&self, values: Vec<f64>) -> Result<Self> {
        self.shaped(self.components.clone(), values)
    }

    pub(crate) fn component_order_for(&self, other: &Self) -> Result<Vec<usize>> {
        align_order(
            "component",
            &self.components,
            &other.components,
            |details| CompositionError::ComponentMismatch { details },
        )
    }

    pub(crate) fn sample_order_for(&self, other: &Self) -> Result<Vec<usize>> {
        align_order("sample", &self.samples, &other.samples, |details| {
            CompositionError::SampleMismatch { details }
        })
    }
}

fn validate_identities(kind: &'static str, identities: &[String]) -> Result<()> {
    let mut seen = HashSet::with_capacity(identities.len());
    for identity in identities {
        if identity.is_empty() {
            return Err(CompositionError::EmptyIdentity { kind });
        }
        if !seen.insert(identity) {
            return Err(CompositionError::DuplicateIdentity {
                kind,
                identity: identity.clone(),
            });
        }
    }
    Ok(())
}

fn align_order(
    kind: &str,
    target: &[String],
    source: &[String],
    error: impl FnOnce(String) -> CompositionError,
) -> Result<Vec<usize>> {
    if target.len() != source.len() {
        return Err(error(format!(
            "left has {} {kind}s and right has {}",
            target.len(),
            source.len()
        )));
    }
    let source_index: HashMap<&str, usize> = source
        .iter()
        .enumerate()
        .map(|(index, identity)| (identity.as_str(), index))
        .collect();
    let mut order = Vec::with_capacity(target.len());
    for identity in target {
        let Some(&index) = source_index.get(identity.as_str()) else {
            return Err(error(format!("right is missing {kind} {identity:?}")));
        };
        order.push(index);
    }
    Ok(order)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn strict_tsv_round_trip() {
        let source = "sample\ta\tb\ns1\t1\t2.5\ns2\t3\t4\n";
        let table = LabeledMatrix::read(source.as_bytes(), DelimitedFormat::Tsv).unwrap();
        let mut output = Vec::new();
        table.write(&mut output, DelimitedFormat::Tsv).unwrap();
        let round_trip = LabeledMatrix::read(output.as_slice(), DelimitedFormat::Tsv).unwrap();
        assert_eq!(table, round_trip);
    }

    #[test]
    fn csv_quotes_identities() {
        let table = LabeledMatrix::new(
            vec!["sample,one".into()],
            vec!["feature,one".into()],
            vec![2.0],
        )
        .unwrap();
        let mut output = Vec::new();
        table.write(&mut output, DelimitedFormat::Csv).unwrap();
        assert_eq!(
            LabeledMatrix::read(output.as_slice(), DelimitedFormat::Csv).unwrap(),
            table
        );
    }

    #[test]
    fn identities_and_shape_are_checked() {
        assert!(matches!(
            LabeledMatrix::new(
                vec!["s".into()],
                vec!["x".into(), "x".into()],
                vec![1.0, 2.0]
            ),
            Err(CompositionError::DuplicateIdentity { .. })
        ));
        assert!(matches!(
            LabeledMatrix::new(vec!["s".into()], vec!["x".into()], vec![]),
            Err(CompositionError::Shape { .. })
        ));
    }

    #[test]
    fn component_alignment_is_identity_based() {
        let left = LabeledMatrix::new(
            vec!["s".into()],
            vec!["a".into(), "b".into()],
            vec![1.0, 2.0],
        )
        .unwrap();
        let right = LabeledMatrix::new(
            vec!["s".into()],
            vec!["b".into(), "a".into()],
            vec![3.0, 4.0],
        )
        .unwrap();
        assert_eq!(left.component_order_for(&right).unwrap(), [1, 0]);
    }
}