Infer orthogroups across all seven species and attach them at harmonization (WP6, part 1)

[sr320]

First part of WP6 of the mussel and clam integration plan. It infers orthogroups across all seven registered species and attaches them to evidence at harmonization. Cross-species pooling on them is the next PR.

Why OrthoFinder on our own proteomes

The proteomes come from the same RefSeq annotations the crosswalks are built on, so every orthogroup member is a GeneID the harmonizer already resolves. OrthoDB's precomputed groups would need a second identifier mapping, and its coverage of these assemblies is uncertain.

What this adds

• aree fetch-reference --proteins. Fetches NCBI's protein FASTA and feature table, MD5-verified, and writes primary_proteins.faa: one protein per GeneID, the longest, with ties going to the lowest accession. The rule and counts are recorded in the bundle provenance. All seven reference assemblies have one, each 100% covered by its crosswalk: 228,833 proteins in all.
• aree build-orthogroups. Runs OrthoFinder in its own conda environment, so the aree environment and environment.yml are untouched. It commits data/reference/orthogroups/<run_id>/:
  • gene_orthogroups.tsv;
  • orthogroups.tsv, with a copy class and the copies in each species;
  • provenance.json, with the OrthoFinder version and command, proteome checksums, and assignment rates.
• Harmonization. resolve_identifier attaches the active run's orthogroup to resolved real GeneIDs. Crosswalks stay NCBI-only, and the demo crosswalk keeps its own illustrative orthogroups. Harmonize manifests record the run ID and the checksum of its gene table.
• Fix: fetch-reference falsely failed M. californianus. Its GTF writes "NCBI RefSeq Mytilus californianus Annotation Release 100", while the registry has the same release without "RefSeq". The check now ignores that word.

The run: orthofinder3.1.5_2026-10-13 (committed, 7.2 MB, active)

OrthoFinder 3.1.5 ran with -M dendroblast, since version 3 has no orthogroups-only mode. It took 6 threads and 55 minutes on Pori. Only Orthogroups.tsv is used.

Copy class	Orthogroups
single-copy in all 7 species	5,552
single-copy where present	7,031
multi-copy	11,877
species-specific	14,047

Shared with at least one other species: 95 to 98% of each mussel's genes, 85 to 88% of each clam's, and 77% of the oyster's. The oyster is the most distant lineage here.

Sanity checks:

• Coverage: every gene in the run is in its own species' crosswalk.
• Names: in 63% of single-copy-in-all orthogroups with named genes, all species' gene names agree exactly. The rest are naming variants such as "forkhead box C1-a" and "forkhead box protein C1".
• HSP70: "heat shock 70 kDa protein" genes fall into 285 orthogroups. The largest holds 17 to 23 copies in each mussel against 3 in the oyster.

On real evidence: re-harmonizing HESSER2024_VCOR attached an orthogroup to 274 of 306 resolved genes; the rest are non-coding. 190 of those 274 are in multi-copy orthogroups and only 18 are single-copy. Most genes stress studies report sit in expanded families, so cross-species pooling must say which copy class it rests on.

Tests

• Proteomes: longest-isoform selection, tie-breaking, missing proteins, and fetching with and without --proteins.
• Orthogroups: OrthoFinder parsing, including unassigned genes; rejection of a gene placed in two orthogroups or an unknown species column; all four copy classes; the written run and provenance; lookup through active.yaml.
• Resolution: orthogroups attach for a real crosswalk but never for the demo.
• Committed run: checksums match its provenance, every species is covered, each gene is in its species' crosswalk, and no gene is in two orthogroups.
• test_real_crosswalk_resolves_a_known_gene now expects the active run's orthogroup instead of none.
• 518 tests pass and ruff is clean.

Not in this PR

• Orthogroup-level meta-analysis: per-species and cross-species estimates, and between-species heterogeneity.
• The cross-species candidate category and its evidence cards.
• The dashboard gate.

Evidence already harmonized before this merges, including the Manila clam study in #41, gains orthogroups when it is re-harmonized; the Pages build re-harmonizes committed results.

🤖 Generated with Claude Code