data_beans/aux/

feature_names.rs

//! Feature-name kind + canonicalizer hooks for multi-file data
//! alignment.
//!
//! NOT to be confused with the sibling [`crate::aux::feature_rows`]. That module
//! defines the row-name **grammar** faba's producers emit
//! (`{unit}/{modality}/{subunit}/{channel}`); this one **canonicalizes** a name
//! that already exists, so the same gene or locus matches across files that
//! spell it differently. Reach for `feature_rows` to build or split a row, and
//! for this module to decide whether two spellings are the same feature.
//!
//! Loaders that union rows across multiple sparse backends
//! ([`crate::aux::data_loading::read_data_on_shared_rows`]) can opt into
//! generous matching by passing a [`FeatureNameKind`] — same row-name
//! canonicalization machinery used by `senna marker` /
//! `FeaturePairGraph::from_edge_list` (via
//! [`legume_numeric::matrix::membership::GeneIndexResolver`]) but plumbed at the
//! [`crate::sparse_io_vector::SparseIoVec`] level so the row
//! intersection itself sees aligned names.
//!
//! The two flavors cover what biology pipelines see in practice:
//!
//! - [`FeatureNameKind::Gene`] for gene rows in scRNA / spatial-RNA
//!   data, where the same gene shows up as `TGFB1`, `ENSG00000105329`,
//!   or `ENSG00000105329_TGFB1` across cohorts;
//! - [`FeatureNameKind::Locus`] for chromosome-coordinate rows in ATAC
//!   / chickpea-style data, where `chr1:1000-2000` and `1:1000-2000`
//!   should resolve to the same peak. Only the colon form is a locus;
//!   `chr1_1000_2000` and `chr1-1000-2000` are not.

use std::sync::Arc;

use crate::sparse_io_vector::RowNameCanonicalizer;
use genomic_data::coordinates::{self, chr_stripped, PeakCoord};
use rustc_hash::FxHashMap as HashMap;

/// Per-name canonicalization rule for cross-backend row alignment.
/// Concrete strategy only — no "request" variants. Callers that want
/// auto-detection pass [`None`] (or whatever wrapping enum they choose)
/// and call [`FeatureNameKind::auto_detect`] once row names are in hand.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub enum FeatureNameKind {
    /// Strict string match — no canonicalization. Default.
    #[default]
    Exact,
    /// Gene-symbol rule: register every `delim`-split component as an
    /// alias of the full name. `ENSG00000105329_TGFB1` and `TGFB1`
    /// resolve to the same row.
    Gene { delim: char },
    /// Genomic-locus rule. A colon-form locus becomes its key
    /// (`chr1:1000-2000` and `1:1000-2000` → `1:1000-2000`); other names
    /// pass through. If `merge_overlapping`, intervals that overlap on
    /// the same chromosome additionally collapse into one cluster
    /// (`chr1:1-20` ∪ `chr1:15-30` → `1:1-30`). Useful for ATAC peak
    /// sets called independently across datasets.
    Locus { merge_overlapping: bool },
    /// Heterogeneous axis: dispatch per row name. Names that parse as
    /// loci go through [`FeatureNameKind::Locus`] with overlap merging;
    /// gene-style names (see [`FeatureNameKind::Gene`]) take the gene
    /// rule; the rest pass through. Picked automatically when [`auto_detect`] finds both
    /// signatures in the same axis (e.g. paired RNA + ATAC union).
    Mixed,
}

impl FeatureNameKind {
    /// Canonicalize a single name under this kind's per-name rule.
    /// [`Locus { merge_overlapping: true }`] and [`Mixed`] only describe
    /// the per-name part here (the locus key for loci, last-token split
    /// for gene-style); the global cluster step lives in
    /// [`build_locus_overlap_canonical_map`] and is installed by
    /// [`build_canonicalizer`].
    pub fn canonicalize(&self, name: &str) -> Box<str> {
        match self {
            FeatureNameKind::Exact => name.into(),
            FeatureNameKind::Gene { delim } => gene_canonicalize(name, *delim),
            FeatureNameKind::Locus { .. } => locus_key(name).unwrap_or_else(|| name.into()),
            FeatureNameKind::Mixed => mixed_canonicalize(name),
        }
    }

    /// True iff this kind is [`Exact`] — no canonicalizer needed.
    pub fn is_exact(&self) -> bool {
        matches!(self, FeatureNameKind::Exact)
    }

