Skip to main content

pixelator_core/common/
panel.rs

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/// An antibody panel indexed for fast marker lookups by barcode sequence.
11///
12/// Each marker in a panel is associated with two barcode sequences. The panel
13/// keeps a separate map for each, mapping the 2-bit-encoded sequence (see
14/// [`encode_dna_2bit`]) to the marker identifier so that a barcode observed in
15/// the data can be resolved back to its marker in O(1).
16///
17/// Both sequences are stored exactly as they appear in the panel file. Callers
18/// are responsible for encoding an observed barcode into the same orientation
19/// before looking it up (e.g. reverse-complementing a `sequence_2` barcode read
20/// off the reverse read via [`encode_dna_2bit_rc`](crate::encoding::encode_dna_2bit_rc)).
21///
22/// Because the maps are keyed by encoded sequence, each sequence must be unique
23/// within its column; [`Panel::from_path`] rejects panels where two markers
24/// share a `sequence_1` or a `sequence_2`.
25#[derive(Clone)]
26pub struct Panel {
27    /// All markers, in the order they were loaded from the panel file. This is
28    /// the source of truth for enumerating markers/sequences; the lookup maps
29    /// below are lossy (encoded, deduped) and cannot reconstruct it.
30    markers: Vec<PanelMarker>,
31    /// Encoded `sequence_1` -> index of the marker in `markers`.
32    map_seq_1: HashMap<u64, i32>,
33    /// Encoded `sequence_2` -> index of the marker in `markers`.
34    map_seq_2: HashMap<u64, i32>,
35}
36
37/// A single marker loaded from a panel: its identifier and its two barcode
38/// sequences, stored exactly as they appear in the panel file.
39#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
40pub struct PanelMarker {
41    /// Human-readable marker identifier (e.g. `CD11b`).
42    pub marker_id: String,
43    /// First barcode sequence for the marker.
44    pub sequence_1: String,
45    /// Second barcode sequence for the marker.
46    pub sequence_2: String,
47}
48
49impl Panel {
50    /// Loads a panel from a CSV file at `path`.
51    ///
52    /// The file is expected to have a header row containing at least the
53    /// `marker_id`, `sequence_1`, and `sequence_2` columns. Lines beginning with
54    /// `#` are treated as comments and skipped, which allows the leading YAML
55    /// metadata block present in the standard panel files.
56    ///
57    /// Each row's `sequence_1` and `sequence_2` are 2-bit encoded via
58    /// [`encode_dna_2bit`] exactly as they appear in the file, and stored as
59    /// keys pointing to the row's index in `markers`.
60    ///
61    /// Real panel files are ragged: rows commonly omit trailing empty columns
62    /// (for example `sample_hashing`). Short rows are padded to the header width
63    /// so header-based deserialization does not fail on the missing columns.
64    ///
65    /// # Errors
66    ///
67    /// Returns an error if the file cannot be opened or read, as soon as any
68    /// row fails to deserialize, or if a `sequence_1` or `sequence_2` is
69    /// duplicated across markers.
70    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    /// Builds a panel from markers already in memory, indexing markers as they appear in
92    /// the input vector.
93    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    /// Returns the index (position in [`markers`](Self::markers)) of the marker
128    /// whose `sequence_1` matches the 2-bit-encoded `seq`, or `None` if no marker
129    /// in the panel uses that sequence.
130    pub fn marker_index_seq1(&self, seq: u64) -> Option<i32> {
131        self.map_seq_1.get(&seq).copied()
132    }
133
134    /// Returns the index (position in [`markers`](Self::markers)) of the marker
135    /// whose `sequence_2` matches the 2-bit-encoded `seq`, or `None` if no marker
136    /// in the panel uses that sequence.
137    pub fn marker_index_seq2(&self, seq: u64) -> Option<i32> {
138        self.map_seq_2.get(&seq).copied()
139    }
140
141    /// Returns the `marker_id` for a 2-bit-encoded `sequence_1` barcode, or
142    /// `None` if no marker in the panel uses that sequence.
143    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    /// Returns the `marker_id` for a 2-bit-encoded `sequence_2` barcode, or
149    /// `None` if no marker in the panel uses that sequence.
150    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    /// Returns all markers loaded from the panel, in file order.
156    pub fn markers(&self) -> &[PanelMarker] {
157        &self.markers
158    }
159}
160
161/// Largest `mismatch_threshold` at which the fuzzy fallback is guaranteed never
162/// to *silently* assign a barcode to the wrong marker.
163///
164/// # Background
165///
166/// A barcode read off the sequencer can carry substitution errors, so an
167/// observed sequence often does not match any panel barcode exactly. We model
168/// the number of errors as the Hamming distance (count of differing bases)
169/// between the observed barcode and a panel barcode, and try to map a noisy read
170/// back to the marker it most likely came from.
171///
172/// This is only possible because panels are *designed* with their barcodes
173/// spread apart: any two differ by at least `d_min` bases (here `d_min = 3`).
174/// That spacing is what makes the barcode self-correcting for up to 1 error.
175///
176/// # How the spacing bounds the safe threshold
177///
178/// Say a read is `t` mismatches from its true marker `A`. By the triangle
179/// inequality for Hamming distance, its distance to any *other* marker `B` is
180///
181/// ```text
182/// d(read, B) ≥ d(A, B) − d(A, read) ≥ d_min − t
183/// ```
184///
185/// so the nearest a wrong marker can ever be is `d_min − t`. Weighing that
186/// against how close the read is to the right marker (`≤ t`) gives three
187/// regimes:
188///
189/// - `d_min > 2t`: the true marker is *strictly* closest — correction is
190///   unambiguous.
191/// - `d_min = 2t`: a wrong marker can *tie* the true one but never beat it — so
192///   detecting and dropping ties is enough to stay correct.
193/// - `d_min < 2t`: a wrong marker can be *strictly* closest — the read is
194///   silently misassigned, and no tie check can catch it.
195///
196/// For `d_min = 3` this makes `t = 1` the largest safe threshold: at `t = 2` a
197/// read could be at d_min - t = 1 distance away from an other marker, namely a
198/// confident wrong answer. That is the boundary [`PanelSearcher::new`] warns past.
199///
200/// # Why only direct distances matter, not reverse complements
201///
202/// The bound above concerns distances between barcodes *as stored in the panel*;
203/// reverse complements never enter it. A reverse-strand read is
204/// reverse-complemented into the panel's orientation (via
205/// [`encode_dna_2bit_rc`](crate::encoding::encode_dna_2bit_rc)) *before* lookup,
206/// based on the strand it came from, so no reverse-complemented sequence is ever
207/// added to the set of match targets. A panel barcode that happens to lie near
208/// the reverse complement of another is therefore harmless — that form is never
209/// searched. (In `proxiome-v2-immuno-155-v2.0` one barcode is only 1 mismatch
210/// from another's reverse complement, yet the minimum *direct* distance is
211/// still 4.)
212const SAFE_MISMATCH_THRESHOLD: u8 = 1;
213
214/// Outcome of resolving an observed barcode against the panel.
215#[derive(Clone, Copy, Debug, PartialEq, Eq)]
216pub enum MarkerMatch {
217    /// Resolved to a single marker (index into the panel's markers).
218    Hit(i32),
219    /// No panel marker within the mismatch threshold.
220    Miss,
221    /// Two or more markers tied for the nearest distance; rejected as unsafe.
222    Ambiguous,
223}
224
225/// Resolves an observed barcode to a panel marker, tolerating up to
226/// `mismatch_threshold` mismatches.
227///
228/// A lookup first tries an exact hash-map hit (the common case). On a miss, the
229/// fuzzy fallback is picked to fit the safety regimes documented on
230/// `SAFE_MISMATCH_THRESHOLD`:
231///
232/// - **0**: no fuzzy fallback; exact matches only (`Miss` on miss).
233/// - **1**: return the *first* marker within range (`search_first_hit`). With
234///   `d_min ≥ 3`, at most one marker can be within 1 mismatch, so the first hit
235///   is necessarily the only hit and there is nothing to disambiguate.
236/// - **≥ 2**: two markers can now be within range at once, so scan them all,
237///   keep the single closest, and return [`MarkerMatch::Ambiguous`] if the two
238///   nearest tie (`search_best_match`).
239///
240/// [`PanelSearcher::new`] warns when `mismatch_threshold` exceeds
241/// `SAFE_MISMATCH_THRESHOLD`: past that point the tie check is no longer enough,
242/// because a wrong marker can be strictly closest and slip through as a
243/// confident but incorrect match.
244#[derive(Clone)]
245pub struct PanelSearcher {
246    panel: Panel,
247    mismatch_threshold: u8,
248    /// Contiguous `(encoded sequence, marker index)` pairs for the fuzzy
249    /// fallback scan. Iterating a packed `Vec` (cache-resident and
250    /// autovectorizable) is far faster than iterating the `HashMap`, which is
251    /// kept only for the O(1) exact-hit fast path.
252    scan_seq_1: Vec<(u64, i32)>,
253    scan_seq_2: Vec<(u64, i32)>,
254}
255
256impl PanelSearcher {
257    /// Builds a searcher over `panel` that tolerates up to `mismatch_threshold`
258    /// mismatches when resolving a barcode.
259    ///
260    /// A `mismatch_threshold` above `SAFE_MISMATCH_THRESHOLD` exceeds the
261    /// collision-free guarantee the panel is designed around (see the type-level
262    /// docs), so a warning is logged: fuzzy matches may assign a read to a
263    /// different marker than intended.
264    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    /// Returns the underlying panel.
284    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    /// Exact hash-map lookup, then a threshold-dependent fuzzy fallback:
297    /// first-hit at threshold 1, best-match with tie rejection at threshold ≥ 2.
298    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        // Dispatch by threshold. See `SAFE_MISMATCH_THRESHOLD`: at threshold 1 at
304        // most one marker can be in range, so the first hit is the only hit; at
305        // ≥ 2 several can be in range, so we must find the unique nearest and
306        // reject ties.
307        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    /// Rows copied from `proxiome-v1-immuno-155-v1.0.csv` as
355    /// (marker_id, sequence_1, sequence_2).
356    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    /// Build a small panel CSV that mirrors the real file: a `#`-commented YAML
365    /// header block followed by the full column set (only marker_id/sequence_1/
366    /// sequence_2 are consumed by `PanelMarker`).
367    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            // Both sequences are stored exactly as they appear in the file.
401            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        // Exactly one entry per data row: comment/header lines are skipped and
409        // produce no bogus entries.
410        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        // Two distinct markers sharing the same sequence_1.
432        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        // A sequence that does not appear in the fixture.
456        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        // No cross-contamination: seq2 is not in map_seq_1 and seq1 is not in map_seq_2.
483        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        // One base differs from the panel sequence.
513        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        // Two bases differ from the panel sequence.
544        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        // Distance 1 from A, distance 2 from B.
601        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        // B is scanned first but A is closer.
623        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        // Distance 2 from both A and B.
645        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}