API

ripserer(dists::AbstractMatrix{T}; kwargs...)
ripserer(points; metric=Euclidean(), births, kwargs...)

Compute the persistent homology of metric space represented by dists or points and metric. points must be an array of bitstypes, such as NTuples or SVectors.

Keyoword Arguments

• dim_max: compute persistent homology up to this dimension. Defaults to 1.
• modulus: compute persistent homology with coefficients in the prime field of integers mod modulus. Defaults to 2.
• field_type: use this type of field of coefficients. Defaults to Mod{modulus}.
• threshold: compute persistent homology up to diameter smaller than threshold. For non-sparse Rips filtrations, it defaults to radius of input space.
• sparse: if true, use SparseRipsFiltration. Defaults to false. If the dists argument is a sparse matrix, it overrides this option.
• cutoff: only keep intervals with persistence(interval) > cutoff. Defaults to 0.
• representatives: if true, return representative cocycles along with persistence intervals. Defaults to false.
• metric: when calculating persistent homology from points, any metric from Distances.jl can be used. Defaults to Euclidean().
• births: when calculating persistent homology from points, births can be used to add birth times to vertices. Defaults to all births equal to 0.

ripserer(filtration::AbstractFiltration; dim_max=1)

Compute persistent homology from filtration object.

PersistenceInterval{T, C}

The type that represents a persistence interval. It behaves exactly like a Tuple{T, Union{T, Infinity}}, but may have a representative cocycle attached to it.

birth(interval::PersistenceInterval)

Get the birth time of interval.

death(interval::PersistenceInterval)

Get the death time of interval. When T<:AbstractFloat, Inf is returned instead of ∞.

death(interval::PersistenceInterval)

Get the persistence of interval, which is equal to death - birth. When T<:AbstractFloat, Inf is returned instead of ∞.

representative(interval::PersistenceInterval)

Get the representative cocycle attached to interval. If representatives were not computed, throw an error.

PersistenceDiagram{P<:PersistenceInterval} <: AbstractVector{P}

Type for representing persistence diagrams. Behaves exactly like an array of PersistenceIntervals, but is aware of its dimension and supports pretty printing and plotting.

barcode(diagram; infinity=nothing)

Plot the barcode plot or AbstractVector of diagrams. The infinity keyword argument determines where the infinity line is placed. If set to nothing the function tries to guess a good infinity poistion.

AbstractFiltration{T, V<:AbstractSimplex{0, T}}

A filtration is used to find the edges in filtration and to determine diameters of simplices.

T is the distance type, accessible by dist_type and S is the edge type, accesible by vertex_type.

Interface

• n_vertices(::AbstractFiltration)
• edges(::AbstractFiltration)
• diam(::AbstractFiltration, vs)
• diam(::AbstractFiltration, ::AbstractSimplex, ::Any, ::Any)
• birth(::AbstractFiltration, v) - optional, defaults to returning zero(T).

n_vertices(filtration::AbstractFiltration)

Return the number of vertices in filtration.

edges(filtration::AbstractFiltration)

Get edges in distance matrix in filtration, sorted by decresing length and increasing combinatorial index. Edges should be of type edge_type(filtration).

diam(flt::AbstractFiltration, vertices)

Get the diameter of list of vertices i.e. diameter of simplex with vertices.

diam(flt::AbstractFiltration, simplex, vertices, vertex)

Get the diameter of coface of simplex that is formed by adding vertex to vertices.

birth(::AbstractFiltration{T}, v)

Get the birth time of vertex v.

AbstractFlagFiltration{T, V} <: AbstractFiltration{T, V}

An abstract flag filtration is a filtration of flag complexes. Its subtypes can overload dist(::AbstractFlagFiltration{T}, u, v)::Union{T, Infinity} instead of diam. diam(::AbstractFlagFiltration, ...) defaults to maximum dist among vertices.

RipsFiltration{T, V<:AbstractSimplex{<:Any, T}} <: AbstractFlagFiltration{T, V}

This type represents a filtration of Vietoris-Rips complexes. Diagonal items are treated as vertex birth times.

Constructor

RipsFiltration(
    distance_matrix;
    threshold=default_rips_threshold(dist),
    vertex_type=Simplex{0, T, Int64},
)

SparseRipsFiltration{T, V<:AbstractSimplex{<:Any, T}} <: AbstractFlagFiltration{T, V}

This type represents a filtration of Vietoris-Rips complexes. The distance matrix will be converted to a sparse matrix with all values greater than threshold deleted. Off-diagonal zeros in the matrix are treated as ∞. Diagonal items are treated as vertex birth times.

Constructor

SparseRipsFiltration(
    distance_matrix;
    threshold=nothing,
    vertex_type=Simplex{0, T, Int64},
)

