Compute the Frechet Mean

This function computes the Frechet mean of a sample using an iterative algorithm with optional parallel processing.

Usage

compute_frechet_mean(
  sample,
  tol = 0.05,
  max_iter = 20,
  lr = 0.2,
  batch_size = 32,
  progress = FALSE
)

Arguments

sample

An object of class CSample containing the sample data.

tol

A numeric value specifying the tolerance for convergence. Default is 0.05.

max_iter

An integer specifying the maximum number of iterations. Default is 20.

lr

A numeric value specifying the learning rate. Default is 0.2.

batch_size

Integer. The number of samples to process in each batch during computation. Default is 32.

progress

Logical indicating whether to show progress during computation (default: FALSE). Requires progressr package.

Value

The computed Frechet mean as a dppMatrix object.

Details

The function iteratively updates the reference point of the sample until the change in the reference point is less than the specified tolerance or the maximum number of iterations is reached. If the tangent images are not already computed, they will be computed before starting the iterations.

When parallel processing is enabled (via set_parallel_plan()), the relocate() function will use parallel processing for relocating tangent images in each iteration, which can significantly speed up computation for large samples.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {
  library(Matrix)
  # Load the AIRM metric object
  data(airm)
  # Create a CSample object with example data
  conns <- list(
    diag(2) |> Matrix::nearPD() |> _$mat |> Matrix::pack(),
    diag(c(2, 3)) |> Matrix::nearPD() |> _$mat |> Matrix::pack()
  )
  sample <- CSample$new(conns = conns, metric_obj = airm)
  # Compute the Frechet mean
  compute_frechet_mean(sample, tol = 0.01, max_iter = 50, lr = 0.1)
}
#> tangent images were null, so they will be computed
#> Computing Frechet mean: iteration 1, delta = Inf
#> Computing Frechet mean: iteration 2, delta = 0.943136
#> Computing Frechet mean: iteration 3, delta = 0.455681
#> Computing Frechet mean: iteration 4, delta = 0.292678
#> Computing Frechet mean: iteration 5, delta = 0.210897
#> Computing Frechet mean: iteration 6, delta = 0.161684
#> Computing Frechet mean: iteration 7, delta = 0.128813
#> Computing Frechet mean: iteration 8, delta = 0.105322
#> Computing Frechet mean: iteration 9, delta = 0.087727
#> Computing Frechet mean: iteration 10, delta = 0.074086
#> Computing Frechet mean: iteration 11, delta = 0.063233
#> Computing Frechet mean: iteration 12, delta = 0.054421
#> Computing Frechet mean: iteration 13, delta = 0.047151
#> Computing Frechet mean: iteration 14, delta = 0.041075
#> Computing Frechet mean: iteration 15, delta = 0.035942
#> Computing Frechet mean: iteration 16, delta = 0.031569
#> Computing Frechet mean: iteration 17, delta = 0.027815
#> Computing Frechet mean: iteration 18, delta = 0.024573
#> Computing Frechet mean: iteration 19, delta = 0.021758
#> Computing Frechet mean: iteration 20, delta = 0.019303
#> Computing Frechet mean: iteration 21, delta = 0.017154
#> Computing Frechet mean: iteration 22, delta = 0.015267
#> Computing Frechet mean: iteration 23, delta = 0.013605
#> Computing Frechet mean: iteration 24, delta = 0.012137
#> Computing Frechet mean: iteration 25, delta = 0.010838
#> Computing Frechet mean: iteration 26, delta = 0.009687
#> 2 x 2 Matrix of class "dppMatrix"
#>          [,1]     [,2]
#> [1,] 1.382898 0.000000
#> [2,] 0.000000 1.671656