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.