    /// True iff installing the canonicalizer requires peeking every row
    /// name across all backends first (to build the locus-overlap cluster
    /// map). Loaders branch on this.
    pub fn needs_global_pass(&self) -> bool {
        matches!(
            self,
            FeatureNameKind::Locus {
                merge_overlapping: true
            } | FeatureNameKind::Mixed
        )
    }

    /// Sniff `names` and pick the right kind. Tallies:
    /// `n_locus` = count where `parse_locus` matches; `n_gene_like` =
    /// count of remaining names the gene rule applies to. Decision:
    /// both ≥ 10% → [`Mixed`]; else loci ≥ 50% →
    /// `Locus { merge_overlapping: true }`; else gene-like ≥ 50% →
    /// `Gene { delim: '_' }`; else [`Exact`].
    pub fn auto_detect(names: &[Box<str>]) -> Self {
        let n = names.len();
        if n == 0 {
            return Self::Exact;
        }
        let mut n_locus = 0usize;
        let mut n_gene_like = 0usize;
        for name in names {
            if coordinates::is_locus(name) {
                n_locus += 1;
            } else if is_gene_like(name, '_') {
                n_gene_like += 1;
            }
        }
        let pct_locus = n_locus as f32 / n as f32;
        let pct_gene = n_gene_like as f32 / n as f32;
        if pct_locus < 0.50 {
            let n_spelled = names
                .iter()
                .filter(|name| {
                    !coordinates::is_locus(name) && coordinates::import_interval(name).is_some()
                })
                .count();
            if n_spelled * 2 >= n {
                log::warn!(
                    "{n_spelled} of {n} row names read as intervals only in a non-colon \
                     spelling (e.g. `chr1-100-200`); they are not loci here. Re-import them so \
                     peaks are named `chr:start-end`."
                );
            }
        }
        if pct_locus >= 0.10 && pct_gene >= 0.10 {
            Self::Mixed
        } else if pct_locus >= 0.50 {
            Self::Locus {
                merge_overlapping: true,
            }
        } else if pct_gene >= 0.50 {
            Self::Gene { delim: '_' }
        } else {
            Self::Exact
        }
    }

    /// The one kind to install for a set of files that were each sniffed
    /// with [`auto_detect`](Self::auto_detect) on their own.
    ///
    /// Sniffing the POOLED names does not work: the signature usually lives
    /// on one side only. A raw `ENSG_SYM` cohort pooled with a reference
    /// already on the bare-symbol axis (a carried `pb_reference`, a
    /// symbol-keyed panel) leaves the gene-like share under half, the pair
    /// sniffs as `Exact`, and every gene becomes two rows. Canonicalizing
    /// under `Gene` is a no-op for names lacking the delimiter, so adopting
    /// the informative side is safe for both.
    ///
    /// Gene-style and locus-style files together dispatch per name
    /// (`Mixed`), which is what `auto_detect` would pick on one axis holding
    /// both; `Mixed` anywhere stays `Mixed`; all-`Exact` stays `Exact`.
    #[must_use]
    pub fn reconcile(kinds: &[FeatureNameKind]) -> FeatureNameKind {
        if kinds.iter().any(|k| matches!(k, FeatureNameKind::Mixed)) {
            return FeatureNameKind::Mixed;
        }
        let gene = kinds
            .iter()
            .find(|k| matches!(k, FeatureNameKind::Gene { .. }));
        let locus = kinds
            .iter()
            .find(|k| matches!(k, FeatureNameKind::Locus { .. }));
        match (gene, locus) {
            (Some(_), Some(_)) => FeatureNameKind::Mixed,
            _ => gene.or(locus).cloned().unwrap_or(FeatureNameKind::Exact),
        }
    }

    /// Build a `RowNameCanonicalizer` suitable for
    /// [`SparseIoVec::with_row_canonicalizer`]. Returns `None` for
    /// [`FeatureNameKind::Exact`] so callers don't install a no-op
    /// closure. **Does not** handle the LocusOverlap global step — for
    /// that, use [`build_locus_overlap_canonicalizer`].
    pub fn into_canonicalizer(self) -> Option<RowNameCanonicalizer> {
        if self.is_exact() {
            return None;
        }
        Some(Arc::new(move |name: &str| self.canonicalize(name)))
    }
}

