Disparity through time (DTT)

Disparity-through-time analysis with MDI statistic (Harmon et al. 2003)

Command identity

Canonical command:

dtt

Handler:

dtt

Aliases:

disparity_through_time

Standalone executables:

pk_dtt, pk_disparity_through_time

Categories:

Trait evolution

Runtime interface

Synopsis

phykit dtt --tree <tree> --traits <traits> [--trait <trait>] [--index <index>] [--nsim <nsim>] [--seed <seed>] [--plot-output <plot_output>] [--fig-width <fig_width>] [--fig-height <fig_height>] [--dpi <dpi>] [--no-title] [--title <title>] [--legend-position <legend_position>] [--ylabel-fontsize <ylabel_fontsize>] [--xlabel-fontsize <xlabel_fontsize>] [--title-fontsize <title_fontsize>] [--axis-fontsize <axis_fontsize>] [--colors <colors>] [--ladderize] [--cladogram] [--circular] [--color-file <color_file>] [--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

-t, --tree

true

str

required

any

--traits

true

str

required

any

--trait

false

str

none

any

--index

false

str

avg_sq

avg_sq, avg_manhattan

--nsim

false

int

0

any

--seed

false

int

none

any

--plot-output

false

str

none

any

--fig-width

false

float

none

any

--fig-height

false

float

none

any

--dpi

false

int

300

any

--no-title

false

boolean

false

any

--title

false

str

none

any

--legend-position

false

str

none

any

--ylabel-fontsize

false

float

none

any

--xlabel-fontsize

false

float

none

any

--title-fontsize

false

float

none

any

--axis-fontsize

false

float

none

any

--colors

false

str

none

any

--ladderize

false

boolean

false

any

--cladogram

false

boolean

false

any

--circular

false

boolean

false

any

--color-file

false

str

none

any

--json

false

boolean

false

any

Output and errors

--json provides the command's structured JSON representation. Output-file options: --plot-output. Invalid command syntax exits with status 2. Input validation and scientific limitations are described in the guidance below.

Guidance, interpretation, and examples

Compute disparity-through-time (DTT) curves following Harmon et al. (2003). At each branching time the mean relative subclade disparity is calculated. Under Brownian motion the DTT curve declines linearly from 1 to 0; deviations from this expectation reveal tempo of morphological diversification.

The Morphological Disparity Index (MDI) measures the area between the observed DTT and the Brownian motion null median. Positive MDI indicates late disparity accumulation; negative MDI indicates early disparity accumulation (consistent with adaptive radiation).

phykit dtt -t <tree> --traits <traits_file>
    [--trait <column>] [--index avg_sq|avg_manhattan]
    [--nsim <int>] [--seed <int>]
    [--plot-output <file>] [--json]
    [--fig-width <float>] [--fig-height <float>] [--dpi <int>] [--no-title] [--title <str>]
    [--legend-position <str>] [--ylabel-fontsize <float>] [--xlabel-fontsize <float>]
    [--title-fontsize <float>] [--axis-fontsize <float>] [--colors <str>] [--ladderize] [--cladogram] [--circular] [--color-file <file>]

Options:
-t/--tree: ultrametric tree file (required)
--traits: TSV file with header row; first column taxon, remaining columns are trait values (required)
--trait: specific trait column name; if omitted all trait columns are used (multivariate DTT)
--index: disparity index — avg_sq (average squared Euclidean distance, default) or avg_manhattan
--nsim: number of Brownian motion simulations for null DTT envelope and MDI p-value (default: 0, no simulations)
--seed: random seed for reproducibility
--plot-output: output filename for the DTT plot (PNG, PDF, SVG)
--json: output results as JSON

Default output: text summary with DTT curve data points.

# Single trait DTT
phykit dtt -t species.tre --traits traits.tsv --trait body_mass

# Multivariate DTT (all traits)
phykit dtt -t species.tre --traits traits.tsv

# With BM null envelope and MDI p-value
phykit dtt -t species.tre --traits traits.tsv --trait body_mass --nsim 1000 --seed 42

# With plot output
phykit dtt -t species.tre --traits traits.tsv --trait body_mass --nsim 1000 --plot-output dtt.png

# JSON output
phykit dtt -t species.tre --traits traits.tsv --trait body_mass --json

R validation: Validated against geiger::dtt() in R (see tests/r_validation/validate_dtt.R).