ripsDiag {TDA}

Rips Persistence Diagram

Description

The function ripsDiag computes the persistence diagram of the Rips filtration built on top of a point cloud.

Usage

ripsDiag(
    X, maxdimension, maxscale, dist = "euclidean",
    library = "GUDHI", location = FALSE, printProgress = FALSE)

Arguments

X

If dist="euclidean", X is an n by d matrix of coordinates, where n is the number of points in the d-dimensional euclidean space. If dist="arbitrary", X is an n by n matrix of distances of n points.

maxdimension

integer: max dimension of the homological features to be computed. (e.g. 0 for connected components, 1 for connected components and loops, 2 for connected components, loops, voids, etc.) Currently there is a bug for computing homological features of dimension higher than 1 when the distance is arbitrary (dist = "arbitrary") and library 'GUDHI' is used (library = "GUDHI").

maxscale

number: maximum value of the rips filtration.

dist

"euclidean" for Euclidean distance, "arbitrary" for an arbitrary distance given in input as a distance matrix. Currently there is a bug for the arbitrary distance (dist = "arbitrary") when computing homological features of dimension higher than 1 and library 'GUDHI' is used (library = "GUDHI").

library

either a string or a vector of length two. When a vector is given, the first element specifies which library to compute the Rips filtration, and the second element specifies which library to compute the persistence diagram. If a string is used, then the same library is used. For computing the Rips filtration, if dist = "euclidean", the user can use either the library "GUDHI" or "Dionysus". If dist = "arbitrary", the user can use either the library "Dionysus". The default value is "GUDHI" if dist = "euclidean", and "Dionysus" if dist == "arbitrary". When "GUDHI" is used for dist = "arbitrary", "Dionysus" is implicitly used. For computing the persistence diagram, the user can choose either the library "GUDHI", "Dionysus", or "PHAT". The default value is "GUDHI". Currently there is a bug for 'GUDHI' (library = "GUDHI") when computing homological features of dimension higher than 1 and the distance is arbitrary (dist = "arbitrary").

location

if TRUE and if "Dionysus" or "PHAT" is used for computing the persistence diagram, 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

logical: if TRUE, a progress bar is printed. The default value is FALSE.

Details

For Rips filtration based on Euclidean distance of the input point cloud, the user can decide to use either the C++ library GUDHI or Dionysus. For Rips filtration based on arbitrary distance, the user can decide to the C++ library Dionysus. Then for computing the persistence diagram from the Rips filtration, the user can use either the C++ library GUDHI, Dionysus, or PHAT. Currently there is a bug for computing homological features of dimension higher than 1 when the distance is arbitrary (dist = "arbitrary") and library 'GUDHI' is used (library = "GUDHI"). See refereneces.

Value

The function ripsDiag returns a list with the following elements:

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 contains the dimension of each feature (0 for components, 1 for loops, 2 for voids, etc.). Second and third columns are Birth and Death of the features.

birthLocation

only if location=TRUE and if "Dionysus" or "PHAT" is used for computing the persistence diagram: if dist="euclidean", then birthLocation is a P by d matrix, where P is the number of points in the resulting persistence diagram. Each row represents the location of the data point completing the simplex that gives birth to an homological feature. If dist="arbitrary", then birthLocation is a vector of length P. Each row represents the index of the data point completing the simplex that gives birth to an homological feature.

deathLocation

only if location=TRUE and if "Dionysus" or "PHAT" is used for computing the persistence diagram: if dist="euclidean", then deathLocation is a P by d matrix, where P is the number of points in the resulting persistence diagram. Each row represents the location of the data point completing the simplex that kills an homological feature. If dist="arbitrary", then deathLocation is a vector of length P. Each row represents the index of the data point completing the simplex that kills an homological feature.

cycleLocation

only if location=TRUE and if "Dionysus" is used for computing the persistence diagram: if dist="euclidean", then cycleLocation is a list of length P, where P is the number of points in the resulting persistence diagram. Each element is a P_i by h_i +1 by d array for h_i dimensional homological feature. It represents location of h_i +1 vertices of P_i simplices, where P_i simplices constitutes the h_i dimensional homological feature. If dist = "arbitrary", then each element is a P_i by h_i +1 matrix for for h_i dimensional homological feature. It represents index of h_i +1 vertices of P_i simplices on a representative cycle of the h_i dimensional homological feature.

Author(s)

Brittany T. Fasy, Jisu Kim, Fabrizio Lecci, and Clement Maria

References

Maria C (2014). "GUDHI, Simplicial Complexes and Persistent Homology Packages." https://project.inria.fr/gudhi/software/.

Morozov D (2007). "Dionysus, a C++ library for computing persistent homology". https://www.mrzv.org/software/dionysus/

Edelsbrunner H, Harer J (2010). "Computational topology: an introduction." American Mathematical Society.

Fasy B, Lecci F, Rinaldo A, Wasserman L, Balakrishnan S, Singh A (2013). "Statistical Inference For Persistent Homology." (arXiv:1303.7117). Annals of Statistics.

See Also

summary.diagram, plot.diagram, gridDiag

Examples

## EXAMPLE 1: rips diagram for circles (euclidean distance)
X <- circleUnif(30)
maxscale <- 5
maxdimension <- 1
## note that the input X is a point cloud
DiagRips <- ripsDiag(
    X = X, maxdimension = maxdimension, maxscale = maxscale,
    library = "Dionysus", location = TRUE, printProgress = TRUE)

# plot
layout(matrix(c(1, 3, 2, 2), 2, 2))
plot(X, cex = 0.5, pch = 19)
title(main = "Data")
plot(DiagRips[["diagram"]])
title(main = "rips Diagram")
one <- which(
    DiagRips[["diagram"]][, 1] == 1 &
    DiagRips[["diagram"]][, 3] - DiagRips[["diagram"]][, 2] > 0.5)
plot(X, col = 2, main = "Representative loop of data points")
for (i in seq(along = one)) {
  for (j in seq_len(dim(DiagRips[["cycleLocation"]][[one[i]]])[1])) {
    lines(
	    DiagRips[["cycleLocation"]][[one[i]]][j, , ], pch = 19, cex = 1,
        col = i)
  }
}


## EXAMPLE 2: rips diagram with arbitrary distance
## distance matrix for triangle with edges of length: 1,2,4
distX <- matrix(c(0, 1, 2, 1, 0, 4, 2, 4, 0), ncol = 3)
maxscale <- 5
maxdimension <- 1
## note that the input distXX is a distance matrix
DiagTri <- ripsDiag(distX, maxdimension, maxscale, dist = "arbitrary",
                    printProgress = TRUE)
#points with lifetime = 0 are not shown. e.g. the loop of the triangle.
print(DiagTri[["diagram"]])