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
8const REQUIRED_REGIONS: [&str; 5] = ["amplicon", "pid-1", "pid-2", "umi-1", "umi-2"];
10
11#[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#[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#[derive(Debug, Clone, Deserialize)]
68pub struct Region {
69 pub region_id: String,
71 pub region_type: RegionType,
73 pub name: String,
75 pub sequence_type: SequenceType,
77 pub sequence: Option<String>,
79 pub min_len: Option<usize>,
81 pub max_len: Option<usize>,
83 #[serde(default)]
85 pub regions: Vec<Region>,
86}
87
88#[derive(Debug, Clone, Deserialize)]
90pub struct Assay {
91 pub name: String,
93 pub assay_spec: Vec<Region>,
95 #[serde(skip)]
100 region_bounds: HashMap<String, (usize, usize)>,
101 #[serde(skip)]
105 total_len: usize,
106}
107
108impl Assay {
109 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 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 fn finalize(&mut self) -> Result<(), Box<dyn Error>> {
150 self.validate()?;
151 self.populate_region_bounds()
152 }
153
154 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 pub fn forward_bounds(&self, region_id: &str) -> Option<(usize, usize)> {
180 self.region_bounds.get(region_id).copied()
181 }
182
183 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 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 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 ®ion.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 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
261fn 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 ®ion.regions {
280 accumulate_bounds(child, offset, out)?;
281 }
282 }
283 out.insert(region.region_id.clone(), (start, *offset));
284 Ok(())
285}
286
287fn collect_region_ids<'a>(
290 region: &'a Region,
291 seen: &mut HashSet<&'a str>,
292) -> Result<(), Box<dyn Error>> {
293 if !seen.insert(®ion.region_id) {
294 return Err(format!("Duplicate region_id detected: {}", region.region_id).into());
295 }
296
297 for child in ®ion.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 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 let uei = &licon.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 let lbs_2 = &licon.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 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 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 assert_eq!(assay.forward_bounds("umi-1"), Some((0, 28)));
539 assert_eq!(assay.forward_bounds("uei"), Some((66, 81)));
540 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 assert_eq!(assay.reverse_bounds("umi-2"), Some((0, 28)));
552 assert_eq!(assay.reverse_bounds("pid-2"), Some((28, 38)));
553 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 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}