Skip to main content

rsomics_call/
samples.rs

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}