Create concatenation matrix

Concatenate multiple alignments into a supermatrix

Command identity

Canonical command:

create_concatenation_matrix

Handler:

create_concatenation_matrix

Aliases:

cc, create_concat

Standalone executables:

pk_create_concatenation_matrix, pk_cc, pk_create_concat

Categories:

Alignment & dataset utilities

Runtime interface

Synopsis

phykit create_concatenation_matrix [--alignment <alignment_list>] [--prefix <prefix>] [--threshold <threshold>] [--plot-occupancy] [--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
-a, --alignment, --alignment-list, --alignment_list	false	str	none	any
-p, --prefix	false	str	none	any
--threshold	false	float	0	any
--plot-occupancy	false	boolean	false	any
--plot-output	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: --plot-output. Invalid command syntax exits with status 2. Input validation and scientific limitations are described in the guidance below.

Guidance, interpretation, and examples

Create a concatenated alignment file. This function is used to help in the construction of multi-locus data matrices.

PhyKIT will output three files: 1) A fasta file with '.fa' appended to the prefix specified with the -p/--prefix parameter. 2) A partition file ready for input into RAxML or IQ-tree. 3) An occupancy file that summarizes the taxon occupancy per sequence.

phykit create_concat -a <file> -p <string> [--threshold <float>] [--plot-occupancy] [--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:
-a/--alignment: alignment list file. --alignment-list and the legacy --alignment_list spelling are also accepted. The file should contain a single column list of alignment sequence files to concatenate into a single matrix. Provide path to files relative to working directory or provide absolute path.
-p/--prefix: prefix of output files
--threshold: minimum fraction of informative (non-gap, non-ambiguous) sites across the concatenated alignment for a taxon to be included. Taxa whose effective occupancy falls below this value are excluded from the output. Set to 0 to disable filtering (default: 0).
--plot-occupancy: optional argument to output an occupancy map figure where x-axis shows concatenated positions with gene boundaries and y-axis shows taxa sorted by total occupancy. Colors denote represented characters, gap/ambiguous characters in present genes, and fully absent gene blocks.
--plot-output: optional custom output path for occupancy map figure (default: <prefix>.occupancy.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 summary metadata as JSON