Module feature_names 

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, chr1_1000_2000, and 1:1000-2000 should all resolve to the same peak.

Enums

FeatureNameKind

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.

FeatureNameKindArg

Clap-facing spelling of FeatureNameKind.

Functions

build_locus_overlap_canonical_map

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.

build_locus_overlap_canonicalizer

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 canon_locus for names that didn’t parse as a locus.

build_mixed_kind_canonicalizer

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). • contains _ → gene rule: last token after the rightmost _. • else → passthrough.

parse_locus

Parse a row name as (chr, start, end). Accepts either chr1:1000-2000, 1:1000-2000, chr1_1000_2000, or 1_1000_2000. Returns None for anything that doesn’t match — those names pass through the overlap pass untouched.