API

The following classes and functions live in the dionysus module.

Filtration

class Simplex

an abstract simplex

__contains__(self: dionysus._dionysus.Simplex, v: int) bool

test whether the simplex contains given vertex

__getitem__(self: dionysus._dionysus.Simplex, i: int) int

access i-th vertex

__iter__(self: dionysus._dionysus.Simplex) Iterator

iterator over the vertices

__len__(self: dionysus._dionysus.Simplex) int

simplex cardinality

boundary(self: dionysus._dionysus.Simplex) Iterator

returns iterator over the boundary of the simplex

property data

access the data associated to the simplex

dimension(self: dionysus._dionysus.Simplex) int

simplex dimension, one less than cardinality

join(self: dionysus._dionysus.Simplex, v: int) dionysus._dionysus.Simplex

join a simplex and a vertex

class Filtration

store an ordered sequence of simplices, providing lookup

__contains__(self: dionysus._dionysus.Filtration, arg0: dionysus._dionysus.Simplex) bool

test whether filtration contains the simplex

__getitem__(self: dionysus._dionysus.Filtration, arg0: int) dionysus._dionysus.Simplex

access the simplex at the given index

__iter__(self: dionysus._dionysus.Filtration) Iterator

iterate over the simplices in sorted order

__len__(self: dionysus._dionysus.Filtration) int

size of the filtration

add(self: dionysus._dionysus.Filtration, s: dionysus._dionysus.Simplex) int

append simplex to the filtration, if not already in the filtration; either way return the index of the simplex

append(self: dionysus._dionysus.Filtration, s: dionysus._dionysus.Simplex) None

append simplex to the filtration

index(self: dionysus._dionysus.Filtration, s: dionysus._dionysus.Simplex) int

find the ordered index of a simplex in the filtration

rearrange(self: dionysus._dionysus.Filtration, indices: List[int]) None

rearrange simplices into the given order

sort(*args, **kwargs)

Overloaded function.

  1. sort(self: dionysus._dionysus.Filtration, reverse: bool = False) -> None

sort the filtration with respect to data, breaking ties using dimension, and then lexicographically

  1. sort(self: dionysus._dionysus.Filtration, cmp: Callable[[dionysus._dionysus.Simplex, dionysus._dionysus.Simplex], int], reverse: bool = False) -> None

sort the filtration with respect to the given functor

fill_rips(data: numpy.ndarray, k: int, r: float) dionysus._dionysus.Filtration

returns (sorted) filtration filled with the k-skeleton of the clique complex built on the points at distance at most r from each other

closure(simplices, k)

Compute the k-skeleton of the closure of the list of simplices.

fill_freudenthal(data: numpy.ndarray, reverse: bool = False) dionysus._dionysus.Filtration

returns (sorted) lower-star (or upper-star if reverse = True) filtration filled with the Freudenthal triangulation of the grid in the array data

Persistence

homology_persistence(*args, **kwargs)

Overloaded function.

  1. homology_persistence(filtration: dionysus._dionysus.Filtration, prime: int = 2, method: str = ‘clearing’, progress: bool = False) -> dionysus::ReducedMatrix<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> >

compute homology persistence of the filtration (pair simplices); method is one of clearing, row, column, or column_no_negative

  1. homology_persistence(filtration: dionysus._dionysus.Filtration, relative: dionysus._dionysus.Filtration, prime: int = 2, method: str = ‘clearing’, progress: bool = False) -> dionysus::ReducedMatrix<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> >

compute homology persistence of the filtration, relative to a subcomplex; method is one of clearing, row, column, or column_no_negative

cohomology_persistence(filtration: dionysus._dionysus.Filtration, prime: int = 2, keep_cocycles: bool = False) dionysus::PairChainRecorder<dionysus::CohomologyPersistence<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> > >

compute cohomology persistence of the filtration

omnifield_homology_persistence(filtration: dionysus._dionysus.Filtration) dionysus::OmniFieldPersistence<unsigned int, std::__1::less<unsigned int>, dionysus::Q<long>, dionysus::ZpField<long> >

compute homology persistence of the filtration (pair simplices) over all fields at once

zigzag_homology_persistence(filtration: dionysus._dionysus.Filtration, times: List[List[float]], prime: int = 2, callback: Callable[[int, float, bool, dionysus::ZigzagPersistence<dionysus::ZpField<long>, int, std::__1::less<int> >, PyTimeIndexMap], None] = <built-in method  of PyCapsule object at 0x11fd363f0>, progress: bool = False) Tuple[dionysus::ZigzagPersistence<dionysus::ZpField<long>, int, std::__1::less<int> >, List[dionysus::Diagram<float, unsigned int>], PyTimeIndexMap]

compute zigzag homology persistence of the filtration with respect to the given times

