[meta]
name = "orthofinder"
category = "comparative-genomics"
description = "Phylogenetic orthology inference for comparative genomics across multiple species proteomes"
tags = ["orthology", "gene-families", "phylogenomics", "proteome", "evolution", "comparative-genomics"]
author = "oxo-call built-in"
source_url = "https://github.com/davidemms/OrthoFinder"

[context]
concepts = [
    "OrthoFinder infers orthogroups, orthologs, gene duplication events, and species trees from a set of proteome FASTA files.",
    "Input is a directory of protein FASTA files, one per species; file names become species identifiers in the output.",
    "OrthoFinder uses DIAMOND for all-vs-all protein search by default; -S blast or -S mmseqs2 can substitute other search tools.",
    "Results are written to a timestamped OrthoFinder/Results_* directory inside the input FASTA directory by default.",
    "-og reports orthogroups only (faster, no gene trees); -M msa builds multiple sequence alignments for each orthogroup.",
    "The Orthogroups/Orthogroups.tsv output maps each orthogroup to member genes per species; Orthogroup_Statistics.tsv provides counts.",
]

pitfalls = [
    "Protein FASTA files must use unique sequence IDs across all files; duplicate IDs cause incorrect gene tree inference.",
    "Species with very different proteome sizes can bias OG size statistics; check that all FASTAs contain complete proteomes.",
    "OrthoFinder requires DIAMOND, MCL, and FastME (or MAFFT/IQ-TREE for -M msa) to be in PATH; missing tools fail with non-obvious errors.",
    "Restarting OrthoFinder after partial completion requires -b (results directory) not -f; using -f restarts from scratch.",
    "Gene tree inference (-M msa) can be very slow for large orthogroups with many paralogs; set --max-msa-genes to cap size.",
    "Results directory names include timestamps; scripting downstream analysis should use -o to set a fixed output path.",
]

[[examples]]
task = "run OrthoFinder on a directory of species proteomes"
args = "orthofinder -f proteomes/ -t 32 -a 8"
explanation = "-f points to directory of protein FASTAs; -t 32 threads for DIAMOND search; -a 8 threads for orthogroup analysis"

[[examples]]
task = "run OrthoFinder with MSA-based gene trees using MAFFT and IQ-TREE"
args = "orthofinder -f proteomes/ -M msa -S diamond -A mafft -T iqtree -t 32 -a 8"
explanation = "-M msa builds gene trees from MSA; -A mafft for alignment; -T iqtree for tree inference; more accurate but slower"

[[examples]]
task = "infer orthogroups only without gene trees for fast proteome comparison"
args = "orthofinder -f proteomes/ -og -t 32"
explanation = "-og stops after orthogroup assignment and statistics; much faster than full analysis with gene trees"

[[examples]]
task = "restart OrthoFinder from existing DIAMOND results (add a new species)"
args = "orthofinder -b proteomes/OrthoFinder/Results_Jan01/ -f new_species/ -t 32 -a 8"
explanation = "-b provides existing results; -f provides new species FASTA directory; OrthoFinder re-runs only new comparisons"

[[examples]]
task = "use MMseqs2 instead of DIAMOND for faster all-vs-all search"
args = "orthofinder -f proteomes/ -S mmseqs2 -t 32 -a 8"
explanation = "-S mmseqs2 substitutes MMseqs2 for the all-vs-all search step; faster for very large proteome sets"

[[examples]]
task = "run OrthoFinder with a fixed output directory name"
args = "orthofinder -f proteomes/ -o results/orthofinder_run -t 32 -a 8"
explanation = "-o sets the output directory explicitly instead of using a timestamped directory inside the input folder"
