bio-comparative-genomics-gene-tree-species-tree-reconciliation

What this skill does

## Version Compatibility

Reference examples tested with: ALE 1.0+ (ssolo/ALE github), GeneRax 2.1.3+ (BenoitMorel/GeneRax), AleRax 1.2.0+ (BenoitMorel/AleRax; Morel 2024 Bioinformatics 40:btae162), Whale.jl 2.0+ (arzwa/Whale.jl), RANGER-DTL 2.0+ (Bansal lab; Bansal 2018 Bioinformatics 34:3214), NOTUNG 2.9.1.5+ (Stolzer 2012; Chen 2000), ecceTERA 1.2.5+, Treerecs 1.2+, IQ-TREE 2.3.6+, MrBayes 3.2.7+, BUSCO 5.7+, ete4 4.1.0+, BioPython 1.84+. Open Tree of Life and NCBI Taxonomy reference databases at 2024-Q3 minimum for species-tree-aware inference.

Before using code patterns, verify installed versions match. If versions differ:
- CLI: `ALEml_undated --help`, `ALEml --help` (dated), `generax --help`, `alerax --help`
- Julia: `using Whale; Whale.WhaleProblem`; `]status` for package versions
- Python: `pip show ete4`; `ete4 --help`

If code throws `species tree mismatch`, `gene tree taxa not in species tree`, or `MPI process pool failure`, these reconciliation tools share strict label-consistency requirements: species labels must match exactly across the species tree and gene trees (case-sensitive, no whitespace), and gene IDs typically encode species via prefix (`species|gene_id` separator convention). Use `sed` / `awk` normalization scripts before reconciliation.

# Gene Tree Species Tree Reconciliation

**"Where did this gene family come from, and what events shaped its history?"** -> Reconcile gene trees against species trees under explicit probabilistic models of duplication (D), horizontal transfer (T), and loss (L). The reconciliation framework converts gene-tree-species-tree discordance into a quantitative history of evolutionary events. Modern probabilistic methods (ALE, GeneRax, AleRax) **distinguish gene-tree-error-driven discordance from biological discordance** by integrating over gene-tree uncertainty -- a critical advance over parsimony reconciliation (NOTUNG, RANGER) which treats input gene trees as fixed and inflates duplication/loss counts from gene-tree noise (Boussau 2013 Genome Res 23:323; Morel 2020 MBE 37:2763).

- CLI: `ALEobserve` + `ALEml_undated` -- Bayesian DTL on a sample of gene trees (amalgamated likelihood)
- CLI: `generax` -- ML reconciliation; refines gene trees jointly with reconciliation
- CLI: `alerax` -- co-estimation of gene and species trees + DTL rates (Morel 2024)
- Julia: `using Whale` -- Bayesian DTL + WGD modeling
- CLI: `ranger-dtl` -- parsimony DTL with cost weights
- CLI: `notung` -- duplication-loss only (DL); user-friendly GUI; legacy

## Algorithmic Taxonomy