CubicalFiltration{T, N, V<:Cubelet{0, T}} <: AbstractFiltration{T, V}

A CubicalFiltration is used to compute sublevel persistent homology on N-dimensional images, which are of type AbstractArray{T, N}.

AbstractSimplex{D, T}

An abstract type for representing simplices. A simplex must have a diameter of type T, which is its birth time. The dimension must be encoded in the type as D and can be accessed by dim.

Interface

• AbstractSimplex{D}(::NTuple{D+1, <:Integer}, ::T)
• diam(::AbstractSimplex)
• Base.sign(::AbstractSimplex)
• Base.:-(::AbstractSimplex)
• Base.isless(::AbstractSimplex, ::AbstractSimplex)
• coface_type(::AbstractSimplex)
• vertices(::AbstractSimplex)
• coboundary(::Any, ::AbstractSimplex)

dim(::AbstractSimplex)
dim(::Type{<:AbstractSimplex})

Get the dimension of simplex i.e. the value of D.

dim(Simplex{2}((3, 2, 1), 3.2))

# output

2

diam(simplex::AbstractSimplex)

Get the diameter of simplex.

diam(Simplex{2}((3, 2, 1), 3.2))

# output

3.2

sign(simplex::AbstractSimplex)

Get the orientation of simplex. Returns -1 or 1.

sign(Simplex{2}((3, 2, 1), 3.2))

# output

+1

-(simplex::AbstractSimplex)

Reverse the simplex orientation.

-Simplex{2}((3, 2, 1), 3.2)

# output

2-dim Simplex(1, 1):
  -(3, 2, 1)

coface_type(::AbstractSimplex)
coface_type(::Type{<:AbstractSimplex})

Get the type of coface a simplex hax. For a D-dimensional simplex, this is usually its D+1-dimensional counterpart. Only the method for the type needs to be implemented.

coface_type(Simplex{2}((3, 2, 1), 3.2))

# output

Simplex{3, Float64, Int}

vertices(simplex::AbstractSimplex{dim})

Get the vertices of simplex. Returns NTuple{dim+1, Int}. In the algorithm, only the method for 2-simplices is actually used.

vertices(Simplex{2}((3, 2, 1), 3.2))

# output

(3, 2, 1)

coboundary(filtration, simplex[, Val{all_cofaces}])

Iterate over the coboundary of simplex. Use the filtration to determine the diameters and validity of cofaces. Iterates values of the type coface_type(simplex). If all_cofaces is false, only return cofaces with vertices added to the beginning of vertex list.

filtration = RipsFiltration([0 1 1 1; 1 0 1 1; 1 1 0 1; 1 1 1 0])

for c in coboundary(filtration, Simplex{1}(2, 1))
    println(c)
end

# output

Simplex{2}(+(4, 3, 1), 1)
Simplex{2}(-(3, 2, 1), 1)

for c in coboundary(filtration, Simplex{1}(2, 1), Val(false))
    println(c)
end

# output

Simplex{2}(+(4, 3, 1), 1)

IndexedSimplex{D, T, I<:Integer} <: AbstractSimplex{D, T}

A refinement of AbstractSimplex. An indexed simplex is represented by its dimension, diameter and combinatorial index. It does not need to hold information about its the vertices it includes, since they can be recomputed from the index and dimension.

By defining the index, a default implementation of sign, isless, vertices and coboundary is provided.

Interface

• IndexedSimplex{D[, T, I]}(index::I, diam::T) - constructor.
• IndexedSimplex{D[, T, I]}(vertices::NTuple{D+1, I}, diam::T) - constructor.
• diam(::AbstractSimplex)
• coface_type(::AbstractSimplex)
• index(::IndexedSimplex)

index(vertices)

Calculate the index from tuple of vertices. The index is equal to

where $i_k$ are the simplex vertex indices.

Simplex{D, T, I} <: IndexedSimplex{D, T, I}

The vanilla simplex type represented by dimension D and index of type I and a diameter of type T.

Constructor

Simplex{D[, T, I]}(::I, ::T)

Examples

```jldoctest julia> Simplex{2}(2, 1) 2-dim Simplex{2}(2, 1): +(4, 2, 1)

julia> Simplex{10}(Int128(-10), 1.0) 4-dim Simplex{3}(1.0, 10, 2) with UInt128 index: -(12, 11, 10, 9, 8, 7, 6, 5, 4, 2, 1) ˙

Cubelet{D, T, I} <: IndexedSimplex{D, T, I}

A Cubelet is similar to a Simplex, but it has 2^D vertices instead of D+1. Like in Simplex, the vertices are encoded from an index and dimension. Because a cubelet knows nothing about the image it came from, it returns linear indices from vertices.

The vertices should be neighboring indices, but this fact is not checked anywhere.