csubst scan

csubst scan

csubst scan lists recurrent nonsynonymous-state substitutions shared by foreground clades. It is a direct scan for repeated amino-acid or recoded-state changes, separate from the omegaC branch-combination search used by csubst search.

Use it when you want a candidate list such as "site 778 changed to S in many foreground clades", together with foreground support, control-branch rate enrichment, site evolutionary rate, and conservation summaries.

Minimal command

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

The default scan writes outputs under csubst_scan/, uses --scan_match any2spe, tests foreground branches against all non-foreground branches, and calibrates rate-enrichment P values with full foreground-clade permutations.

When to use it

Use csubst scan when you want to:

• find recurrent substitutions shared by foreground clades without enumerating foreground branch combinations
• detect partial foreground sharing, such as a substitution present in 8 of 10 foreground lineages
• compare foreground event counts and branch-length exposure with non-foreground or sister branches
• prioritize candidates by site rate, rate quantile, amino-acid conservation, state conservation, and rate-enrichment P values
• generate a quick tree + detected-site summary plot for top scan hits

Run csubst doctor first when working with a new dataset.

Foreground units

csubst scan treats each foreground lineage ID as one foreground unit. Multiple tips with the same lineage ID are analyzed as one clade-level unit. The lineage IDs do not have to be consecutive, but consecutive IDs are easier to inspect in csubst_scan_units.tsv.

With the default stem-only discovery, candidate support is called on each foreground stem. Rate event/exposure accounting uses the whole descendant foreground clade, so post-hit branches are reduced by state-aware opportunity instead of being placed in the non-foreground control.

For foreground file details, see: Foreground specification

Recurrent substitution patterns

Use --scan_match to choose which state-change pattern classes to scan:

• any2any: any ancestor state to any derived state at the same site
• any2spe: any ancestor state to the same specific derived state
• any2dif: any ancestor state to at least two different derived states
• spe2any: the same specific ancestor state to any derived state
• spe2spe: the same specific ancestor state to the same specific derived state
• spe2dif: the same specific ancestor state to at least two different derived states
• dif2any: at least two different ancestor states to any derived state
• dif2spe: at least two different ancestor states to the same specific derived state
• dif2dif: at least two different ancestor states to at least two different derived states

--scan_match all scans all nine classes. The default is any2spe, which is usually the most direct representation of convergent amino-acid substitutions.

Important options

• --scan_min_event_pp: posterior probability threshold for candidate discovery and foreground-lineage support calls. With --scan_rate_event_mode posterior_sum, this threshold does not filter event mass used for rate P values.
• --scan_min_support: minimum number or fraction of foreground units that must support a candidate. Integer tokens, including 1, are counts. Decimal or scientific-notation values <=1 are fractions.
• --scan_rate_event_mode posterior_sum|called: event mass used for rate-enrichment tests. posterior_sum sums matching posterior event mass; called uses only events passing --scan_min_event_pp.
• --scan_rate_length raw|sn_rescaled|n_rescaled: branch-length scale for rate-enrichment tests. The default, n_rescaled, uses CSUBST nonsynonymous-substitution branch lengths.
• --scan_rate_exposure q_weighted|state_aware|raw_branch_length: exposure model for rate-enrichment tests. q_weighted is the default and integrates the candidate transition weight over the parent codon posterior using the codon Q matrix. With 3di20, it resolves to state_aware because the fitted codon Q does not define 3Di-state transition rates.
• --scan_other_scope all|sister: control branch set for rate-enrichment tests. all uses all non-foreground branches; sister uses sister branches of the foreground units.
• --scan_pvalue_calibration none|candidate_fixed|full_scan: empirical calibration for rate-enrichment P values. full_scan reruns candidate discovery for each size-binned, non-overlapping foreground-clade permutation.
• --scan_n_permutations: number of foreground-clade permutations. Permutations are parallelized over --threads; multiprocessing workers reopen large substitution and posterior-state arrays from shared read-only memmaps.
• --nonsyn_recode: scan standard amino-acid states or recoded nonsynonymous states, including 3Di structural-alphabet recoding.
• --scan_site_plot: write a tree + detected-site summary plot using the csubst sites plotter. The default format is PDF. If multiple candidate patterns share one site, the best-supported candidate represents that site.

For the full option list, run:

csubst scan -h

