Metadata-Version: 2.4
Name: fastbaps
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: pysam>=0.20
Requires-Dist: scikit-learn>=1.0
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: Fast Bayesian hierarchical clustering of bacterial populations
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/thanhleviet/fastbaps-py
Project-URL: Repository, https://github.com/thanhleviet/fastbaps-py

# 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](https://crates.io/crates/fastbaps-core) crate (available separately
on crates.io for Rust users).

## Installation

```bash
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

```python
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

```bash
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](https://github.com/thanhleviet/fastbaps-py/blob/main/FOR-DEVELOPERS.md).
The standalone Rust core is published as
[fastbaps-core](https://crates.io/crates/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.