/// Parse a row name as `(chr, start, end)` under the shared locus grammar
/// ([`coordinates::parse_interval`]): colon form only, `chr1:1000-2000` or
/// `1:1000-2000`. The chromosome comes back with its `chr` prefix dropped
/// and its case kept (`chrX` and `X` match, `x` does not). Returns `None`
/// for anything that doesn't match; those names pass through the overlap
/// pass untouched.
pub fn parse_locus(name: &str) -> Option<(Box<str>, u64, u64)> {
    let (chr, start, end) = coordinates::split_interval(name)?;
    Some((chr_stripped(chr).into(), start as u64, end as u64))
}

/// Canonical key of one locus (`chrX:0-100` and `CHRX:0-100` become
/// `X:0-100`), or `None` when `name` is not a locus: the one answer to "is
/// this row a locus, and under which key".
pub use genomic_data::coordinates::locus_key;

/// Per-name rule of [`FeatureNameKind::Mixed`]: locus key, else the gene
/// rule for gene-style names, else the name unchanged.
fn mixed_canonicalize(name: &str) -> Box<str> {
    locus_key(name)
        .or_else(|| gene_symbol(name, '_').map(Into::into))
        .unwrap_or_else(|| name.into())
}

/// Build the overlap-merge canonical map from a flat list of row names
/// across all input backends. Names that parse as `(chr, start, end)`
/// are grouped per chromosome, sorted by start, and clustered by
/// transitive overlap (any interval whose start falls before the
/// running cluster's max end). The cluster canonical is
/// `{chr}:{min_start}-{max_end}` so every member name maps to a single
/// well-defined string.
///
/// Names that fail to parse are not entered into the map; the caller
/// falls back to the per-name rule for those.
pub fn build_locus_overlap_canonical_map(names: &[Box<str>]) -> HashMap<Box<str>, Box<str>> {
    let n = names.len();
    let parsed: Vec<Option<PeakCoord>> = names
        .iter()
        .map(|n| coordinates::parse_interval(n))
        .collect();

    // Bucket valid indices by chromosome (`chr1` and `1` together).
    let mut by_chr: HashMap<&str, Vec<usize>> = HashMap::default();
    for (i, p) in parsed.iter().enumerate() {
        if let Some(p) = p {
            by_chr.entry(chr_stripped(&p.chr)).or_default().push(i);
        }
    }

    // Union-find with path compression.
    let mut parent: Vec<usize> = (0..n).collect();
    fn find(p: &mut [usize], mut x: usize) -> usize {
        while p[x] != x {
            let g = p[p[x]];
            p[x] = g;
            x = g;
        }
        x
    }

    // Per chr: sort by start, sweep, union anything overlapping the running cluster.
    let mut cluster_extent: HashMap<usize, (i64, i64)> = HashMap::default();
    for (_, mut idxs) in by_chr {
        idxs.sort_by_key(|&i| parsed[i].as_ref().map_or(0, |p| p.start));
        let mut current_root: Option<usize> = None;
        let mut current_min_start: i64 = 0;
        let mut current_max_end: i64 = 0;
        for i in idxs {
            let PeakCoord {
                start: s, end: e, ..
            } = parsed[i].as_ref().unwrap();
            match current_root {
                Some(root) if *s < current_max_end => {
                    let ra = find(&mut parent, root);
                    let rb = find(&mut parent, i);
                    if ra != rb {
                        parent[rb] = ra;
                    }
                    current_max_end = current_max_end.max(*e);
                    cluster_extent
                        .insert(find(&mut parent, i), (current_min_start, current_max_end));
                }
                _ => {
                    current_root = Some(i);
                    current_min_start = *s;
                    current_max_end = *e;
                    cluster_extent.insert(i, (*s, *e));
                }
            }
        }
    }

    // Build name → canonical map: the cluster extent under `locus_key`.
    let mut out: HashMap<Box<str>, Box<str>> = HashMap::default();
    for (i, p) in parsed.iter().enumerate() {
        if let Some(p) = p {
            let root = find(&mut parent, i);
            let (start, end) = cluster_extent.get(&root).copied().unwrap_or((0, 0));
            // The member's own chromosome spelling: `locus_key` strips it
            // once, as on every per-name path.
            let cluster = PeakCoord {
                chr: p.chr.clone(),
                start,
                end,
            };
            out.insert(names[i].clone(), cluster.locus_key());
        }
    }
    out
}

