fastnntpy 0.2.0

Fast NeighborNet (Rust) with Python bindings

fast-nnt

fast-nnt (read Fast Ent) is a simple Rust implementation of the Neighbor Net algorithm

Introduction

Fast-NNT is a Rust implementation of the NeighborNet algorithm, designed for efficient phylogenetic analysis. It constructs split trees from distance matrices, providing a fast and reliable tool for researchers in evolutionary biology.

Why does this exist when SplitsTree is available?

Well, SplitsTree4/6 are GUI-based applications, while Fast-NNT is a command-line tool that can be easily integrated into automated workflows and pipelines. It's meant to be lightweight and simple to use, you provide a simple input and it generates the nexus file. You can then use this file in R or Python to generate your own plots. This is perfect for people who love to manually beautify their visualizations.

How do the results compare to SplitsTree?

Fast-NNT aims to produce results that are consistent with those generated by SplitsTree, but there may be differences due to the underlying implementations and algorithms used. Users are encouraged to compare the output from Fast-NNT with that of SplitsTree to assess any discrepancies and determine the best tool for their specific needs.

Installation

Install Rust via rustup.

Python

You can install the Python package via pip:

pip install fastnntpy

R

You can install the R package via:

install.packages("fastnntr")

CLI

cargo install fast-nnt

Alternatively, you can build from source. Clone and install this repo via:

git clone https://github.com/rhysnewell/fast-nnt.git
cd fast-nnt
cargo install --path .

Usage

For Python and R, complete usage examples can be found in test/python and test/R. But a brief summary is as follows.

Python

Read data in via numpy, pandas, or polars:

import fastnntpy as fn
import pandas as pd
data = pd.read_csv("test/data/large/large_dist_matrix.csv")
n = fn.run_neighbour_net(data, data.columns)
print("Labels")
print(len(n.get_labels()))
print("Splits Records")
print(len(n.get_splits_records()))
print("Node Translations")
print(len(n.get_node_translations()))
print("Node Positions")
print(len(n.get_node_positions()))
print("Graph Edges")
print(len(n.get_graph_edges()))

R

Read your distance matrix in using your preferred method (e.g., data.table):

library(fastnntr)
library(data.table)
data <- fread("test/data/large/large_dist_matrix.csv", header=TRUE)
# Load network
Nnet <- run_neighbornet_networx(data, names(data), TRUE)

The run_neighbornet_networx function will return an object almost identical to that produced by phangorn, so should be compatible with existing workflows.

CLI

Required input is a symmetrical distance matrix, ideally with a header row indicating the taxa labels. Can be separated by any delimiter.

To generate a split nexus file (mostly) identical to SplitsTree4 and SplitsTree6:

fast_nnt neighbour_net -t 4 -i test/data/large_dist_matrix.csv -d output_dir -o prefix -O splits-tree4

Use the new Huson 2023 ordering algorithm (default):

fast_nnt neighbour_net -t 4 -i test/data/large_dist_matrix.csv -d output_dir -o prefix -O huson2023

Output

The output will include a nexus file containing the split network and network layout.

Known issues

• Floating point drift in the CGNR function, as observed in the smoke_30 test.
• Not sure where it is happening, but the final results on real data end up looking pretty much the same so not sure if it is an issue. Will need to be fixed at some point.

TODO

• R bindings for direct use within R
• Python bindings for direct use within Python
• Work on parallelism. Not a priority as the program is fast enough.
• Test on giant datasets.

Citations

If you use this tool in your work, please cite the original authors work:

• Bryant & Huson 2023: D. Bryant and DH Huson, NeighborNet- improved algorithms and implementation. Front. Bioinform. 3, 2023.
• Bryant & Moulton 2004: D. Bryant and V. Moulton. Neighbor-net: An agglomerative method for the construction of phylogenetic networks. Molecular Biology and Evolution, 21(2):255– 265, 2004.

You can also cite this repository directly:

• Newell, R. J. P., & McMaster, E. S. (2025). Fast-NNT: Fast NeighborNet Split Trees For Unrooted Phylogenetic Analysis (v0.1.0). Zenodo. https://doi.org/10.5281/zenodo.16907380