Quartet network

Quartet-based network visualization

Command identity

Canonical command:: quartet_network
Handler:: quartet_network
Aliases:: nanuq, qnet, quartet_net
Standalone executables:: pk_quartet_network, pk_nanuq, pk_qnet, pk_quartet_net
Categories:: Tree comparison & consensus

Runtime interface

Synopsis

phykit quartet_network --trees <trees> [--alpha <alpha>] [--beta <beta>] [--missing-taxa <missing_taxa>] [--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
`-t, --trees`	true	str	required	any
`--alpha`	false	float	0.05	any
`--beta`	false	float	0.95	any
`--missing-taxa`	false	str	error	error, shared
`--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

Quartet-based network inference (NANUQ-style) for distinguishing incomplete lineage sorting (ILS) from hybridization/gene flow using quartet concordance factors from gene trees.

For each 4-taxon subset, counts how many gene trees display each of the 3 possible unrooted topologies and applies two hypothesis tests:

Star test (Pearson chi-squared): tests whether the three topology counts are consistent with a star tree (equal probabilities 1/3 each). If p_star > beta (default 0.95), the quartet is classified as unresolved.
T3 tree model test (G-test / likelihood ratio): tests whether the counts are consistent with any resolved quartet tree under the multispecies coalescent. If p_tree > alpha (default 0.05), the quartet is classified as tree-like (conflict is due to ILS).
If both tests reject their null hypotheses, the quartet is classified as hybrid (asymmetric discordance indicating gene flow or hybridization).

This algorithm matches the NANUQ method of Allman, Baños & Rhodes (2019), implemented in R's MSCquartets package.

Polytomies (collapsed branches) in gene trees are handled conservatively: bipartitions from polytomous nodes are excluded, so quartets spanning a polytomy are treated as unresolved rather than misclassified. Trifurcating roots (standard unrooted Newick) are not affected. This allows gene trees with collapsed low-support branches to be used directly as input.

Input can be either: 1) a file with one Newick tree per line, or 2) a file with one tree-file path per line.

phykit quartet_network -t/--trees <trees> [--alpha 0.05] [--beta 0.95] [--missing-taxa error|shared] [--plot-output <file>]
    [--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:
-t/--trees: file containing trees (one Newick per line) or tree-file paths (one per line)
--alpha: significance level for the T3 tree model test (default: 0.05)
--beta: threshold for the star tree test; quartets with p_star > beta are called unresolved (default: 0.95)
--missing-taxa: handling strategy for mismatched taxa (error or shared; default: error)
--plot-output: output filename for the quartet network plot (optional)
--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

When --plot-output is specified, a NANUQ-style splits graph is drawn from the quartet distance matrix using Neighbor-Joining and circular split decomposition. Tree-like relationships appear as simple branching, while hybridization / reticulation produces characteristic box (parallelogram) structures — the same style of output produced by R's MSCquartets + NeighborNet pipeline.

No hybridization signal — all quartets are tree-like, so the splits graph is a clean unrooted tree:

Hybridization signal present — hybrid quartets introduce conflicting splits that appear as boxes in the network, indicating reticulation among C, D, E, and F: