1use std::collections::{HashMap, HashSet};
2
3use rsomics_bamio::raw::RawRecord;
4
5use crate::{CallError, Result};
6
7#[derive(Clone, Debug, Default)]
8pub struct SampleSelection {
9 mode: SelectionMode,
10}
11
12#[derive(Clone, Debug, Default)]
13enum SelectionMode {
14 #[default]
15 All,
16 Include(HashMap<Box<str>, Box<str>>),
17 Exclude(HashSet<Box<str>>),
18}
19
20impl SampleSelection {
21 pub fn include<N, O>(samples: impl IntoIterator<Item = (N, Option<O>)>) -> Result<Self>
22 where
23 N: Into<Box<str>>,
24 O: Into<Box<str>>,
25 {
26 let mut selected = HashMap::new();
27 for (name, output) in samples {
28 let name = name.into();
29 validate_sample_name(&name)?;
30 let output = output.map_or_else(|| name.clone(), Into::into);
31 validate_sample_name(&output)?;
32 if selected.insert(name.clone(), output).is_some() {
33 return Err(CallError::DuplicateSampleSelection(name.into()));
34 }
35 }
36 if selected.is_empty() {
37 return Err(CallError::InvalidSampleCount);
38 }
39 Ok(Self {
40 mode: SelectionMode::Include(selected),
41 })
42 }
43
44 pub fn exclude(samples: impl IntoIterator<Item = impl Into<Box<str>>>) -> Result<Self> {
45 let mut selected = HashSet::new();
46 for name in samples {
47 let name = name.into();
48 validate_sample_name(&name)?;
49 if !selected.insert(name.clone()) {
50 return Err(CallError::DuplicateSampleSelection(name.into()));
51 }
52 }
53 if selected.is_empty() {
54 return Err(CallError::InvalidSampleCount);
55 }
56 Ok(Self {
57 mode: SelectionMode::Exclude(selected),
58 })
59 }
60}
61
62#[derive(Debug)]
63pub struct SampleMapBuilder {
64 selection: SampleSelection,
65 seen: HashSet<Box<str>>,
66 samples: Vec<Box<str>>,
67 sample_indices: HashMap<Box<str>, usize>,
68 sources: HashMap<u32, SourceSamples>,
69}
70
71impl SampleMapBuilder {
72 pub fn new(selection: SampleSelection) -> Self {
73 Self {
74 selection,
75 seen: HashSet::new(),
76 samples: Vec::new(),
77 sample_indices: HashMap::new(),
78 sources: HashMap::new(),
79 }
80 }
81
82 pub fn add_source<I, R, S>(
83 &mut self,
84 source_id: u32,
85 name: impl Into<Box<str>>,
86 ignore_read_groups: bool,
87 read_groups: I,
88 ) -> Result<()>
89 where
90 I: IntoIterator<Item = (R, S)>,
91 R: Into<Box<[u8]>>,
92 S: Into<Box<str>>,
93 {
94 if self.sources.contains_key(&source_id) {
95 return Err(CallError::DuplicateAlignmentSource(source_id));
96 }
97 let name = name.into();
98 validate_sample_name(&name)?;
99 if ignore_read_groups {
100 let default = self.select_sample(name);
101 self.sources.insert(
102 source_id,
103 SourceSamples {
104 default,
105 fallback: default,
106 read_groups: HashMap::new(),
107 },
108 );
109 return Ok(());
110 }
111
112 let mut groups = HashMap::new();
113 let mut fallback = None;
114 let mut group_count = 0;
115 let mut all_same = true;
116 let mut first_mapping = None;
117 for (read_group, sample) in read_groups {
118 group_count += 1;
119 let read_group = read_group.into();
120 validate_read_group(&read_group)?;
121 let sample = sample.into();
122 validate_sample_name(&sample)?;
123 let mapping = self.select_sample(sample);
124 if fallback.is_none() {
125 fallback = mapping;
126 }
127 match first_mapping {
128 None => first_mapping = Some(mapping),
129 Some(first) if first != mapping => all_same = false,
130 Some(_) => {}
131 }
132 if groups.insert(read_group.clone(), mapping).is_some() {
133 return Err(CallError::InvalidReadGroup(
134 String::from_utf8_lossy(&read_group).into_owned(),
135 ));
136 }
137 }
138
139 if group_count == 0 {
140 let default = self.select_sample(name);
141 self.sources.insert(
142 source_id,
143 SourceSamples {
144 default,
145 fallback: default,
146 read_groups: groups,
147 },
148 );
149 } else {
150 let default = if all_same {
151 first_mapping.flatten()
152 } else {
153 None
154 };
155 self.sources.insert(
156 source_id,
157 SourceSamples {
158 default,
159 fallback,
160 read_groups: groups,
161 },
162 );
163 }
164 Ok(())
165 }
166
167 pub fn finish(self) -> Result<SampleMap> {
168 if let SelectionMode::Include(selected) = &self.selection.mode
169 && let Some(missing) = selected
170 .keys()
171 .filter(|name| !self.seen.contains(*name))
172 .min()
173 {
174 return Err(CallError::MissingSelectedSample(missing.to_string()));
175 }
176 if self.samples.is_empty() {
177 return Err(CallError::InvalidSampleCount);
178 }
179 Ok(SampleMap {
180 samples: self.samples.into_boxed_slice(),
181 sources: self.sources,
182 })
183 }
184
185 fn select_sample(&mut self, name: Box<str>) -> Option<usize> {
186 self.seen.insert(name.clone());
187 let output = match &self.selection.mode {
188 SelectionMode::All => Some(name),
189 SelectionMode::Include(selected) => selected.get(&name).cloned(),
190 SelectionMode::Exclude(excluded) => (!excluded.contains(&name)).then_some(name),
191 };
192 output.map(|name| self.intern_sample(name))
193 }
194
195 fn intern_sample(&mut self, name: Box<str>) -> usize {
196 if let Some(&index) = self.sample_indices.get(&name) {
197 return index;
198 }
199 let index = self.samples.len();
200 self.samples.push(name.clone());
201 self.sample_indices.insert(name, index);
202 index
203 }
204}
205
206#[derive(Debug)]
207pub struct SampleMap {
208 samples: Box<[Box<str>]>,
209 sources: HashMap<u32, SourceSamples>,
210}
211
212impl SampleMap {
213 pub fn samples(&self) -> &[Box<str>] {
214 &self.samples
215 }
216
217 pub fn sample_index(&self, source_id: u32, record: &RawRecord) -> Result<Option<usize>> {
218 let source = if self.sources.len() == 1 {
219 let (&expected, source) = self.sources.iter().next().unwrap();
220 if source_id != expected {
221 return Err(CallError::UnknownAlignmentSource(source_id));
222 }
223 source
224 } else {
225 self.sources
226 .get(&source_id)
227 .ok_or(CallError::UnknownAlignmentSource(source_id))?
228 };
229 if source.default.is_some() {
230 return Ok(source.default);
231 }
232 let Some(raw) = record.aux_value(*b"RG") else {
233 return Ok(source.fallback);
234 };
235 if record.aux_type(*b"RG") != Some(b'Z') {
236 return Err(CallError::InvalidReadGroupField);
237 }
238 let read_group = raw
239 .strip_suffix(&[0])
240 .filter(|value| !value.is_empty())
241 .ok_or(CallError::InvalidReadGroupField)?;
242 Ok(source
243 .read_groups
244 .get(read_group)
245 .copied()
246 .unwrap_or(source.fallback))
247 }
248}
249
250#[derive(Debug)]
251struct SourceSamples {
252 default: Option<usize>,
253 fallback: Option<usize>,
254 read_groups: HashMap<Box<[u8]>, Option<usize>>,
255}
256
257pub(crate) fn validate_sample_name(name: &str) -> Result<()> {
258 if name.is_empty()
259 || name
260 .bytes()
261 .any(|byte| matches!(byte, 0 | b'\t' | b'\n' | b'\r'))
262 {
263 Err(CallError::InvalidSampleName(name.to_owned()))
264 } else {
265 Ok(())
266 }
267}
268
269fn validate_read_group(read_group: &[u8]) -> Result<()> {
270 if read_group.is_empty()
271 || matches!(read_group, b"*" | b"?")
272 || read_group
273 .iter()
274 .any(|byte| matches!(byte, 0 | b'\t' | b'\n' | b'\r'))
275 {
276 Err(CallError::InvalidReadGroup(
277 String::from_utf8_lossy(read_group).into_owned(),
278 ))
279 } else {
280 Ok(())
281 }
282}
283
284#[cfg(test)]
285mod tests {
286 use super::*;
287
288 fn record(read_group: Option<(&[u8], u8)>) -> RawRecord {
289 let mut record = RawRecord::default();
290 if let Some((read_group, kind)) = read_group {
291 let mut value = read_group.to_vec();
292 if kind == b'Z' {
293 value.push(0);
294 }
295 record.append_aux(*b"RG", kind, &value).unwrap();
296 }
297 record
298 }
299
300 #[test]
301 fn read_groups_merge_samples_across_sources() {
302 let mut builder = SampleMapBuilder::new(SampleSelection::default());
303 builder
304 .add_source(
305 4,
306 "first.bam",
307 false,
308 [(b"rg1".as_slice(), "S1"), (b"rg2".as_slice(), "S2")],
309 )
310 .unwrap();
311 builder
312 .add_source(9, "second.bam", false, [(b"rg3".as_slice(), "S1")])
313 .unwrap();
314 let samples = builder.finish().unwrap();
315
316 assert_eq!(
317 samples
318 .samples()
319 .iter()
320 .map(AsRef::as_ref)
321 .collect::<Vec<_>>(),
322 ["S1", "S2"]
323 );
324 assert_eq!(
325 samples.sample_index(4, &record(Some((b"rg2", b'Z')))),
326 Ok(Some(1))
327 );
328 assert_eq!(
329 samples.sample_index(9, &record(Some((b"rg3", b'Z')))),
330 Ok(Some(0))
331 );
332 assert_eq!(samples.sample_index(4, &record(None)), Ok(Some(0)));
333 }
334
335 #[test]
336 fn ignored_read_groups_use_one_sample_per_input() {
337 let mut builder = SampleMapBuilder::new(SampleSelection::default());
338 builder
339 .add_source(3, "input.bam", true, [(b"rg".as_slice(), "header-sample")])
340 .unwrap();
341 let samples = builder.finish().unwrap();
342
343 assert_eq!(samples.samples()[0].as_ref(), "input.bam");
344 assert_eq!(
345 samples.sample_index(3, &record(Some((b"rg", b'Z')))),
346 Ok(Some(0))
347 );
348 }
349
350 #[test]
351 fn inclusion_renames_and_excludes_read_groups() {
352 let selection = SampleSelection::include([("S2", Some("renamed")), ("S3", None)]).unwrap();
353 let mut builder = SampleMapBuilder::new(selection);
354 builder
355 .add_source(
356 0,
357 "input.bam",
358 false,
359 [
360 (b"one".as_slice(), "S1"),
361 (b"two".as_slice(), "S2"),
362 (b"three".as_slice(), "S3"),
363 ],
364 )
365 .unwrap();
366 let samples = builder.finish().unwrap();
367
368 assert_eq!(
369 samples
370 .samples()
371 .iter()
372 .map(AsRef::as_ref)
373 .collect::<Vec<_>>(),
374 ["renamed", "S3"]
375 );
376 assert_eq!(
377 samples.sample_index(0, &record(Some((b"one", b'Z')))),
378 Ok(None)
379 );
380 assert_eq!(
381 samples.sample_index(0, &record(Some((b"two", b'Z')))),
382 Ok(Some(0))
383 );
384 assert_eq!(
385 samples.sample_index(0, &record(Some((b"unknown", b'Z')))),
386 Ok(Some(0))
387 );
388 }
389
390 #[test]
391 fn exclusion_and_duplicate_boundaries_are_checked() {
392 let selection = SampleSelection::exclude(["S2"]).unwrap();
393 let mut builder = SampleMapBuilder::new(selection);
394 builder
395 .add_source(
396 0,
397 "input.bam",
398 false,
399 [(b"one".as_slice(), "S1"), (b"two".as_slice(), "S2")],
400 )
401 .unwrap();
402 assert_eq!(
403 builder.add_source(0, "duplicate.bam", false, Vec::<(&[u8], &str)>::new(),),
404 Err(CallError::DuplicateAlignmentSource(0))
405 );
406 let samples = builder.finish().unwrap();
407 assert_eq!(samples.samples()[0].as_ref(), "S1");
408 assert_eq!(
409 samples.sample_index(0, &record(Some((b"two", b'Z')))),
410 Ok(None)
411 );
412
413 let mut duplicate = SampleMapBuilder::new(SampleSelection::default());
414 assert!(matches!(
415 duplicate.add_source(
416 1,
417 "input.bam",
418 false,
419 [(b"rg".as_slice(), "S1"), (b"rg".as_slice(), "S2")],
420 ),
421 Err(CallError::InvalidReadGroup(_))
422 ));
423 }
424
425 #[test]
426 fn invalid_source_selection_and_rg_fields_fail() {
427 let selection = SampleSelection::include([("absent", None::<&str>)]).unwrap();
428 let mut missing = SampleMapBuilder::new(selection);
429 missing
430 .add_source(0, "input.bam", false, [(b"rg".as_slice(), "S1")])
431 .unwrap();
432 assert_eq!(
433 missing.finish().unwrap_err(),
434 CallError::MissingSelectedSample("absent".to_owned())
435 );
436
437 let mut builder = SampleMapBuilder::new(SampleSelection::default());
438 builder
439 .add_source(
440 0,
441 "input.bam",
442 false,
443 [(b"rg".as_slice(), "S1"), (b"rg2".as_slice(), "S2")],
444 )
445 .unwrap();
446 let samples = builder.finish().unwrap();
447 assert_eq!(
448 samples.sample_index(1, &record(None)),
449 Err(CallError::UnknownAlignmentSource(1))
450 );
451 assert_eq!(
452 samples.sample_index(0, &record(Some((b"x", b'A')))),
453 Err(CallError::InvalidReadGroupField)
454 );
455 }
456}