D-statistic (ABBA-BABA test)

Patterson's D-statistic for detecting introgression

Command identity

Canonical command:: dstatistic
Handler:: dstatistic
Aliases:: abba_baba, dstat
Standalone executables:: pk_dstatistic, pk_abba_baba, pk_dstat
Categories:: Introgression & gene flow

Runtime interface

Synopsis

phykit dstatistic [--alignment <alignment>] [--gene-trees <gene_trees>] --p1 <p1> --p2 <p2> --p3 <p3> --outgroup <outgroup> [--block-size <block_size>] [--support <support>] [--json]

Arguments

This table is generated from the live command parser. It is the authoritative source for accepted spellings, required arguments, types, defaults, and choices.

Argument	Required	Type	Default	Choices
`-a, --alignment`	false	str	none	any
`-g, --gene-trees`	false	str	none	any
`--p1`	true	str	required	any
`--p2`	true	str	required	any
`--p3`	true	str	required	any
`--outgroup`	true	str	required	any
`--block-size`	false	int	100	any
`--support`	false	float	none	any
`--json`	false	boolean	false	any

Output and errors

--json provides the command's structured JSON representation. Unless the guidance below states otherwise, results are emitted as command output. Invalid command syntax exits with status 2. Input validation and scientific limitations are described in the guidance below.

Guidance, interpretation, and examples

Compute Patterson's D-statistic (ABBA-BABA test) for detecting introgression or gene flow between taxa. Given a four-taxon alignment with topology (((P1, P2), P3), Outgroup), the test counts ABBA and BABA site patterns:

ABBA: P1 has the ancestral allele, P2 and P3 share the derived allele — suggests introgression between P2 and P3
BABA: P2 has the ancestral allele, P1 and P3 share the derived allele — suggests introgression between P1 and P3
D = (ABBA - BABA) / (ABBA + BABA): D = 0 under ILS alone; D significantly different from 0 indicates introgression

Note: the D-statistic identifies which pair of lineages exchanged genetic material but cannot determine the direction of gene flow within that pair.

Significance is assessed via block jackknife (Green et al. 2010), producing a Z-score and p-value.

Two input modes are supported:

Site patterns (-a): counts ABBA/BABA from a FASTA alignment. Only biallelic sites with no gaps or ambiguous characters are considered. Significance via block jackknife.
Gene trees (-g): counts discordant quartet topologies from gene trees. Gene trees can have any number of taxa; only the quartet induced by the four specified taxa is evaluated. Significance via chi-squared test.

# Site-pattern mode
phykit dstatistic -a <alignment> --p1 <taxon> --p2 <taxon> --p3 <taxon> \
    --outgroup <taxon> [--block-size 100] [--json]

# Gene-tree mode
phykit dstatistic -g <gene_trees> --p1 <taxon> --p2 <taxon> --p3 <taxon> \
    --outgroup <taxon> [--json]

Options:
-a/--alignment: FASTA alignment file (site-pattern mode)
-g/--gene-trees: gene trees file, one Newick per line (gene-tree mode; trees can have any number of taxa)
--p1: taxon name for P1, sister to P2 (required)
--p2: taxon name for P2, sister to P1, potential recipient of gene flow from P3 (required)
--p3: taxon name for P3, donor lineage (required)
--outgroup: outgroup taxon name, determines ancestral allele (required)
--block-size: block size in sites for jackknife standard error estimation (default: 100; alignment mode only)
--support: minimum branch support threshold; gene tree branches below this value are collapsed and treated as unresolved (gene-tree mode only)
--json: optional argument to print results as JSON