1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
//! Reference genome matching engine and scoring algorithms.
//!
//! This module provides the core matching functionality:
//!
//! - [`engine::MatchingEngine`]: Main entry point for finding reference matches
//! - [`scoring::MatchScore`]: Detailed similarity scores between a query and reference
//! - [`diagnosis::MatchDiagnosis`]: Detailed analysis of differences and suggestions
//!
//! ## Matching Algorithm
//!
//! The matching process uses multiple strategies:
//!
//! 1. **Signature matching**: Exact match via sorted MD5 hash signature
//! 2. **MD5-based scoring**: Jaccard similarity of MD5 checksum sets
//! 3. **Name+length fallback**: When MD5s are missing, uses contig names and lengths
//! 4. **Order analysis**: Detects if contigs are reordered vs. reference
//!
//! ## Scoring
//!
//! The composite score combines multiple factors:
//!
//! - **MD5 Jaccard**: Set similarity of sequence checksums
//! - **Name+Length Jaccard**: Set similarity of (name, length) pairs
//! - **Query coverage**: Fraction of query contigs matched
//! - **Order score**: Fraction of contigs in correct relative order
//!
//! ## Example
//!
//! ```rust,no_run
//! use ref_solver::{ReferenceCatalog, MatchingEngine, MatchingConfig, QueryHeader};
//! use ref_solver::parsing::sam::parse_header_text;
//!
//! let catalog = ReferenceCatalog::load_embedded().unwrap();
//! let query = parse_header_text("@SQ\tSN:chr1\tLN:248_956_422\n").unwrap();
//!
//! let engine = MatchingEngine::new(&catalog, MatchingConfig::default());
//! let matches = engine.find_matches(&query, 5);
//!
//! for m in &matches {
//! println!("{}: {:?} ({:.1}%)",
//! m.reference.display_name,
//! m.diagnosis.match_type,
//! m.score.composite * 100.0
//! );
//! }
//! ```
pub use Suggestion;