Tree space visualization

Visualize gene tree topology space via MDS, t-SNE, UMAP, or clustered distance heatmap

Command identity

Canonical command:

tree_space

Handler:

tree_space

Aliases:

tree_landscape, tspace

Standalone executables:

pk_tree_space, pk_tree_landscape, pk_tspace

Categories:

Tree comparison & consensus

Runtime interface

Synopsis

phykit tree_space --trees <trees> --output <output> [--metric <metric>] [--method <method>] [--species-tree <species_tree>] [--k <k>] [--seed <seed>] [--heatmap] [--distance-matrix <distance_matrix>] [--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, --trees	true	str	required	any
-o, --output	true	str	required	any
--metric	false	str	rf	rf, kf
--method	false	str	mds	mds, tsne, umap
--species-tree	false	str	none	any
--k	false	int	none	any
--seed	false	int	none	any
--heatmap	false	boolean	false	any
--distance-matrix	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

Visualize how gene trees cluster in topology space by computing pairwise distances (Robinson-Foulds or Kuhner-Felsenstein) and projecting into 2D via MDS, t-SNE, or UMAP. Points are colored by spectral clustering with automatic cluster detection via the eigengap heuristic.

Alternatively, use --heatmap to draw a clustered distance heatmap with a dendrogram showing hierarchical relationships among gene trees. Use --distance-matrix to export the raw pairwise distance matrix as a CSV file.

Optionally highlight a species tree as a distinct marker to see where it sits relative to the gene tree cloud.

phykit tree_space -t <trees> -o <output>
    [--metric rf|kf] [--method mds|tsne|umap]
    [--species-tree <file>] [--k <int>] [--seed <int>]
    [--heatmap] [--distance-matrix <file>]
    [--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/--trees: file with gene trees (one Newick per line, or one file path per line) (required)
-o/--output: output figure path (.png, .pdf, .svg) (required)
--metric: distance metric: rf (normalized Robinson-Foulds, default) or kf (Kuhner-Felsenstein)
--method: dimensionality reduction: mds (default), tsne, or umap
--species-tree: optional species tree to highlight in the plot as a star marker
--k: number of clusters (auto-detected via eigengap if omitted)
--seed: random seed for reproducibility (t-SNE/UMAP)
--heatmap: draw a clustered distance heatmap instead of a scatter plot
--distance-matrix: output the pairwise distance matrix as a CSV file
--json: optional argument to print results as JSON