TDA (version 1.9.1)

alphaShapeDiag: Persistence Diagram of Alpha Shape in 3d

Description

The function alphaShapeDiag computes the persistence diagram of the alpha shape filtration built on top of a point cloud in 3 dimension.

Usage

alphaShapeDiag(
    X, maxdimension = NCOL(X) - 1, library = "GUDHI", location = FALSE,
    printProgress = FALSE)

Value

The function alphaShapeDiag 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 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 the features.

birthLocation

only if location=TRUE and if "Dionysus" or "PHAT" is used for computing the persistence diagram: 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 and if "Dionysus" or "PHAT" is used for computing the persistence diagram: 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 if "Dionysus" is used for computing the persistence diagram: 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.

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. Currently \(d\) should be 3.

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.)

library

either a string or a vector of length two. When a vector is given, the first element specifies which library to compute the Alpha Shape 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 Alpha Shape filtration, the user can use the library "GUDHI", and is also the default value. For computing the persistence diagram, the user can choose either the library "GUDHI", "Dionysus", or "PHAT". The default value is "GUDHI".

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. The default value is FALSE.

printProgress

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

Author

Jisu Kim and Vincent Rouvreau

Details

The function alphaShapeDiag constructs the Alpha Shape filtration, using the C++ library GUDHI. Then for computing the persistence diagram from the Alpha Shape filtration, the user can use either the C++ library GUDHI, Dionysus, or PHAT. See refereneces.

References

Fischer K (2005). "Introduction to Alpha Shapes."

Edelsbrunner H, Mucke EP (1994). "Three-dimensional Alpha Shapes." ACM Trans. Graph.

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

Morozov D (2008). "Homological Illusions of Persistence and Stability."

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

See Also

summary.diagram, plot.diagram, alphaComplexDiag, gridDiag, ripsDiag

Examples

# input data generated from cylinder
n <- 30
X <- cbind(circleUnif(n = n), runif(n = n, min = -0.1, max = 0.1))

# persistence diagram of alpha shape
DiagAlphaShape <- alphaShapeDiag(
    X = X, maxdimension = 1, library = c("GUDHI", "Dionysus"), location = TRUE,
    printProgress = TRUE)

# plot diagram and first two dimension of data
par(mfrow = c(1, 2))
plot(DiagAlphaShape[["diagram"]])
plot(X[, 1:2], col = 2, main = "Representative loop of alpha shape filtration")
one <- which(DiagAlphaShape[["diagram"]][, 1] == 1)
one <- one[which.max(
    DiagAlphaShape[["diagram"]][one, 3] - DiagAlphaShape[["diagram"]][one, 2])]
for (i in seq(along = one)) {
  for (j in seq_len(dim(DiagAlphaShape[["cycleLocation"]][[one[i]]])[1])) {
    lines(
        DiagAlphaShape[["cycleLocation"]][[one[i]]][j, , 1:2], pch = 19,
        cex = 1, col = i)
  }
}
par(mfrow = c(1, 1))