BNPy (or bnpy) is Bayesian Nonparametric clustering for Python.
Our goal is to make it easy for Python programmers to train state-of-the-art clustering models on large datasets. We focus on nonparametric models based on the Dirichlet process, especially extensions that handle hierarchical and sequential datasets. Traditional parametric counterparts (like finite mixture models) are also supported.
Training a model with bnpy requires the user to specify the dataset, the model, and the algorithm to use. Flexible keyword options allow advanced users lots of control, but smart defaults make it simple for beginners. bnpy‘s modular implementation makes it possible to try many variants of models and algorithms, to find the best fit for the data at hand.
You can find many examples of bnpy in action in our curated Example Gallery.
These same demos are also directly available as Python scrips inside the project Github repository.
You can use bnpy to train a model in two ways: (1) from a command line/terminal, or (2) from within a Python script (of course). Both options require specifying a dataset, an allocation model, an observation model (likelihood), and an algorithm. Optional keyword arguments with reasonable defaults allow control of specific model hyperparameters, algorithm parameters, etc.
Below, we show how to call bnpy to train a 8 component Gaussian mixture model on a default toy dataset stored in a .csv file on disk. In both cases, log information is printed to stdout, and all learned model parameters are saved to disk.
python -m bnpy.Run /path/to/my_dataset.csv FiniteMixtureModel Gauss EM --K 8 --output_path /tmp/my_dataset/results/
import bnpy bnpy.run('/path/to/dataset.csv', 'FiniteMixtureModel', 'Gauss', 'EM', K=8, output_path='/tmp/my_dataset/results/')
Train a Dirichlet-process Gaussian mixture model (DP-GMM) via full-dataset variational coordinate ascent. This algorithm is often called “VB” for variational Bayes.
python -m bnpy.Run /path/to/dataset.csv DPMixtureModel Gauss VB --K 8
Train DP-GMM via scalable incremental or “memoized” variational coordinate ascent, with birth and merge moves, with data divided into 10 batches.
python -m bnpy.Run /path/to/dataset.csv DPMixtureModel Gauss memoVB --K 8 --nBatch 10 --moves birth,merge
Train HDP-HMM model to capture sequential structure in the dataset
# print help message for required arguments python -m bnpy.Run --help
# print help message for specific keyword options for Gaussian mixture models python -m bnpy.Run /path/to/dataset.csv FiniteMixtureModel Gauss EM --kwhelp
The following are possible allocation models, which is bnpy-terminology for a generative model which assigns clusters to structured datasets.
Any of the above allocation models can be combined with one of these observation models, which describe how to produce data assigned to a specific cluster.