/// Build a `RowNameCanonicalizer` for [`FeatureNameKind::LocusOverlap`].
/// `names` should be the concatenation of every input backend's row
/// names (in any order). The returned canonicalizer does
/// `map.get(name).cloned()` first, falling back to per-name
/// locus canonical for names outside the map.
pub fn build_locus_overlap_canonicalizer(names: &[Box<str>]) -> RowNameCanonicalizer {
    let map = Arc::new(build_locus_overlap_canonical_map(names));
    Arc::new(move |name: &str| {
        map.get(name)
            .cloned()
            .or_else(|| locus_key(name))
            .unwrap_or_else(|| name.into())
    })
}

/// Per-name dispatcher for **mixed-kind** axes (e.g. multiome with peaks
/// ∪ genes in one feature axis). For each name:
///   • parses as `(chr, start, end)` → LocusOverlap canonical
///     (cluster representative from `names`).
///   • gene-style (see [`FeatureNameKind::Gene`]) → gene rule: last token
///     after the rightmost `_`.
///   • else → passthrough.
///
/// Use this when the auto-detector sees significant evidence of BOTH
/// loci and gene-style names in the same axis.
pub fn build_mixed_kind_canonicalizer(names: &[Box<str>]) -> RowNameCanonicalizer {
    let map = Arc::new(build_locus_overlap_canonical_map(names));
    Arc::new(move |name: &str| {
        map.get(name)
            .cloned()
            .unwrap_or_else(|| mixed_canonicalize(name))
    })
}

/// Gene-symbol canonicalization with Cell Ranger feature-type suffix
/// awareness. 10x Cell Ranger HDF5 row names commonly arrive as
/// `ENSG..._SYMBOL_<feature_type>` where the third component is a
/// sanitized `feature_type` tag (e.g. `Gene` for `Gene Expression`).
/// A naive `rsplit(delim).next()` would return that constant tag,
/// canonicalizing *every* row to the same string and collapsing the
/// row intersection to one global key. Strip the known tag suffix
/// first so the actual symbol becomes the rsplit target.
fn gene_canonicalize(name: &str, delim: char) -> Box<str> {
    gene_symbol(name, delim).unwrap_or(name).into()
}

/// The gene rule applies: see [`gene_symbol`].
fn is_gene_like(name: &str, delim: char) -> bool {
    gene_symbol(name, delim).is_some()
}

/// The symbol the gene rule keys `name` on: its last `delim` component once
/// a Cell Ranger feature-type tag is stripped. `None` (the name is kept
/// whole) for a locus, a name without `delim`, or a symbol that is all
/// digits: cutting `chrUn_CTG1v1:0-100` would key it on `CTG1v1:0-100`, and
/// `chr1_100_200` or `chr1_100_200_Peaks` (not colon form, so not loci)
/// would collapse onto `200`.
fn gene_symbol(name: &str, delim: char) -> Option<&str> {
    if !name.contains(delim) {
        return None;
    }
    let stripped = strip_feature_type_suffix(name, delim);
    if coordinates::is_locus(stripped) {
        return None;
    }
    let symbol = stripped.rsplit(delim).next().unwrap_or(stripped);
    (!symbol.bytes().all(|b| b.is_ascii_digit())).then_some(symbol)
}

/// Cell Ranger sanitizes `features/feature_type` into the row name as
/// the trailing component. Strip the known tags so the actual gene
/// symbol becomes the rsplit target. Conservative list — only the
/// shapes we've actually seen in the wild — so an unknown tag falls
/// through untouched rather than corrupting a real symbol.
fn strip_feature_type_suffix(name: &str, delim: char) -> &str {
    // Names come pre-sanitized in different ways depending on the
    // producer (Cell Ranger's own h5, scanpy/anndata exports, R-side
    // tools), so accept both `_Gene` and `_Gene_Expression` plus the
    // common companion tags.
    const TAGS: &[&str] = &[
        "Gene_Expression",
        "Gene",
        "Antibody_Capture",
        "CRISPR_Guide_Capture",
        "Multiplexing_Capture",
        "Custom",
        "Peaks",
    ];
    for tag in TAGS {
        // Only strip if the suffix sits behind `delim` (otherwise we'd
        // mangle a real symbol that happens to end in "Gene").
        if let Some(rest) = name.strip_suffix(tag).and_then(|r| r.strip_suffix(delim)) {
            return rest;
        }
    }
    name
}