| Tool | Approach | Events modeled | Inference | Strength | Fails when |
|------|----------|----------------|-----------|----------|------------|
| ALE undated (Szöllősi 2013 Syst Biol 62:901) | Amalgamated likelihood over gene-tree distribution; species-tree-aware | D, T, L | Bayesian | Posterior over D/T/L events at every species-tree branch; integrates over gene-tree uncertainty | Requires gene-tree posterior sample (>= 100 bootstrap/UFBoot trees); slow for many families |
| ALE dated | Same as undated but uses time-calibrated species tree | D, T, L | Bayesian | Time-aware; better donor inference | Requires dated species tree (BEAST2 / RevBayes calibration) |
| GeneRax (Morel 2020 MBE 37:2763) | ML reconciliation + joint gene-tree refinement | D, T, L | ML | Faster than ALE; refines noisy gene trees; species-tree-aware | Less uncertainty quantification than ALE |
| AleRax (Morel 2024 Bioinformatics 40:btae162) | Co-estimation of gene tree, species tree, and DTL rates | D, T, L | Bayesian / ML hybrid | Gold standard 2024; corrects gene-tree-error feedback into species tree | Computationally heaviest; needs >= 20 species |
| Whale.jl (Zwaenepoel & Van de Peer 2019 MBE 36:1384) | Bayesian DTL + WGD via amalgamated likelihood | D, T, L, WGD | Bayesian (Turing.jl) | Native WGD modeling; modern Bayesian framework | Julia ecosystem dependency |
| RANGER-DTL 2.0 (Bansal 2018 Bioinformatics 34:3214) | Parsimony DTL with user cost weights (D-cost, T-cost, L-cost) | D, T, L | Parsimony | Fast; deterministic; many gene families per minute | Cost weights are user choices; results sensitive to costs |
| NOTUNG (Chen 2000 JCB 7:429; Stolzer 2012 Bioinformatics 28:i409) | Parsimony DL; HGT extension | D, L (optional T) | Parsimony | User-friendly GUI; widely used | DL-only by default; HGT extension less rigorous than ALE |
| ecceTERA (Jacox 2016 Bioinformatics 32:2056) | DTL on input set of trees; ILS extension | D, T, L (+ ILS) | Parsimony / DP | Handles ILS jointly with DTL | Less popular than ALE; smaller community |
| Treerecs (Comte 2020 Bioinformatics 36:4822) | Joint species tree + gene tree refinement | D, L | ML | Refines gene trees by species-tree constraint | No HGT; eukaryote-focused |
| DLCpar (Wu 2014 MBE 31:1290) | DLC parsimony for DL + coalescence (ILS) | D, L, C | Parsimony | Models ILS explicitly | No HGT; older |
| GraphDTL (Tofigh 2010) | Graph algorithm for DTL | D, T, L | Parsimony | Fast on small instances | Less used today |
| Phyldog (Boussau 2013 GR 23:323) | Joint species-tree-gene-tree DL with site-rate variation | D, L | Bayesian | Joint inference; refines gene trees | Bacteria-unfriendly; eukaryote-only |

Methodology evolves; verify the AleRax / ALE documentation and the Szöllősi 2024 review (eLife 13:RP91040) before locking on a single approach. The probabilistic ALE / GeneRax / AleRax tools have largely superseded parsimony reconciliation for serious phylogenomic work; parsimony is fine for screening but not for publication-grade DTL inference.

## Decision Tree by Experimental Scenario

| Scenario | Recommended approach | Why |
|----------|------------------------|-----|
| Bacterial / archaeal phylogenomics, 50-500 genomes | GeneRax (refinement) -> ALE undated (posterior) | Two-stage: GeneRax refines, ALE provides posterior |
| Eukaryote DL inference, no HGT expected | NOTUNG (legacy) or Treerecs | DL is the dominant signal; HGT rare in animals |
| Mixed prokaryote/eukaryote with HGT | ALE undated | Probabilistic D/T/L; ALE-rooting (Williams 2017) for deep questions |
| Plant comparative genomics with WGD | Whale.jl | Native WGD modeling; Bayesian |
| Need uncertainty quantification | ALE or AleRax | Posteriors on every branch; ML methods give point estimates only |
| Need fastest possible per-family analysis | RANGER-DTL parsimony | Deterministic; multi-gene parallel |
| Co-estimate species tree from many gene families | AleRax | Modern gold-standard; corrects gene-tree-error |
| Root a deep species tree from DTL signal | ALE undated rooting (Williams 2017 method) | Root inference from D/T/L event distribution |
| Detect ancient HGT in archaea / bacteria | ALE undated | Probabilistic T detection at each branch; donor inferred |
| Identify ancestral gene family content | ALE; report origination events per branch | Posterior over presence/absence at internal nodes |
| Test specific HGT hypothesis (e.g. plant -> nematode) | ALE on filtered OG set; manual gene tree inspection | Quantitative T posterior |
| Distinguish HGT from differential gene loss | ALE event posteriors (T vs L on candidate branch) | Probabilistic ratio between alternatives |
| WGD detection alongside DTL | Whale.jl explicit WGD modeling | Joint inference; replaces post hoc Ks plotting |
| Refine noisy gene trees against species tree | GeneRax `--strategy SPR` | Species-tree-aware gene-tree refinement |
| Gene family birth-death modeling | See [[gene-family-evolution]] (CAFE5) | Reconciliation is per-family; CAFE5 is across families |
| Single gene of interest, single species | Manual gene-tree placement; ALE not needed | Reconciliation framework is genome-scale |

## Per-Tool Failure Modes

### Gene-tree-error feedback inflating duplications

**Trigger:** Using GeneRax or ALE with poorly-supported gene trees (low bootstrap, short alignments).

**Mechanism:** Noisy gene trees show spurious topology that, when reconciled, produces apparent duplications-follo