Skip to content

csubst search

Jump to bottom
Kenji Fukushima edited this page Jun 3, 2026 · 1 revision

csubst search

csubst search is the main CSUBST command. It estimates substitution histories on a rooted tree and calculates convergence statistics for branch combinations.

csubst analyze remains available as a legacy alias, but the wiki uses csubst search.

Minimal command

csubst search \
  --alignment_file alignment.fa.gz \
  --rooted_tree_file tree.nwk \
  --foreground foreground.txt

When to use it

Use csubst search when you want to:

  • calculate convergence-rate metrics such as omegaC, dNC, and dSC
  • compare foreground branch combinations with background or marginal branches
  • run higher-order convergence searches with --max_arity
  • export branch, site, or branch-site summary tables for downstream analyses

Run csubst doctor first when working with a new dataset.

Important inputs

  • --alignment_file: in-frame codon alignment in FASTA format
  • --rooted_tree_file: rooted tree in Newick format
  • --foreground: foreground lineage file
  • --iqtree_*: optional paths to existing IQ-TREE intermediate files

Common options

  • --max_arity: maximum number of branches in a combination
  • --foreground, --fg_format, --fg_exclude_wg: foreground definition
  • --expectation_method codon_model|urn: expectation model
  • --asrv: among-site rate variation handling
  • --pseudocount_mode: pseudocount behavior
  • --output_stat: which convergence/divergence statistic groups to keep
  • --b, --s, --bs, --cs, --cbs: optional output table controls

For the full option list, run:

csubst search -h

Output files

By default, outputs are written under csubst_search/ with prefix csubst_. Common files include:

  • csubst_cb_2.tsv or csubst_cb_K.tsv
  • csubst_cb_stats.tsv
  • csubst_b.tsv
  • optional csubst_s.tsv, csubst_bs.tsv, csubst_cs.tsv, and csubst_cbs.tsv

For output interpretation, see: Interpreting output files of csubst search

Related pages

Clone this wiki locally