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

`birth_range`	Range of birth values covered by the persistence image.
`height`	Persistence image height.
`pers_range`	Range of persistence values covered by the persistence image.
`pixel_size`	Persistence image square pixel dimensions.
`resolution`	Persistence image resolution.
`width`	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.