Alignment outlier taxa

Identify outlier taxa in alignments

Command identity

Canonical command:

alignment_outlier_taxa

Handler:

alignment_outlier_taxa

Aliases:

aot, outlier_taxa

Standalone executables:

pk_alignment_outlier_taxa, pk_aot, pk_outlier_taxa

Categories:

Alignment quality & statistics

Runtime interface

Synopsis

phykit alignment_outlier_taxa <alignment> [--gap-z <gap_z>] [--composition-z <composition_z>] [--distance-z <distance_z>] [--rcvt-z <rcvt_z>] [--occupancy-z <occupancy_z>] [--entropy-z <entropy_z>] [--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
alignment	true	str	required	any
--gap-z	false	float	3.0	any
--composition-z	false	float	3.0	any
--distance-z	false	float	3.0	any
--rcvt-z	false	float	3.0	any
--occupancy-z	false	float	3.0	any
--entropy-z	false	float	3.0	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

Identify potential outlier taxa in an alignment and explicitly report why each taxon was flagged.

The following features are evaluated per taxon: 1) gap_rate: fraction of gap/ambiguous symbols
2) occupancy: fraction of valid symbols
3) composition_distance: Euclidean distance from the median composition profile
4) long_branch_proxy: mean pairwise sequence distance to other taxa
5) rcvt: relative composition variability per taxon
6) entropy_burden: average site entropy over this taxon's valid positions

If a taxon exceeds one or more feature-specific thresholds, PhyKIT reports the exact feature(s), observed value(s), threshold(s), and explanation(s) for the flag.

phykit alignment_outlier_taxa <alignment> [--gap-z <float>] [--composition-z <float>] [--distance-z <float>] [--rcvt-z <float>] [--occupancy-z <float>] [--entropy-z <float>] [--json]

Example output:

features_evaluated      gap_rate,occupancy,composition_distance,long_branch_proxy,rcvt,entropy_burden
thresholds      gap_rate>0.0;occupancy<0.4;composition_distance>0.1;long_branch_proxy>0.4181;rcvt>0.0095;entropy_burden>0.35
taxon_d composition_distance=1.3454>0.1;long_branch_proxy=1.0>0.4181    Unusual sequence composition profile relative to other taxa. | High mean pairwise sequence distance to other taxa.
taxon_e gap_rate=0.6>0.0;occupancy=0.4<0.4      High fraction of gap/ambiguous symbols compared to other taxa. | Low fraction of valid symbols compared to other taxa.

Options:
<alignment>: first argument after function name should be an alignment file
--gap-z: z-threshold used for high-gap outlier detection (default: 3.0)
--composition-z: z-threshold used for composition-distance outlier detection (default: 3.0)
--distance-z: z-threshold used for long-branch-proxy outlier detection (default: 3.0)
--rcvt-z: z-threshold used for RCVT outlier detection (default: 3.0)
--occupancy-z: z-threshold used for low-occupancy outlier detection (default: 3.0)
--entropy-z: z-threshold used for entropy-burden outlier detection (default: 3.0)
--json: optional argument to print results as JSON