Output files

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

• csubst_scan.tsv: one row per detected candidate substitution and target class
• csubst_scan_units.tsv: foreground units, matched leaves, foreground branch IDs, whole-clade rate branch IDs, and sister branch IDs
• csubst_foreground_branch.txt: branch IDs assigned to the foreground
• csubst_scan.tree_site.pdf: tree + detected-site summary plot, when --scan_site_plot yes

csubst scan does not write csubst_scan.tree_site.tsv; the scan result table itself is csubst_scan.tsv.

PEPC sample output

The example below was generated from the bundled PEPC sample data with an independent foreground file, --scan_match any2spe, --scan_min_event_pp 0.5, --scan_min_support 2, --scan_pvalue_calibration none, and --tree_site_plot_format png. The run reported 78 candidate substitutions from 10 foreground units. The P and q values in the table are analytical rate-enrichment values, not permutation-calibrated values.

Top foreground candidates:

state_change	codon_site_alignment	support_unit_count	support_fraction	target_event_count	other_event_count	p_rate_enrichment	q_rate_enrichment	site_rate_quantile	aa_bg_conservation
778S	778	8	0.80	7.2607	1.7296	2.18e-06	0.000170	0.935	1.000
759A	759	6	0.60	6.2127	1.0093	1.51e-05	0.000588	0.820	0.983
538T	538	4	0.40	3.9687	0.0311	0.000193	0.00502	0.752	0.981
625I	625	5	0.50	4.9857	1.0228	0.000312	0.00528	0.590	1.000
571N	571	4	0.40	3.9619	0.0383	0.000339	0.00528	0.935	0.679
749F	749	3	0.30	2.9769	0.0232	0.00119	0.0103	0.451	0.983
837K	837	3	0.30	2.9762	0.0237	0.000697	0.00777	0.820	0.982
577T	577	4	0.40	3.9798	2.3767	0.00178	0.0139	0.935	0.660

Key output columns

• state_change: compact candidate label, such as 778S or A123T
• candidate_event_pp_sum: posterior probability sum over events used to build the candidate
• support_unit_count, support_fraction, support_pp_sum: foreground support across foreground units
• support_unit_ids, support_branch_ids: units and foreground branches supporting the candidate
• target_event_count, other_event_count: event mass in foreground and control branches. With --scan_rate_event_mode posterior_sum, these are posterior expected counts.
• target_exposure_branch_length, other_exposure_branch_length: exposure used in the foreground-vs-control rate test
• target_event_rate, other_event_rate, rate_ratio: rate summaries
• p_rate_enrichment: one-sided foreground enrichment P value from the Poisson rate test
• p_rate_enrichment_empirical, p_rate_enrichment_empirical_maxT: empirical permutation-calibrated P values, when enabled
• q_rate_enrichment, q_rate_enrichment_by_trait, q_rate_enrichment_by_trait_match: Benjamini-Hochberg corrected analytic Q values
• q_rate_enrichment_empirical, q_rate_enrichment_empirical_by_trait, q_rate_enrichment_empirical_by_trait_match: BH correction of candidate-wise empirical P values. The maxT P value is already scan-wide family-wise calibrated.
• site_rate, site_rate_categorized, site_rate_quantile: IQ-TREE posterior-mean site rate, category representative, and tie-aware mean-rate quantile
• aa_all_conservation, aa_bg_conservation, state_all_conservation, state_bg_conservation: amino-acid or recoded-state conservation summaries

Example

csubst scan \
  --alignment_file alignment.fa.gz \
  --rooted_tree_file tree.nwk \
  --foreground foreground.txt \
  --scan_match any2spe \
  --scan_min_support 0.8 \
  --scan_rate_event_mode posterior_sum \
  --scan_rate_exposure q_weighted \
  --scan_rate_length n_rescaled \
  --scan_other_scope all \
  --scan_pvalue_calibration full_scan \
  --scan_n_permutations 1000 \
  --threads 8

This command reports substitutions shared by at least 80% of foreground units, uses posterior expected counts for rate tests, and calibrates scan-wide significance with parallel foreground-clade permutations.

P and Q columns are written in scientific notation independently of --float_digit; posterior counts and other continuous measurements continue to use the requested fixed precision.

Related pages

• Foreground specification
• csubst search
• csubst sites
• Parallel processing and performance tuning