SAMap v2: samap.io onboarding + samap.analysis interpretation

[atarashansky]

SAMap v2: samap.io onboarding + samap.analysis interpretation

This PR adds two modules that bracket the core SAMap pipeline: samap.io
makes it easy to get into SAMap (resolving the var_names ↔ FASTA-header
mismatch that is the most common onboarding failure), and
samap.analysis makes it possible to get something out of SAMap (mapping
diagnostics, gene-program decomposition, and a disk-based ontology builder
for many-species corpora).

Both modules were driven by a 21-species, 210-pair pan-metazoan benchmark
(Ctenophora → Mammalia, ~3.9 M cells). See docs/io.md and
docs/analysis.md for full usage guides.

samap.io — preparing inputs

• detect_id_flavor — regex classifier for var_names namespace
  (Ensembl/RefSeq/NCBI GeneID/UniProt/model-org DBs/symbol/unknown).
• fetch_proteome — derive a protein FASTA whose headers are your
  var_names (Ensembl REST, NCBI Datasets), one record per gene, longest
  isoform.
• match_fasta — score a header-transform cascade (first-token,
  strip-version, gene:=/gene_id= extraction, GTF tx→gene, explicit
  mapping) against your var_names and write a renamed FASTA.
• run_blast — DIAMOND / MMseqs2 / NCBI BLAST+ with engine auto-detect
  (DIAMOND for prot↔prot, MMseqs2 for translated nucl↔nucl with GPU
  auto-detect, BLAST+ fallback).
• gnnm_from_pairs / homology_from_eggnog — bypass BLAST entirely if
  you already have an orthology table.
• save_gnnm / load_gnnm — npz cache for the homology graph.
• samap CLI — detect-ids, fetch-proteome, match-fasta, blast.
• Initialization warning when var_names ↔ BLAST overlap is below 70%
  (catches the most common silent failure).

samap.analysis — interpreting mappings

• get_mapping_scores(..., which_iter=0|'final') — score against the
  iter-0 (raw BLAST homology) manifold as well as the converged one.
  SAMAP.run now stores obsp['connectivities_iter0'] and
  nnm_per_iter[] so the "find" vs "measure" axes are separable.
• permutation_null_scores — label-permutation null for mapping scores
  (no manifold rerun; cheap empirical p-values per pair).
• cluster_to_k / mapping_degeneracy — leiden-to-target-k for
  granularity-matched comparison; reciprocal-best fraction, entropy, and
  effective-rank summaries of the score matrix. These are the metrics that
  track phylogenetic distance — they decay cleanly to ≈550 Mya, while
  max_score saturates almost immediately.
• gene_modules / module_factored_scores — Leiden-partition the
  homology graph and decompose each cell-type alignment by how many
  independent gene modules support it. with_coexpression=k is
  load-bearing: the BLAST graph alone fragments into ~3,000 size-2
  components; bridging it with within-species gene–gene correlation kNN
  produces interpretable modules (sarcomere, ciliome, ECM, neural, …).
• homology_graph_delta / find_paralog_substitutions — per-edge
  sequence-similarity vs expression-correlation residuals; ranked
  paralog-substitution candidates without an external orthology DB.
• samap.analysis.ontology — disk-based re-scoring of persisted
  obsp['connectivities'] against arbitrary per-species label sets
  (~0.2 s/pair, no SAM/SAMAP objects); union-graph assembly and Leiden
  community detection for many-species cell-type-family discovery;
  family_phylogenetic_signal classifies families as "lineage" vs
  "program" by within-family score–divergence correlation with
  same-study-clade exclusion control.
• SAMAP.run(..., joint_weights=True) — experimental: recompute SAM
  gene weights on the joint manifold after iteration 1. Off by default;
  no behaviour change.

Tests

• 261 passed / 26 skipped.
• 1 known pre-existing failure (tests/regression/test_golden_3species):
  gnnm_refined mismatches the recorded golden (max abs diff 1.34e−2 vs
  tol 1e-4) — hnswlib add_items is non-deterministic across platforms
  even with the thin determinism wrapper. Verified to fail identically
  on main (8ffeaec); unrelated to samap.io / samap.analysis.
• NUMBA_NUM_THREADS pinning hoisted to root tests/conftest.py so it
  applies before any test module imports numba.
• ruff clean.

Docs

• docs/io.md — onboarding guide with workflow diagram and CLI summary.
• docs/analysis.md — interpretation guide with workflow diagram,
  per-function rationale, and a quick-reference table.
• CHANGELOG.md updated under [Unreleased].

Numbers from the benchmark

Used to set defaults and validate API design (not committed to the repo):

• 21 species, 210 pairs, ~3.9 M cells (CELLxGENE / GEO / org-specific DBs).
• 838 cell-type clusters (k=40 Leiden), 12,731 cross-species edges,
  2,954 reciprocal-best edges.
• Permutation null q95 ≈ 0.01–0.05; tile-ability horizon ≈ 90–160 Mya.
• 39 cross-method consensus cell-type families (RBH ∩ program-expression),
  housekeeper filter improves modularity 0.65 → 0.67.