TDA (version 1.0)

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 dimension $d=$1, 2 or 3.

Usage

gridDiag(X, FUN, Xlim, Ylim = NA, Zlim = NA, by=(Xlim[2]-Xlim[1])/20, 
         sublevel = TRUE, printStatus = 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 (1, 2 or 3).

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

Xlim

a numeric vector of length 2, specifying the range of the first dimension of the grid, over which the function FUN is evaluated.

Ylim

a numeric vector of length 2, specifying the range of the second dimension of the grid, over which the function FUN is evaluated. NA for a 1 dimensional grid.

Zlim

a numeric vector of length 2, specifying the range of the third dimension of the grid, over which the function FUN is evaluated. NA for a 1 dimensional or 2 dimensional grid.

by

number: space between points of the grid in each dimension.

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.

printStatus

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 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 contains the dimension of each feature (0 for components, 1 for loops, 2 for voids). Second and third columns are Birth and Death of features, in case of a filtration constructed using sublevel sets, or Death and Birth of features, in case of a filtration constructed using superlevel sets.

Details

The function 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.

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.

http://www.mrzv.org/software/dionysus/

See Also

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

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)
by=0.05

h = .3  #bandwidth for the function kde

#Distance Function Diagram of the sublevel sets
Diag1=gridDiag(XX,distFct, Xlim, Ylim, by=by, sublevel=TRUE, printStatus=TRUE) 

#Kernel Density Diagram of the superlevel sets
Diag2=gridDiag(XX, kde, Xlim, Ylim, by=by, sublevel=FALSE, printStatus=TRUE, h=h) 

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