Nearest neighbor interchange

Generate NNI tree rearrangements

Command identity

Canonical command:

nearest_neighbor_interchange

Handler:

nearest_neighbor_interchange

Aliases:

nni

Standalone executables:

pk_nearest_neighbor_interchange, pk_nni

Categories:

Tree manipulation & utilities

Runtime interface

Synopsis

phykit nearest_neighbor_interchange <tree> [--output <output>] [--branch <branch>] [--branches <branches>] [--no-input-tree] [--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
tree	true	str	required	any
-o, --output	false	str	none	any
--branch	false	str	none	any
--branches	false	str	none	any
--no-input-tree	false	boolean	false	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

Generate nearest neighbor interchange (NNI) moves for a binary rooted tree.

By default, all NNI rearrangements are emitted (one tree per neighbor), and the output file will have the same name as the input file but with the suffix .nnis. The input phylogeny is written at the top of the output unless --no-input-tree is supplied.

Pass --branch (a comma-separated pair of taxa) or --branches (a file with one pair per line) to restrict output to the two NNI rearrangements around a specific internal branch. The branch is identified as the edge leading to the most recent common ancestor (MRCA) of the supplied taxa. This is useful for branch-by-branch likelihood comparison in IQ-TREE / RAxML: re-score the bundle of output trees against an alignment and compare site-likelihoods at the labelled split.

phykit nearest_neighbor_interchange <tree> [-o/--output <output_file>]
    [--branch A,B] [--branches <file>] [--no-input-tree] [--json]

Options:
<tree>: first argument after function name should be a tree file
-o/--output: optional argument to specify output file name
--branch: optional argument. Two taxa separated by a comma (e.g., --branch A,B) whose MRCA defines the internal branch to rearrange. Emits the two alternative NNI topologies for that branch.
--branches: optional argument. Path to a file with one taxon pair per line (comma- or tab-separated). Lines may optionally start with a label followed by the two taxa (label<TAB>A<TAB>B), in which case the label is echoed in the --json report. Lines that are blank or start with # are ignored. Each pair yields two NNI trees, emitted in the order the pairs appear.
--no-input-tree: optional argument. Omit the input phylogeny from the top of the output file.
--json: optional argument to print summary metadata as JSON

Example: explore likelihoods around a single internal split

# Emit the input tree + the 2 NNIs around the MRCA of taxa A, B
phykit nni species.tre --branch A,B -o candidates.nwk

# Then evaluate likelihoods in IQ-TREE
iqtree -s alignment.fa -te candidates.nwk -pre nni_compare