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.
`set_output`(*[, transform])	Set output container.
`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.