Parameters:
  • filtration – an instance of Filtration with the set of simplices used in the zigzag construction

  • times – a list of lists; the outer list runs parallel with the filtration; the inner list specifies for each simplex when it enters and leaves the zigzag (even entries, starting the indexing from 0, are interpreted as appearance times, odd entires as disappearance)

  • prime – prime modulo which to perform computation

  • callback – function to call after every step in the zigzag; it gets arguments (i,t,d,zz,cells), where i is the index of the simplex being added or removed, t is the time, d is the “direction” (True if the simplex is being added, False if it`s being removed), zz is the current state of the ZigzagPersistence, cells is the map from the internal indices of the zigzag representation to the filtration indices,

  • progress – show a progress bar.

Returns:

A triple. The first element is an instance of ZigzagPersistence, which offers access to the cycles alive at the end of the zigzag; the second is a list of persistence diagrams; the third is an instance of TimeIndexMap for translating cycles from the internal representation to filtration indices.

Diagrams

init_diagrams(*args, **kwargs)

Overloaded function.

  1. init_diagrams(m: dionysus::ReducedMatrix<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> >, f: dionysus._dionysus.Filtration) -> List[dionysus::Diagram<float, unsigned int>]

initialize diagrams from reduced matrix and filtration

  1. init_diagrams(m: dionysus::PairChainRecorder<dionysus::CohomologyPersistence<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> > >, f: dionysus._dionysus.Filtration) -> List[dionysus::Diagram<float, unsigned int>]

initialize diagrams from cohomology persistence and filtration

  1. init_diagrams(ofp: dionysus::OmniFieldPersistence<unsigned int, std::__1::less<unsigned int>, dionysus::Q<long>, dionysus::ZpField<long> >, f: dionysus._dionysus.Filtration, p: int) -> List[dionysus::Diagram<float, unsigned int>]

initialize diagrams for a specific prime from omnifield persistence and filtration

class Diagram

persistence diagram

__iter__(self: dionysus._dionysus.Diagram) Iterator

iterate over the points of the diagram

__len__(self: dionysus._dionysus.Diagram) int

size of the diagram

append(self: dionysus._dionysus.Diagram, p: dionysus::Diagram<float, unsigned int>::Point) None

append point to the diagram

class DiagramPoint

persistence diagram point

property birth

birth value

property data

auxiliary data associated to the point (e.g., birth index)

property death

death value

wasserstein_distance(dgm1: dionysus._dionysus.Diagram, dgm2: dionysus._dionysus.Diagram, q: int = 2, delta: float = 0.01, internal_p: float = - 1.0, initial_eps: float = 0.0, eps_factor: float = 0.0) float

compute Wasserstein distance between two persistence diagrams

bottleneck_distance(dgm1: dionysus._dionysus.Diagram, dgm2: dionysus._dionysus.Diagram, delta: float = 0.01) float

compute bottleneck distance between two persistence diagrams

Matrices

class Chain

chain of indices (formal sum with coefficients in Zp)

__eq__(self: dionysus._dionysus.Chain, arg0: dionysus._dionysus.Chain) bool

equality comparison

__getitem__(self: dionysus._dionysus.Chain, arg0: int) dionysus::ChainEntry<dionysus::ZpField<long>, unsigned int>

access the entry at a given index

__iter__(self: dionysus._dionysus.Chain) Iterator

iterate over the entries of the chain

__len__(self: dionysus._dionysus.Chain) int

size of the chain

__ne__(self: dionysus._dionysus.Chain, arg0: dionysus._dionysus.Chain) bool

nonequal comparison

class ChainEntry

(coefficient, index) entry in a chain)

property element

coefficient of the chain element

property index

index of the chain element

class ReducedMatrix

matrix, where each column has a lowest non-zero entry in a unique row; supports iteration and indexing

__getitem__(self: dionysus._dionysus.ReducedMatrix, arg0: int) std::__1::vector<dionysus::ChainEntry<dionysus::ZpField<long>, unsigned int>, std::__1::allocator<dionysus::ChainEntry<dionysus::ZpField<long>, unsigned int> > >

access the column at a given index

__iter__(self: dionysus._dionysus.ReducedMatrix) Iterator

iterate over the columns of the matrix

__len__(self: dionysus._dionysus.ReducedMatrix) int

size of the matrix

homologous(self: dionysus._dionysus.ReducedMatrix, arg0: std::__1::vector<dionysus::ChainEntry<dionysus::ZpField<long>, unsigned int>, std::__1::allocator<dionysus::ChainEntry<dionysus::ZpField<long>, unsigned int> > >, arg1: std::__1::vector<dionysus::ChainEntry<dionysus::ZpField<long>, unsigned int>, std::__1::allocator<dionysus::ChainEntry<dionysus::ZpField<long>, unsigned int> > >) bool

test if two cycles are homologous

pair(self: dionysus._dionysus.ReducedMatrix, arg0: int) int

pair of the given index

property unpaired

index representing lack of pair

class OmniFieldPersistence

compact composition of multiple reduced matrices

__len__(self: dionysus._dionysus.OmniFieldPersistence) int

size of the persistence object

column(self: dionysus._dionysus.OmniFieldPersistence, arg0: int, arg1: int) dionysus._dionysus.Chain

get the column over a specific prime

primes(self: dionysus._dionysus.OmniFieldPersistence) List[int]

primes over which the matrix differs from the rest

special(self: dionysus._dionysus.OmniFieldPersistence, arg0: int, arg1: int) bool

test whether the column has a special value over the given prime

class CoChain

chain of indices (formal sum with coefficients in Zp)

__eq__(self: dionysus._dionysus.CoChain, arg0: dionysus._dionysus.CoChain) bool

equality comparison

__getitem__(self: dionysus._dionysus.CoChain, arg0: int) dionysus::CohomologyPersistence<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> >::Entry

access the entry at a given index

__iter__(self: dionysus._dionysus.CoChain) Iterator

iterate over the entries of the chain

__len__(self: dionysus._dionysus.CoChain) int

size of the chain

__ne__(self: dionysus._dionysus.CoChain, arg0: dionysus._dionysus.CoChain) bool

nonequal comparison

class CoChainEntry

(coefficient, index) entry in a chain)

property element

coefficient of the chain element

property index

index of the chain element

class CohomologyPersistenceColumnHead

Wrapper around columns in CohomologyPersistence.

property cocycle

still alive cocycle

property index

index when the column was added

class CohomologyPersistence

representation of pairs and alive cocycles

__iter__(self: dionysus._dionysus.CohomologyPersistence) Iterator

iterate over the column heads of the matrix

__len__(self: dionysus._dionysus.CohomologyPersistence) int

size of the matrix

cocycle(self: dionysus._dionysus.CohomologyPersistence, arg0: int) std::__1::vector<dionysus::CohomologyPersistence<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> >::Entry, std::__1::allocator<dionysus::CohomologyPersistence<dionysus::ZpField<long>, unsigned int, std::__1::less<unsigned int> >::Entry> >

cocycle that died with the addition of the cell at the given index

pair(self: dionysus._dionysus.CohomologyPersistence, arg0: int) int

pair of the given index

property unpaired

index representing lack of pair

class ZigzagPersistence

representation of the current homology basis

__iter__(self: object) dionysus._dionysus.ZZAliveCycleIterator

iterator over the alive cycles

__len__(self: dionysus._dionysus.ZigzagPersistence) int

number of alive cycles

class Zp

arithmetic mod p

Plotting

The following functions live in dionysus.plot module.

plot_diagram(dgm, show=False, labels=False, ax=None, line_style=None, pt_style=None)

Plot the persistence diagram.

Parameters:

dgm (Diagram) – See for example init_diagrams.

Keyword Arguments:
  • show (bool) – Display the plot. (Default: False)

  • labels (bool) – Set axis labels. (Default: False)

  • ax (AxesSubplot) – Axes that should be used for plotting (Default: None)

  • pt_style (dict) – argments passed to ax.scatter for style of points.

  • line_style (dict) – argments passed to ax.plot for style of diagonal line.

plot_bars(dgm, order='birth', show=False, ax=None, **bar_style)

Plot the barcode.

Parameters:

dgm (Diagram) – See for example init_diagrams.

Keyword Arguments:
  • order (str) – How to sort the bars, either ‘death’ or ‘birth’ (Default: ‘birth’)

  • show (bool) – Display the plot. (Default: False)

  • ax (AxesSubplot) – Axes that should be used for plotting (Default: None)

  • **bar_style – Arguments passed to ax.plot for style of the bars. (Defaults: color=’b’)

plot_diagram_density(dgm, lognorm=True, diagonal=True, show=False, labels=False, ax=None, **hist_style)

Plot the histogram of point density.

Parameters:

dgm (Diagram) – See for example init_diagrams.

Keyword Arguments:
  • bins (int) – bins for histogram, see ax.hist2d (Default: 200)

  • lognorm (bool) – Use logarithmic norm (Default: True)

  • diagonal (bool) – (Default: True)

  • show (bool) – Display the plot. (Default: False)

  • labels (bool) – Set axis labels. (Default: False)

  • ax (AxesSubplot) – Axes that should be used for plotting (Default: None)

  • **hist_style – Arguments passed to ax.hist2d for style of the histogram. (Defaults: bins=200)

Diagnostics

is_simplicial(f, report=False)

Check if filtration is simplicial. If report = True, output the problems.