pyBregMan:
A Python library for geometric computing on BREGman MANifolds with applications. The focus of the library is to provide a specialized framework for Bregman manifolds: dually flat manifolds which consists of two convex generators related via Legendre–Fenchel duality.
Documentation is available on Read the Docs.
Currently in pre-release.
pyBregMan can be installed via pip3
or git
.
For the former (using pip3
), one can call:
pip3 install pyBregMan
For git
installation, one can directly clone from GitHub.
git clone https://github.com/alexandersoen/pyBregMan.git
cd pyBregMan
pip3 install .
To use pyBregMan
, a user can define Point
s on a specified Bregman manifold, where additional geometric objects (Geodesics, notions of dissimilarities, etc) can be defined on.
Such a procedure consists of:
- defining a
BregmanManifold
object; - specifying data via
Point
objects; - defining additional objects which act on a manifold object and data.
In addition, we also provide an inbuilt visualization framework which calls matplotlib
.
In the following code example, we define the manifold of bivariate Gaussian distribution. We then define and compute different types of centroids. Finally, we visualize the data and centroids.
Pre-defined manifolds can be found in the bregman.application
submodule.
The following demonstrates how to define a manifold object for bivariate Gaussians. We additionally define two points.
import numpy as np
from bregman.application.distribution.exponential_family.gaussian import GaussianManifold
from bregman.base import LAMBDA_COORDS, DualCoords, Point
# Define Bivariate Normal Manifold
manifold = GaussianManifold(input_dimension=2)
# Define data
to_vector = lambda mu, sigma: np.concatenate([mu, sigma.flatten()])
mu_1, sigma_1 = np.array([0.0, 1.0]), np.array([[1.0, 0.5], [0.5, 2.0]])
mu_2, sigma_2 = np.array([1.0, 2.0]), np.array([[2.0, 1.0], [1.0, 1.0]])
point_1 = Point(LAMBDA_COORDS, to_vector(mu_1, sigma_1))
point_2 = Point(LAMBDA_COORDS, to_vector(mu_2, sigma_2))
We note that the points are not specific to the Gaussian manifold. However, given compatible dimensions, one can utilize manifold specific method. For instance, we can define the KL divergence between the two points.
# KL divergence can be calculated
kl = manifold.kl_divergence(point_1, point_2)
rkl = manifold.kl_divergence(point_2, point_1)
print("KL(point_1 || point_2):", kl)
print("KL(point_2 || point_1):", rkl)
# >>> KL(point_1 || point_2): 0.9940936082534253
# >>> KL(point_2 || point_1): 1.2201921060322891
More complicated geometric objects can be imported from other submodules. In this example, we will import various objects to allow us to compute a centroid of the two Gaussian distributions we have defined.
from bregman.barycenter.bregman import BregmanBarycenter, SkewBurbeaRaoBarycenter
from bregman.application.distribution.exponential_family.gaussian.geodesic import FisherRaoKobayashiGeodesic
# We can define and calculate centroids
theta_barycenter = BregmanBarycenter(manifold, DualCoords.THETA)
eta_barycenter = BregmanBarycenter(manifold, DualCoords.ETA)
br_barycenter = SkewBurbeaRaoBarycenter(manifold)
dbr_barycenter = SkewBurbeaRaoBarycenter(manifold, DualCoords.ETA)
theta_centroid = theta_barycenter([point_1, point_2])
eta_centroid = eta_barycenter([point_1, point_2])
br_centroid = br_barycenter([point_1, point_2])
dbr_centroid = dbr_barycenter([point_1, point_2])
# Mid point of Fisher-Rao Geodesic is its corresponding centroid of two points
fr_geodesic = FisherRaoKobayashiGeodesic(manifold, point_1, point_2)
fr_centroid = fr_geodesic(t=0.5)
print("Right-Sided Centroid:", manifold.convert_to_display(theta_centroid))
print("Left-Sided Centroid:", manifold.convert_to_display(eta_centroid))
print("Bhattacharyya Centroid:", manifold.convert_to_display(br_centroid))
print("Fisher-Rao Centroid:", manifold.convert_to_display(fr_centroid))
# >>> Right-Sided Centroid: $\mu$ = [0.33333333 1.55555556]; $\Sigma$ = [[1.33333333 0.66666667]
# >>> [0.66666667 1.11111111]]
# >>> Left-Sided Centroid: $\mu$ = [0.5 1.5]; $\Sigma$ = [[1.75 1. ]
# >>> [1. 1.75]]
# >>> Bhattacharyya Centroid: $\mu$ = [0.41772374 1.53238683]; $\Sigma$ = [[1.53973074 0.82458984]
# >>> [0.82458984 1.40126629]]
# >>> Fisher-Rao Centroid: $\mu$ = [0.5326167 1.62759115]; $\Sigma$ = [[1.72908532 0.98542147]
# >>> [0.98542147 1.54545598]]
Finally, one can simply visualize the objects by using the inbuilt matplotlib
visualizer.
from bregman.visualizer.matplotlib.callback import VisualizeGaussian2DCovariancePoints
from bregman.visualizer.matplotlib.matplotlib import MatplotlibVisualizer
# These objects can be visualized through matplotlib
visualizer = MatplotlibVisualizer(manifold, (0, 1))
visualizer.plot_object(point_1, c="black")
visualizer.plot_object(point_2, c="black")
visualizer.plot_object(theta_centroid, c="red", label="Right-Sided Centroid")
visualizer.plot_object(eta_centroid, c="blue", label="Left-Sided Centroid")
visualizer.plot_object(br_centroid, c="purple", label="Bhattacharyya Centroid")
visualizer.plot_object(fr_centroid, c="pink", label="Fisher-Rao Centroid")
visualizer.add_callback(VisualizeGaussian2DCovariancePoints())
visualizer.visualize(LAMBDA_COORDS) # Display coordinate type
Code can be found in examples/centroids.py
.