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]);
}
}