persim.PersistenceImager¶
- class persim.PersistenceImager(birth_range=None, pers_range=None, pixel_size=None, weight=None, weight_params=None, kernel=None, kernel_params=None)[source]¶
Transformer which converts persistence diagrams into persistence images.
- Parameters
birth_range (pair of floats) – Range of persistence pair birth values covered by the persistence image (default: (0.0, 1.0)).
pers_range (pair of floats) – Range of persistence pair persistence (death-birth) values covered by the persistence image (default: (0.0, 1.0)).
pixel_size (float) – Dimensions of each square pixel (default: 0.2).
weight (callable or str in ['persistence', 'linear_ramp']) – Function which weights the birth-persistence plane (default: ‘persistence’).
weight_params (dict) – Arguments needed to specify the weight function (default: {‘n’: 1.0}).
kernel (callable or str in ['gaussian', 'uniform']) – Cumulative distribution function defining the kernel (default: ‘gaussian’).
kernel_params (dict) – Arguments needed to specify the kernel function (default: {‘sigma’: [[1.0, 0.0], [0.0, 1.0]]}).
Example
First instantiate a PersistenceImager() object:
> from persim import PersistenceImager > pimgr = PersistenceImager(pixel_size=0.2, birth_range=(0,1))
Printing a PersistenceImager() object will print its hyperparameters:
> print(pimgr) PersistenceImager(birth_range=(0.0, 1.0), pers_range=(0.0, 1.0), pixel_size=0.2, weight=persistence, weight_params={'n': 1.0}, kernel=gaussian, kernel_params={'sigma': [[1.0, 0.0], [0.0, 1.0]]})
PersistenceImager() attributes can be adjusted at or after instantiation. Updating attributes of a PersistenceImager() object will automatically update all other dependent attributes:
> pimgr.pixel_size = 0.1 > pimgr.birth_range = (0, 2) > print(pimgr) > print(pimgr.resolution) PersistenceImager(birth_range=(0.0, 2.0), pers_range=(0.0, 1.0), pixel_size=0.1, weight=persistence, weight_params={'n': 1.0}, kernel=gaussian, kernel_params={'sigma': [[1.0, 0.0], [0.0, 1.0]]}) (20, 10)
The fit() method can be called on one or more (-,2) numpy.ndarrays to automatically determine the miniumum birth and persistence ranges needed to capture all persistence pairs. The ranges and resolution are automatically adjusted to accomodate the specified pixel size. The option skew=True specifies that the diagram is currently in birth-death coordinates and must first be transformed to birth-persistence coordinates:
> import numpy as np > pimgr = PersistenceImager(pixel_size=0.5) > pdgms = [np.array([[0.5, 0.8], [0.7, 2.2], [2.5, 4.0]]), np.array([[0.1, 0.2], [3.1, 3.3], [1.6, 2.9]]), np.array([[0.2, 1.5], [0.4, 0.6], [0.2, 2.6]])] > pimgr.fit(pdgms, skew=True) > print(pimgr) > print(pimgr.resolution) PersistenceImager(birth_range=(0.1, 3.1), pers_range=(-8.326672684688674e-17, 2.5), pixel_size=0.5, weight=persistence, weight_params={'n': 1.0}, kernel=gaussian, kernel_params={'sigma': [[1.0, 0.0], [0.0, 1.0]]}) (6, 5)
The transform() method can then be called on one or more (-,2) numpy.ndarrays to generate persistence images from diagrams. The option skew=True specifies that the diagrams are currently in birth-death coordinates and must first be transformed to birth-persistence coordinates:
> pimgs = pimgr.transform(pdgms, skew=True) > pimgs[0] array([[0.03999068, 0.05688393, 0.06672051, 0.06341749, 0.04820814], [0.04506697, 0.06556791, 0.07809764, 0.07495246, 0.05730671], [0.04454486, 0.06674611, 0.08104366, 0.07869919, 0.06058808], [0.04113063, 0.0636504 , 0.07884635, 0.07747833, 0.06005714], [0.03625436, 0.05757744, 0.07242608, 0.07180125, 0.05593626], [0.02922239, 0.04712024, 0.05979033, 0.05956698, 0.04653357]])
Notes
[1] Adams et. al., “Persistence Images: A Stable Vector Representation of Persistent Homology,” Journal of Machine Learning Research, vol. 18, pp. 1-35, 2017. http://www.jmlr.org/papers/volume18/16-337/16-337.pdf
- __init__(birth_range=None, pers_range=None, pixel_size=None, weight=None, weight_params=None, kernel=None, kernel_params=None)[source]¶
PersistenceImager constructor method
Methods
__init__
([birth_range, pers_range, …])PersistenceImager constructor method
fit
(pers_dgms[, skew])Choose persistence image range parameters which minimally enclose all persistence pairs across one or more persistence diagrams.
fit_transform
(pers_dgms[, skew])Choose persistence image range parameters which minimally enclose all persistence pairs across one or more persistence diagrams and transform the persistence diagrams into persistence images.
plot_diagram
(pers_dgm[, skew, ax, out_file])Plot a persistence diagram.
plot_image
(pers_img[, ax, out_file])Plot a persistence image.
transform
(pers_dgms[, skew, n_jobs])Transform a persistence diagram or an iterable containing a collection of persistence diagrams into persistence images.
Attributes
Range of birth values covered by the persistence image.
Persistence image height.
Range of persistence values covered by the persistence image.
Persistence image square pixel dimensions.
Persistence image resolution.
Persistence image width.
- fit(pers_dgms, skew=True)[source]¶
Choose persistence image range parameters which minimally enclose all persistence pairs across one or more persistence diagrams.
- Parameters
pers_dgms (one or an iterable of (-,2) numpy.ndarrays) – Collection of one or more persistence diagrams.
skew (boolean) – Flag indicating if diagram(s) need to first be converted to birth-persistence coordinates (default: True).
- fit_transform(pers_dgms, skew=True)[source]¶
Choose persistence image range parameters which minimally enclose all persistence pairs across one or more persistence diagrams and transform the persistence diagrams into persistence images.
- Parameters
pers_dgms (one or an iterable of (-,2) numpy.ndarray) – Collection of one or more persistence diagrams.
skew (boolean) – Flag indicating if diagram(s) need to first be converted to birth-persistence coordinates (default: True).
- Returns
list – Collection of numpy.ndarrays encoding the persistence images in the same order as pers_dgms.
- plot_diagram(pers_dgm, skew=True, ax=None, out_file=None)[source]¶
Plot a persistence diagram.
- Parameters
pers_dgm ((-,2) numpy.ndarray) – A persistence diagram.
skew (boolean) – Flag indicating if diagram needs to first be converted to birth-persistence coordinates (default: True).
ax (matplotlib.Axes) – Instance of a matplotlib.Axes object in which to plot (default: None, generates a new figure)
out_file (str) – Path and file name including extension to save the figure (default: None, figure not saved).
- Returns
matplotlib.Axes – The matplotlib.Axes which contains the persistence diagram
- plot_image(pers_img, ax=None, out_file=None)[source]¶
Plot a persistence image.
- Parameters
pers_img ((M,N) numpy.ndarray) – A persistence image, as output by PersistenceImager().transform()
ax (matplotlib.Axes) – Instance of a matplotlib.Axes object in which to plot (default: None, generates a new figure)
out_file (str) – Path and file name including extension to save the figure (default: None, figure not saved).
- Returns
matplotlib.Axes – The matplotlib.Axes which contains the persistence image
- transform(pers_dgms, skew=True, n_jobs=None)[source]¶
Transform a persistence diagram or an iterable containing a collection of persistence diagrams into persistence images.
- Parameters
pers_dgms (one or an iterable of (-,2) numpy.ndarrays) – Collection of one or more persistence diagrams.
skew (boolean) – Flag indicating if diagram(s) need to first be converted to birth-persistence coordinates (default: True).
n_jobs (int) – Number of cores to use to transform a collection of persistence diagrams into persistence images (default: None, uses a single core).
- Returns
list – Collection of numpy.ndarrays encoding the persistence images in the same order as pers_dgms.
- property birth_range¶
Range of birth values covered by the persistence image.
- Returns
birth_range (pair of floats (min. birth, max. birth)) – The minimum and maximum birth values covered by the persistence image.
- property height¶
Persistence image height.
- Returns
height (float) – The height of the region of the birth-persistence plane covered by the persistence image in persistence units.
- property pers_range¶
Range of persistence values covered by the persistence image.
- Returns
pers_range (pair of floats (min. persistence, max. persistence)) – The minimum and maximum persistence values covered by the persistence image.
- property pixel_size¶
Persistence image square pixel dimensions.
- Returns
pixel_size (float) – The width (and height) in birth/persistence units of each square pixel in the persistence image.
- property resolution¶
Persistence image resolution.
- Returns
resolution (pair of ints (width, height)) – The number of pixels along each dimension of the persistence image, determined by the birth and persistence ranges and the pixel size.
- property width¶
Persistence image width.
- Returns
width (float) – The width of the region of the birth-persistence plane covered by the persistence image in birth units.