DBOpt is a python library enabling reproducible and robust parameter selection for density-based clusterering algorithms. The method combines an efficient implementaion of density based cluster validation (k-DBCV) with Bayesian optimization to find optimal clustering algorithm parameters that maximize the DBCV score. DBOpt is currently compatible with the density based clustering algorithms: DBSCAN, HDBSCAN, and OPTICS. For more information about the DBOpt method read Hammer et al. Preprint at https://www.biorxiv.org/content/10.1101/2024.11.01.621498v1 (2024).
- k-DBCV
- BayesianOptimization
- scikit-learn
- NumPy
DBOpt can be installed via pip:
pip install DBOpt
The DBOpt class can be initialized by setting hyperparameters for the optimization. These include the algorithm to be optimized, the number of optimization iterations (runs), the number of initial parameter combinations to probe (rand_n), and the parameter space that is to be optimized. Each algorithm has its own set of parameters that can be optimized. More information about these parameters can be found in the corresponding scikit-learn documentation.
For DBSCAN, the relevant parameters are eps and min_samples. Bounds for one or both of these parameters must be set.
model = DBOpt.DBOpt(algorithm = 'DBSCAN', runs = 200, rand_n = 40,
eps = [3,200], min_samples = [3,200])
Parameters can be held constant:
model = DBOpt.DBOpt(algorithm = 'DBSCAN', runs = 200, rand_n = 40,
eps = [4,200], min_samples = 6)
HDBSCAN has two primary parameters, min_cluster_size and min_samples.
model = DBOpt.DBOpt(algorithm = 'HDBSCAN', runs = 200, rand_n = 40,
min_cluster_size = [4,200], min_samples = [4,200])
DBOpt is capable of optimizing addition parameters for HDBSCAN including cluster_selection_epsilon, cluster_selection_method, and alpha.
In cases like these when parameter spaces are vastly different in size, it can be helpful to scale all parameters to the same range by setting scale_params = True. scale_params is set to False by default.
model = DBOpt.DBOpt(algorithm = 'HDBSCAN', runs = 200, rand_n = 40,
min_cluster_size = [4,200], min_samples = [4,200], eps = [0,200], method = [0,1], alpha = [0,1],
scale_params = True)
OPTICS can currently be optimized with the xi method.
model = DBOpt.DBOpt(algorithm = 'OPTICS', runs = 200, rand_n = 40,
xi = [0.05,0.5], min_samples = [4,200])
DBOpt can process n-dimensional data. Here we use the C01 simulation from the data folder.
We create an array X which is a 2D array with x positions in column 0 and y positions in column 1.
Once hyperparameters have beeen set, the algorithm can be optimized for the data.
model.optimize(X)
Information about the chosen parameters and the full parameter sweep can be extracted after optimizing.
parameter_sweep_arr = model.parameter_sweep_
DBOpt_selected_parameters = model.parameters_
The optimization can be plotted:
parameter_sweep_plot = model.plot_optimization()
The data is clustered via the fit() method.
model.fit(X)
The optimization step and fit step can be performed together:
model.optimize_fit(X)
After fitting the labels and DBCV score can be stored:
labels = model.labels_
DBCV_score = model.DBCV_score_
The clusters can be plotted where show_noise will determine if the noise is shown or not (Default = True) and setting ind_cluster_scores = True will plot clusters colormapped to the individual cluster scores instead of colored randomly (Default = False) :
cluster_plot = model.plot_clusters()
cluster_plot_modified = model.plot_clusters(show_noise = True, ind_cluster_scores = True)
DBOpt is licensed with an MIT license. See LICENSE file for more information.
If you use DBOpt for your work, please cite with the following:
Hammer, J.L., Devanny, A.J. & Kaufman, L.J. Bayesian optimized parameter selection for density-based clustering applied to single molecule localization microscopy. Commun Biol 8, 902 (2025). https://doi.org/10.1038/s42003-025-08332-0
Code DOI:
