TDA (version 1.3)

gridDiag: Persistence Diagram of a function over a Grid

Description

gridDiag computes the Persistence Diagram of a filtration of sublevel sets (or superlevel sets) of a function evaluated over a grid of points in arbitrary dimension d.

Usage

gridDiag(X, FUN, lim, by, maxdimension=length(lim)/2-1, sublevel = TRUE,
         library="Dionysus", location = FALSE, printProgress = FALSE, diagLimit=NULL, ...)

Arguments

X

an $n$ by $d$ matrix of coordinates, used by the function FUN, where $n$ is the number of points stored in X and $d$ is the dimension of the space.

FUN

a function whose inputs are 1) an $n$ by $d$ matrix of coordinates X, 2) an $m$ by $d$ matrix of coordinates Grid, 3) an optional smoothing parameter, and returns a numeric vector of length $m$. For example see

lim

a $2$ by $d$ matrix, where each column specifying the range of each dimension of the grid, over which the function FUN is evaluated.

by

either a number or a vector of length $d$ specifying space between points of the grid in each dimension. If a number is given, then same space is used in each dimension.

maxdimension

a number that indicates the maximum dimension of the homological features to compute: 0 for connected components, 1 for loops, 2 for voids and so on. Default is $d-1$, which is (dimension of embedding space - 1).

sublevel

a logical variable indicating if the Persistence Diagram should be computed for sublevel sets (TRUE) or superlevel sets (FALSE) of the function. Default is TRUE.

library

The user can compute the persistence diagram using either the library 'Dionysus', or 'PHAT'. Default is 'Dionysus'.

location

if TRUE, location of birth point and death point of each homological feature is returned. Additionaly if library="Dionysus", location of representative cycles of each homological feature is also returned.

printProgress

if TRUE a progress bar is printed. Default is FALSE.

diagLimit

a number that replaces Inf (if sublevel is TRUE) or -Inf (if sublevel is FALSE) in the Death value of the most persistent connected component. Deafult is NULL and t

...

additional parameters for the function FUN.

Value

• gridDiag returns a list with the following components:
• diagram
  an object of class diagram, a $P$ by 3 matrix, where $P$ is the number of points in the resulting persistence diagram. The first column stores the dimension of each feature (0 for components, 1 for loops, 2 for voids, etc). Second and third columns are Birth and Death of features, in case of a filtration constructed using sublevel sets (from -Inf to Inf), or Death and Birth of features, in case of a filtration constructed using superlevel sets (from Inf to -Inf).
• birthLocation
  only if location=TRUE: a $P$ by $d$ matrix, where $P$ is the number of points in the resulting persistence diagram. Each row represents the location of the grid point completing the simplex that gives birth to an homological feature.
• deathLocation
  only if location=TRUE: a $P$ by $d$ matrix, where $P$ is the number of points in the resulting persistence diagram. Each row represents the location of the grid point completing the simplex that kills an homological feature.
• cycleLocation
  only if location=TRUE and library="Dionysus": a list of length $P$, where $P$ is the number of points in the resulting persistence diagram. Each element is a $P_i$ by $d$ matrix and represents location of $P_i$ grid points on a representative cycle of each homological feature.

Details

gridDiag evaluates the function FUN over a grid. Then it constructs a filtration by triangulating the grid and considering the simplices determined by the values of the function of dimension up to maxdimension+1.

References

Brittany Fasy, Fabrizio Lecci, Alessandro Rinaldo, Larry Wasserman, Sivaraman Balakrishnan, and Aarti Singh. (2013), "Statistical Inference For Persistent Homology", (arXiv:1303.7117). To appear, Annals of Statistics. Dmitriy Morozov, "Dionysus, a C++ library for computing persistent homology". http://www.mrzv.org/software/dionysus/ Ulrich Bauer, Michael Kerber, Jan Reininghaus, "PHAT, a software library for persistent homology". https://code.google.com/p/phat/

See Also

summary.diagram, plot.diagram, distFct, kde, kernelDist, dtm, ripsDiag

Examples

## Distance Function Diagram and Kernel Density Diagram

# input data
n = 300
XX = circleUnif(n)

## Ranges of the grid
Xlim=c(-1.8,1.8)
Ylim=c(-1.6,1.6)
lim=cbind(Xlim, Ylim)
by=0.05

h = .3  #bandwidth for the function kde

#Distance Function Diagram of the sublevel sets
Diag1=gridDiag(XX,distFct, lim=lim, by=by, sublevel=TRUE, printProgress=TRUE) 

#Kernel Density Diagram of the superlevel sets
Diag2=gridDiag(XX, kde, lim=lim, by=by, sublevel=FALSE, location=TRUE, printProgress=TRUE, h=h) 

#plot
par(mfrow=c(2,2))
plot(XX,cex=0.5, pch=19)
title(main="Data")
plot(Diag1$diagram)
title(main="Distance Function Diagram")
plot(Diag2$diagram)
title(main="Density Persistence Diagram")

one=which(Diag2$diag[,1]==1)
plot(XX, col=2, main="Representative loop of grid points")
for (i in 1:length(one))
{
	points(Diag2$birth[one[i],], pch=15, cex=3, col=i)
	points(Diag2$death[one[i],], pch=17, cex=3, col=i)
	points(Diag2$cycleLocation[[one[i]]], pch=19, cex=1, col=i)
}