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}