Identity matrix

Pairwise sequence identity heatmap

Command identity

Canonical command:

identity_matrix

Handler:

identity_matrix

Aliases:

id_matrix, seqid

Standalone executables:

pk_identity_matrix, pk_id_matrix, pk_seqid

Categories:

Alignment quality & statistics

Runtime interface

Synopsis

phykit identity_matrix --alignment <alignment> --output <output> [--metric <metric>] [--tree <tree>] [--sort <sort>] [--partition <partition>] [--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
-a, --alignment	true	str	required	any
-o, --output	true	str	required	any
--metric	false	str	identity	identity, p-distance
--tree	false	str	none	any
--sort	false	str	cluster	alpha, cluster, tree
--partition	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 a pairwise sequence identity matrix from an alignment and plot it as a clustered heatmap.

For each pair of taxa, identity is defined as the fraction of non-gap, non-ambiguous columns that are identical. Gaps, '?', 'N', 'X', and '*' in either sequence cause a column to be skipped.

The matrix can be displayed as identity (default) or p-distance (1 - identity) using --metric. Ordering can be by hierarchical clustering (default), tree tip order (--sort tree --tree <file>), or alphabetical (--sort alpha).

phykit identity_matrix -a <alignment> -o <output>
        [--metric identity|p-distance] [--tree <file>]
        [--sort alpha|cluster|tree] [--partition <file>] [--json]
        [--fig-width <float>] [--fig-height <float>] [--dpi <int>]
        [--no-title] [--title <str>]
        [--ylabel-fontsize <float>] [--xlabel-fontsize <float>]
        [--title-fontsize <float>] [--axis-fontsize <float>]

Options:
-a/--alignment: alignment file (FASTA or other supported format)
-o/--output: output figure path (.png, .pdf, .svg)
--metric: 'identity' (fraction matching) or 'p-distance' (1 - identity); default: identity
--tree: tree file for tree-guided ordering (Newick format)
--sort: ordering method: 'cluster' (hierarchical), 'tree' (requires --tree), or 'alpha' (alphabetical); default: cluster
--partition: RAxML-style partition file (reserved for future use)
--json: output structured JSON instead of plain text
--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
--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