Package: dbsampler
Decision Boundary Sampler (DBS)ContentsInstallationCompiling from sourceUsageSparseHow does it workPerformanceCitingDBSampler is a package to sample points in the decision boundary of  classification problems (binary or multiclass). It is theorically exact and efficient for very high dimensions. The guarentees:Returns a sample of points uniformly distributed in the decision boundary.Number of points is user defined. More points for a denser sample, less for a faster run.The points are guarenteed to come from the edges of the condensed Voronoi Diagram (more below).InstallationPre-built packages currently for MacOS, Windows and Linux systems are available inPyPIand can be installed with:pipinstalldbsamplerOn uncommon architectures, you may need to firstinstall Cargobefore runningpip install vlmc.Compilation from sourceIn order to compile from source you will need toinstall Rust/Cargoandmaturinfor the python bindings.
Maturin is best used within a Python virtual environment:# activate your desired virtual environment first, then:pipinstallmaturin
gitclonehttps://github.com/antonio-leitao/dbsampler.gitcdvlmc# build and install the package:maturindevelop--releaseUsageimportdbsamplercover=dbsampler.dbs(data=X,labels=y,n_points=1000,n_epochs=5,sparse=True,parallel=True)Parameters:data: numpy array of shape (samples,features) with the points of every class.labels: 1-dimensional numpy array with labels of each points. Array must be flattened.n_points: This determines the number of points sampled from the decision boundary. More points equates for a denser sample but slows the algorithm. Default is 1000.sparse: boolean (defaultTrue), whether to remove points that are in the same Voronoi Edge or not.parallel: boolean (defaultTrue)Returns:cover: numpy array (n_points, n_features) of points in the decision boundary.SparsePassing thesparseflag will remove the cover points that fall on the same Voronoi Edge, favoring the first one.
This can drastically reduce the number of points while maintaining a uniform and complete cover of the decision boundary.
Below is the example of5000points sampled (left) and the same points withsparse=True.PerformanceDBSampler is written in Rust pre-builds the binaries for Windows, MacOS and most Linux distributions.
DBSampler achieves very high performance due to effective parallization and BLAS support.
Currently manages to calculate a cover of5 000points given10 000points in500dimensions in less than 10 seconds.More improvments are planned targeted situations where the number of samples times the dimensions is higher than 1 billion where the current implmentations starts to slow down.How does it work?For an in-depth explanation check at ourpaper. The algorithm aims at sampling uniformly points from the edges of Voronoi Cells belonging to points of different classes. The union of these edges is the decision boundary that maximizes the distance between classes.It starts by building an initial uniform sample of the space containingn_points. It then iterativelly "pushes" each point to the hyperplane orthogonal to the one between its closest neighbors of different classes.Sketch of proof of convergence. At each iteration inn_epochs:If both nearest neighbours have adjacent Voronoi Cells then, after projection the point is in the decision boundary (by construction).Else then there must exist a point from class A (or not A) that is the new nearest neighbour (by definition of Voronoi Cells).CitingIf you use DBSampler in your work or parts of the algorithm please consider citing:@inproceedings{petri2020on,
               title={On The Topological Expressive Power of Neural Networks},
               author={Giovanni Petri and Ant{\'o}nio Leit{\~a}o},
               booktitle={NeurIPS 2020 Workshop on Topological Data Analysis and Beyond},
               year={2020},
               url={https://openreview.net/forum?id=I44kJPuvqPD}
}In the paper above you can find the pseudocode of the algorithm along with the proof of convergence. A complete paper about the method is coming soon.