[OlgaPushkarev]

Summary

Lets the pipeline run on scRNA-seq data without perturbations (no guide information) and on mouse data. Human perturbation runs are unchanged.

Third of three stacked PRs. It is based on #19 (ruff format), which is based on #18 (lab-content cleanup). Merge those first; GitHub then retargets this PR to main. Replaces #17.

Non-perturbed data (no guides)

• K-selection plots: new --no_perturbation and --no_trait flags skip the perturbation and trait inputs and their plots. The regulator row shared by both panel functions is moved into one helper and hidden when there is no perturbation data.
• Program analysis: a missing uns['guide_targets'] is handled; perturbed-gene annotations are left empty, with a message.
• Excel summary: the Targets Summary sheet (and the specificity scores it writes) is skipped when there are no guides. The gene-symbol lookup falls back to var_names when the --gene_names_key column is absent.
• Evaluation: with --Perform_perturbation, every input h5mu is checked for guide information before any metric runs, with a clear error. A wrong --prog_key is reported as such.

Mouse data

• Curated ortholog mapping (new src/Stage2_Evaluation/A_Metrics/src/orthologs.py): mouse genes are matched to the human Enrichr libraries and to human gene summaries through orthologs (the union of MGI HOM_MouseHumanSequence and Ensembl BioMart homologs), instead of upper-casing symbols. Upper-casing misses orthologs with different names (e.g. Zfp451 → ZNF451, mouse H2-* → human HLA-*) and sometimes picks a non-orthologous human gene.
  • Cache: the table is downloaded once and cached in src/Stage2_Evaluation/Resources/; --ortholog_table pins a fixed copy.
  • Download safety: a truncated BioMart response is rejected (completion stamp required). The cache is written atomically, and a failed download points to --ortholog_table.
  • Mapping rules: mouse genes without a human ortholog are excluded from enrichment. A gene with several human orthologs contributes to all of them; a human gene with several mouse orthologs keeps the highest loading. MSigDB mouse gene sets keep mouse symbols.
• --organism: accepts only human or mouse (case-insensitive) in evaluation and the Excel summary.
• Excel summary: with --organism mouse, each gene is annotated with its human orthologs' MyGene summaries, in a new Human ortholog column.
• Evaluation: trait (GWAS) enrichment is human-only (OpenTargets) and is skipped with a message for mouse data.
• Plotting utilities: the MyGene helpers now honor their species argument.

Other changes

• ensure_umap reuses embeddings stored as obsm['UMAP'] / obsm['PCA'] (e.g. Seurat conversions) instead of computing a different UMAP.
• Docs: README section "Non-perturbed and mouse data" (per-stage flags), parameter tables, and CHANGELOG entries. ⚠️ Mouse enrichment output changes.

Testing

• New tests (synthetic data, offline):

  • tests/Script/test_non_perturbed.py
  • tests/Script/Stage2_Evaluation/test_orthologs.py
  • tests/Script/Stage3_Interpretation/A_Plotting/Program/test_ensure_umap.py

  25 tests, all passing. Against the previous code, the tests for new behavior fail and the tests for unchanged behavior pass.

• Regression:

  • The existing Stage 2 metrics and Stage 3 suites give identical per-test outcomes before and after.
  • On human test data, the Reactome and GO enrichment outputs are byte-identical to main's.

• End to end: a 4,000-cell subsample of a public mouse endothelial scRNA-seq dataset without perturbations ran through inference, evaluation, K-selection, program analysis and the Excel summary. With ortholog mapping:

  • An MHC class II program (top genes Cd74, H2-Ab1, H2-Aa, H2-Eb1, Ciita) is correctly annotated as antigen presentation. Upper-casing had dropped its H2-* genes and returned "regulation of cell migration".
  • 90% of top program genes get a gene summary.

• An independent review of the changes was done before opening.

Pre-existing issues (not changed here)

• 6 Stage 3 tests and 1 torch inference test fail on main because they are stale (see also Fix stale tests and empty significant-programs crash #15).
• gseapy's Biomart client currently fails ("Method Not Allowed") because www.ensembl.org redirects. get_idconversion uses it for Ensembl-ID-to-symbol conversion and falls back silently. The new ortholog code queries an Ensembl mirror directly.
• cNMF_program_analysis.py rejects --output_format HTML without --perturb_path_base, although the HTML exporter now handles missing perturbation data. The README documents using PDF/SVG for now; relaxing the guard could be a follow-up.

🤖 Generated with Claude Code