[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7EC7EB2M579SGV0GQJ40APE":3,"skill-same:01M7EC7EB2M579SGV0GQJ40APE":62},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":14,"repositoryHtmlUrl":33,"repositoryHomepageUrl":33,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":35,"install":36,"resources":49},"01M7EC7EB2M579SGV0GQJ40APE","bio-comparative-genomics-gene-family-evolution",null,"Model gene-family birth-death dynamics across a species tree using CAFE5 (Mendes et al 2020 Bioinformatics 36:5516 gamma-distributed rate categories), CAFE5-error (annotation-error-aware), Count (Csurös 2010 ancestral state reconstruction), BadiRate (Librado 2012 likelihood + parsimony), DupliPHY-Family, and ALE\u002FAleRax (for per-family DTL; see [[gene-tree-species-tree-reconciliation]]). Test lineage-specific gene-family expansions and contractions, distinguish biological dynamics from annotation artifacts, account for assembly fragmentation, identify functional enrichment in expanded \u002F contracted families. Use when correlating gene-family changes with phenotype evolution, ranking lineages by adaptive gene-family-rate shifts, post-WGD dosage-balance analysis, or building Birth-death models from OrthoFinder presence\u002Fabsence matrices.","Mr-Nobody-Anonymous\u002FAll-skills","Mr-Nobody-Anonymous","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F184253119?v=4","01M7AEXFJHKTYQW5R0ZCQQTWFV","anonymous","01M7C00M3GQR4QKP9GZA42GFAK",0,"MIT","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-comparative-genomics-gene-family-evolution\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: bio-comparative-genomics-gene-family-evolution\ndescription: Model gene-family birth-death dynamics across a species tree using CAFE5 (Mendes et al 2020 Bioinformatics 36:5516 gamma-distributed rate categories), CAFE5-error (annotation-error-aware), Count (Csurös 2010 ancestral state reconstruction), BadiRate (Librado 2012 likelihood + parsimony), DupliPHY-Family, and ALE\u002FAleRax (for per-family DTL; see [[gene-tree-species-tree-reconciliation]]). Test lineage-specific gene-family expansions and contractions, distinguish biological dynamics from annotation artifacts, account for assembly fragmentation, identify functional enrichment in expanded \u002F contracted families. Use when correlating gene-family changes with phenotype evolution, ranking lineages by adaptive gene-family-rate shifts, post-WGD dosage-balance analysis, or building Birth-death models from OrthoFinder presence\u002Fabsence matrices.\ntool_type: cli\nprimary_tool: CAFE5\nsource: \"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills\"\nsource_repository: \"GPTomics\u002FbioSkills\"\nsource_path: \"comparative-genomics\u002Fgene-family-evolution\u002FSKILL.md\"\nlicense: \"MIT\"\nimported_at: \"2026-09-20\"\n---\n\n## Version Compatibility\n\nReference examples tested with: CAFE5 5.1.0+ (Mendes et al 2020 Bioinformatics 36(22-23):5516-5518), Count 11.0319+ (Csurös 2010 Bioinformatics 26:1910), BadiRate 1.35+ (Librado 2012 Bioinformatics 28:279), DupliPHY-Family (Ames et al 2012), CAFExp (legacy CAFE 4.2 -- DEPRECATED; use CAFE5), OrthoFinder 3.0+ for HOG input, R 4.4+, mclust 6.1+, phytools 2.3+, ETE4 4.1.0+ for tree manipulation. ALE\u002FGeneRax\u002FAleRax in companion skill [[gene-tree-species-tree-reconciliation]].\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: `cafe5 --help`; `Count.exe` (Java); `badirate --help`\n- R: `packageVersion('phytools')`\n- Python: `pip show ete4`\n\nIf code throws `CAFE5: lambda did not converge`, `Count negative branch length`, `BadiRate gamma not initialized`, the most common causes are: (1) annotation heterogeneity inflating family sizes, (2) saturated families (CAFE5 needs reasonable rate variation), (3) negative branch lengths in input tree (Count requires ultrametric). Pre-process: filter OG matrix to families present in >= 50% of species; resolve polytomies; ultrametricize tree.\n\n# Gene Family Evolution\n\n**\"Which gene families expanded or contracted in which lineages?\"** -> Birth-death models on phylogeny (Hahn 2005; Csurös 2010) treat each orthogroup's per-species count as evolving under a stochastic birth-death process; lineage-specific rate shifts are detected as departures from a global rate. **Annotation heterogeneity is the single largest confounder**: different annotation pipelines predict different numbers of genes per family, producing apparent lineage-specific expansions that are artifacts of annotation choice (Tonkin-Hill 2020 demonstrated this for bacterial pangenomes). Consistent annotation + BUSCO\u002FCompleasm completeness filtering are mandatory before any birth-death model interpretation. CAFE5 (Mendes et al 2020 Bioinformatics 36:5516) replaces older CAFE versions with gamma-distributed rate categories for more biologically realistic modeling.\n\n- CLI: `cafe5 -i orthogroup_counts.tsv -t species_tree.nwk -p` -- main CAFE5 workflow\n- CLI: `cafe5 -e` -- error-aware mode for annotation uncertainty\n- CLI: `Count` -- Java GUI \u002F CLI for parsimony + likelihood ASR\n- CLI: `badirate -t tree.nwk -d counts.tsv` -- likelihood birth-death + branch parsimony\n\n## Algorithmic Taxonomy\n\n| Tool | Approach | Output | Strength | Fails when |\n|------|----------|--------|----------|------------|\n| CAFE5 (Mendes et al 2020 Bioinformatics 36(22-23):5516-5518) | Birth-death with gamma rate categories | Global \u002F per-family lambda + significant rate shifts | Modern standard; handles rate heterogeneity; explicit Type-I control | Annotation heterogeneity confounds; needs > 100 families |\n| CAFE5-error | Annotation-error-aware extension | Same plus error estimates | Critical for noisy annotations | Manual error-rate specification or estimation |\n| Count (Csurös 2010 Bioinformatics 26:1910) | Both ML and parsimony ASR | Branch event counts (D, L) per family | Comprehensive output; GUI | Slower than CAFE5; less modern UX |\n| BadiRate (Librado 2012 Bioinformatics 28:279) | Likelihood birth-death + branch parsimony | Lineage-specific rate shifts | Combines stochastic + parsimony | Less commonly used; older |\n| DupliPHY-Family (Ames et al 2012) | Per-family birth-death | Ancestral counts per family | Family-level granularity | Older; less integrated with modern OrthoFinder |\n| ALE \u002F GeneRax \u002F AleRax (Szöllősi 2013; Morel 2024) | Per-family DTL reconciliation | Per-family D\u002FT\u002FL event counts | Direct integration with [[gene-tree-species-tree-reconciliation]] | Slower; per-family rather than across-family |\n| CAFExp \u002F CAFE 4.2 (DEPRECATED) | Earlier CAFE | -- | Historical | Use CAFE5 |\n| Whale.jl with WGD (Zwaenepoel 2019) | Bayesian DL+WGD | WGD-aware family dynamics | Native WGD integration | Julia ecosystem |\n| Functional enrichment downstream | clusterProfiler \u002F topGO on expanded\u002Fcontracted | GO\u002FKEGG enrichment | Standard | Multiple testing across families |\n\nMethodology evolves; CAFE5 is the modern standard; verify the current CAFE5 manual (hahnlab\u002FCAFE5) and Hahn lab papers before locking on a single approach.\n\n## Decision Tree by Experimental Scenario\n\n| Scenario | Recommended approach | Why |\n|----------|------------------------|-----|\n| Standard CAFE-style birth-death analysis | CAFE5 with gamma rate categories | Modern standard; handles rate variation |\n| Annotation-pipeline-heterogeneity | CAFE5-error mode | Explicit error modeling |\n| Post-WGD retention bias | CAFE5 + DupGen_finder classification + functional enrichment | Combine birth-death with WGD-specific analysis |\n| Lineage-specific gene-family-rate shifts correlated with phenotype | CAFE5 with binary phenotype | Standard CAFE workflow |\n| Ancestral gene-family counts at internal nodes | Count ASR | Per-node count posteriors |\n| Test for \"fast-evolving\" family on specific lineage | CAFE5 lambda-tree (per-clade lambda) | Compares lambdas across clades |\n| Functional enrichment in expanded families | clusterProfiler \u002F topGO on expansion lists | Standard |\n| HGT-affected families (prokaryotes) | ALE \u002F GeneRax per-family DTL (see [[gene-tree-species-tree-reconciliation]]) | DTL framework explicit |\n| Test if all families share single lambda | CAFE5 global lambda hypothesis | Restricted model |\n| Specific family analysis (e.g. immune gene family) | ALE \u002F AleRax per-family | Per-family detail |\n| Distinguish gain from loss as primary driver | Count separate D and L counts | Standard parsimony |\n| Convergent gene-family-rate shifts | RERconverge on family-count vectors | Trait-correlated rate shifts |\n| Identify ancestral pan-clade family complement | CAFE5 ASR at MRCA | Pre-radiation family complement |\n| Sub-clade-specific expansions in plant genomes | CAFE5 with clade-specific lambda | Compare angiosperm to gymnosperm |\n\n## Per-Tool Failure Modes\n\n### Annotation heterogeneity inflating expansions \u002F contractions\n\n**Trigger:** Running CAFE5 on counts from genomes annotated by different pipelines (Augustus, MAKER, BRAKER, NCBI).\n\n**Mechanism:** Different annotation tools predict different numbers of genes per family; the same biological gene family may be annotated with 5 genes in BRAKER and 8 in MAKER. CAFE5 sees the difference as an \"expansion\" in the MAKER-annotated species (Tonkin-Hill 2020 documented this for bacterial pangenomes; same principle in eukaryotes).\n\n**Symptom:** \"Most expanded families\" cluster in species annotated by a single pipeline (often more permissive tool); per-species \"expansion rate\" correlates with annotation pipeline rather than biology.\n\n**Fix:** Re-annotate all genomes with a single pipeline (currently BRAKER3 or Funannotate for eukaryotes; Bakta for bacteria) before CAFE5. Alternatively use CAFE5-error mode with explicit error rates per species. Document annotation pipeline + version per species.\n\n### Assembly fragmentation creating false contractions\n\n**Trigger:** Including draft assemblies with low N50 in CAFE5 analysis.\n\n**Mechanism:** Fragmented assemblies miss genes; the same family appears with fewer genes than expected. CAFE5 reports this as a contraction in the affected species.\n\n**Symptom:** \"Contracted\" families in fragmented assemblies; correlation between BUSCO completeness and CAFE5 \"contraction\" rate; per-species missing-gene count varies 5-10x.\n\n**Fix:** Require >= 90% BUSCO\u002FCompleasm completeness for inclusion. Exclude species with > 5% lower BUSCO than median. Document N50 + BUSCO per assembly. For unavoidably fragmented assemblies, exclude from CAFE5 or use CAFE5-error with empirical error estimates.\n\n### CAFE5 lambda non-convergence\n\n**Trigger:** CAFE5 reports \"lambda did not converge\"; lambda jumps between values across runs.\n\n**Mechanism:** Insufficient data (\u003C 100 families); strong rate heterogeneity not captured; or input tree non-ultrametric.\n\n**Symptom:** lambda estimate unstable; AIC of model selection variable.\n\n**Fix:** Require >= 100 orthogroups (preferably > 1000) in input. Ensure tree is ultrametric (`ape::chronos()` or `treePL`); CAFE5 expects time-scaled tree. Use gamma rate categories (CAFE5 default `-k 4`) for rate heterogeneity. If still non-convergent, restrict to single-copy or small families; check tree branch lengths for negative values.\n\n### Gamma rate-category misinterpretation\n\n**Trigger:** Reporting \"gamma rate categories\" as biological gene-family clusters.\n\n**Mechanism:** CAFE5 gamma categories are statistical buckets representing rate heterogeneity across families; they're not \"fast-evolving family clusters\" with biological meaning per se.\n\n**Symptom:** Confusion in interpretation; \"category-1 families are special.\"\n\n**Fix:** Treat gamma categories as a statistical device. Report per-family lambda (estimated under per-family rate model) or per-clade lambda. Functional interpretation comes from family-level statistical tests, not category assignment.\n\n### Multiple-testing across many families\n\n**Trigger:** Reporting \"significant\" expansions \u002F contractions without correction.\n\n**Mechanism:** With ~10,000 families tested, ~500 will be significant at p=0.05 under H0. Without correction, false-discovery rate is high.\n\n**Symptom:** Long lists of \"expanded\" families; functional enrichment dominated by chance hits.\n\n**Fix:** Apply FDR (Benjamini-Hochberg) across families; or restrict to a priori hypothesized families. CAFE5 reports per-family p-values; FDR-correct downstream.\n\n### Tree non-ultrametric \u002F negative branches\n\n**Trigger:** Using ML tree directly (substitutions per site) as input to CAFE5.\n\n**Mechanism:** CAFE5 expects ultrametric (time-calibrated) tree; substitution-based branch lengths are not time-calibrated and may even have negative branches after rate variation.\n\n**Symptom:** CAFE5 errors with \"negative branch length\"; or produces unreliable lambda estimates.\n\n**Fix:** Time-calibrate the tree: use `ape::chronos()`, treePL (Smith & O'Meara 2012 Bioinformatics 28:2689), or LSD2 (To et al 2016 Syst Biol 65:82; gascuel-lab\u002FLSD2) for fast NP-like calibration. Or use existing time-calibrated tree from TimeTree database.\n\n### Outlier-family-driven lambda estimate\n\n**Trigger:** Including extreme-size families (e.g., NLR resistance gene clusters in plants with 500+ members) in CAFE5.\n\n**Mechanism:** Birth-death model's likelihood is dominated by large families; one or two outlier families can overwhelm the global lambda estimate.\n\n**Symptom:** Excluding the top-5 largest families changes lambda by > 30%; lambda confidence intervals huge.\n\n**Fix:** Robust analysis: report lambda with and without outliers; consider per-family lambda for largest families. Functional annotation of outliers reveals if they're biologically expected expansions (rapidly evolving gene families).\n\n### Convergent gene-family-rate shifts not captured\n\n**Trigger:** Phylogenomic question is whether multiple independent lineages show similar gene-family-rate shifts.\n\n**Mechanism:** CAFE5 doesn't natively test for convergent rate shifts; per-clade lambda is the closest analog.\n\n**Symptom:** Manual inspection of expansions across independent lineages shows pattern; CAFE5 doesn't formalize it.\n\n**Fix:** Combine CAFE5 per-family lambdas with RERconverge (Redlich et al 2024 MBE 41:msae210) for trait-correlated rate shifts; use CSUBST (Fukushima 2023 Nat Eco Evo 7:155) for convergent substitution patterns.\n\n### CAFE5 vs ALE for HGT-affected family\n\n**Trigger:** Applying CAFE5 to bacterial families where transfer is common.\n\n**Mechanism:** CAFE5 models birth-death (D, L) only; ignores transfer (T). For HGT-affected families, the dynamics include T events that CAFE5 cannot capture.\n\n**Symptom:** CAFE5 lambda for bacterial families is implausibly high; family counts don't fit birth-death model.\n\n**Fix:** Use ALE \u002F GeneRax \u002F AleRax for HGT-affected families ([[gene-tree-species-tree-reconciliation]]); CAFE5 is appropriate for vertical-inheritance-dominated families. Combine: CAFE5 for the bulk; ALE for HGT-confirmed families.\n\n### Family classification (single-copy \u002F multi-copy) affecting interpretation\n\n**Trigger:** Treating single-copy orthogroups (always = 1 per species) and multi-copy uniformly.\n\n**Mechanism:** Single-copy OGs have no count variation; including them dilutes the analysis. Multi-copy families show meaningful variation.\n\n**Symptom:** Including single-copy OGs lowers lambda; per-family results dominated by them.\n\n**Fix:** Restrict CAFE5 input to multi-copy orthogroups (max count >= 2 in any species). Filter via OrthoFinder HOG-classification single-copy column.\n\n## Quantitative Thresholds\n\n| Quantity | Threshold | Source \u002F Rationale |\n|----------|-----------|-------------------|\n| Minimum orthogroups for CAFE5 | >= 100; preferably > 1000 | Mendes et al 2020 Bioinformatics 36:5516 |\n| Maximum gene-family count | depends on tree depth; typical \u003C 1000 per family | Practical |\n| BUSCO\u002FCompleasm completeness | >= 90% for inclusion | Standard |\n| FDR for expansions \u002F contractions | q \u003C 0.05 (Benjamini-Hochberg) | Standard |\n| Significant lambda shift | LRT p \u003C 0.05 \u002F corrected for clade tests | CAFE5 LRT |\n| Gamma categories | 4 default (`-k 4`) | CAFE5 docs |\n| Tree ultrametricity | required; calibrate with ape::chronos or treePL | CAFE5 requirement |\n| Per-clade lambda significance | LRT vs global lambda | CAFE5 docs |\n| Annotation pipeline | one pipeline across all species; document version | Best practice |\n| Functional enrichment q-value | q \u003C 0.05 (BH-corrected) | Standard |\n| Multi-copy family filter | max count across species >= 2 | Practical |\n| Tree time-calibration source | TimeTree, treePL, LSD2 | Standard alternatives |\n| Excluded singletons | yes, in some workflows | Standard |\n| Outlier family exclusion threshold | top 5% by max count, exclude or per-family lambda | Robust |\n| Convergent shift detection | RERconverge or CSUBST | Companion methods |\n\n## CAFE5 Standard Workflow\n\n**Goal:** Identify gene families with lineage-specific rate shifts (expansions \u002F contractions).\n\n**Approach:** Prepare ortholog count matrix -> ultrametricize tree -> run CAFE5 with gamma categories -> FDR-correct -> annotate.\n\n```bash\n# 1. Generate ortholog matrix from OrthoFinder v3 HOG file (inline Python; no external script needed)\npython3 \u003C\u003C'PY'\nimport pandas as pd\nhog = pd.read_csv('Phylogenetic_Hierarchical_Orthogroups\u002FN0.tsv', sep='\\t')\nsp_cols = [c for c in hog.columns if c not in ('HOG', 'OG', 'Gene Tree Parent Clade')]\ncounts = pd.DataFrame({sp: hog[sp].fillna('').apply(\n    lambda x: len(str(x).split(',')) if x and ',' in str(x) else (1 if str(x).strip() else 0)\n) for sp in sp_cols})\ncounts.insert(0, 'family_id', hog['HOG'])\ncounts.insert(0, 'Description', '(null)')\ncounts.to_csv('cafe_input.tsv', sep='\\t', index=False)\nPY\n\n# Output format: Description  family_id  Species1  Species2  ... (counts per species)\n\n# 2. Ultrametricize tree\nRscript -e \"\nlibrary(ape)\ntree \u003C- read.tree('SpeciesTree_rooted.txt')\ntree_ultra \u003C- chronos(tree)\nwrite.tree(tree_ultra, 'tree_ultrametric.nwk')\n\"\n\n# 3. Run CAFE5 with gamma categories\ncafe5 \\\n    -i cafe_input.tsv \\\n    -t tree_ultrametric.nwk \\\n    -p \\\n    -k 4 \\\n    -e \\\n    -o cafe_output\n# `-e` (no argument) lets CAFE5 estimate a global error model. To supply a pre-built\n# error model file, use `-eerror.txt` (CAFE5 concatenates the flag and argument).\n# Verify with `cafe5 --help`.\n\n# Output:\n#   cafe_output\u002FBase_results.txt        Per-family results\n#   cafe_output\u002FBase_clade_results.txt   Per-clade lambda\n#   cafe_output\u002FBase_asr.tre            ASR tree\n#   cafe_output\u002FBase_clade_results.txt   LRT against null\n\n# 4. FDR-correct across families (inline Python; see filter_significant_families() below)\n```\n\n```python\n'''Filter expanded \u002F contracted families with FDR-correction.'''\nimport pandas as pd\nfrom statsmodels.stats.multitest import multipletests\n\n\ndef filter_significant_families(cafe_results_path, change_table_path, fdr_threshold=0.05):\n    '''Identify families with significant rate shifts and their per-branch expansion\u002Fcontraction direction.\n\n    CAFE5 outputs (Base_family_results.txt or similar) include a per-family p-value (vs the null\n    of a single global lambda). The per-branch expansion\u002Fcontraction comes from a separate\n    `Base_change.tab` file (per-family x per-branch count change). Per-family lambda is NOT\n    a column in Base_family_results.txt; that's a global parameter.\n    '''\n    df = pd.read_csv(cafe_results_path, sep='\\t')\n    pcol = 'p-value' if 'p-value' in df.columns else 'pvalue'\n    df['fdr'] = multipletests(df[pcol].fillna(1.0), method='fdr_bh')[1]\n    significant = df[df['fdr'] \u003C fdr_threshold]\n\n    # Pair with per-branch change table; positive cell = expansion on that branch\n    changes = pd.read_csv(change_table_path, sep='\\t')\n    return {'significant_families': significant, 'per_branch_changes': changes}\n```\n\n## CAFE5-error for Annotation Heterogeneity\n\n```bash\n# Prepare per-species error rates (from BUSCO completeness or empirical)\ncat > error_rates.tsv \u003C\u003C 'EOF'\nspecies_id    error_rate\nSpecies_A     0.05\nSpecies_B     0.08\nSpecies_C     0.03\nEOF\n\n# Run with error-aware mode (supply pre-built error model file).\n# CAFE5 concatenates the -e flag with its argument (no space): -e\u003Cerror_model_file>\ncafe5 \\\n    -i cafe_input.tsv \\\n    -t tree_ultrametric.nwk \\\n    -p \\\n    -k 4 \\\n    -eerror_model.txt \\\n    -o cafe_error_output\n```\n\n## Count for Per-Branch Ancestral State\n\n```bash\n# Count requires Java\njava -jar Count.jar -i count_format.tsv -t species_tree.nwk \\\n    -o count_output --ancestral_counts\n\n# Per-branch D and L counts in count_output\u002Fbranch_events.tsv\n```\n\n## Functional Enrichment Downstream\n\n```r\nlibrary(clusterProfiler)\nlibrary(org.Hs.eg.db)  # or appropriate species DB\n\n# Enrichment of expanded families\nexpanded_genes \u003C- read.csv('expanded_genes.tsv', stringsAsFactors = FALSE)$gene_id\n\ngo_enrich \u003C- enrichGO(gene = expanded_genes,\n                      OrgDb = org.Hs.eg.db,\n                      ont = 'BP',\n                      pAdjustMethod = 'BH',\n                      pvalueCutoff = 0.05)\n\nkegg_enrich \u003C- enrichKEGG(gene = expanded_genes,\n                          organism = 'hsa',\n                          pvalueCutoff = 0.05)\n```\n\n## Reconciliation: When Methods Disagree\n\n| Pattern | Likely cause | Action |\n|---------|--------------|--------|\n| CAFE5 significant; ALE shows no DTL signal | CAFE5 detects count change; ALE detects events | Both can be true; CAFE5 is count-level, ALE is event-level |\n| CAFE5 significant in bacterial family | Possibly HGT-driven; CAFE5 ignores T | Re-run with ALE for HGT-affected families |\n| Per-clade lambda differs in CAFE5 vs uniform lambda | Real rate heterogeneity | Trust per-clade |\n| Annotation heterogeneity hypothesis | Re-annotation eliminates \"expansion\" | Confirm annotation artifact; report as such |\n| CAFE5 + RERconverge agree on expansion + trait shift | Convergent biological mechanism | Strong evidence |\n| Outlier-family-driven global lambda | Top-5 families distort estimate | Report robust lambda; manually flag outliers |\n| CAFE5 expansion in fragmented species | False; assembly fragmentation | Re-assess BUSCO; exclude or correct |\n| Single-copy family flagged as significant | Statistical artifact; no variation | Exclude single-copy OGs; restrict to multi-copy |\n| Whale.jl WGD branch shows D burst, CAFE5 shows expansion | Same event; WGD modeling preferred | Whale.jl is more biological for known WGD |\n| Count parsimony vs CAFE5 likelihood disagree | Parsimony underestimates losses | Trust CAFE5 likelihood |\n\n**Operational rule for publication:** CAFE5 with gamma rate categories + annotation pipeline normalized + BUSCO completeness > 90% + FDR-corrected significance + functional enrichment of expanded\u002Fcontracted + (for bacteria) ALE complement = publication-grade gene-family evolution analysis.\n\n## Cohort Gotchas\n\n- **WGD lineages:** post-WGD retention bias; gene balance hypothesis (Birchler & Veitia 2007); analyze with [[whole-genome-duplication]] context\n- **Plant gene families:** NLR clusters (resistance) and ribosomal proteins are inherently large; expect lineage variation\n- **Mammalian gene families:** olfactory receptors are highly variable; expect lineage-specific changes\n- **Bacterial gene families:** HGT-driven dynamics; use ALE\u002FAleRax instead of CAFE5\n- **Polyploid species:** subgenome assignment first; analyze each subgenome separately\n- **Rapidly evolving lineages:** higher branch-specific rates; per-clade lambda model\n- **Conserved species (e.g., extant cyanobacteria):** lambda may be very low; few changes to detect\n- **Recent radiations:** insufficient time for divergence; CAFE5 may have low power\n- **Highly fragmented MAGs:** include only high-quality MAGs\n\n## Anticipated Reviewer Pushback\n\n| Pushback | Standard response |\n|----------|-------------------|\n| \"Annotation pipeline?\" | Single pipeline (BRAKER3 \u002F Funannotate \u002F Bakta) across all species; version pinned |\n| \"BUSCO completeness?\" | >= 90% required; per-species reported |\n| \"Assembly fragmentation?\" | N50 reported; species with > 5% lower BUSCO than median excluded |\n| \"Multiple testing?\" | FDR (Benjamini-Hochberg) applied across families |\n| \"Lambda non-convergence?\" | CAFE5 with -k 4 gamma categories; tree ultrametricized |\n| \"Outlier families?\" | Robust analysis with and without; outliers individually annotated |\n| \"HGT in bacteria?\" | ALE \u002F GeneRax cross-checked for HGT-affected families |\n| \"Functional enrichment?\" | clusterProfiler \u002F topGO with FDR; pathway-level interpretation |\n| \"Tree time-calibration?\" | TimeTree-based or treePL\u002FLSD2; documented |\n| \"WGD effects?\" | DupGen_finder + WGD-specific analysis; subgenome-aware |\n| \"Convergent shifts?\" | RERconverge complementary analysis |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|-----------------|-------|----------|\n| CAFE5 \"lambda did not converge\" | Insufficient data or non-ultrametric tree | Ultrametricize; increase families; check tree |\n| CAFE5 \"negative branch length\" | ML tree input | Time-calibrate with chronos \u002F treePL \u002F LSD2 |\n| CAFE5 errors on input format | Wrong column order | Check OrthoFinder HOG format; species in column 2 onward |\n| Count GUI hangs | Java memory | Increase Java heap: `java -Xmx16G -jar Count.jar` |\n| BadiRate gamma errors | Initialization issue | Use default `-g 1` or specify per family |\n| Per-clade lambda implausibly high | Outlier family or tree issue | Exclude top families; re-run |\n| All families significant | No FDR correction | Apply BH correction |\n| Annotation heterogeneity not addressed | Mixed pipelines | Re-annotate consistently |\n| Family with 0 count for all species | Annotation issue | Filter rows with all zeros |\n| Highly variable family count (e.g. 500-5000) | Real biological variation or annotation | Annotate manually; consider exclusion |\n\n## Tool Installation Notes\n\n```bash\n# CAFE5\nconda install -c bioconda cafe\n# Or: git clone https:\u002F\u002Fgithub.com\u002Fhahnlab\u002FCAFE5\n\n# Count\nwget http:\u002F\u002Fwww.iro.umontreal.ca\u002F~csuros\u002Fgene_content\u002Fcount.tar.gz\ntar xf count.tar.gz\n\n# BadiRate\ngit clone https:\u002F\u002Fgithub.com\u002FPauloRoldan\u002Fbadirate\n\n# DupliPHY-Family\n# Web only; no public CLI\n\n# Whale.jl (Julia) -- see [[gene-tree-species-tree-reconciliation]]\njulia -e 'using Pkg; Pkg.add(\"Whale\")'\n\n# R packages\ninstall.packages(c('ape', 'phytools', 'clusterProfiler', 'org.Hs.eg.db'))\n\n# Time calibration\nconda install -c bioconda treepl\n# Or use ape::chronos (R)\n\n# For OrthoFinder input\nconda install -c bioconda orthofinder\n```\n\nFor Funannotate \u002F BRAKER3 reannotation (essential pre-CAFE5):\n```bash\nconda install -c bioconda funannotate braker3\n```\n\n## References\n\n- Hahn MW et al 2005 Genome Res 15:1153 (CAFE original framework)\n- Mendes FK et al 2020 Bioinformatics 36:5516 (CAFE5)\n- Csurös M 2010 Bioinformatics 26:1910 (Count)\n- Librado P et al 2012 Bioinformatics 28:279 (BadiRate)\n- Ames RM et al 2012 Bioinformatics 28:48 (DupliPHY-Family)\n- Tonkin-Hill G et al 2020 Genome Biol 21:180 (Panaroo; annotation heterogeneity)\n- Smith SA & Dunn CW 2008 Bioinformatics 24:715 (Phyutility)\n- Smith SA & O'Meara BC 2012 Bioinformatics 28:2689 (treePL)\n- To T-H, Jung M, Lycett S & Gascuel O 2016 Syst Biol 65:82 (LSD2)\n- Birchler JA & Veitia RA 2007 Plant Cell 19:395 (gene balance)\n- Redlich R et al 2024 MBE 41:msae210 (RERconverge categorical)\n- Fukushima K & Pollock DD 2023 Nat Eco Evo 7:155 (CSUBST)\n- Lynch M & Conery JS 2000 Science 290:1151 (gene duplication mechanism)\n- Force A et al 1999 Genetics 151:1531 (subfunctionalization)\n- De Bie T et al 2006 Bioinformatics 22:1269 (CAFE original software)\n- Han MV et al 2013 MBE 30:1987 (CAFE 3)\n- Otto SP & Whitton J 2000 Annu Rev Genet 34:401 (polyploidy mechanisms)\n- TimeTree (database, http:\u002F\u002Fwww.timetree.org)\n\n## Related Skills\n\n- comparative-genomics\u002Fortholog-inference - OrthoFinder HOG matrix is CAFE5 input\n- comparative-genomics\u002Fgene-tree-species-tree-reconciliation - ALE per-family DTL, complement to CAFE5\n- comparative-genomics\u002Fwhole-genome-duplication - Post-WGD retention bias context\n- comparative-genomics\u002Fpositive-selection - Selection within expanded families\n- comparative-genomics\u002Fancestral-reconstruction - Ancestral count reconstruction\n- phylogenetics\u002Fdivergence-dating - Time-calibrated tree for CAFE5\n- phylogenetics\u002Fmodern-tree-inference - Species tree input\n- pathway-analysis\u002Fgo-enrichment - Functional enrichment of expanded families\n- pathway-analysis\u002Fgsea - GSEA on family expansions\n- single-cell\u002Fcell-annotation - Cell-type-specific gene-family expansions\n","## Version Compatibility\n\nReference examples tested with: CAFE5 5.1.0+ (Mendes et al 2020 Bioinformatics 36(22-23):5516-5518), Count 11.0319+ (Csurös 2010 Bioinformatics 26:1910), BadiRate 1.35+ (Librado 2012 Bioinformatics 28:279), DupliPHY-Family (Ames et al 2012), CAFExp (legacy CAFE 4.2 -- DEPRECATED; use CAFE5), OrthoFinder 3.0+ for HOG input, R 4.4+, mclust 6.1+, phytools 2.3+, ETE4 4.1.0+ for tree manipulation. ALE\u002FGeneRax\u002FAleRax in companion skill [[gene-tree-species-tree-reconciliation]].\n\nBefore using code patterns, verify installed versions match. If versions differ:\n- CLI: `cafe5 --help`; `Count.exe` (Java); `badirate --help`\n- R: `packageVersion('phytools')`\n- Python: `pip show ete4`\n\nIf code throws `CAFE5: lambda did not converge`, `Count negative branch length`, `BadiRate gamma not initialized`, the most common causes are: (1) annotation heterogeneity inflating family sizes, (2) saturated families (CAFE5 needs reasonable rate variation), (3) negative branch lengths in input tree (Count requires ultrametric). Pre-process: filter OG matrix to families present in >= 50% of species; resolve polytomies; ultrametricize tree.\n\n# Gene Family Evolution\n\n**\"Which gene families expanded or contracted in which lineages?\"** -> Birth-death models on phylogeny (Hahn 2005; Csurös 2010) treat each orthogroup's per-species count as evolving under a stochastic birth-death process; lineage-specific rate shifts are detected as departures from a global rate. **Annotation heterogeneity is the single largest confounder**: different annotation pipelines predict different numbers of genes per family, producing apparent lineage-specific expansions that are artifacts of annotation choice (Tonkin-Hill 2020 demonstrated this for bacterial pangenomes). Consistent annotation + BUSCO\u002FCompleasm completeness filtering are mandatory before any birth-death model interpretation. CAFE5 (Mendes et al 2020 Bioinformatics 36:5516) replaces older CAFE versions with gamma-distributed rate categories for more biologically realistic modeling.\n\n- CLI: `cafe5 -i orthogroup_counts.tsv -t species_tree.nwk -p` -- main CAFE5 workflow\n- CLI: `cafe5 -e` -- error-aware mode for annotation uncertainty\n- CLI: `Count` -- Java GUI \u002F CLI for parsimony + likelihood ASR\n- CLI: `badirate -t tree.nwk -d counts.tsv` -- likelihood birth-death + branch parsimony\n\n## Algorithmic Taxonomy\n\n| Tool | Approach | Output | Strength | Fails when |\n|------|----------|--------|----------|------------|\n| CAFE5 (Mendes et al 2020 Bioinformatics 36(22-23):5516-5518) | Birth-death with gamma rate categories | Global \u002F per-family lambda + significant rate shifts | Modern standard; handles rate heterogeneity; explicit Type-I control | Annotation heterogeneity confounds; needs > 100 families |\n| CAFE5-error | Annotation-error-aware extension | Same plus error estimates | Critical for noisy annotations | Manual error-rate specification or estimation |\n| Count (Csurös 2010 Bioinformatics 26:1910) | Both ML and parsimony ASR | Branch event counts (D, L) per family | Comprehensive output; GUI | Slower than CAFE5; less modern UX |\n| BadiRate (Librado 2012 Bioinformatics 28:279) | Likelihood birth-death + branch parsimony | Lineage-specific rate shifts | Combines stochastic + parsimony | Less commonly used; older |\n| DupliPHY-Family (Ames et al 2012) | Per-family birth-death | Ancestral counts per family | Family-level granularity | Older; less integrated with modern OrthoFinder |\n| ALE \u002F GeneRax \u002F AleRax (Szöllősi 2013; Morel 2024) | Per-family DTL reconciliation | Per-family D\u002FT\u002FL event counts | Direct integration with [[gene-tree-species-tree-reconciliation]] | Slower; per-family rather than across-family |\n| CAFExp \u002F CAFE 4.2 (DEPRECATED) | Earlier CAFE | -- | Historical | Use CAFE5 |\n| Whale.jl with WGD (Zwaenepoel 2019) | Bayesian DL+WGD | WGD-aware family dynamics | Native WGD integration | Julia ecosystem |\n| Functional enrichment downstream | clusterProfiler \u002F topGO on expanded\u002Fcontracted | GO\u002FKEGG enrichment | Standard | Multiple testing across families |\n\nMethodology evolves; CAFE5 is the modern standard; verify the current CAFE5 manual (hahnlab\u002FCAFE5) and Hahn lab papers before locking on a single approach.\n\n## Decision Tree by Experimental Scenario\n\n| Scenario | Recommended approach | Why |\n|----------|------------------------|-----|\n| Standard CAFE-style birth-death analysis | CAFE5 with gamma rate categories | Modern standard; handles rate variation |\n| Annotation-pipeline-heterogeneity | CAFE5-error mode | Explicit error modeling |\n| Post-WGD retention bias | CAFE5 + DupGen_finder classification + functional enrichment | Combine birth-death with WGD-specific analysis |\n| Lineage-specific gene-family-rate shifts correlated with phenotype | CAFE5 with binary phenotype | Standard CAFE workflow |\n| Ancestral gene-family counts at internal nodes | Count ASR | Per-node count posteriors |\n| Test for \"fast-evolving\" family on specific lineage | CAFE5 lambda-tree (per-clade lambda) | Compares lambdas across clades |\n| Functional enrichment in expanded families | clusterProfiler \u002F topGO on expansion lists | Standard |\n| HGT-affected families (prokaryotes) | ALE \u002F GeneRax per-family DTL (see [[gene-tree-species-tree-reconciliation]]) | DTL framework explicit |\n| Test if all families share single lambda | CAFE5 global lambda hypothesis | Restricted model |\n| Specific family analysis (e.g. immune gene family) | ALE \u002F AleRax per-family | Per-family detail |\n| Distinguish gain from loss as primary driver | Count separate D and L counts | Standard parsimony |\n| Convergent gene-family-rate shifts | RERconverge on family-count vectors | Trait-correlated rate shifts |\n| Identify ancestral pan-clade family complement | CAFE5 ASR at MRCA | Pre-radiation family complement |\n| Sub-clade-specific expansions in plant genomes | CAFE5 with clade-specific lambda | Compare angiosperm to gymnosperm |\n\n## Per-Tool Failure Modes\n\n### Annotation heterogeneity inflating expansions \u002F contractions\n\n**Trigger:** Running CAFE5 on counts from genomes annotated by different pipelines (Augustus, MAKER, BRAKER, NCBI).\n\n**Mechanism:** Different annotation tools predict different numbers of genes per family; the same biological gene family may be annotated with 5 genes in BRAKER and 8 in MAKER. CAFE5 sees the difference as an \"expansion\" in the MAKER-annotated species (Tonkin-Hill 2020 documented this for bacterial pangenomes; same principle in eukaryotes).\n\n**Symptom:** \"Most expanded families\" cluster in species annotated by a single pipeline (often more permissive tool); per-species \"expansion rate\" correlates with annotation pipeline rather than biology.\n\n**Fix:** Re-annotate all genomes with a single pipeline (currently BRAKER3 or Funannotate for eukaryotes; Bakta for bacteria) before CAFE5. Alternatively use CAFE5-error mode with explicit error rates per species. Document annotation pipeline + version per species.\n\n### Assembly fragmentation creating false contractions\n\n**Trigger:** Including draft assemblies with low N50 in CAFE5 analysis.\n\n**Mechanism:** Fragmented assemblies miss genes; the same family appears with fewer genes than expected. CAFE5 reports this as a contraction in the affected species.\n\n**Symptom:** \"Contracted\" families in fragmented assemblies; correlation between BUSCO completeness and CAFE5 \"contraction\" rate; per-species missing-gene count varies 5-10x.\n\n**Fix:** Require >= 90% BUSCO\u002FCompleasm completeness for inclusion. Exclude species with > 5% lower BUSCO than median. Document N50 + BUSCO per assembly. For unavoidably fragmented assemblies, exclude from CAFE5 or use CAFE5-error with empirical error estimates.\n\n### CAFE5 lambda non-convergence\n\n**Trigger:** CAFE5 reports \"lambda did not converge\"; lambda jumps between values across runs.\n\n**Mechanism:** Insufficient data (\u003C 100 families); strong rate heterogeneity not captured; or input tree non-ultrametric.\n\n**Symptom:** lambda estimate unstable; AIC of model selection variable.\n\n**Fix:** Require >= 100 orthogroups (preferably > 1000) in input. Ensure tree is ultrametric (`ape::chronos()` or `treePL`); CAFE5 expects time-scaled tree. Use gamma rate categories (CAFE5 default `-k 4`) for rate heterogeneity. If still non-convergent, restrict to single-copy or small families; check tree branch lengths for negative values.\n\n### Gamma rate-category misinterpretation\n\n**Trigger:** Reporting \"gamma rate categories\" as biological gene-family clusters.\n\n**Mechanism:** CAFE5 gamma categories are statistical buckets representing rate heterogeneity across families; they're not \"fast-evolving family clusters\" with biological meaning per se.\n\n**Symptom:** Confusion in interpretation; \"category-1 families are special.\"\n\n**Fix:** Treat gamma categories as a statistical device. Report per-family lambda (estimated under per-family rate model) or per-clade lambda. Functional interpretation comes from family-level statistical tests, not category assignment.\n\n### Multiple-testing across many families\n\n**Trigger:** Reporting \"significant\" expansions \u002F contractions without correction.\n\n**Mechanism:** With ~10,000 families tested, ~500 will be significant at p=0.05 under H0. Without correction, false-discovery rate is high.\n\n**Symptom:** Long lists of \"expanded\" families; functional enrichment dominated by chance hits.\n\n**Fix:** Apply FDR (Benjamini-Hochberg) across families; or restrict to a priori hypothesized families. CAFE5 reports per-family p-values; FDR-correct downstream.\n\n### Tree non-ultrametric \u002F negative branches\n\n**Trigger:** Using ML tree directly (substitutions per site) as input to CAFE5.\n\n**Mechanism:** CAFE5 expects ultrametric (time-calibrated) tree; substitution-based branch lengths are not time-calibrated and may even have negative branches after rate variation.\n\n**Symptom:** CAFE5 errors with \"negative branch length\"; or produces unreliable lambda estimates.\n\n**Fix:** Time-calibrate the tree: use `ape::chronos()`, treePL (Smith & O'Meara 2012 Bioinformatics 28:2689), or LSD2 (To et al 2016 Syst Biol 65:82; gascuel-lab\u002FLSD2) for fast NP-like calibration. Or use existing time-calibrated tree from TimeTree database.\n\n### Outlier-family-driven lambda estimate\n\n**Trigger:** Including extreme-size families (e.g., NLR resistance gene clusters in plants with 500+ members) in CAFE5.\n\n**Mechanism:** Birth-death model's likelihood is dominated by large families; one or two outlier families can overwhelm the global lambda estimate.\n\n**Symptom:** Excluding the top-5 largest families changes lambda by > 30%; lambda confidence intervals huge.\n\n**Fix:** Robust analysis: report lambda with and without outliers; consider per-family lambda for largest families. Functional annotation of outliers reveals if they're biologically expected expansions (rapidly evolving gene families).\n\n### Convergent gene-family-rate shifts not captured\n\n**Trigger:** Phylogenomic question is whether multiple independent lineages show similar gene-family-rate shifts.\n\n**Mechanism:** CAFE5 doesn't natively test for convergent rate shifts; per-clade lambda is the closest analog.\n\n**Symptom:** Manual inspection of expansions across independent lineages shows pattern; CAFE5 doesn't formalize it.\n\n**Fix:** Combine CAFE5 per-family lambdas with RERconverge (Redlich et al 2024 MBE 41:msae210) for trait-correlated rate shifts; use CSUBST (Fukushima 2023 Nat Eco Evo 7:155) for convergent substitution patterns.\n\n### CAFE5 vs ALE for HGT-affected family\n\n**Trigger:** Applying CAFE5 to bacterial families where transfer is common.\n\n**Mechanism:** CAFE5 models birth-death (D, L) only; ignores transfer (T). For HGT-affected families, the dynamics include T events that CAFE5 cannot capture.\n\n**Symptom:** CAFE5 lambda for bacterial families is implausibly high; family counts don't fit birth-death model.\n\n**Fix:** Use ALE \u002F GeneRax \u002F AleRax for HGT-affected families ([[gene-tree-species-tree-reconciliation]]); CAFE5 is appropriate for vertical-inheritance-dominated families. Combine: CAFE5 for the bulk; ALE for HGT-confirmed families.\n\n### Family classification (single-copy \u002F multi-copy) affecting interpretation\n\n**Trigger:** Treating single-copy orthogroups (always = 1 per species) and multi-copy uniformly.\n\n**Mechanism:** Single-copy OGs have no count variation; including them dilutes the analysis. Multi-copy families show meaningful variation.\n\n**Symptom:** Including single-copy OGs lowers lambda; per-family results dominated by them.\n\n**Fix:** Restrict CAFE5 input to multi-copy orthogroups (max count >= 2 in any species). Filter via OrthoFinder HOG-classification single-copy column.\n\n## Quantitative Thresholds\n\n| Quantity | Threshold | Source \u002F Rationale |\n|----------|-----------|-------------------|\n| Minimum orthogroups for CAFE5 | >= 100; preferably > 1000 | Mendes et al 2020 Bioinformatics 36:5516 |\n| Maximum gene-family count | depends on tree depth; typical \u003C 1000 per family | Practical |\n| BUSCO\u002FCompleasm completeness | >= 90% for inclusion | Standard |\n| FDR for expansions \u002F contractions | q \u003C 0.05 (Benjamini-Hochberg) | Standard |\n| Significant lambda shift | LRT p \u003C 0.05 \u002F corrected for clade tests | CAFE5 LRT |\n| Gamma categories | 4 default (`-k 4`) | CAFE5 docs |\n| Tree ultrametricity | required; calibrate with ape::chronos or treePL | CAFE5 requirement |\n| Per-clade lambda significance | LRT vs global lambda | CAFE5 docs |\n| Annotation pipeline | one pipeline across all species; document version | Best practice |\n| Functional enrichment q-value | q \u003C 0.05 (BH-corrected) | Standard |\n| Multi-copy family filter | max count across species >= 2 | Practical |\n| Tree time-calibration source | TimeTree, treePL, LSD2 | Standard alternatives |\n| Excluded singletons | yes, in some workflows | Standard |\n| Outlier family exclusion threshold | top 5% by max count, exclude or per-family lambda | Robust |\n| Convergent shift detection | RERconverge or CSUBST | Companion methods |\n\n## CAFE5 Standard Workflow\n\n**Goal:** Identify gene families with lineage-specific rate shifts (expansions \u002F contractions).\n\n**Approach:** Prepare ortholog count matrix -> ultrametricize tree -> run CAFE5 with gamma categories -> FDR-correct -> annotate.\n\n```bash\n# 1. Generate ortholog matrix from OrthoFinder v3 HOG file (inline Python; no external script needed)\npython3 \u003C\u003C'PY'\nimport pandas as pd\nhog = pd.read_csv('Phylogenetic_Hierarchical_Orthogroups\u002FN0.tsv', sep='\\t')\nsp_cols = [c for c in hog.columns if c not in ('HOG', 'OG', 'Gene Tree Parent Clade')]\ncounts = pd.DataFrame({sp: hog[sp].fillna('').apply(\n    lambda x: len(str(x).split(',')) if x and ',' in str(x) else (1 if str(x).strip() else 0)\n) for sp in sp_cols})\ncounts.insert(0, 'family_id', hog['HOG'])\ncounts.insert(0, 'Description', '(null)')\ncounts.to_csv('cafe_input.tsv', sep='\\t', index=False)\nPY\n\n# Output format: Description  family_id  Species1  Species2  ... (counts per species)\n\n# 2. Ultrametricize tree\nRscript -e \"\nlibrary(ape)\ntree \u003C- read.tree('SpeciesTree_rooted.txt')\ntree_ultra \u003C- chronos(tree)\nwrite.tree(tree_ultra, 'tree_ultrametric.nwk')\n\"\n\n# 3. Run CAFE5 with gamma categories\ncafe5 \\\n    -i cafe_input.tsv \\\n    -t tree_ultrametric.nwk \\\n    -p \\\n    -k 4 \\\n    -e \\\n    -o cafe_output\n# `-e` (no argument) lets CAFE5 estimate a global error model. To supply a pre-built\n# error model file, use `-eerror.txt` (CAFE5 concatenates the flag and argument).\n# Verify with `cafe5 --help`.\n\n# Output:\n#   cafe_output\u002FBase_results.txt        Per-family results\n#   cafe_output\u002FBase_clade_results.txt   Per-clade lambda\n#   cafe_output\u002FBase_asr.tre            ASR tree\n#   cafe_output\u002FBase_clade_results.txt   LRT against null\n\n# 4. FDR-correct across families (inline Python; see filter_significant_families() below)\n```\n\n```python\n'''Filter expanded \u002F contracted families with FDR-correction.'''\nimport pandas as pd\nfrom statsmodels.stats.multitest import multipletests\n\n\ndef filter_significant_families(cafe_results_path, change_table_path, fdr_threshold=0.05):\n    '''Identify families with significant rate shifts and their per-branch expansion\u002Fcontraction direction.\n\n    CAFE5 outputs (Base_family_results.txt or similar) include a per-family p-value (vs the null\n    of a single global lambda). The per-branch expansion\u002Fcontraction comes from a separate\n    `Base_change.tab` file (per-family x per-branch count change). Per-family lambda is NOT\n    a column in Base_family_results.txt; that's a global parameter.\n    '''\n    df = pd.read_csv(cafe_results_path, sep='\\t')\n    pcol = 'p-value' if 'p-value' in df.columns else 'pvalue'\n    df['fdr'] = multipletests(df[pcol].fillna(1.0), method='fdr_bh')[1]\n    significant = df[df['fdr'] \u003C fdr_threshold]\n\n    # Pair with per-branch change table; positive cell = expansion on that branch\n    changes = pd.read_csv(change_table_path, sep='\\t')\n    return {'significant_families': significant, 'per_branch_changes': changes}\n```\n\n## CAFE5-error for Annotation Heterogeneity\n\n```bash\n# Prepare per-species error rates (from BUSCO completeness or empirical)\ncat > error_rates.tsv \u003C\u003C 'EOF'\nspecies_id    error_rate\nSpecies_A     0.05\nSpecies_B     0.08\nSpecies_C     0.03\nEOF\n\n# Run with error-aware mode (supply pre-built error model file).\n# CAFE5 concatenates the -e flag with its argument (no space): -e\u003Cerror_model_file>\ncafe5 \\\n    -i cafe_input.tsv \\\n    -t tree_ultrametric.nwk \\\n    -p \\\n    -k 4 \\\n    -eerror_model.txt \\\n    -o cafe_error_output\n```\n\n## Count for Per-Branch Ancestral State\n\n```bash\n# Count requires Java\njava -jar Count.jar -i count_format.tsv -t species_tree.nwk \\\n    -o count_output --ancestral_counts\n\n# Per-branch D and L counts in count_output\u002Fbranch_events.tsv\n```\n\n## Functional Enrichment Downstream\n\n```r\nlibrary(clusterProfiler)\nlibrary(org.Hs.eg.db)  # or appropriate species DB\n\n# Enrichment of expanded families\nexpanded_genes \u003C- read.csv('expanded_genes.tsv', stringsAsFactors = FALSE)$gene_id\n\ngo_enrich \u003C- enrichGO(gene = expanded_genes,\n                      OrgDb = org.Hs.eg.db,\n                      ont = 'BP',\n                      pAdjustMethod = 'BH',\n                      pvalueCutoff = 0.05)\n\nkegg_enrich \u003C- enrichKEGG(gene = expanded_genes,\n                          organism = 'hsa',\n                          pvalueCutoff = 0.05)\n```\n\n## Reconciliation: When Methods Disagree\n\n| Pattern | Likely cause | Action |\n|---------|--------------|--------|\n| CAFE5 significant; ALE shows no DTL signal | CAFE5 detects count change; ALE detects events | Both can be true; CAFE5 is count-level, ALE is event-level |\n| CAFE5 significant in bacterial family | Possibly HGT-driven; CAFE5 ignores T | Re-run with ALE for HGT-affected families |\n| Per-clade lambda differs in CAFE5 vs uniform lambda | Real rate heterogeneity | Trust per-clade |\n| Annotation heterogeneity hypothesis | Re-annotation eliminates \"expansion\" | Confirm annotation artifact; report as such |\n| CAFE5 + RERconverge agree on expansion + trait shift | Convergent biological mechanism | Strong evidence |\n| Outlier-family-driven global lambda | Top-5 families distort estimate | Report robust lambda; manually flag outliers |\n| CAFE5 expansion in fragmented species | False; assembly fragmentation | Re-assess BUSCO; exclude or correct |\n| Single-copy family flagged as significant | Statistical artifact; no variation | Exclude single-copy OGs; restrict to multi-copy |\n| Whale.jl WGD branch shows D burst, CAFE5 shows expansion | Same event; WGD modeling preferred | Whale.jl is more biological for known WGD |\n| Count parsimony vs CAFE5 likelihood disagree | Parsimony underestimates losses | Trust CAFE5 likelihood |\n\n**Operational rule for publication:** CAFE5 with gamma rate categories + annotation pipeline normalized + BUSCO completeness > 90% + FDR-corrected significance + functional enrichment of expanded\u002Fcontracted + (for bacteria) ALE complement = publication-grade gene-family evolution analysis.\n\n## Cohort Gotchas\n\n- **WGD lineages:** post-WGD retention bias; gene balance hypothesis (Birchler & Veitia 2007); analyze with [[whole-genome-duplication]] context\n- **Plant gene families:** NLR clusters (resistance) and ribosomal proteins are inherently large; expect lineage variation\n- **Mammalian gene families:** olfactory receptors are highly variable; expect lineage-specific changes\n- **Bacterial gene families:** HGT-driven dynamics; use ALE\u002FAleRax instead of CAFE5\n- **Polyploid species:** subgenome assignment first; analyze each subgenome separately\n- **Rapidly evolving lineages:** higher branch-specific rates; per-clade lambda model\n- **Conserved species (e.g., extant cyanobacteria):** lambda may be very low; few changes to detect\n- **Recent radiations:** insufficient time for divergence; CAFE5 may have low power\n- **Highly fragmented MAGs:** include only high-quality MAGs\n\n## Anticipated Reviewer Pushback\n\n| Pushback | Standard response |\n|----------|-------------------|\n| \"Annotation pipeline?\" | Single pipeline (BRAKER3 \u002F Funannotate \u002F Bakta) across all species; version pinned |\n| \"BUSCO completeness?\" | >= 90% required; per-species reported |\n| \"Assembly fragmentation?\" | N50 reported; species with > 5% lower BUSCO than median excluded |\n| \"Multiple testing?\" | FDR (Benjamini-Hochberg) applied across families |\n| \"Lambda non-convergence?\" | CAFE5 with -k 4 gamma categories; tree ultrametricized |\n| \"Outlier families?\" | Robust analysis with and without; outliers individually annotated |\n| \"HGT in bacteria?\" | ALE \u002F GeneRax cross-checked for HGT-affected families |\n| \"Functional enrichment?\" | clusterProfiler \u002F topGO with FDR; pathway-level interpretation |\n| \"Tree time-calibration?\" | TimeTree-based or treePL\u002FLSD2; documented |\n| \"WGD effects?\" | DupGen_finder + WGD-specific analysis; subgenome-aware |\n| \"Convergent shifts?\" | RERconverge complementary analysis |\n\n## Common Errors\n\n| Error \u002F symptom | Cause | Solution |\n|-----------------|-------|----------|\n| CAFE5 \"lambda did not converge\" | Insufficient data or non-ultrametric tree | Ultrametricize; increase families; check tree |\n| CAFE5 \"negative branch length\" | ML tree input | Time-calibrate with chronos \u002F treePL \u002F LSD2 |\n| CAFE5 errors on input format | Wrong column order | Check OrthoFinder HOG format; species in column 2 onward |\n| Count GUI hangs | Java memory | Increase Java heap: `java -Xmx16G -jar Count.jar` |\n| BadiRate gamma errors | Initialization issue | Use default `-g 1` or specify per family |\n| Per-clade lambda implausibly high | Outlier family or tree issue | Exclude top families; re-run |\n| All families significant | No FDR correction | Apply BH correction |\n| Annotation heterogeneity not addressed | Mixed pipelines | Re-annotate consistently |\n| Family with 0 count for all species | Annotation issue | Filter rows with all zeros |\n| Highly variable family count (e.g. 500-5000) | Real biological variation or annotation | Annotate manually; consider exclusion |\n\n## Tool Installation Notes\n\n```bash\n# CAFE5\nconda install -c bioconda cafe\n# Or: git clone https:\u002F\u002Fgithub.com\u002Fhahnlab\u002FCAFE5\n\n# Count\nwget http:\u002F\u002Fwww.iro.umontreal.ca\u002F~csuros\u002Fgene_content\u002Fcount.tar.gz\ntar xf count.tar.gz\n\n# BadiRate\ngit clone https:\u002F\u002Fgithub.com\u002FPauloRoldan\u002Fbadirate\n\n# DupliPHY-Family\n# Web only; no public CLI\n\n# Whale.jl (Julia) -- see [[gene-tree-species-tree-reconciliation]]\njulia -e 'using Pkg; Pkg.add(\"Whale\")'\n\n# R packages\ninstall.packages(c('ape', 'phytools', 'clusterProfiler', 'org.Hs.eg.db'))\n\n# Time calibration\nconda install -c bioconda treepl\n# Or use ape::chronos (R)\n\n# For OrthoFinder input\nconda install -c bioconda orthofinder\n```\n\nFor Funannotate \u002F BRAKER3 reannotation (essential pre-CAFE5):\n```bash\nconda install -c bioconda funannotate braker3\n```\n\n## References\n\n- Hahn MW et al 2005 Genome Res 15:1153 (CAFE original framework)\n- Mendes FK et al 2020 Bioinformatics 36:5516 (CAFE5)\n- Csurös M 2010 Bioinformatics 26:1910 (Count)\n- Librado P et al 2012 Bioinformatics 28:279 (BadiRate)\n- Ames RM et al 2012 Bioinformatics 28:48 (DupliPHY-Family)\n- Tonkin-Hill G et al 2020 Genome Biol 21:180 (Panaroo; annotation heterogeneity)\n- Smith SA & Dunn CW 2008 Bioinformatics 24:715 (Phyutility)\n- Smith SA & O'Meara BC 2012 Bioinformatics 28:2689 (treePL)\n- To T-H, Jung M, Lycett S & Gascuel O 2016 Syst Biol 65:82 (LSD2)\n- Birchler JA & Veitia RA 2007 Plant Cell 19:395 (gene balance)\n- Redlich R et al 2024 MBE 41:msae210 (RERconverge categorical)\n- Fukushima K & Pollock DD 2023 Nat Eco Evo 7:155 (CSUBST)\n- Lynch M & Conery JS 2000 Science 290:1151 (gene duplication mechanism)\n- Force A et al 1999 Genetics 151:1531 (subfunctionalization)\n- De Bie T et al 2006 Bioinformatics 22:1269 (CAFE original software)\n- Han MV et al 2013 MBE 30:1987 (CAFE 3)\n- Otto SP & Whitton J 2000 Annu Rev Genet 34:401 (polyploidy mechanisms)\n- TimeTree (database, http:\u002F\u002Fwww.timetree.org)\n\n## Related Skills\n\n- comparative-genomics\u002Fortholog-inference - OrthoFinder HOG matrix is CAFE5 input\n- comparative-genomics\u002Fgene-tree-species-tree-reconciliation - ALE per-family DTL, complement to CAFE5\n- comparative-genomics\u002Fwhole-genome-duplication - Post-WGD retention bias context\n- comparative-genomics\u002Fpositive-selection - Selection within expanded families\n- comparative-genomics\u002Fancestral-reconstruction - Ancestral count reconstruction\n- phylogenetics\u002Fdivergence-dating - Time-calibrated tree for CAFE5\n- phylogenetics\u002Fmodern-tree-inference - Species tree input\n- pathway-analysis\u002Fgo-enrichment - Functional enrichment of expanded families\n- pathway-analysis\u002Fgsea - GSEA on family expansions\n- single-cell\u002Fcell-annotation - Cell-type-specific gene-family expansions\n",{"name":5,"source":24,"license":15,"tool_type":25,"description":7,"imported_at":26,"source_path":27,"primary_tool":28,"source_repository":29},"https:\u002F\u002Fgithub.com\u002FGPTomics\u002FbioSkills","cli","2026-09-20","comparative-genomics\u002Fgene-family-evolution\u002FSKILL.md","CAFE5","GPTomics\u002FbioSkills","main","2d1750717747097b602acf30bd09a7cbd4b4c6ea","awesome_skills\u002Fbiology\u002Fbio-comparative-genomics-gene-family-evolution","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous","2026-11-09 11:45:36",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-comparative-genomics-gene-family-evolution",{"tool":42,"command":43},"bunx","bunx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-comparative-genomics-gene-family-evolution",{"tool":45,"command":46},"pnpm","pnpm dlx skills add Mr-Nobody-Anonymous\u002FAll-skills --skill bio-comparative-genomics-gene-family-evolution","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-comparative-genomics-gene-family-evolution\u002FSKILL.md",true,[50,56],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"examples\u002Fcafe5_birth_death_analysis.sh","SCRIPT","脚本",3444,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-comparative-genomics-gene-family-evolution\u002Fexamples\u002Fcafe5_birth_death_analysis.sh",{"path":57,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":60,"sourceHtmlUrl":61},"usage-guide.md","REFERENCE","参考文档",5400,"https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fbiology\u002Fbio-comparative-genomics-gene-family-evolution\u002Fusage-guide.md",[63,71,78,85,92,99],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":70},"01M7EXRQF9GFM7D9BG6N5HAT34","oath","Auditing regulatory compliance (SOC2\u002FPCI-DSS\u002FHIPAA\u002FISO 27001): maps requirements, checks controls, designs audit trails, implements Policy as Code. Use when compliance auditing is needed.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fdevsecops\u002Foath\u002FSKILL.md",[],[],"2026-11-15 14:25:24",{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M7EXRH7TYTNZJT0BQXEWAMW7","nexus","Orchestrating multi-specialist task chains and scope-adaptive product delivery: classifies intent, selects and executes the minimum viable chain, aggregates results, and verifies acceptance criteria. For multi-domain tasks, build-first delivery, and product lifecycle execution.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fdevsecops\u002Fnexus\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7EXRCDPFWVEEEFR2ZQGJCYY","nest","Designing LLM-optimized folder structures: audits and restructures directories for context efficiency, progressive disclosure, and prompt cache performance. Not for general repo structure (Grove).","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fdevsecops\u002Fnest\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7EXR7JEER60TH0HD0AH4EE9","native","Implementing production iOS\u002FAndroid\u002FmacOS native features (SwiftUI, Compose) and iterating a screen against a reference design. Not for cross-platform RN\u002FFlutter (Port) or web (Artisan).","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fdevsecops\u002Fnative\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7EXR133J7DD5961R80QTRZY","muse","Defining and managing design tokens, applying token systems to existing codebases, building design system foundations. Use for spacing, color, typography, dark mode, cross-platform output.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fdevsecops\u002Fmuse\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7EXQWWX7ECQN0J50B41YN5N","morph","Converting document formats (Markdown\u002FWord\u002FExcel\u002FPDF\u002FHTML) and generating reusable conversion scripts. Use for distributable specs, accessibility-compliant PDFs, or Pandoc\u002FLibreOffice pipelines.","https:\u002F\u002Fgithub.com\u002FMr-Nobody-Anonymous\u002FAll-skills\u002Fblob\u002Fmain\u002Fawesome_skills\u002Fdevsecops\u002Fmorph\u002FSKILL.md",[],[]]