pyflagser.flagser_weighted(adjacency_matrix, max_edge_weight=None, min_dimension=0, max_dimension=inf, directed=True, filtration='max', coeff=2, approximation=None)

Compute persistent homology of a directed/undirected filtered flag complex.

From an adjacency_matrix and a filtration algorithm construct a filtered flag complex as a sequence of its cells associated to their filtration values and compute its persistent homology.

adjacency_matrix2d ndarray or scipy.sparse matrix of shape (n_vertices, n_vertices), required

Matrix representation of a directed/undirected weighted graph. Diagonal elements are vertex weights. The way zero values are handled depends on the format of the matrix. If the matrix is a dense numpy.ndarray, zero values denote zero-weighted edges. If the matrix is a sparse scipy.sparse matrix, explicitly stored off-diagonal zeros and all diagonal zeros denote zero-weighted edges. Off-diagonal values that have not been explicitely stored are treated by scipy.sparse as zeros but will be understood as infinitely-valued edges, i.e., edges absent from the filtration.

max_edge_weightint or float or None, optional, default: None

Maximum edge weight to be considered in the filtration. All edge weights greater than that value will be considered as infinitely-valued, i.e., absent from the filtration. If None, all finite edge weights are considered.

min_dimensionint, optional, default: 0

Minimum homology dimension to compute.

max_dimensionint or np.inf, optional, default: np.inf

Maximum homology dimension to compute.

directedbool, optional, default: True

If True, computes persistent homology for the directed filtered flag complex determined by adjacency_matrix. If False, computes persistent homology for the undirected filtered flag complex obtained by considering all weighted edges as undirected, and if two directed edges corresponding to the same undirected edge are explicitly assigned different weights and neither exceeds max_edge_weight, only the one in the upper triangular part of the adjacency matrix is considered. Therefore:

  • if max_edge_weight is numpy.inf, it is sufficient to pass a (dense or sparse) upper-triangular matrix;

  • if max_edge_weight is finite, it is recommended to pass either a symmetric dense matrix, or a sparse upper-triangular matrix.

filtrationstring, optional, default: 'max'

Algorithm determining the filtration. Warning: if an edge filtration is specified, it is assumed that the resulting filtration is consistent, meaning that the filtration value of every simplex of dimension at least two should evaluate to a value that is at least the maximal value of the filtration values of its containing edges. For performance reasons, this is not checked automatically. Possible values are: [‘dimension’, ‘zero’, ‘max’, ‘max3’, ‘max_plus_one’, ‘product’, ‘sum’, ‘pmean’, ‘pmoment’, ‘remove_edges’, ‘vertex_degree’]

coeffint, optional, default: 2

Compute homology with coefficients in the prime field \(\mathbb{F}_p = \{ 0, \ldots, p - 1 \}\) where \(p\) equals coeff.

approximationint or None, optional, default: None

Skip all cells creating columns in the reduction matrix with more than this number of entries. Use this for hard problems; a good value is often 100,000. Increase for higher precision, decrease for faster computation. If None, no approximation is made and all cells are used. For more details, please refer to [1].

outdict of list

A dictionary with the following key-value pairs:

  • 'dgms': list of ndarray of shape (n_pairs, 2) A list of persistence diagrams, one for each dimension greater than or equal than min_dimension and less than max_dimension. Each diagram is an ndarray of size (n_pairs, 2) with the first column representing the birth time and the second column representing the death time of each pair.

  • 'betti': list of int Betti numbers at filtration value max_edge_weight, per dimension greater than or equal to min_dimension and less than max_dimension.

  • 'cell_count': list of int Cell counts (number of simplices) at filtration value max_edge_weight, per dimension greater than or equal to min_dimension and less than max_dimension.

  • 'euler': int Euler characteristic at filtration value max_edge_weight.


The input graphs cannot contain self-loops, i.e. edges that start and end in the same vertex, therefore diagonal elements of the input adjacency matrix store vertex weights.



D. Luetgehetmann, “Documentation of the C++ flagser library”; GitHub: luetge/flagser.