TDApplied (version 3.0.3)

gram_matrix: Compute the gram matrix for a group of persistence diagrams.

Description

Calculate the Gram matrix \(K\) for either a single list of persistence diagrams \((D_1,D_2,\dots,D_n)\), i.e. \(K[i,j] = k_{PF}(D_i,D_j)\), or between two lists of persistence diagrams, \((D_1,D_2,\dots,D_n)\) and \((D'_1,D'_2,\dots,D'_n)\), \(K[i,j] = k_{PF}(D_i,D'_j)\), in parallel.

Usage

gram_matrix(
  diagrams,
  other_diagrams = NULL,
  dim = 0,
  sigma = 1,
  t = 1,
  rho = NULL,
  num_workers = parallelly::availableCores(omit = 1)
)

Value

the numeric (cross) Gram matrix of class 'kernelMatrix'.

Arguments

diagrams

a list of persistence diagrams, where each diagram is either the output of a persistent homology calculation like ripsDiag/calculate_homology/PyH, or diagram_to_df.

other_diagrams

either NULL (default) or another list of persistence diagrams to compute a cross-Gram matrix.

dim

the non-negative integer homological dimension in which the distance is to be computed, default 0.

sigma

a positive number representing the bandwidth for the Fisher information metric, default 1.

t

a positive number representing the scale for the kernel, default 1.

rho

an optional positive number representing the heuristic for Fisher information metric approximation, see diagram_distance. Default NULL. If supplied, code execution is sequential, but functions in the "exec" directory of the package can be loaded to calculate distance matrices in parallel with approximation.

num_workers

the number of cores used for parallel computation, default is one less than the number of cores on the machine.

Author

Shael Brown -

Details

Gram matrices are used in downstream analyses, like in the `diagram_kkmeans`, `diagram_nearest_cluster`,`diagram_kpca`, `predict_diagram_kpca`, `predict_diagram_ksvm` and `independence_test` functions.

See Also

diagram_kernel for individual persistence Fisher kernel calculations.

Examples

if(require("TDAstats"))
{
  # create two diagrams
  D1 <- TDAstats::calculate_homology(TDAstats::circle2d[sample(1:100,20),],
                      dim = 1,threshold = 2)
  D2 <- TDAstats::calculate_homology(TDAstats::circle2d[sample(1:100,20),],
                      dim = 1,threshold = 2)
  g <- list(D1,D2)

  # calculate the Gram matrix in dimension 0 with sigma = 2, t = 2
  G <- gram_matrix(diagrams = g,dim = 0,sigma = 2,t = 2,num_workers = 2)

  # calculate cross-Gram matrix, which is the same as G
  G_cross <- gram_matrix(diagrams = g,other_diagrams = g,dim = 0,sigma = 2,
                         t = 2,num_workers = 2)
}