/// Clap-facing spelling of [`FeatureNameKind`].
///
/// The rule and the flag that selects it belong together: every crate that
/// aligns feature names across files exposes the same `--feature-name-kind`
/// vocabulary, so `senna` and anything after it agree on what
/// `gene` or `locus` means without each inventing a local rule.
#[derive(clap::ValueEnum, Clone, Debug, Default, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum FeatureNameKindArg {
    #[default]
    Auto,
    Exact,
    Gene,
    Locus,
    LocusOverlap,
    Mixed,
}

impl FeatureNameKindArg {
    /// Resolve to a concrete [`FeatureNameKind`], defaulting `Auto` to
    /// `Gene { delim: '_' }` — the standard for gene-keyed pre-train
    /// inputs (bge / fne / topic-family dictionaries).
    pub fn resolve_or_gene(&self) -> FeatureNameKind {
        Option::<FeatureNameKind>::from(self.clone())
            .unwrap_or(FeatureNameKind::Gene { delim: '_' })
    }
}

impl From<FeatureNameKindArg> for Option<FeatureNameKind> {
    fn from(arg: FeatureNameKindArg) -> Self {
        match arg {
            FeatureNameKindArg::Auto => None,
            FeatureNameKindArg::Exact => Some(FeatureNameKind::Exact),
            FeatureNameKindArg::Gene => Some(FeatureNameKind::Gene { delim: '_' }),
            FeatureNameKindArg::Locus => Some(FeatureNameKind::Locus {
                merge_overlapping: false,
            }),
            FeatureNameKindArg::LocusOverlap => Some(FeatureNameKind::Locus {
                merge_overlapping: true,
            }),
            FeatureNameKindArg::Mixed => Some(FeatureNameKind::Mixed),
        }
    }
}

