Phylomorphospace

Phylomorphospace visualization

Command identity

Canonical command:

phylomorphospace

Handler:

phylomorphospace

Aliases:

phmo, phylomorpho

Standalone executables:

pk_phylomorphospace, pk_phmo, pk_phylomorpho

Categories:

Phylogenetic comparative methods

Runtime interface

Synopsis

phykit phylomorphospace --tree <tree> --trait_data <trait_data> [--trait-x <trait_x>] [--trait-y <trait_y>] [--color-by <color_by>] [--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
-d, --trait_data	true	str	required	any
--trait-x	false	str	none	any
--trait-y	false	str	none	any
--color-by	false	str	none	any
--plot-output	false	str	phylomorphospace_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

Plot a phylomorphospace: two raw traits in trait space with the phylogeny overlaid via ML-reconstructed ancestral states at internal nodes. This differs from the phylogenetic_ordination --plot-tree option, which plots in PC space; phylomorphospace plots raw trait values directly on the x and y axes.

Tree edges connect species through ML-reconstructed ancestral states and are colored by distance from root (coolwarm colormap with colorbar). Tip points default to blue, or can be colored by a continuous or discrete variable using the --color-by option.

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

If the trait file has exactly 2 trait columns and --trait-x / --trait-y are omitted, the first two columns are selected automatically.

phykit phylomorphospace -t <tree> -d <trait_data> [--trait-x <name>] [--trait-y <name>] [--color-by <col_or_file>] [--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:
-t/--tree: a tree file in Newick format
-d/--trait_data: tab-delimited multi-trait file with header row
--trait-x: column name for x-axis trait
--trait-y: column name for y-axis trait
--color-by: color tip points by a trait; specify a column name from the multi-trait file or a separate tab-delimited file (taxon<tab>value) for continuous or discrete coloring
--plot-output: output path for plot (default: phylomorphospace_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