ripsDiag: 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)

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.

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.

Author

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

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.

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.

Examples

Run this code

## 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"]])

Run the code above in your browser using DataLab