Skip to main content

rsomics_composition/
table.rs

1use std::collections::{HashMap, HashSet};
2use std::io::{Read, Write};
3
4use crate::{CompositionError, Result};
5
6#[derive(Clone, Copy, Debug, Eq, PartialEq)]
7pub enum DelimitedFormat {
8    Tsv,
9    Csv,
10}
11
12impl DelimitedFormat {
13    pub(crate) const fn delimiter(self) -> u8 {
14        match self {
15            Self::Tsv => b'\t',
16            Self::Csv => b',',
17        }
18    }
19}
20
21#[derive(Clone, Debug, PartialEq)]
22pub struct LabeledMatrix {
23    samples: Vec<String>,
24    components: Vec<String>,
25    values: Vec<f64>,
26}
27
28impl LabeledMatrix {
29    pub fn new(samples: Vec<String>, components: Vec<String>, values: Vec<f64>) -> Result<Self> {
30        if samples.is_empty() || components.is_empty() {
31            return Err(CompositionError::EmptyMatrix);
32        }
33        validate_identities("sample", &samples)?;
34        validate_identities("component", &components)?;
35        let expected =
36            samples
37                .len()
38                .checked_mul(components.len())
39                .ok_or(CompositionError::Shape {
40                    samples: samples.len(),
41                    components: components.len(),
42                    values: values.len(),
43                    expected: usize::MAX,
44                })?;
45        if values.len() != expected {
46            return Err(CompositionError::Shape {
47                samples: samples.len(),
48                components: components.len(),
49                values: values.len(),
50                expected,
51            });
52        }
53        Ok(Self {
54            samples,
55            components,
56            values,
57        })
58    }
59
60    pub fn read(reader: impl Read, format: DelimitedFormat) -> Result<Self> {
61        let mut parser = csv::ReaderBuilder::new()
62            .delimiter(format.delimiter())
63            .has_headers(true)
64            .flexible(true)
65            .from_reader(reader);
66        let header = parser
67            .headers()
68            .map_err(|error| CompositionError::Delimited(error.to_string()))?
69            .clone();
70        if header.is_empty() {
71            return Err(CompositionError::MissingHeader);
72        }
73        if header.len() < 2 || header.get(0).is_none_or(str::is_empty) {
74            return Err(CompositionError::InvalidHeader);
75        }
76        let components: Vec<String> = header.iter().skip(1).map(str::to_owned).collect();
77        let mut samples = Vec::new();
78        let mut values = Vec::new();
79        for record in parser.records() {
80            let record = record.map_err(|error| CompositionError::Delimited(error.to_string()))?;
81            let sample = record.get(0).unwrap_or_default();
82            if record.len() != components.len() + 1 {
83                return Err(CompositionError::RaggedRow {
84                    row: sample.to_owned(),
85                    found: record.len().saturating_sub(1),
86                    expected: components.len(),
87                });
88            }
89            samples.push(sample.to_owned());
90            for (component, field) in components.iter().zip(record.iter().skip(1)) {
91                let value = field
92                    .parse::<f64>()
93                    .map_err(|_| CompositionError::InvalidNumber {
94                        sample: sample.to_owned(),
95                        component: component.clone(),
96                        value: field.to_owned(),
97                    })?;
98                values.push(value);
99            }
100        }
101        Self::new(samples, components, values)
102    }
103
104    pub fn write(&self, writer: impl Write, format: DelimitedFormat) -> Result<()> {
105        let mut output = csv::WriterBuilder::new()
106            .delimiter(format.delimiter())
107            .from_writer(writer);
108        let header = std::iter::once("sample").chain(self.components.iter().map(String::as_str));
109        output
110            .write_record(header)
111            .map_err(|error| CompositionError::Io(error.to_string()))?;
112        for (sample, row) in self.samples.iter().zip(self.rows()) {
113            let mut record = Vec::with_capacity(row.len() + 1);
114            record.push(sample.clone());
115            record.extend(row.iter().map(ToString::to_string));
116            output
117                .write_record(record)
118                .map_err(|error| CompositionError::Io(error.to_string()))?;
119        }
120        output
121            .flush()
122            .map_err(|error| CompositionError::Io(error.to_string()))
123    }
124
125    #[must_use]
126    pub fn samples(&self) -> &[String] {
127        &self.samples
128    }
129
130    #[must_use]
131    pub fn components(&self) -> &[String] {
132        &self.components
133    }
134
135    #[must_use]
136    pub fn values(&self) -> &[f64] {
137        &self.values
138    }
139
140    #[must_use]
141    pub fn sample_count(&self) -> usize {
142        self.samples.len()
143    }
144
145    #[must_use]
146    pub fn component_count(&self) -> usize {
147        self.components.len()
148    }
149
150    #[must_use]
151    pub fn row(&self, index: usize) -> Option<&[f64]> {
152        let width = self.component_count();
153        self.values
154            .get(index.checked_mul(width)?..(index + 1).checked_mul(width)?)
155    }
156
157    pub fn rows(&self) -> impl ExactSizeIterator<Item = &[f64]> {
158        self.values.chunks_exact(self.component_count())
159    }
160
161    pub(crate) fn shaped(&self, components: Vec<String>, values: Vec<f64>) -> Result<Self> {
162        Self::new(self.samples.clone(), components, values)
163    }
164
165    pub(crate) fn same_shape(&self, values: Vec<f64>) -> Result<Self> {
166        self.shaped(self.components.clone(), values)
167    }
168
169    pub(crate) fn component_order_for(&self, other: &Self) -> Result<Vec<usize>> {
170        align_order(
171            "component",
172            &self.components,
173            &other.components,
174            |details| CompositionError::ComponentMismatch { details },
175        )
176    }
177
178    pub(crate) fn sample_order_for(&self, other: &Self) -> Result<Vec<usize>> {
179        align_order("sample", &self.samples, &other.samples, |details| {
180            CompositionError::SampleMismatch { details }
181        })
182    }
183}
184
185fn validate_identities(kind: &'static str, identities: &[String]) -> Result<()> {
186    let mut seen = HashSet::with_capacity(identities.len());
187    for identity in identities {
188        if identity.is_empty() {
189            return Err(CompositionError::EmptyIdentity { kind });
190        }
191        if !seen.insert(identity) {
192            return Err(CompositionError::DuplicateIdentity {
193                kind,
194                identity: identity.clone(),
195            });
196        }
197    }
198    Ok(())
199}
200
201fn align_order(
202    kind: &str,
203    target: &[String],
204    source: &[String],
205    error: impl FnOnce(String) -> CompositionError,
206) -> Result<Vec<usize>> {
207    if target.len() != source.len() {
208        return Err(error(format!(
209            "left has {} {kind}s and right has {}",
210            target.len(),
211            source.len()
212        )));
213    }
214    let source_index: HashMap<&str, usize> = source
215        .iter()
216        .enumerate()
217        .map(|(index, identity)| (identity.as_str(), index))
218        .collect();
219    let mut order = Vec::with_capacity(target.len());
220    for identity in target {
221        let Some(&index) = source_index.get(identity.as_str()) else {
222            return Err(error(format!("right is missing {kind} {identity:?}")));
223        };
224        order.push(index);
225    }
226    Ok(order)
227}
228
229#[cfg(test)]
230mod tests {
231    use super::*;
232
233    #[test]
234    fn strict_tsv_round_trip() {
235        let source = "sample\ta\tb\ns1\t1\t2.5\ns2\t3\t4\n";
236        let table = LabeledMatrix::read(source.as_bytes(), DelimitedFormat::Tsv).unwrap();
237        let mut output = Vec::new();
238        table.write(&mut output, DelimitedFormat::Tsv).unwrap();
239        let round_trip = LabeledMatrix::read(output.as_slice(), DelimitedFormat::Tsv).unwrap();
240        assert_eq!(table, round_trip);
241    }
242
243    #[test]
244    fn csv_quotes_identities() {
245        let table = LabeledMatrix::new(
246            vec!["sample,one".into()],
247            vec!["feature,one".into()],
248            vec![2.0],
249        )
250        .unwrap();
251        let mut output = Vec::new();
252        table.write(&mut output, DelimitedFormat::Csv).unwrap();
253        assert_eq!(
254            LabeledMatrix::read(output.as_slice(), DelimitedFormat::Csv).unwrap(),
255            table
256        );
257    }
258
259    #[test]
260    fn identities_and_shape_are_checked() {
261        assert!(matches!(
262            LabeledMatrix::new(
263                vec!["s".into()],
264                vec!["x".into(), "x".into()],
265                vec![1.0, 2.0]
266            ),
267            Err(CompositionError::DuplicateIdentity { .. })
268        ));
269        assert!(matches!(
270            LabeledMatrix::new(vec!["s".into()], vec!["x".into()], vec![]),
271            Err(CompositionError::Shape { .. })
272        ));
273    }
274
275    #[test]
276    fn component_alignment_is_identity_based() {
277        let left = LabeledMatrix::new(
278            vec!["s".into()],
279            vec!["a".into(), "b".into()],
280            vec![1.0, 2.0],
281        )
282        .unwrap();
283        let right = LabeledMatrix::new(
284            vec!["s".into()],
285            vec!["b".into(), "a".into()],
286            vec![3.0, 4.0],
287        )
288        .unwrap();
289        assert_eq!(left.component_order_for(&right).unwrap(), [1, 0]);
290    }
291}