Covarying evolutionary rates

Detect covariation in evolutionary rates

Command identity

Canonical command:

covarying_evolutionary_rates

Handler:

covarying_evolutionary_rates

Aliases:

cover

Standalone executables:

pk_covarying_evolutionary_rates, pk_cover

Categories:

Evolutionary rate analysis

Runtime interface

Synopsis

phykit covarying_evolutionary_rates <tree_zero> <tree_one> --reference <reference> [--verbose] [--plot] [--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

tree_zero

true

str

required

any

tree_one

true

str

required

any

-r, --reference

true

str

required

any

-v, --verbose

false

boolean

false

any

--plot

false

boolean

false

any

--plot-output

false

str

covarying_rates_plot.png

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

Determine if two genes have a signature of covariation with one another. Genes that have covarying evolutionary histories tend to have similar functions and expression levels.

Input two gene phylogenies and calculate the Pearson correlation among their relative evolutionary rates. The two gene trees and the reference tree may initially contain different taxa. PhyKIT prunes all three trees to their shared taxa, after which they must have the same rooted topology.

For each corresponding terminal and internal branch, PhyKIT calculates gene branch length / reference branch length. A root stem is not a phylogenetic branch and is excluded. Branches with a zero or missing reference length are also excluded because their ratio is undefined; zero-length gene branches are retained. A branch pair is removed if either relative rate is greater than five. The remaining values are Z-transformed, and their Pearson correlation coefficient is reported.

PhyKIT reports two tab delimited values: col1: correlation coefficient col2: p-value

This implementation is the CovER procedure described by Steenwyk et al. (2022). It is based on the mirror-tree principle developed by Sato et al. (2005), and the biological basis of evolutionary rate covariation was evaluated by Clark et al. (2012).

Comparison with other ERC software

An independent implementation of this branch-ratio procedure using R ape and stats::cor.test reproduces PhyKIT's coefficient and p-value. The validation is maintained in tests/validation/validate_covarying_rates.R.

Do not expect the same numerical coefficient from ERC2.0 or RERconverge. Those programs estimate relative rates as regression residuals and include additional normalization such as heteroskedasticity correction and winsorization. These are related ERC methods, not independent implementations of the PhyKIT/CovER statistic.

The reported p-value is the standard two-sided Pearson correlation p-value, using the retained branches as observations. Because branches in a phylogeny are not strictly independent, interpret this parametric p-value cautiously; for gene-network analyses, establish an empirical coefficient threshold or null distribution appropriate for the data set.

phykit covarying_evolutionary_rates <tree_file_zero> <tree_file_one> -r/--reference <reference_tree_file> [-v/--verbose] [--plot] [--plot-output <path>]
    [--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:
<tree_file_zero>: first argument after function name should be a tree file
<tree_file_one>: second argument after function name should be a tree file
-r/--reference: a tree whose corresponding branch lengths normalize the two gene trees. Typically, this is a putative species tree.
-v/--verbose: print out corrected branch lengths shared between tree 0 and tree 1
--plot: save a covarying-rates scatter plot
--plot-output: output path for plot (default: covarying_rates_plot.png)
--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