Spectral discordance decomposition

PCA ordination and clustering of gene tree topologies

Command identity

Canonical command:

spectral_discordance

Handler:

spectral_discordance

Aliases:

sd, spec_disc

Standalone executables:

pk_spectral_discordance, pk_sd, pk_spec_disc

Categories:

Tree comparison & consensus

Runtime interface

Synopsis

phykit spectral_discordance --gene-trees <gene_trees> [--tree <tree>] [--metric <metric>] [--clusters <clusters>] [--n-pcs <n_pcs>] [--top-loadings <top_loadings>] [--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
-g, --gene-trees	true	str	required	any
-t, --tree	false	str	none	any
--metric	false	str	nrf	nrf, wrf
--clusters	false	int	none	any
--n-pcs	false	int	none	any
--top-loadings	false	int	5	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

Decompose gene tree space via PCA on a bipartition presence/absence (or branch-length) matrix, with spectral clustering and automatic cluster detection via the eigengap heuristic.

Each gene tree is encoded as a vector over the union of all observed bipartitions. PCA reveals the axes of topological variation, with loading vectors directly identifying which bipartitions drive each PC. Spectral clustering groups genes sharing similar topologies; the number of clusters is auto-detected from the eigengap of the graph Laplacian.

Two metrics are available:

• nrf (default): binary presence/absence, consistent with normalized Robinson-Foulds distance

• wrf: branch-length weighted

Polytomies (collapsed branches) in gene trees are handled conservatively: splits from polytomous nodes are excluded from the bipartition matrix since they represent unresolved relationships. Trifurcating roots (standard unrooted Newick) are not affected. This allows gene trees with collapsed low-support branches to be used directly as input.

phykit spectral_discordance -g <gene_trees> [-t <tree>] [--metric nrf|wrf] [--clusters K] [--n-pcs N] [--top-loadings N] [--plot <prefix>]
    [--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:
-g/--gene-trees: file of gene trees (one Newick per line, or file of filenames)
-t/--tree: species tree (optional; flags species-tree bipartitions in loadings)
--metric: distance metric: nrf or wrf (default: nrf)
--clusters: override auto-detected number of clusters
--n-pcs: number of PCs to report (default: min(10, G-1))
--top-loadings: top bipartitions per PC to display (default: 5)
--plot: output prefix for plots (generates _scatter.png and _eigengap.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: output results as JSON