Stochastic character mapping (SIMMAP)

Stochastic character mapping on a phylogeny

Command identity

Canonical command:

stochastic_character_map

Handler:

stochastic_character_map

Aliases:

scm, simmap

Standalone executables:

pk_stochastic_character_map, pk_scm, pk_simmap

Categories:

Trait evolution

Runtime interface

Synopsis

phykit stochastic_character_map --tree <tree> --trait_data <trait_data> --trait <trait> [--model <model>] [--nsim <nsim>] [--seed <seed>] [--plot <plot>] [--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

-d, --trait_data

true

str

required

any

-c, --trait

true

str

required

any

-m, --model

false

str

ER

ER, SYM, ARD

-n, --nsim

false

int

100

any

--seed

false

int

none

any

--plot

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. 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

Perform Stochastic Character Mapping (SIMMAP) of discrete traits onto a phylogeny (Huelsenbeck et al. 2003; Bollback 2006), analogous to R's phytools::make.simmap().

Fits a continuous-time Markov chain (CTMC) rate matrix Q via maximum likelihood using Felsenstein's pruning algorithm. Three substitution models are available:

  • ER (equal rates): 1 free parameter

  • SYM (symmetric rates): k(k-1)/2 free parameters

  • ARD (all rates differ): k(k-1) free parameters

The input trait file should be tab-delimited with a header row: taxon<tab>trait_column<tab>... Lines starting with '#' are treated as comments. If the tree and trait file have different taxa, the intersection is used and warnings are printed to stderr.

Output includes the fitted Q matrix, log-likelihood, mean dwelling times, mean transition counts, and posterior probabilities at internal nodes.

Optionally, a horizontal phylogram plot with branches colored by mapped character state can be generated using the --plot argument.

All results have been validated against R 4.4.0 using phytools::fitMk and phytools::make.simmap. ER log-likelihoods match R to within 0.002 (both optimizers converge to the same flat plateau). For the ARD model, PhyKIT's multi-start optimizer finds a slightly better local optimum than R (loglik -8.38 vs -8.43). Dwelling times sum to total tree length exactly, and Q matrix structural properties (rows sum to zero, model nesting) are verified.

phykit stochastic_character_map -t <tree> -d <trait_data> -c <trait_column> [-m <model>] [-n <nsim>] [--seed <seed>] [--plot <output.png>]
    [--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>] [--json]

Options:
-t/--tree: a tree file in Newick format
-d/--trait_data: tab-delimited trait file with header row
-c/--trait: column name for discrete character trait
-m/--model: substitution model: ER, SYM, or ARD (default: ER)
-n/--nsim: number of stochastic mapping simulations (default: 100)
--seed: random seed for reproducibility
--plot: output plot file path for phylogram with colored branches
--fig-width: figure width in inches (auto-scaled if omitted)
--fig-height: figure height in inches (auto-scaled if omitted)
--dpi: resolution in DPI (default: 300)
--no-title: hide the plot title
--title: custom title text
--legend-position: legend location (e.g., "upper right", "none" to hide)
--ylabel-fontsize: font size for y-axis labels; 0 to hide
--xlabel-fontsize: font size for x-axis labels; 0 to hide
--title-fontsize: font size for the title
--axis-fontsize: font size for axis labels
--colors: comma-separated colors (hex or named)
--ladderize: ladderize (sort) the tree before plotting
--cladogram: draw cladogram (equal branch lengths, tips aligned) instead of phylogram
--circular: draw circular (radial/fan) phylogram instead of rectangular
--color-file: color annotation file for tip labels, clade ranges, and branch colors (iTOL-inspired TSV format)
--json: optional argument to print results as JSON