Skip to main content

pixelator_core/common/
assay.rs

1use rustc_hash::FxHashMap as HashMap;
2use rustc_hash::FxHashSet as HashSet;
3use serde::Deserialize;
4use std::error::Error;
5use std::path::Path;
6use std::str::FromStr;
7
8/// The region_ids that every assay is required to define.
9const REQUIRED_REGIONS: [&str; 5] = ["amplicon", "pid-1", "pid-2", "umi-1", "umi-2"];
10
11/// Type of a region within an assay.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
13#[serde(rename_all = "lowercase")]
14pub enum RegionType {
15    Umi,
16    Pid,
17    Lbs,
18    Uei,
19    Amplicon,
20}
21
22impl FromStr for RegionType {
23    type Err = String;
24
25    fn from_str(s: &str) -> Result<Self, Self::Err> {
26        match s {
27            "umi" => Ok(Self::Umi),
28            "pid" => Ok(Self::Pid),
29            "lbs" => Ok(Self::Lbs),
30            "uei" => Ok(Self::Uei),
31            "amplicon" => Ok(Self::Amplicon),
32            other => Err(format!("unknown region_type '{other}'")),
33        }
34    }
35}
36
37/// How the sequence of a region is determined.
38///
39/// - `Joined`: the sequence is the concatenation of the sub-regions' sequences.
40/// - `Fixed`: the sequence is a fixed, given string.
41/// - `Random`: the sequence is random (typically written as a run of `N`s).
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
43#[serde(rename_all = "lowercase")]
44pub enum SequenceType {
45    Joined,
46    Fixed,
47    Random,
48}
49
50impl FromStr for SequenceType {
51    type Err = String;
52
53    fn from_str(s: &str) -> Result<Self, Self::Err> {
54        match s {
55            "joined" => Ok(Self::Joined),
56            "fixed" => Ok(Self::Fixed),
57            "random" => Ok(Self::Random),
58            other => Err(format!("unknown sequence_type '{other}'")),
59        }
60    }
61}
62
63/// A single region of an assay, possibly containing nested sub-regions.
64///
65/// The nested `regions` preserve the order given in the YAML, which is
66/// significant: regions describe the sequential layout of the amplicon.
67#[derive(Debug, Clone, Deserialize)]
68pub struct Region {
69    /// Unique identifier of the region (e.g. `umi-1`).
70    pub region_id: String,
71    /// Type of the region.
72    pub region_type: RegionType,
73    /// Human-readable name of the region.
74    pub name: String,
75    /// How the region's sequence is determined.
76    pub sequence_type: SequenceType,
77    /// String representation of the region's sequence, when applicable.
78    pub sequence: Option<String>,
79    /// Minimum length of the region in bases.
80    pub min_len: Option<usize>,
81    /// Maximum length of the region in bases.
82    pub max_len: Option<usize>,
83    /// Ordered list of nested sub-regions.
84    #[serde(default)]
85    pub regions: Vec<Region>,
86}
87
88/// A parsed assay design: a name and an ordered list of top-level regions.
89#[derive(Debug, Clone, Deserialize)]
90pub struct Assay {
91    /// Name of the assay.
92    pub name: String,
93    /// Ordered list of top-level regions defining the assay structure.
94    pub assay_spec: Vec<Region>,
95    /// Precomputed forward slice bounds `(start, end)` per region, keyed by
96    /// `region_id`. Filled in by [`Assay::populate_region_bounds`] after
97    /// parsing; not part of the YAML. Reverse bounds are derived from these
98    /// and `total_len` on demand (see [`Assay::reverse_bounds`]).
99    #[serde(skip)]
100    region_bounds: HashMap<String, (usize, usize)>,
101    /// Total length of the assay read (sum of all leaf region lengths). Used to
102    /// derive reverse bounds from forward bounds. Filled in by
103    /// [`Assay::populate_region_bounds`].
104    #[serde(skip)]
105    total_len: usize,
106}
107
108impl Assay {
109    /// Builds an assay from a name and region tree already in memory.
110    ///
111    /// Validates the region tree and precomputes slice bounds.
112    ///
113    /// # Errors
114    ///
115    /// Returns an error if the assay is structurally invalid: a duplicate
116    /// `region_id`, a missing required region, or a leaf region without a
117    /// `min_len`.
118    pub fn new(name: String, assay_spec: Vec<Region>) -> Result<Self, Box<dyn Error>> {
119        let mut assay = Self {
120            name,
121            assay_spec,
122            region_bounds: HashMap::default(),
123            total_len: 0,
124        };
125        assay.finalize()?;
126        Ok(assay)
127    }
128
129    /// Loads and validates an assay from a YAML file at `path`.
130    ///
131    /// # Errors
132    ///
133    /// Returns an error if the file cannot be read, the YAML cannot be
134    /// deserialized, or the assay is structurally invalid: a duplicate
135    /// `region_id`, a missing required region, or a leaf region without a
136    /// `min_len`.
137    pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Self, Box<dyn Error>> {
138        let text = std::fs::read_to_string(path)?;
139        let mut assay: Self = serde_saphyr::from_str(&text)?;
140        assay.finalize()?;
141        Ok(assay)
142    }
143
144    /// Runs structural checks and fills in slice bounds.
145    ///
146    /// Serde leaves `region_bounds` / `total_len` empty; this is the shared
147    /// step that turns that incomplete value (or a freshly built one) into a
148    /// usable assay.
149    fn finalize(&mut self) -> Result<(), Box<dyn Error>> {
150        self.validate()?;
151        self.populate_region_bounds()
152    }
153
154    /// Precomputes the forward and reverse slice bounds of every region and
155    /// stores them keyed by `region_id`.
156    ///
157    /// Bounds are relative to the start of the whole assay read (all leaf
158    /// regions concatenated). Region lengths use `min_len`, which assumes
159    /// fixed-length regions (matching the Python `get_position_in_parent`).
160    ///
161    /// # Errors
162    ///
163    /// Returns an error if a leaf region has no `min_len`.
164    fn populate_region_bounds(&mut self) -> Result<(), Box<dyn Error>> {
165        let mut forward: HashMap<String, (usize, usize)> = HashMap::default();
166        let mut offset = 0usize;
167        for region in &self.assay_spec {
168            accumulate_bounds(region, &mut offset, &mut forward)?;
169        }
170
171        self.region_bounds = forward;
172        self.total_len = offset;
173        Ok(())
174    }
175
176    /// Forward slice bounds `(s, e)` so that `read[s..e]` extracts the region
177    /// from a forward-oriented assay read. Returns `None` if `region_id` is
178    /// unknown.
179    pub fn forward_bounds(&self, region_id: &str) -> Option<(usize, usize)> {
180        self.region_bounds.get(region_id).copied()
181    }
182
183    /// Reverse slice bounds `(s, e)` so that `read[s..e]` extracts the region
184    /// directly from the raw (non-reverse-complemented) reverse read. The read
185    /// is sequenced from the amplicon 3' end, so these bounds index from the
186    /// start of that read and are independent of read length. Returns `None` if
187    /// `region_id` is unknown.
188    pub fn reverse_bounds(&self, region_id: &str) -> Option<(usize, usize)> {
189        self.region_bounds
190            .get(region_id)
191            .map(|&(start, end)| (self.total_len - end, self.total_len - start))
192    }
193
194    /// Returns the YAML `sequence` string for `region_id`, searching the nested
195    /// region tree. Returns `None` if the id is unknown or the region has no
196    /// sequence.
197    pub fn region_sequence(&self, region_id: &str) -> Option<&str> {
198        fn find<'a>(region: &'a Region, id: &str) -> Option<&'a str> {
199            if region.region_id == id {
200                return region.sequence.as_deref();
201            }
202            region.regions.iter().find_map(|child| find(child, id))
203        }
204        self.assay_spec
205            .iter()
206            .find_map(|region| find(region, region_id))
207    }
208
209    /// Returns the YAML `sequence` strings for every region of type
210    /// `region_type`, searching the nested region tree in document order.
211    ///
212    /// Panics if a matching region has no `sequence`.
213    pub fn region_sequences_by_type(&self, region_type: RegionType) -> Vec<&str> {
214        fn collect<'a>(region: &'a Region, region_type: RegionType, out: &mut Vec<&'a str>) {
215            if region.region_type == region_type {
216                out.push(region.sequence.as_deref().unwrap_or_else(|| {
217                    panic!("No sequence found for region type {region_type:?}")
218                }));
219            }
220            for child in &region.regions {
221                collect(child, region_type, out);
222            }
223        }
224
225        let mut out = Vec::new();
226        for region in &self.assay_spec {
227            collect(region, region_type, &mut out);
228        }
229        out
230    }
231
232    /// Validates structural invariants of the assay:
233    ///
234    /// - every `region_id` is unique across the whole (nested) region tree, and
235    /// - all [`REQUIRED_REGIONS`] are present somewhere in the tree.
236    ///
237    /// # Errors
238    ///
239    /// Returns an error describing the first duplicate `region_id` encountered,
240    /// or the set of required regions that are missing.
241    fn validate(&self) -> Result<(), Box<dyn Error>> {
242        let mut seen: HashSet<&str> = HashSet::default();
243        for region in &self.assay_spec {
244            collect_region_ids(region, &mut seen)?;
245        }
246
247        let missing: Vec<&str> = REQUIRED_REGIONS
248            .iter()
249            .copied()
250            .filter(|id| !seen.contains(id))
251            .collect();
252
253        if !missing.is_empty() {
254            return Err(format!("Missing required regions: {}", missing.join(", ")).into());
255        }
256
257        Ok(())
258    }
259}
260
261/// Recursively records the forward `(start, end)` offsets of `region` and all
262/// its sub-regions into `out`, advancing `offset` by each leaf's `min_len`.
263///
264/// A container region spans from the start of its first leaf to the end of its
265/// last leaf (derived from the offset delta), so its length is the sum of its
266/// leaves' lengths.
267fn accumulate_bounds(
268    region: &Region,
269    offset: &mut usize,
270    out: &mut HashMap<String, (usize, usize)>,
271) -> Result<(), Box<dyn Error>> {
272    let start = *offset;
273    if region.regions.is_empty() {
274        let len = region
275            .min_len
276            .ok_or_else(|| format!("Region {} has no min_len", region.region_id))?;
277        *offset += len;
278    } else {
279        for child in &region.regions {
280            accumulate_bounds(child, offset, out)?;
281        }
282    }
283    out.insert(region.region_id.clone(), (start, *offset));
284    Ok(())
285}
286
287/// Recursively inserts a region's id (and those of its sub-regions) into `seen`,
288/// erroring on the first duplicate.
289fn collect_region_ids<'a>(
290    region: &'a Region,
291    seen: &mut HashSet<&'a str>,
292) -> Result<(), Box<dyn Error>> {
293    if !seen.insert(&region.region_id) {
294        return Err(format!("Duplicate region_id detected: {}", region.region_id).into());
295    }
296
297    for child in &region.regions {
298        collect_region_ids(child, seen)?;
299    }
300
301    Ok(())
302}
303
304#[cfg(test)]
305mod tests {
306    use super::*;
307    use std::io::Write;
308    use std::str::FromStr;
309    use tempfile::NamedTempFile;
310
311    /// A complete, valid assay containing the `amplicon` parent and all seven
312    /// required child regions.
313    const VALID_ASSAY: &str = "\
314name: test-assay
315assay_spec:
316  - region_id: amplicon
317    region_type: amplicon
318    name: amplicon
319    sequence_type: joined
320    regions:
321      - region_id: umi-1
322        region_type: umi
323        name: Unique molecular identifier 1
324        sequence_type: random
325        sequence: NNNNNNNNNNNNNNNNNNNNNNNNNNNN
326        min_len: 28
327        max_len: 28
328      - region_id: pid-1
329        region_type: pid
330        name: Protein identifier 1
331        sequence_type: random
332        sequence: NNNNNNNNNN
333        min_len: 10
334        max_len: 10
335      - region_id: lbs-1
336        region_type: lbs
337        name: Linker binding site 1
338        sequence_type: fixed
339        sequence: CAAGTGACGCTGGTCAAACACTCATGTC
340        min_len: 28
341        max_len: 28
342      - region_id: uei
343        region_type: uei
344        name: Unique event identifier 1
345        sequence_type: random
346        sequence: NNNNNNNNNNNNNNN
347        min_len: 15
348        max_len: 15
349      - region_id: lbs-2
350        region_type: lbs
351        name: Linker binding site 2
352        sequence_type: fixed
353        sequence: CGCTTAGATGTCGG
354        min_len: 14
355        max_len: 14
356      - region_id: pid-2
357        region_type: pid
358        name: Protein identifier 2
359        sequence_type: random
360        sequence: NNNNNNNNNN
361        min_len: 10
362        max_len: 10
363      - region_id: umi-2
364        region_type: umi
365        name: Unique molecular identifier 2
366        sequence_type: random
367        sequence: NNNNNNNNNNNNNNNNNNNNNNNNNNNN
368        min_len: 28
369        max_len: 28
370";
371
372    fn write_fixture(contents: &str) -> NamedTempFile {
373        let mut file = NamedTempFile::new().expect("create temp file");
374        file.write_all(contents.as_bytes()).expect("write fixture");
375        file.flush().expect("flush fixture");
376        file
377    }
378
379    #[test]
380    fn from_path_parses_full_assay() {
381        let file = write_fixture(VALID_ASSAY);
382        let assay = Assay::from_path(file.path()).expect("load assay");
383
384        assert_eq!(assay.name, "test-assay");
385        assert_eq!(assay.assay_spec.len(), 1);
386
387        let amplicon = &assay.assay_spec[0];
388        assert_eq!(amplicon.region_id, "amplicon");
389        assert_eq!(amplicon.region_type, RegionType::Amplicon);
390        assert_eq!(amplicon.sequence_type, SequenceType::Joined);
391        assert_eq!(amplicon.regions.len(), 7);
392
393        // Spot-check a nested region.
394        let uei = &amplicon.regions[3];
395        assert_eq!(uei.region_id, "uei");
396        assert_eq!(uei.region_type, RegionType::Uei);
397        assert_eq!(uei.sequence_type, SequenceType::Random);
398        assert_eq!(uei.sequence.as_deref(), Some("NNNNNNNNNNNNNNN"));
399        assert_eq!(uei.min_len, Some(15));
400        assert_eq!(uei.max_len, Some(15));
401
402        // A fixed region carries its literal sequence.
403        let lbs_2 = &amplicon.regions[4];
404        assert_eq!(lbs_2.region_type, RegionType::Lbs);
405        assert_eq!(lbs_2.sequence_type, SequenceType::Fixed);
406        assert_eq!(lbs_2.sequence.as_deref(), Some("CGCTTAGATGTCGG"));
407    }
408
409    #[test]
410    fn enum_values_deserialize() {
411        #[derive(Deserialize)]
412        struct Wrapper {
413            region_type: RegionType,
414            sequence_type: SequenceType,
415        }
416
417        let cases = [
418            ("umi", RegionType::Umi),
419            ("pid", RegionType::Pid),
420            ("lbs", RegionType::Lbs),
421            ("uei", RegionType::Uei),
422            ("amplicon", RegionType::Amplicon),
423        ];
424        for (raw, expected) in cases {
425            let yaml = format!("region_type: {raw}\nsequence_type: joined\n");
426            let parsed: Wrapper = serde_saphyr::from_str(&yaml).expect("parse enum");
427            assert_eq!(parsed.region_type, expected);
428        }
429
430        let seq_cases = [
431            ("joined", SequenceType::Joined),
432            ("fixed", SequenceType::Fixed),
433            ("random", SequenceType::Random),
434        ];
435        for (raw, expected) in seq_cases {
436            let yaml = format!("region_type: umi\nsequence_type: {raw}\n");
437            let parsed: Wrapper = serde_saphyr::from_str(&yaml).expect("parse enum");
438            assert_eq!(parsed.sequence_type, expected);
439        }
440    }
441
442    #[test]
443    fn enum_from_str_matches_yaml_names() {
444        assert_eq!(RegionType::from_str("umi").unwrap(), RegionType::Umi);
445        assert_eq!(RegionType::from_str("pid").unwrap(), RegionType::Pid);
446        assert_eq!(RegionType::from_str("lbs").unwrap(), RegionType::Lbs);
447        assert_eq!(RegionType::from_str("uei").unwrap(), RegionType::Uei);
448        assert_eq!(
449            RegionType::from_str("amplicon").unwrap(),
450            RegionType::Amplicon
451        );
452        assert!(RegionType::from_str("UMI").is_err());
453
454        assert_eq!(
455            SequenceType::from_str("joined").unwrap(),
456            SequenceType::Joined
457        );
458        assert_eq!(
459            SequenceType::from_str("fixed").unwrap(),
460            SequenceType::Fixed
461        );
462        assert_eq!(
463            SequenceType::from_str("random").unwrap(),
464            SequenceType::Random
465        );
466        assert!(SequenceType::from_str("JOINED").is_err());
467    }
468
469    #[test]
470    fn duplicate_region_id_is_rejected() {
471        // `pid-1` appears twice (top-level and nested), which must be rejected.
472        let yaml = VALID_ASSAY.replace("region_id: umi-1", "region_id: pid-1");
473        let file = write_fixture(&yaml);
474
475        let err = Assay::from_path(file.path()).expect_err("should reject duplicate");
476        assert!(
477            err.to_string().contains("Duplicate region_id"),
478            "unexpected error: {err}",
479        );
480    }
481
482    #[test]
483    fn missing_required_region_is_rejected() {
484        // Rename `pid-1` so the required region is absent.
485        let yaml = VALID_ASSAY.replace("region_id: pid-1", "region_id: extra");
486        let file = write_fixture(&yaml);
487
488        let err = Assay::from_path(file.path()).expect_err("should reject missing region");
489        assert!(
490            err.to_string().contains("Missing required regions"),
491            "unexpected error: {err}",
492        );
493    }
494
495    #[test]
496    fn valid_assay_passes_validation() {
497        let file = write_fixture(VALID_ASSAY);
498        assert!(Assay::from_path(file.path()).is_ok());
499    }
500
501    #[test]
502    fn new_matches_from_path_bounds() {
503        let file = write_fixture(VALID_ASSAY);
504        let from_file = Assay::from_path(file.path()).expect("load assay");
505        let parsed: Assay = serde_saphyr::from_str(VALID_ASSAY).expect("deserialize");
506        let from_new = Assay::new(parsed.name, parsed.assay_spec).expect("new");
507
508        assert_eq!(from_file.name, from_new.name);
509        assert_eq!(
510            from_file.forward_bounds("umi-1"),
511            from_new.forward_bounds("umi-1")
512        );
513        assert_eq!(
514            from_file.forward_bounds("uei"),
515            from_new.forward_bounds("uei")
516        );
517        assert_eq!(
518            from_file.forward_bounds("amplicon"),
519            from_new.forward_bounds("amplicon")
520        );
521        assert_eq!(
522            from_file.reverse_bounds("umi-1"),
523            from_new.reverse_bounds("umi-1")
524        );
525        assert_eq!(
526            from_file.reverse_bounds("umi-2"),
527            from_new.reverse_bounds("umi-2")
528        );
529    }
530
531    #[test]
532    fn forward_bounds_are_precomputed() {
533        let file = write_fixture(VALID_ASSAY);
534        let assay = Assay::from_path(file.path()).expect("load assay");
535
536        // Leaf lengths: umi-1=28, pid-1=10, lbs-1=28, uei=15, lbs-2=14,
537        // pid-2=10, umi-2=28; total=133.
538        assert_eq!(assay.forward_bounds("umi-1"), Some((0, 28)));
539        assert_eq!(assay.forward_bounds("uei"), Some((66, 81)));
540        // The container spans the whole read.
541        assert_eq!(assay.forward_bounds("amplicon"), Some((0, 133)));
542    }
543
544    #[test]
545    fn reverse_bounds_index_into_the_raw_read() {
546        let file = write_fixture(VALID_ASSAY);
547        let assay = Assay::from_path(file.path()).expect("load assay");
548
549        // The raw reverse read starts at the amplicon 3' end, so umi-2 (the
550        // 3'-most region) comes first, then pid-2, etc. (total=133).
551        assert_eq!(assay.reverse_bounds("umi-2"), Some((0, 28)));
552        assert_eq!(assay.reverse_bounds("pid-2"), Some((28, 38)));
553        // umi-1 (the 5'-most region) sits at the far end of the reverse read.
554        assert_eq!(assay.reverse_bounds("umi-1"), Some((105, 133)));
555    }
556
557    #[test]
558    fn bounds_return_none_for_unknown_region() {
559        let file = write_fixture(VALID_ASSAY);
560        let assay = Assay::from_path(file.path()).expect("load assay");
561
562        assert_eq!(assay.forward_bounds("nope"), None);
563        assert_eq!(assay.reverse_bounds("nope"), None);
564    }
565
566    #[test]
567    fn region_sequences_by_type_collects_nested_matches_in_order() {
568        let file = write_fixture(VALID_ASSAY);
569        let assay = Assay::from_path(file.path()).expect("load assay");
570
571        assert_eq!(
572            assay.region_sequences_by_type(RegionType::Lbs),
573            vec!["CAAGTGACGCTGGTCAAACACTCATGTC", "CGCTTAGATGTCGG",],
574        );
575        assert_eq!(
576            assay.region_sequences_by_type(RegionType::Umi),
577            vec![
578                "NNNNNNNNNNNNNNNNNNNNNNNNNNNN",
579                "NNNNNNNNNNNNNNNNNNNNNNNNNNNN",
580            ],
581        );
582        assert_eq!(
583            assay.region_sequences_by_type(RegionType::Uei),
584            vec!["NNNNNNNNNNNNNNN"],
585        );
586        assert_eq!(
587            assay.region_sequences_by_type(RegionType::Pid),
588            vec!["NNNNNNNNNN", "NNNNNNNNNN"],
589        );
590    }
591
592    #[test]
593    fn region_sequences_by_type_returns_empty_when_no_match() {
594        // LBS is not among the required region ids, so an assay without any
595        // lbs regions is still valid.
596        let yaml = VALID_ASSAY.replace("region_type: lbs", "region_type: uei");
597        let file = write_fixture(&yaml);
598        let assay = Assay::from_path(file.path()).expect("load assay");
599
600        assert!(assay.region_sequences_by_type(RegionType::Lbs).is_empty());
601    }
602}