Trait correlation

Phylogenetic correlations between all pairs of traits with heatmap visualization

Command identity

Canonical command:

trait_correlation

Handler:

trait_correlation

Aliases:

phylo_corr, trait_corr

Standalone executables:

pk_trait_correlation, pk_phylo_corr, pk_trait_corr

Categories:

Phylogenetic signal

Runtime interface

Synopsis

phykit trait_correlation --tree <tree> --trait-data <trait_data> --output <output> [--alpha <alpha>] [--cluster] [--gene-trees <gene_trees>] [--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
-o, --output	true	str	required	any
--alpha	false	float	0.05	any
--cluster	false	boolean	false	any
-g, --gene-trees	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: --output. Invalid command syntax exits with status 2. Input validation and scientific limitations are described in the guidance below.

Guidance, interpretation, and examples

Compute phylogenetic correlations between all pairs of traits and display them as a heatmap with significance indicators.

Uses GLS-centering via the tree's variance-covariance matrix to account for phylogenetic non-independence among species. P-values are computed from the t-distribution and displayed as significance stars on the heatmap cells:

• *** p < 0.001

• ** p < 0.01

• * p < alpha (default 0.05)

The multi-trait input file should be tab-delimited with a header row: taxon<tab>trait1<tab>trait2<tab>... At least 2 traits are required. 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.

The --cluster option clusters traits by correlation similarity (using 1 - |r| as distance) and draws dendrograms alongside the heatmap.

phykit trait_correlation -t <tree> -d <trait_data> -o <output>
    [--alpha 0.05] [--cluster] [-g <gene_trees>] [--json]
    [--fig-width <float>] [--fig-height <float>] [--dpi <int>]
    [--no-title] [--title <str>]

Options:
-t/--tree: a tree file in Newick format
-d/--trait-data: tab-delimited multi-trait file with header row (at least 2 traits)
-o/--output: output figure path (supports .png, .pdf, .svg)
--alpha: significance threshold for marking p-values (default: 0.05)
--cluster: cluster traits by correlation similarity and display dendrograms
-g/--gene-trees: optional multi-Newick file of gene trees for discordance-aware VCV
--json: optional argument to print results as JSON