fastbaps 0.1.0

Fast Bayesian hierarchical clustering of bacterial populations

fastbaps

Fast Bayesian hierarchical clustering of bacterial populations from SNP alignments.

fastbaps is a Python+Rust port of the R fastbaps package. Given a whole-genome alignment of bacterial isolates in FASTA format, it infers population structure by running Bayesian hierarchical clustering (BHC) over single-nucleotide polymorphisms and returns a cluster label for each isolate. The Python layer handles orchestration and I/O; the numerically intensive kernels run in compiled Rust via the companion fastbaps-core crate (available separately on crates.io for Rust users).

Installation

pip install fastbaps

Prebuilt abi3 wheels are available for Linux and macOS (x86_64 and arm64). Windows is not supported because the pysam runtime dependency wraps htslib, a Unix-only C library. Python 3.9 or newer is required.

You do not need a Rust toolchain to install from PyPI; all wheels include the compiled extension.

Quickstart

from fastbaps import import_fasta_sparse_nt, fast_baps, best_baps_partition

# Load a whole-genome SNP alignment
sparse_data = import_fasta_sparse_nt("alignment.fa")          # prior="baps" (default)

# Run two-phase Bayesian hierarchical clustering
hc = fast_baps(sparse_data, n_cores=4)
# hc keys: "merge", "height", "order", "labels"

# Cut the dendrogram to find the best partition
clusters = best_baps_partition(sparse_data, hc)
# clusters: integer array, one 1-indexed label per isolate

for name, label in zip(hc["labels"], clusters):
    print(f"{name}\t{label}")

import_fasta_sparse_nt takes a required fasta_path and an optional prior argument ("baps" or "mean", default "baps"). fast_baps accepts k_init (initial partition count; auto-selected if omitted), n_cores (default 1), and quiet (default False).

Command line

fastbaps --input alignment.fa --output clusters.csv --threads 4

Full options:

fastbaps --input INPUT --output OUTPUT
         [--prior {baps,mean,optimise.symmetric,optimise.baps}]
         [--levels N] [--threads N] [--quiet]

The output CSV has columns Isolates and Clusters.

How it works

• Phase 1 (coarse) — Ward's D2 hierarchical clustering divides isolates into k_init initial partitions, reducing the search space cheaply.
• Phase 2 (BHC refinement) — the partitions are agglomerated greedily using a Dirichlet-multinomial marginal log-likelihood, building a full merge tree with heights and posterior merge ratios (rk), parallelized with Rayon.
• Best partition — the tree is cut wherever the posterior favors two subtrees being separate (threshold ln(0.5)), yielding one cluster label per isolate.
• The heavy kernels (py_bhier_parallel, py_calc_ddk, py_tree_llk, py_summarise_clusters) live in Rust; everything else is Python.

For a full technical walk-through see FOR-DEVELOPERS.md. The standalone Rust core is published as fastbaps-core on crates.io.

License

Dual-licensed under MIT or Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.

Credits

This package ports the algorithm from the original R fastbaps package. Please cite the original work when using fastbaps in research.