#[cfg(test)]
#[path = "feature_names_tests.rs"]
mod feature_names_tests;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn exact_passthrough() {
        let k = FeatureNameKind::Exact;
        assert_eq!(
            k.canonicalize("ENSG00000000003_TSPAN6").as_ref(),
            "ENSG00000000003_TSPAN6"
        );
        assert!(k.is_exact());
        assert!(k.into_canonicalizer().is_none());
    }

    #[test]
    fn gene_takes_last_underscore_component() {
        let k = FeatureNameKind::Gene { delim: '_' };
        assert_eq!(k.canonicalize("ENSG00000000003_TSPAN6").as_ref(), "TSPAN6");
        // Symbol-only inputs survive unchanged.
        assert_eq!(k.canonicalize("TSPAN6").as_ref(), "TSPAN6");
        // Unknown trailing tokens still get rsplit — caller's responsibility
        // to pick a sensible delim if a non-feature-type trailing token matters.
        assert_eq!(k.canonicalize("A_B_C").as_ref(), "C");
        assert!(!k.is_exact());
        assert!(k.into_canonicalizer().is_some());
    }

    #[test]
    fn gene_strips_cell_ranger_feature_type_suffix() {
        let k = FeatureNameKind::Gene { delim: '_' };
        // 10x Cell Ranger HDF5: `ENSG..._SYMBOL_Gene`. Trailing `_Gene`
        // would otherwise collapse every gene to the literal "Gene".
        assert_eq!(
            k.canonicalize("ENSG00000187634_SAMD11_Gene").as_ref(),
            "SAMD11"
        );
        // Full `Gene_Expression` tag variant.
        assert_eq!(
            k.canonicalize("ENSG00000187634_SAMD11_Gene_Expression")
                .as_ref(),
            "SAMD11"
        );
        // A real gene whose name happens to end in "Gene" *without* the
        // delimiter shouldn't be stripped (no underscore in front of "Gene").
        assert_eq!(k.canonicalize("FakeGene").as_ref(), "FakeGene");
    }

    #[test]
    fn locus_strips_chr_and_leaves_other_spellings_alone() {
        let k = FeatureNameKind::Locus {
            merge_overlapping: false,
        };
        assert_eq!(k.canonicalize("chr1:1000-2000").as_ref(), "1:1000-2000");
        assert_eq!(k.canonicalize("ChrX:5000-6000").as_ref(), "X:5000-6000");
        // Not colon form: not a locus, so the name passes through.
        assert_eq!(k.canonicalize("1_1000_2000").as_ref(), "1_1000_2000");
    }

    // -- Genomic region parsing edge cases ----------------------------------

    #[test]
    fn parse_locus_accepts_common_formats() {
        // colon-dash, bare chromosome, chr prefix in any case, chrX caps.
        assert_eq!(
            parse_locus("chr1:1000-2000"),
            Some(("1".into(), 1000, 2000))
        );
        assert_eq!(parse_locus("1:1000-2000"), Some(("1".into(), 1000, 2000)));
        assert_eq!(
            parse_locus("CHR1:1000-2000"),
            Some(("1".into(), 1000, 2000))
        );
        assert_eq!(
            parse_locus("chrX:5000-6000"),
            Some(("X".into(), 5000, 6000))
        );
        assert_eq!(parse_locus("chrMT:1-100"), Some(("MT".into(), 1, 100)));
    }

    #[test]
    fn parse_locus_keeps_contig_names_with_separators() {
        assert_eq!(
            parse_locus("chrUn_CTG1v1:0-100"),
            Some(("Un_CTG1v1".into(), 0, 100))
        );
        // The canonical key parses back to the same locus.
        assert_eq!(
            parse_locus("Un_CTG1v1:0-100"),
            Some(("Un_CTG1v1".into(), 0, 100))
        );
    }

    #[test]
    fn contig_peaks_stay_loci_on_a_mixed_axis() {
        let names: Vec<Box<str>> = vec![
            "chr1_CTG1v1_random:5-10".into(),
            "chr4_CTG2v2_random:5-10".into(),
            "ENSG000_GENE1".into(),
        ];
        let canon = build_mixed_kind_canonicalizer(&names);
        assert_eq!(canon(&names[0]).as_ref(), "1_CTG1v1_random:5-10");
        assert_eq!(canon(&names[1]).as_ref(), "4_CTG2v2_random:5-10");
        assert_eq!(canon(&names[2]).as_ref(), "GENE1");
    }

    #[test]
    fn every_locus_path_gives_one_key() {
        let names: Vec<Box<str>> = vec!["chrChr1:0-100".into(), "chr1:0-100".into()];
        let map = build_locus_overlap_canonical_map(&names);
        let k = FeatureNameKind::Locus {
            merge_overlapping: false,
        };
        for name in &names {
            assert_eq!(map.get(name).unwrap(), &k.canonicalize(name));
        }
    }

    #[test]
    fn locus_canonical_keeps_case_on_every_path() {
        let names: Vec<Box<str>> = vec!["chrX:0-100".into(), "chr1:0-100".into()];
        let map = build_locus_overlap_canonical_map(&names);
        assert_eq!(map.get(&names[0]).unwrap().as_ref(), "X:0-100");
        assert_eq!(map.get(&names[1]).unwrap().as_ref(), "1:0-100");
        // Names outside the map land on the same key.
        let canon = build_locus_overlap_canonicalizer(&names);
        assert_eq!(canon("chrX:200-300").as_ref(), "X:200-300");
        let mixed = build_mixed_kind_canonicalizer(&names);
        assert_eq!(mixed("chrX:0-100").as_ref(), "X:0-100");
        assert_eq!(mixed("chrM:200-300").as_ref(), "M:200-300");
        let k = FeatureNameKind::Locus {
            merge_overlapping: false,
        };
        assert_eq!(k.canonicalize("chrM:0-100").as_ref(), "M:0-100");
    }

    #[test]
    fn parse_locus_rejects_non_loci() {
        assert!(parse_locus("TGFB1").is_none()); // gene symbol
        assert!(parse_locus("ENSG00000105329").is_none()); // ensembl
        assert!(parse_locus("chr1:bad-2000").is_none()); // non-numeric start
        assert!(parse_locus("chr1:1000").is_none()); // missing end
        assert!(parse_locus("chr1:2000-1000").is_none()); // end < start
        assert!(parse_locus("").is_none()); // empty
        assert!(parse_locus("chr1").is_none()); // chr-only
        assert!(parse_locus("chr:1-2").is_none()); // empty chromosome
        assert!(parse_locus("ENSG000_GENE1").is_none()); // gene-style
        assert!(parse_locus("GENE1-AS1").is_none()); // antisense symbol
        assert!(parse_locus("chr1_1000_2000").is_none()); // underscore form
        assert!(parse_locus("chr1-1000-2000").is_none()); // dash form
    }

    #[test]
    fn overlap_map_merges_two_overlapping_intervals() {
        // User's motivating example: chr1:1-20 and chr1:15-30 → same cluster.
        let names = vec![
            "chr1:1-20".to_string().into_boxed_str(),
            "chr1:15-30".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        let c0 = map.get(&names[0]).unwrap();
        let c1 = map.get(&names[1]).unwrap();
        assert_eq!(c0, c1, "both inputs should map to the same canonical");
        assert_eq!(c0.as_ref(), "1:1-30"); // union-range canonical
    }

    #[test]
    fn overlap_map_keeps_non_overlapping_separate() {
        let names = vec![
            "chr1:1-20".to_string().into_boxed_str(),
            "chr1:100-200".to_string().into_boxed_str(),
            "chr2:1-20".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        assert_eq!(map.get(&names[0]).unwrap().as_ref(), "1:1-20");
        assert_eq!(map.get(&names[1]).unwrap().as_ref(), "1:100-200");
        // different chromosome — separate cluster even if start overlaps
        assert_eq!(map.get(&names[2]).unwrap().as_ref(), "2:1-20");
    }

    #[test]
    fn overlap_map_handles_transitive_chain() {
        // A overlaps B (1-20 vs 15-30), B overlaps C (15-30 vs 25-40),
        // A does NOT overlap C directly — but they should still cluster
        // via transitive closure through B.
        let names = vec![
            "chr1:1-20".to_string().into_boxed_str(),
            "chr1:15-30".to_string().into_boxed_str(),
            "chr1:25-40".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        let c0 = map.get(&names[0]).unwrap();
        let c1 = map.get(&names[1]).unwrap();
        let c2 = map.get(&names[2]).unwrap();
        assert_eq!(c0, c1);
        assert_eq!(c1, c2);
        assert_eq!(c0.as_ref(), "1:1-40"); // union of full chain
    }

    #[test]
    fn overlap_map_handles_full_containment() {
        // chr1:1-100 contains chr1:30-50 — should cluster.
        let names = vec![
            "chr1:1-100".to_string().into_boxed_str(),
            "chr1:30-50".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        let c0 = map.get(&names[0]).unwrap();
        let c1 = map.get(&names[1]).unwrap();
        assert_eq!(c0, c1);
        assert_eq!(c0.as_ref(), "1:1-100");
    }

    #[test]
    fn overlap_map_treats_adjacent_as_separate() {
        // chr1:1-20 and chr1:20-30 are *touching* but not overlapping
        // (end of first == start of second, exclusive end convention).
        let names = vec![
            "chr1:1-20".to_string().into_boxed_str(),
            "chr1:20-30".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        assert_ne!(map.get(&names[0]).unwrap(), map.get(&names[1]).unwrap());
    }

    #[test]
    fn overlap_map_normalizes_chr_prefix_within_cluster() {
        // chr1:1-20 and 1:15-30 (no chr prefix) should still cluster
        // because parse_locus normalizes both to chr="1".
        let names = vec![
            "chr1:1-20".to_string().into_boxed_str(),
            "1:15-30".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        let c0 = map.get(&names[0]).unwrap();
        let c1 = map.get(&names[1]).unwrap();
        assert_eq!(c0, c1);
        assert_eq!(c0.as_ref(), "1:1-30");
    }

    #[test]
    fn overlap_map_leaves_non_colon_spellings_out() {
        // chr1_15_30 is not a locus, so it neither joins nor extends the cluster.
        let names = vec![
            "chr1:1-20".to_string().into_boxed_str(),
            "chr1_15_30".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        assert_eq!(map.get(&names[0]).unwrap().as_ref(), "1:1-20");
        assert!(!map.contains_key(&names[1]));
    }

    #[test]
    fn underscore_peaks_are_not_collapsed_by_the_gene_rule() {
        // Neither loci nor genes: an axis of these is Exact, and the gene
        // rule leaves them whole rather than keying every row on `200`.
        let names: Vec<Box<str>> = (1..=20)
            .map(|i| format!("chr{i}_100_200").into_boxed_str())
            .collect();
        assert_eq!(FeatureNameKind::auto_detect(&names), FeatureNameKind::Exact);
        let mixed = build_mixed_kind_canonicalizer(&names);
        assert_eq!(mixed("chr2_100_200").as_ref(), "chr2_100_200");
        let gene = FeatureNameKind::Gene { delim: '_' };
        assert_eq!(gene.canonicalize("chr2_100_200").as_ref(), "chr2_100_200");
        assert_eq!(gene.canonicalize("ENSG000_GENE1").as_ref(), "GENE1");
        assert_eq!(gene.canonicalize("GENE1_Gene").as_ref(), "GENE1");
        assert_eq!(
            gene.canonicalize("chr2_100_200_Peaks").as_ref(),
            "chr2_100_200_Peaks"
        );
        // A locus is never cut at `_`, even when its contig name has one or
        // it carries a feature-type tag.
        assert_eq!(
            gene.canonicalize("chrUn_CTG1v1:0-100_Peaks").as_ref(),
            "chrUn_CTG1v1:0-100_Peaks"
        );
        assert_eq!(
            gene.canonicalize("chrUn_CTG1v1:0-100").as_ref(),
            "chrUn_CTG1v1:0-100"
        );
    }

    #[test]
    fn overlap_map_ignores_non_locus_names() {
        // Non-locus names should not appear in the map; caller falls
        // back to the per-name rule.
        let names = vec![
            "TGFB1".to_string().into_boxed_str(),
            "chr1:1-20".to_string().into_boxed_str(),
        ];
        let map = build_locus_overlap_canonical_map(&names);
        assert!(!map.contains_key(&names[0]));
        assert!(map.contains_key(&names[1]));
    }

    #[test]
    fn overlap_map_skips_empty_intervals() {
        // chr1:1000-1000 holds no base, so it is not a locus.
        let names = vec!["chr1:1000-1000".to_string().into_boxed_str()];
        let map = build_locus_overlap_canonical_map(&names);
        assert!(map.is_empty());
    }

    #[test]
    fn overlap_canonicalizer_falls_back_for_unmatched() {
        let names = vec!["chr1:1-20".to_string().into_boxed_str()];
        let canon = build_locus_overlap_canonicalizer(&names);
        // In-cluster name → cluster canonical.
        assert_eq!(canon("chr1:1-20").as_ref(), "1:1-20");
        // Unrelated locus not in the map → its own key.
        assert_eq!(canon("chr2:500-600").as_ref(), "2:500-600");
        // Non-locus → unchanged.
        assert_eq!(canon("GENE1").as_ref(), "GENE1");
    }

    // -- Auto-detect & Mixed dispatcher -------------------------------------

    #[test]
    fn auto_detect_pure_locus_axis() {
        let names: Vec<Box<str>> = (0..100)
            .map(|i| format!("chr1:{}-{}", i * 100, i * 100 + 50).into_boxed_str())
            .collect();
        assert!(matches!(
            FeatureNameKind::auto_detect(&names),
            FeatureNameKind::Locus {
                merge_overlapping: true
            }
        ));
    }

    #[test]
    fn auto_detect_pure_gene_axis() {
        let names: Vec<Box<str>> = (0..100)
            .map(|i| format!("ENSG000_GENE{}", i).into_boxed_str())
            .collect();
        assert!(matches!(
            FeatureNameKind::auto_detect(&names),
            FeatureNameKind::Gene { delim: '_' }
        ));
    }

    #[test]
    fn auto_detect_mixed_axis() {
        // 80 loci + 20 gene-style → both fractions ≥ 10% → Mixed.
        let mut names: Vec<Box<str>> = (0..80)
            .map(|i| format!("chr1:{}-{}", i * 1000, i * 1000 + 500).into_boxed_str())
            .collect();
        names.extend((0..20).map(|i| format!("ENSG000_GENE{}", i).into_boxed_str()));
        assert!(matches!(
            FeatureNameKind::auto_detect(&names),
            FeatureNameKind::Mixed
        ));
    }

    #[test]
    fn auto_detect_empty_or_exact() {
        assert!(matches!(
            FeatureNameKind::auto_detect(&[]),
            FeatureNameKind::Exact
        ));
        let names = vec!["TGFB1".into(), "CD4".into(), "IL2".into(), "GAPDH".into()];
        assert!(matches!(
            FeatureNameKind::auto_detect(&names),
            FeatureNameKind::Exact
        ));
    }

    #[test]
    fn mixed_dispatcher_canonicalizes_each_name_by_kind() {
        let names: Vec<Box<str>> = vec![
            "chr1:1-20".into(),     // locus → cluster canonical
            "chr1:15-30".into(),    // locus, overlaps above → same cluster
            "ENSG000_TGFB1".into(), // gene-style → "TGFB1"
            "CD4".into(),           // plain symbol → passthrough
        ];
        let canon = build_mixed_kind_canonicalizer(&names);
        assert_eq!(canon("chr1:1-20").as_ref(), "1:1-30");
        assert_eq!(canon("chr1:15-30").as_ref(), "1:1-30");
        assert_eq!(canon("ENSG000_TGFB1").as_ref(), "TGFB1");
        assert_eq!(canon("CD4").as_ref(), "CD4");
    }
}