gram_matrix {TDApplied}

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

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.

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.

Value

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

Author(s)

Shael Brown - [e-mail]

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