NeighborNet

NeighborNet phylogenetic network from distance matrix (Bryant & Moulton 2004)

Command identity

Canonical command:

neighbor_net

Handler:

neighbor_net

Aliases:

nnet

Standalone executables:

pk_neighbor_net, pk_nnet

Categories:

Tree comparison & consensus

Runtime interface

Synopsis

phykit neighbor_net [--alignment <alignment>] [--distance-matrix <distance_matrix>] --output <output> [--metric <metric>] [--max-splits <max_splits>] [--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	false	str	none	any
--distance-matrix	false	str	none	any
-o, --output	true	str	required	any
--metric	false	str	p-distance	identity, p-distance, jc
--max-splits	false	int	30	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

Construct a NeighborNet phylogenetic network from pairwise distances (Bryant & Moulton 2004). Unlike a consensus network (which summarizes conflict across gene trees), NeighborNet infers a splits graph directly from a distance matrix — analogous to Neighbor-Joining but producing a network instead of a tree.

Input is either a FASTA alignment (distances computed internally) or a pre-computed distance matrix CSV. The algorithm:

1. Computes pairwise distances (p-distance, identity, or Jukes-Cantor)

2. Builds a NJ tree to determine the circular taxon ordering

3. Enumerates all circular splits compatible with that ordering

4. Estimates split weights via non-negative least squares (NNLS)

5. Visualizes as a planar splits graph (Buneman graph)

# From an alignment
phykit neighbor_net -a alignment.fa -o network.pdf

# From a pre-computed distance matrix
phykit neighbor_net --distance-matrix distances.csv -o network.pdf

# With Jukes-Cantor correction
phykit neighbor_net -a alignment.fa -o network.pdf --metric jc

Options:
-a/--alignment: FASTA alignment file (computes distances internally)
--distance-matrix: pre-computed distance matrix CSV with taxon headers
-o/--output: output figure path (required)
--metric: distance metric when using -a: identity, p-distance (default), or jc (Jukes-Cantor)
--max-splits: maximum splits for visualization (default: 30)
--json: optional argument to print results as JSON