1use crate::common::distances::{hamming_distance_2bit, within_hamming_distance};
2use crate::encoding::encode_dna_2bit;
3
4use csv::ReaderBuilder;
5use rustc_hash::FxHashMap as HashMap;
6use serde::Deserialize;
7use std::error::Error;
8use std::path::Path;
9
10#[derive(Clone)]
26pub struct Panel {
27 markers: Vec<PanelMarker>,
31 map_seq_1: HashMap<u64, i32>,
33 map_seq_2: HashMap<u64, i32>,
35}
36
37#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
40pub struct PanelMarker {
41 pub marker_id: String,
43 pub sequence_1: String,
45 pub sequence_2: String,
47}
48
49impl Panel {
50 pub fn from_path<P: AsRef<Path>>(path: P) -> Result<Self, Box<dyn Error>> {
71 let mut reader = ReaderBuilder::new()
72 .comment(Some(b'#'))
73 .flexible(true)
74 .from_path(path)?;
75
76 let headers = reader.headers()?.clone();
77
78 let mut markers = Vec::new();
79
80 for result in reader.records() {
81 let mut row = result?;
82 while row.len() < headers.len() {
83 row.push_field("");
84 }
85 markers.push(row.deserialize(Some(&headers))?);
86 }
87
88 Self::from_markers(markers)
89 }
90
91 pub fn from_markers(markers: Vec<PanelMarker>) -> Result<Self, Box<dyn Error>> {
94 let mut map_seq_1 = HashMap::default();
95 let mut map_seq_2 = HashMap::default();
96 for (index, m) in markers.iter().enumerate() {
97 let index = index as i32;
98 if map_seq_1
99 .insert(encode_dna_2bit(m.sequence_1.as_bytes()), index)
100 .is_some()
101 {
102 return Err(format!(
103 "Duplicate sequence_1 '{}' found in panel (marker {})",
104 m.sequence_1, m.marker_id
105 )
106 .into());
107 }
108 if map_seq_2
109 .insert(encode_dna_2bit(m.sequence_2.as_bytes()), index)
110 .is_some()
111 {
112 return Err(format!(
113 "Duplicate sequence_2 '{}' found in panel (marker {})",
114 m.sequence_2, m.marker_id
115 )
116 .into());
117 }
118 }
119
120 Ok(Self {
121 markers,
122 map_seq_1,
123 map_seq_2,
124 })
125 }
126
127 pub fn marker_index_seq1(&self, seq: u64) -> Option<i32> {
131 self.map_seq_1.get(&seq).copied()
132 }
133
134 pub fn marker_index_seq2(&self, seq: u64) -> Option<i32> {
138 self.map_seq_2.get(&seq).copied()
139 }
140
141 pub fn lookup_seq1(&self, seq: u64) -> Option<&str> {
144 self.marker_index_seq1(seq)
145 .map(|idx| self.markers[idx as usize].marker_id.as_str())
146 }
147
148 pub fn lookup_seq2(&self, seq: u64) -> Option<&str> {
151 self.marker_index_seq2(seq)
152 .map(|idx| self.markers[idx as usize].marker_id.as_str())
153 }
154
155 pub fn markers(&self) -> &[PanelMarker] {
157 &self.markers
158 }
159}
160
161const SAFE_MISMATCH_THRESHOLD: u8 = 1;
213
214#[derive(Clone, Copy, Debug, PartialEq, Eq)]
216pub enum MarkerMatch {
217 Hit(i32),
219 Miss,
221 Ambiguous,
223}
224
225#[derive(Clone)]
245pub struct PanelSearcher {
246 panel: Panel,
247 mismatch_threshold: u8,
248 scan_seq_1: Vec<(u64, i32)>,
253 scan_seq_2: Vec<(u64, i32)>,
254}
255
256impl PanelSearcher {
257 pub fn new(panel: Panel, mismatch_threshold: u8) -> Self {
265 if mismatch_threshold > SAFE_MISMATCH_THRESHOLD {
266 log::warn!(
267 "PanelSearcher mismatch_threshold {mismatch_threshold} exceeds the safe limit of \
268 {SAFE_MISMATCH_THRESHOLD}; within that radius, all barcodes are guaranteed to be \
269 self-correcting, but beyond it a query can be strictly closest to the wrong marker \
270 and be silently misassigned."
271 );
272 }
273 let scan_seq_1 = panel.map_seq_1.iter().map(|(&s, &i)| (s, i)).collect();
274 let scan_seq_2 = panel.map_seq_2.iter().map(|(&s, &i)| (s, i)).collect();
275 Self {
276 panel,
277 mismatch_threshold,
278 scan_seq_1,
279 scan_seq_2,
280 }
281 }
282
283 pub fn panel(&self) -> &Panel {
285 &self.panel
286 }
287
288 pub fn search_seq1(&self, seq: u64) -> MarkerMatch {
289 self.search(seq, &self.panel.map_seq_1, &self.scan_seq_1)
290 }
291
292 pub fn search_seq2(&self, seq: u64) -> MarkerMatch {
293 self.search(seq, &self.panel.map_seq_2, &self.scan_seq_2)
294 }
295
296 fn search(&self, seq: u64, panel_map: &HashMap<u64, i32>, scan: &[(u64, i32)]) -> MarkerMatch {
299 if let Some(index) = panel_map.get(&seq) {
300 return MarkerMatch::Hit(*index);
301 }
302
303 match self.mismatch_threshold {
308 0 => MarkerMatch::Miss,
309 1 => self.search_first_hit(seq, scan),
310 _ => self.search_best_match(seq, scan),
311 }
312 }
313
314 fn search_first_hit(&self, seq: u64, scan: &[(u64, i32)]) -> MarkerMatch {
315 scan.iter()
316 .find(|&&(marker_seq, _)| {
317 within_hamming_distance(seq, marker_seq, self.mismatch_threshold)
318 })
319 .map(|&(_, index)| MarkerMatch::Hit(index))
320 .unwrap_or(MarkerMatch::Miss)
321 }
322
323 fn search_best_match(&self, seq: u64, scan: &[(u64, i32)]) -> MarkerMatch {
324 let mut best_index = None;
325 let mut best_distance = self.mismatch_threshold + 1;
326 let mut tie = false;
327 for &(marker_seq, index) in scan {
328 let distance = hamming_distance_2bit(seq, marker_seq);
329 if distance > self.mismatch_threshold {
330 continue;
331 }
332 if distance < best_distance {
333 best_distance = distance;
334 best_index = Some(index);
335 tie = false;
336 } else if distance == best_distance {
337 tie = true;
338 }
339 }
340 match best_index {
341 Some(index) if !tie => MarkerMatch::Hit(index),
342 Some(_) => MarkerMatch::Ambiguous,
343 None => MarkerMatch::Miss,
344 }
345 }
346}
347
348#[cfg(test)]
349mod tests {
350 use super::*;
351 use std::io::Write;
352 use tempfile::NamedTempFile;
353
354 const FIXTURE_ROWS: &[(&str, &str, &str)] = &[
357 ("HLA-ABC", "ACTTCCTAGG", "ACTTCCTAGG"),
358 ("B2M", "CCAGGTTCCG", "CCAGGTTCCG"),
359 ("CD11b", "CAGCTATGGT", "CAGCTATGGT"),
360 ("CD11c", "ATATGACGGT", "ATATGACGGT"),
361 ("mIgG1", "ATGCTAGTCG", "ATGCTAGTCG"),
362 ];
363
364 fn fixture_csv() -> String {
368 let mut csv = String::from(
369 "# ---\n\
370 # name: test-panel\n\
371 # version: 1.0.0\n\
372 # ---\n\
373 marker_id,control,full_name,alt_id,uniprot_id,sequence_1,sequence_2\n",
374 );
375 for (marker, seq1, seq2) in FIXTURE_ROWS {
376 csv.push_str(&format!("{marker},,Some name,,P00000,{seq1},{seq2}\n"));
377 }
378 csv
379 }
380
381 fn write_fixture() -> NamedTempFile {
382 let mut file = NamedTempFile::new().expect("create temp file");
383 file.write_all(fixture_csv().as_bytes())
384 .expect("write fixture csv");
385 file.flush().expect("flush fixture csv");
386 file
387 }
388
389 #[test]
390 fn from_path_loads_all_markers_and_sequences() {
391 let file = write_fixture();
392 let panel = Panel::from_path(file.path()).expect("load panel");
393
394 for (marker, seq1, seq2) in FIXTURE_ROWS {
395 assert_eq!(
396 panel.lookup_seq1(encode_dna_2bit(seq1.as_bytes())),
397 Some(*marker),
398 "sequence_1 lookup failed for {marker}",
399 );
400 assert_eq!(
402 panel.lookup_seq2(encode_dna_2bit(seq2.as_bytes())),
403 Some(*marker),
404 "sequence_2 lookup failed for {marker}",
405 );
406 }
407
408 assert_eq!(panel.map_seq_1.len(), FIXTURE_ROWS.len());
411 assert_eq!(panel.map_seq_2.len(), FIXTURE_ROWS.len());
412 }
413
414 #[test]
415 fn from_path_exposes_markers_in_file_order() {
416 let file = write_fixture();
417 let panel = Panel::from_path(file.path()).expect("load panel");
418
419 let markers = panel.markers();
420 assert_eq!(markers.len(), FIXTURE_ROWS.len());
421 for (marker, (id, seq1, seq2)) in markers.iter().zip(FIXTURE_ROWS) {
422 assert_eq!(marker.marker_id, *id);
423 assert_eq!(marker.sequence_1, *seq1);
424 assert_eq!(marker.sequence_2, *seq2);
425 }
426 }
427
428 #[test]
429 fn duplicate_sequence_is_rejected() {
430 let mut csv = String::from("marker_id,sequence_1,sequence_2\n");
431 csv.push_str("CD11b,CAGCTATGGT,CAGCTATGGT\n");
433 csv.push_str("CD11c,CAGCTATGGT,ATATGACGGT\n");
434
435 let mut file = NamedTempFile::new().expect("create temp file");
436 file.write_all(csv.as_bytes()).expect("write csv");
437 file.flush().expect("flush csv");
438
439 let msg = match Panel::from_path(file.path()) {
440 Ok(_) => panic!("duplicate should error"),
441 Err(e) => e.to_string(),
442 };
443 assert!(
444 msg.contains("Duplicate sequence_1"),
445 "unexpected error: {msg}"
446 );
447 assert!(msg.contains("CD11c"), "error should name the marker: {msg}");
448 }
449
450 #[test]
451 fn lookup_returns_none_for_unknown_sequence() {
452 let file = write_fixture();
453 let panel = Panel::from_path(file.path()).expect("load panel");
454
455 let unknown = encode_dna_2bit(b"TTTTTTTTTT");
457 assert_eq!(panel.lookup_seq1(unknown), None);
458 assert_eq!(panel.lookup_seq2(unknown), None);
459 }
460
461 #[test]
462 fn lookup_seq1_and_seq2_are_independent() {
463 let seq1 = "ACGTACGTAC";
464 let seq2 = "TGCATGCATG";
465
466 let panel = Panel::from_markers(vec![PanelMarker {
467 marker_id: String::from("SYNTH"),
468 sequence_1: seq1.to_string(),
469 sequence_2: seq2.to_string(),
470 }])
471 .expect("build panel from markers");
472
473 assert_eq!(
474 panel.lookup_seq1(encode_dna_2bit(seq1.as_bytes())),
475 Some("SYNTH")
476 );
477 assert_eq!(
478 panel.lookup_seq2(encode_dna_2bit(seq2.as_bytes())),
479 Some("SYNTH")
480 );
481
482 assert_eq!(panel.lookup_seq1(encode_dna_2bit(seq2.as_bytes())), None);
484 assert_eq!(panel.lookup_seq2(encode_dna_2bit(seq1.as_bytes())), None);
485 }
486
487 #[test]
488 fn panel_searcher_exact_match_returns_marker_index() {
489 let panel = Panel::from_markers(vec![PanelMarker {
490 marker_id: String::from("CD11b"),
491 sequence_1: String::from("CAGCTATGGT"),
492 sequence_2: String::from("CAGCTATGGT"),
493 }])
494 .expect("build panel from markers");
495 let searcher = PanelSearcher::new(panel, 0);
496
497 let seq = encode_dna_2bit(b"CAGCTATGGT");
498 assert_eq!(searcher.search_seq1(seq), MarkerMatch::Hit(0));
499 assert_eq!(searcher.search_seq2(seq), MarkerMatch::Hit(0));
500 }
501
502 #[test]
503 fn panel_searcher_zero_threshold_rejects_near_match() {
504 let panel = Panel::from_markers(vec![PanelMarker {
505 marker_id: String::from("CD11b"),
506 sequence_1: String::from("CAGCTATGGT"),
507 sequence_2: String::from("CAGCTATGGT"),
508 }])
509 .expect("build panel from markers");
510 let searcher = PanelSearcher::new(panel, 0);
511
512 let near = encode_dna_2bit(b"AAGCTATGGT");
514 assert_eq!(searcher.search_seq1(near), MarkerMatch::Miss);
515 assert_eq!(searcher.search_seq2(near), MarkerMatch::Miss);
516 }
517
518 #[test]
519 fn panel_searcher_fuzzy_match_within_threshold() {
520 let panel = Panel::from_markers(vec![PanelMarker {
521 marker_id: String::from("CD11b"),
522 sequence_1: String::from("CAGCTATGGT"),
523 sequence_2: String::from("CAGCTATGGT"),
524 }])
525 .expect("build panel from markers");
526 let searcher = PanelSearcher::new(panel, 1);
527
528 let near = encode_dna_2bit(b"AAGCTATGGT");
529 assert_eq!(searcher.search_seq1(near), MarkerMatch::Hit(0));
530 assert_eq!(searcher.search_seq2(near), MarkerMatch::Hit(0));
531 }
532
533 #[test]
534 fn panel_searcher_returns_miss_when_distance_exceeds_threshold() {
535 let panel = Panel::from_markers(vec![PanelMarker {
536 marker_id: String::from("CD11b"),
537 sequence_1: String::from("CAGCTATGGT"),
538 sequence_2: String::from("CAGCTATGGT"),
539 }])
540 .expect("build panel from markers");
541 let searcher = PanelSearcher::new(panel, 1);
542
543 let far = encode_dna_2bit(b"AAGCTATGGA");
545 assert_eq!(searcher.search_seq1(far), MarkerMatch::Miss);
546 assert_eq!(searcher.search_seq2(far), MarkerMatch::Miss);
547 }
548
549 #[test]
550 fn panel_searcher_returns_miss_for_unknown_sequence() {
551 let panel = Panel::from_markers(vec![PanelMarker {
552 marker_id: String::from("CD11b"),
553 sequence_1: String::from("CAGCTATGGT"),
554 sequence_2: String::from("CAGCTATGGT"),
555 }])
556 .expect("build panel from markers");
557 let searcher = PanelSearcher::new(panel, 2);
558
559 let unknown = encode_dna_2bit(b"TTTTTTTTTT");
560 assert_eq!(searcher.search_seq1(unknown), MarkerMatch::Miss);
561 assert_eq!(searcher.search_seq2(unknown), MarkerMatch::Miss);
562 }
563
564 #[test]
565 fn panel_searcher_seq1_and_seq2_are_independent() {
566 let panel = Panel::from_markers(vec![PanelMarker {
567 marker_id: String::from("SYNTH"),
568 sequence_1: String::from("ACGTACGTAC"),
569 sequence_2: String::from("TGCATGCATG"),
570 }])
571 .expect("build panel from markers");
572 let searcher = PanelSearcher::new(panel, 0);
573
574 let seq1 = encode_dna_2bit(b"ACGTACGTAC");
575 let seq2 = encode_dna_2bit(b"TGCATGCATG");
576
577 assert_eq!(searcher.search_seq1(seq1), MarkerMatch::Hit(0));
578 assert_eq!(searcher.search_seq2(seq2), MarkerMatch::Hit(0));
579 assert_eq!(searcher.search_seq1(seq2), MarkerMatch::Miss);
580 assert_eq!(searcher.search_seq2(seq1), MarkerMatch::Miss);
581 }
582
583 #[test]
584 fn best_match_returns_nearest_within_threshold() {
585 let panel = Panel::from_markers(vec![
586 PanelMarker {
587 marker_id: String::from("A"),
588 sequence_1: String::from("AAAAAAAAAA"),
589 sequence_2: String::from("GGGGGGGGGG"),
590 },
591 PanelMarker {
592 marker_id: String::from("B"),
593 sequence_1: String::from("TTTAAAAAAA"),
594 sequence_2: String::from("CCCCCCCCCC"),
595 },
596 ])
597 .expect("build panel from markers");
598 let searcher = PanelSearcher::new(panel, 2);
599
600 let query = encode_dna_2bit(b"TAAAAAAAAA");
602 assert_eq!(searcher.search_seq1(query), MarkerMatch::Hit(0));
603 }
604
605 #[test]
606 fn best_match_returns_nearest_regardless_of_scan_order() {
607 let panel = Panel::from_markers(vec![
608 PanelMarker {
609 marker_id: String::from("B"),
610 sequence_1: String::from("TTTAAAAAAA"),
611 sequence_2: String::from("CCCCCCCCCC"),
612 },
613 PanelMarker {
614 marker_id: String::from("A"),
615 sequence_1: String::from("AAAAAAAAAA"),
616 sequence_2: String::from("GGGGGGGGGG"),
617 },
618 ])
619 .expect("build panel from markers");
620 let searcher = PanelSearcher::new(panel, 2);
621
622 let query = encode_dna_2bit(b"TAAAAAAAAA");
624 assert_eq!(searcher.search_seq1(query), MarkerMatch::Hit(1));
625 }
626
627 #[test]
628 fn best_match_rejects_tie() {
629 let panel = Panel::from_markers(vec![
630 PanelMarker {
631 marker_id: String::from("A"),
632 sequence_1: String::from("AAAAAAAAAA"),
633 sequence_2: String::from("GGGGGGGGGG"),
634 },
635 PanelMarker {
636 marker_id: String::from("B"),
637 sequence_1: String::from("TTTTAAAAAA"),
638 sequence_2: String::from("CCCCCCCCCC"),
639 },
640 ])
641 .expect("build panel from markers");
642 let searcher = PanelSearcher::new(panel, 2);
643
644 let query = encode_dna_2bit(b"TTAAAAAAAA");
646 assert_eq!(
647 hamming_distance_2bit(query, encode_dna_2bit(b"AAAAAAAAAA")),
648 2
649 );
650 assert_eq!(
651 hamming_distance_2bit(query, encode_dna_2bit(b"TTTTAAAAAA")),
652 2
653 );
654 assert_eq!(searcher.search_seq1(query), MarkerMatch::Ambiguous);
655 }
656
657 #[test]
658 fn best_match_returns_miss_beyond_threshold() {
659 let panel = Panel::from_markers(vec![PanelMarker {
660 marker_id: String::from("CD11b"),
661 sequence_1: String::from("CAGCTATGGT"),
662 sequence_2: String::from("GGGGGGGGGG"),
663 }])
664 .expect("build panel from markers");
665 let searcher = PanelSearcher::new(panel, 2);
666
667 let unknown = encode_dna_2bit(b"TTTTTTTTTT");
668 assert_eq!(searcher.search_seq1(unknown), MarkerMatch::Miss);
669 }
670
671 #[test]
672 fn best_match_exact_still_hits() {
673 let panel = Panel::from_markers(vec![PanelMarker {
674 marker_id: String::from("CD11b"),
675 sequence_1: String::from("CAGCTATGGT"),
676 sequence_2: String::from("GGGGGGGGGG"),
677 }])
678 .expect("build panel from markers");
679 let searcher = PanelSearcher::new(panel, 2);
680
681 let seq = encode_dna_2bit(b"CAGCTATGGT");
682 assert_eq!(searcher.search_seq1(seq), MarkerMatch::Hit(0));
683 }
684}