Saturation

Test for substitution saturation

Command identity

Canonical command:

saturation

Handler:

saturation

Aliases:

sat

Standalone executables:

pk_saturation, pk_sat

Categories:

Saturation & model adequacy

Runtime interface

Synopsis

phykit saturation --alignment <alignment> --tree <tree> [--verbose] [--exclude_gaps] [--plot] [--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

true

str

required

any

-t, --tree

true

str

required

any

-v, --verbose

false

boolean

false

any

-e, --exclude_gaps

false

boolean

false

any

--plot

false

boolean

false

any

--plot-output

false

str

saturation_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

Calculate saturation for a given tree and alignment.

Saturation is defined as sequences in multiple sequence alignments that have undergone numerous substitutions such that the distances between taxa are underestimated.

Data with no saturation will have a value of 1. The closer the value is to 1, the less saturated the data.

This function outputs two values (as of v1.19.9). The first value is the saturation value and the second column is the absolute value of saturation minus 1. Thus, lower values in the second column are indicative of values closer to one and, thus, less saturation.

Saturation is calculated following Philippe et al., PLoS Biology (2011), doi: 10.1371/journal.pbio.1000602.

phykit saturation -a <alignment> -t <tree> [-v/--verbose] [-e/--exclude_gaps] [--plot] [--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: an alignment file
-t/--tree: a tree file
-e/--exclude_gaps: if a site has a gap, ignore it
-v/--verbose: print out patristic distances and uncorrected
distances used to determine saturation
--plot: save a saturation scatter plot with fitted slope through origin
--plot-output: output path for saturation plot (default: saturation_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