Movatterモバイル変換

Title:	Riemannian Metrics for Symmetric Positive Definite Matrices
Version:	0.2.5
Description:	Implements various Riemannian metrics for symmetric positive definite matrices, including AIRM (Affine Invariant Riemannian Metric, <doi:10.1007/s11263-005-3222-z>), Log-Euclidean (<doi:10.1002/mrm.20965>), Euclidean, Log-Cholesky (<doi:10.1137/18M1221084>), and Bures-Wasserstein metrics (<doi:10.1016/j.exmath.2018.01.002>). Provides functions for computing logarithmic and exponential maps, vectorization, and statistical operations on the manifold of positive definite matrices.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
LinkingTo:	Rcpp, RcppEigen
Depends:	R (≥ 4.3.0)
Imports:	arrow, future, furrr, jsonlite, Matrix, methods, R6, purrr,MASS, matrixStats, Rcpp (≥ 1.0.0)
Suggests:	progressr, testthat (≥ 3.0.0), knitr, rmarkdown
VignetteBuilder:	knitr
URL:	https://nicoesve.github.io/riemtan/
BugReports:	https://github.com/nicoesve/riemtan/issues
Config/testthat/edition:	3
Maintainer:	Nicolas Escobar <nescoba@iu.edu>
NeedsCompilation:	yes
Packaged:	2025-11-10 20:46:26 UTC; new user
Author:	Nicolas Escobar [aut, cre], Jaroslaw Harezlak [ths]
Repository:	CRAN
Date/Publication:	2025-11-10 21:20:02 UTC

riemtan: Riemannian Metrics for Symmetric Positive Definite Matrices

Description

Implements various Riemannian metrics for symmetric positive definite matrices, including AIRM (Affine Invariant Riemannian Metric,doi:10.1007/s11263-005-3222-z), Log-Euclidean (doi:10.1002/mrm.20965), Euclidean, Log-Cholesky (doi:10.1137/18M1221084), and Bures-Wasserstein metrics (doi:10.1016/j.exmath.2018.01.002). Provides functions for computing logarithmic and exponential maps, vectorization, and statistical operations on the manifold of positive definite matrices.

Author(s)

Maintainer: Nicolas Escobarnescoba@iu.edu (ORCID)

Other contributors:

• Jaroslaw Harezlak [thesis advisor]

See Also

Useful links:

• https://nicoesve.github.io/riemtan/

• Report bugs athttps://github.com/nicoesve/riemtan/issues

CSample Class

Description

This class represents a sample of connectomes, with various properties and methods to handle their tangent and vectorized images.

Active bindings

Methods

Public methods

• CSample$new()

• CSample$load_connectomes_batched()

• CSample$compute_tangents()

• CSample$compute_conns()

• CSample$compute_vecs()

• CSample$compute_unvecs()

• CSample$compute_fmean()

• CSample$change_ref_pt()

• CSample$center()

• CSample$compute_variation()

• CSample$compute_dists()

• CSample$compute_sample_cov()

• CSample$clone()

Methodnew()

Initialize a CSample object

Usage

CSample$new(  conns = NULL,  tan_imgs = NULL,  vec_imgs = NULL,  centered = NULL,  ref_pt = NULL,  metric_obj,  batch_size = NULL,  backend = NULL)

Arguments

Returns

A newCSample object.

Methodload_connectomes_batched()

Load connectomes in parallel batches from ParquetBackend.This method is particularly useful for large Parquet-backed datasetswhere loading all matrices at once would be memory-prohibitive.

Usage

CSample$load_connectomes_batched(  indices = NULL,  batch_size = 50,  progress = FALSE)

Arguments

Details

This method only works when the CSample was initialized with a ParquetBackend.It loads matrices in parallel batches, clearing the cache between batches tomanage memory usage. Sequential loading is used for ListBackend.

Returns

A list of dppMatrix objects.

Examples

\dontrun{# Create CSample with ParquetBackendbackend <- create_parquet_backend("my_data")sample <- CSample$new(backend = backend, metric_obj = airm)# Load first 100 matrices in batches of 20conns <- sample$load_connectomes_batched(indices = 1:100, batch_size = 20)}

Methodcompute_tangents()

This function computes the tangent images from the connectomes.

Usage

CSample$compute_tangents(ref_pt = default_ref_pt(private$p), progress = FALSE)

Arguments

Details

Error ifref_pt is not adppMatrix object or ifconns is not specified.

Returns

None

Methodcompute_conns()

This function computes the connectomes from the tangent images.

Usage

CSample$compute_conns(progress = FALSE)

Arguments

Details

Error if tangent images are not specified.

Returns

None

Methodcompute_vecs()

This function computes the vectorized tangent images from the tangent images.

Usage

CSample$compute_vecs(progress = FALSE)

Arguments

Details

Error if tangent images are not specified.

Returns

None

Methodcompute_unvecs()

This function computes the tangent images from the vector images.

Usage

CSample$compute_unvecs(progress = FALSE)

Arguments

Details

Error ifvec_imgs is not specified.

Returns

None

Methodcompute_fmean()

This function computes the Frechet mean of the sample.

Usage

CSample$compute_fmean(  tol = 0.001,  max_iter = 100,  lr = 0.2,  batch_size = NULL,  progress = FALSE)

Arguments

Returns

None

Methodchange_ref_pt()

This function changes the reference point for the tangent images.

Usage

CSample$change_ref_pt(new_ref_pt, progress = FALSE)

Arguments

Details

Error if tangent images have not been computed or ifnew_ref_pt is not adppMatrix object.

Returns

None

Methodcenter()

Center the sample

Usage

CSample$center()

Details

This function centers the sample by computing the Frechet mean if it is not already computed, and then changing the reference point to the computed Frechet mean. Error if tangent images are not specified. Error if the sample is already centered.

Returns

None. This function is called for its side effects.

Methodcompute_variation()

Compute Variation

Usage

CSample$compute_variation()

Details

This function computes the variation of the sample. It first checks if the vector images are null, and if so, it computes the vectors, computing first the tangent images if necessary. If the sample is not centered, it centers the sample and recomputes the vectors. Finally, it calculates the variation as the mean of the sum of squares of the vector images. Error ifvec_imgs is not specified.

Returns

None. This function is called for its side effects.

Methodcompute_dists()

Compute distances

Usage

CSample$compute_dists()

Details

This function computes the distances of the elements of the sample to the Frechet mean. It first checks if the vector images are null, and if so, it computes the vectors, computing first the tangent images if necessary. If the sample is not centered, it centers the sample and recomputes the vectors. Finally, it calculates the distances as the Euclidean norms of the vector images. Error ifvec_imgs is not specified.

Returns

None. This function is called for its side effects.

Methodcompute_sample_cov()

Compute Sample Covariance

Usage

CSample$compute_sample_cov()

Details

This function computes the sample covariance matrix for the vector images. It first checks if the vector images are null, and if so, it computes the vectors, computing first the tangent images if necessary.

Returns

None. This function is called for its side effects.

Methodclone()

The objects of this class are cloneable with this method.

Usage

CSample$clone(deep = FALSE)

Arguments

Examples

## ------------------------------------------------## Method `CSample$load_connectomes_batched`## ------------------------------------------------## Not run: # Create CSample with ParquetBackendbackend <- create_parquet_backend("my_data")sample <- CSample$new(backend = backend, metric_obj = airm)# Load first 100 matrices in batches of 20conns <- sample$load_connectomes_batched(indices = 1:100, batch_size = 20)## End(Not run)

CSuperSample Class

Description

This class represents a collection of CSample objects (samples of connectomes), providing methods to aggregate, analyze, and compute statistics across multiple samples sharing the same Riemannian metric.

Active bindings

Methods

Public methods

• CSuperSample$new()

• CSuperSample$compute_variation()

• CSuperSample$compute_sample_cov()

• CSuperSample$gather()

• CSuperSample$compute_fmean()

• CSuperSample$compute_W()

• CSuperSample$compute_T()

• CSuperSample$clone()

Methodnew()

Initialize a CSuperSample object

Usage

CSuperSample$new(samples)

Arguments

Returns

A newCSuperSample object.

Methodcompute_variation()

Compute the total variation of the aggregated sample.

Usage

CSuperSample$compute_variation()

Returns

None. This function is called for its side effects. The result is stored in thevariation active binding.

Methodcompute_sample_cov()

Compute the sample covariance matrix of the aggregated sample.

Usage

CSuperSample$compute_sample_cov()

Returns

None. This function is called for its side effects. The result is stored in thesample_cov active binding.

Methodgather()

Gather all connectomes from the list of samples into a single CSample object.

Usage

CSuperSample$gather()

Returns

None. This function is called for its side effects. The result is stored in thefull_sample active binding.

Methodcompute_fmean()

Compute the Frechet mean of the aggregated sample.

Usage

CSuperSample$compute_fmean(batch_size = NULL)

Arguments

Returns

None. This function is called for its side effects. The result is stored in thefrechet_mean active binding.

Methodcompute_W()

Compute the within-group covariance matrix (W) for the samples.

Usage

CSuperSample$compute_W()

Returns

None. This function is called for its side effects. The result is stored in theWithin active binding.

Methodcompute_T()

Compute the total covariance matrix (T) for the samples.

Usage

CSuperSample$compute_T()

Returns

None. This function is called for its side effects. The result is stored in theTotal active binding.

Methodclone()

The objects of this class are cloneable with this method.

Usage

CSuperSample$clone(deep = FALSE)

Arguments

DataBackend Abstract Class

Description

Abstract base class defining the interface for storage backends.All backend implementations must inherit from this class and implementthe required methods.

Details

This class provides a common interface for different storage strategies:

• ListBackend: In-memory list storage (current default)

• ParquetBackend: Lazy-loaded Parquet files with LRU cache

Methods

Public methods

• DataBackend$get_matrix()

• DataBackend$get_all_matrices()

• DataBackend$length()

• DataBackend$get_dimensions()

• DataBackend$clone()

Methodget_matrix()

Get a specific matrix by index

Usage

DataBackend$get_matrix(i)

Arguments

Returns

A dppMatrix object

Methodget_all_matrices()

Get all matrices

Usage

DataBackend$get_all_matrices()

Returns

A list of dppMatrix objects

Methodlength()

Get the number of matrices

Usage

DataBackend$length()

Returns

Integer count of matrices

Methodget_dimensions()

Get matrix dimensions

Usage

DataBackend$get_dimensions()

Returns

Integer dimension (p) where matrices are p x p

Methodclone()

The objects of this class are cloneable with this method.

Usage

DataBackend$clone(deep = FALSE)

Arguments

ListBackend Class

Description

Backend implementation using in-memory list storage.This wraps the existing list-based storage mechanism for backwards compatibility.

Super class

riemtan::DataBackend ->ListBackend

Methods

Public methods

• ListBackend$new()

• ListBackend$get_matrix()

• ListBackend$get_all_matrices()

• ListBackend$length()

• ListBackend$get_dimensions()

• ListBackend$clone()

Methodnew()

Initialize a ListBackend

Usage

ListBackend$new(matrices)

Arguments

Methodget_matrix()

Get a specific matrix by index

Usage

ListBackend$get_matrix(i)

Arguments

Returns

A dppMatrix object

Methodget_all_matrices()

Get all matrices

Usage

ListBackend$get_all_matrices()

Returns

A list of dppMatrix objects

Methodlength()

Get the number of matrices

Usage

ListBackend$length()

Returns

Integer count

Methodget_dimensions()

Get matrix dimensions

Usage

ListBackend$get_dimensions()

Returns

Integer p (matrices are p x p)

Methodclone()

The objects of this class are cloneable with this method.

Usage

ListBackend$clone(deep = FALSE)

Arguments

ParquetBackend Class

Description

Backend implementation using Apache Arrow Parquet files with lazy loading.Matrices are stored as individual Parquet files and loaded on-demand with LRU caching.

Super class

riemtan::DataBackend ->ParquetBackend

Methods

Public methods

• ParquetBackend$new()

• ParquetBackend$get_matrix()

• ParquetBackend$get_all_matrices()

• ParquetBackend$get_matrices_parallel()

• ParquetBackend$length()

• ParquetBackend$get_dimensions()

• ParquetBackend$get_metadata()

• ParquetBackend$clear_cache()

• ParquetBackend$get_cache_size()

• ParquetBackend$clone()

Methodnew()

Load metadata from JSON file

Load a matrix from Parquet file

Update LRU cache with a new matrix

Initialize a ParquetBackend

Usage

ParquetBackend$new(data_dir, cache_size = 10)

Arguments

Returns

A dppMatrix object

Methodget_matrix()

Get a specific matrix by index

Usage

ParquetBackend$get_matrix(i)

Arguments

Returns

A dppMatrix object

Methodget_all_matrices()

Get all matrices (loads all from disk if necessary)

Usage

ParquetBackend$get_all_matrices(parallel = NULL, progress = FALSE)

Arguments

Returns

A list of dppMatrix objects

Methodget_matrices_parallel()

Load multiple matrices in parallel (batch loading)

Usage

ParquetBackend$get_matrices_parallel(indices, progress = FALSE)

Arguments

Returns

A list of dppMatrix objects

Methodlength()

Get the number of matrices

Usage

ParquetBackend$length()

Returns

Integer count

Methodget_dimensions()

Get matrix dimensions

Usage

ParquetBackend$get_dimensions()

Returns

Integer p (matrices are p x p)

Methodget_metadata()

Get metadata

Usage

ParquetBackend$get_metadata()

Returns

List containing metadata information

Methodclear_cache()

Clear the cache

Usage

ParquetBackend$clear_cache()

Methodget_cache_size()

Get current cache size

Usage

ParquetBackend$get_cache_size()

Returns

Integer number of cached matrices

Methodclone()

The objects of this class are cloneable with this method.

Usage

ParquetBackend$clone(deep = FALSE)

Arguments

TangentImageHandler Class

Description

TangentImageHandler Class

TangentImageHandler Class

Details

This class handles tangent images on a manifold. It provides methods to set a reference point, compute tangents, and perform various operations using a provided metric.Initialize the TangentImageHandler

Error if the tangent images have not been specified

Error if the reference point is not an object of class dppMatrix

Error if the matrix is not of type dspMatrixTangent images getter

Active bindings

Methods

Public methods

• TangentImageHandler$new()

• TangentImageHandler$set_reference_point()

• TangentImageHandler$compute_tangents()

• TangentImageHandler$compute_vecs()

• TangentImageHandler$compute_conns()

• TangentImageHandler$set_tangent_images()

• TangentImageHandler$add_tangent_image()

• TangentImageHandler$get_tangent_images()

• TangentImageHandler$relocate_tangents()

• TangentImageHandler$clone()

Methodnew()

Usage

TangentImageHandler$new(metric_obj, reference_point = NULL)

Arguments

Returns

A new instance of TangentImageHandler.Set a new reference point.

Methodset_reference_point()

If tangent images have been created, it recomputes them by mapping to the manifold and then to the new tangent space.

Usage

TangentImageHandler$set_reference_point(new_ref_pt, progress = FALSE)

Arguments

Returns

None.Computes the tangent images from the points in the manifold

Methodcompute_tangents()

Usage

TangentImageHandler$compute_tangents(manifold_points, progress = FALSE)

Arguments

Returns

NoneComputes vectorizations from tangent images

Methodcompute_vecs()

Usage

TangentImageHandler$compute_vecs(progress = FALSE)

Arguments

Returns

A matrix, each row of which is a vectorizationComputes connectomes from tangent images

Methodcompute_conns()

Usage

TangentImageHandler$compute_conns(progress = FALSE)

Arguments

Returns

A list of connectomesSetter for the tangent images

Methodset_tangent_images()

Usage

TangentImageHandler$set_tangent_images(reference_point, tangent_images)

Arguments

Returns

NoneAppends a matrix to the list of tangent images

Methodadd_tangent_image()

Usage

TangentImageHandler$add_tangent_image(image)

Arguments

Methodget_tangent_images()

Usage

TangentImageHandler$get_tangent_images()

Returns

list of tangent matricesWrapper for set_reference_point

Methodrelocate_tangents()

Usage

TangentImageHandler$relocate_tangents(new_ref_pt, progress = FALSE)

Arguments

Returns

None

Methodclone()

The objects of this class are cloneable with this method.

Usage

TangentImageHandler$clone(deep = FALSE)

Arguments

Compute the AIRM Exponential

Description

This function computes the Riemannian exponential map for the Affine-Invariant Riemannian Metric (AIRM).

Usage

airm_exp(sigma, v, validate = FALSE)

Arguments

Value

A symmetric positive-definite matrix of classdppMatrix.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {  library(Matrix)  sigma <- diag(2) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  v <- diag(c(1, 0.5)) |>    Matrix::symmpart() |>    Matrix::pack()  airm_exp(sigma, v)}

Compute the AIRM Logarithm

Description

This function computes the Riemannian logarithmic map for the Affine-Invariant Riemannian Metric (AIRM).

Usage

airm_log(sigma, lambda, validate = FALSE)

Arguments

Value

A symmetric matrix of classdspMatrix, representing the tangent space image oflambda atsigma.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {  library(Matrix)  sigma <- diag(2) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  lambda <- diag(c(2, 3)) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  airm_log(sigma, lambda)}

Compute the Inverse Vectorization (AIRM)

Description

Converts a vector back into a tangent matrix relative to a reference point using AIRM.

Usage

airm_unvec(sigma, w)

Arguments

Value

A symmetric matrix of classdspMatrix, representing the tangent vector.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {  library(Matrix)  sigma <- diag(2) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  w <- c(1, sqrt(2), 2)  airm_unvec(sigma, w)}

Compute the AIRM Vectorization of Tangent Space

Description

Vectorizes a tangent matrix into a vector in Euclidean space using AIRM.

Usage

airm_vec(sigma, v)

Arguments

Value

A numeric vector, representing the vectorized tangent image.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {  library(Matrix)  sigma <- diag(2) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  v <- diag(c(1, 0.5)) |>    Matrix::symmpart() |>    Matrix::pack()  airm_vec(sigma, v)}

Compute the Bures-Wasserstein Exponential

Description

This function computes the Riemannian exponential map using the Bures-Wasserstein metric for symmetric positive-definite matrices. The map operates by solving a Lyapunov equation and then constructing the exponential.

Usage

bures_wasserstein_exp(sigma, v, validate = FALSE)

Arguments

Value

A symmetric positive-definite matrix of classdppMatrix, representing the point on the manifold.

Compute the Bures-Wasserstein Logarithm

Description

This function computes the Riemannian logarithmic map using the Bures-Wasserstein metric for symmetric positive-definite matrices.

Usage

bures_wasserstein_log(sigma, lambda, validate = FALSE)

Arguments

Value

A symmetric matrix of classdspMatrix, representing the tangent space image oflambda atsigma.

Compute the Bures-Wasserstein Inverse Vectorization

Description

Compute the Bures-Wasserstein Inverse Vectorization

Usage

bures_wasserstein_unvec(sigma, w)

Arguments

Value

A symmetric matrix of classdspMatrix

Compute the Bures-Wasserstein Vectorization

Description

Compute the Bures-Wasserstein Vectorization

Usage

bures_wasserstein_vec(sigma, v)

Arguments

Value

A numeric vector representing the vectorized tangent image

Compute the Frechet Mean

Description

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

Details

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

When parallel processing is enabled (viaset_parallel_plan()), therelocate() function will use parallelprocessing for relocating tangent images in each iteration, which can significantly speed up computationfor large samples.

Value

The computed Frechet mean as a dppMatrix object.

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

Configure Progress Handlers

Description

Convenience function to configure progressr handlers for the current session.

Usage

configure_progress(handler = "txtprogressbar", ...)

Arguments

Details

This is a convenience wrapper aroundprogressr::handlers().If progressr is not available, a warning is issued and the function returns NULL.

Value

Invisibly returns the configured handlers (viaprogressr::handlers()).

See Also

progressr::handlers()

Examples

## Not run: # Use base R text progress barconfigure_progress("txtprogressbar")# Use cli style (if cli package is installed)configure_progress("cli")# Disable progress reportingconfigure_progress("none")## End(Not run)

Create ParquetBackend from Directory

Description

Convenience function to create a ParquetBackend from a validated directory.

Usage

create_parquet_backend(data_dir, cache_size = 10, validate = TRUE)

Arguments

Value

A ParquetBackend object

Examples

## Not run: backend <- create_parquet_backend("my_connectomes")sample <- CSample$new(backend = backend, metric_obj = airm())## End(Not run)

Create a Progress Reporter for Iterative Operations

Description

Creates a progress reporting function for use in loops or apply-style operations.Returns a no-op function if progressr is not available or disabled.

Usage

create_progressor(steps, enable = TRUE)

Arguments

Details

This function wrapsprogressr::progressor() with a fallback for when progressris not available.

Value

A function that signals progress when called. If progressr is not availableorenable = FALSE, returns a no-op function.

See Also

progressr::progressor(),with_progress()

Examples

## Not run: # Enable progress reportingprogressr::handlers("progress")# Use in a loopp <- create_progressor(10)results <- lapply(1:10, function(i) {  Sys.sleep(0.1)  p()  # Signal progress  i^2})## End(Not run)

Default reference point

Description

Default reference point

Usage

default_ref_pt(p)

Arguments

Value

A diagonal matrix of the desired dimension

Differential of Matrix Exponential Map

Description

Computes the differential of the matrix exponential map located at a point a, evaluated at x

Usage

dexp(a, x)

Arguments

Value

A positive definite symmetric matrix representing the differential located at a and evaluated at x, of class dppMatrix

Differential of Matrix Logarithm Map

Description

Computes the differential of the matrix logarithm map at a point Sigma, evaluated at H

Usage

dlog(sigma, h)

Arguments

Value

A symmetric matrix representing the differential evaluated at H of class dsyMatrix

Compute the Euclidean Exponential

Description

Compute the Euclidean Exponential

Usage

euclidean_exp(sigma, v, validate = FALSE)

Arguments

Value

The point on the manifold corresponding to the tangent vector atsigma.

Compute the Euclidean Logarithm

Description

Compute the Euclidean Logarithm

Usage

euclidean_log(sigma, lambda, validate = FALSE)

Arguments

Value

The tangent space image oflambda atsigma.

Compute the Inverse Vectorization (Euclidean)

Description

Converts a vector back into a tangent matrix relative to a reference point using Euclidean metric.

Usage

euclidean_unvec(sigma, w)

Arguments

Value

A symmetric matrix, representing the tangent vector.

Vectorize at Identity Matrix (Euclidean)

Description

Converts a symmetric matrix into a vector representation.

Usage

euclidean_vec(sigma, v)

Arguments

Value

A numeric vector, representing the vectorized tangent image.

Get Current Number of Parallel Workers

Description

Returns the number of parallel workers configured in the current future plan.

Usage

get_n_workers()

Value

Integer specifying the number of workers, or 1 if sequential processing is enabled.

See Also

set_parallel_plan()

Examples

## Not run: set_parallel_plan("multisession", workers = 4)get_n_workers()  # Returns 4set_parallel_plan("sequential")get_n_workers()  # Returns 1## End(Not run)

Half-underscore operation for use in the log-Cholesky metric

Description

Half-underscore operation for use in the log-Cholesky metric

Usage

half_underscore(x)

Arguments

Value

The strictly lower triangular part of the matrix, plus half its diagonal part

Create an Identity Matrix

Description

Create an Identity Matrix

Usage

id_matr(sigma)

Arguments

Value

An identity matrix of the same dimensions assigma.

Check if Parallel Processing is Enabled

Description

Checks whether parallel processing is currently enabled based on the future plan.

Usage

is_parallel_enabled()

Value

Logical value:TRUE if parallel processing is enabled,FALSE if sequential.

See Also

set_parallel_plan(),should_parallelize()

Examples

## Not run: # Check current statusis_parallel_enabled()# Enable parallel processingset_parallel_plan("multisession")is_parallel_enabled()  # Returns TRUE# Disable parallel processingset_parallel_plan("sequential")is_parallel_enabled()  # Returns FALSE## End(Not run)

Check if Progress Reporting is Available

Description

Checks whether the progressr package is available and can be used for progress reporting.

Usage

is_progress_available()

Value

Logical value: TRUE if progressr is available, FALSE otherwise.

Examples

if (is_progress_available()) {  message("Progress reporting is available")}

Compute the Log-Cholesky Exponential

Description

This function computes the Riemannian exponential map using the Log-Cholesky metric for symmetric positive-definite matrices. The map operates by transforming the tangent vector via Cholesky decomposition of the reference point.

Usage

log_cholesky_exp(sigma, v, validate = FALSE)

Arguments

Value

A symmetric positive-definite matrix of classdppMatrix, representing the point on the manifold.

Compute the Log-Cholesky Logarithm

Description

This function computes the Riemannian logarithmic map using the Log-Cholesky metric for symmetric positive-definite matrices. The Log-Cholesky metric operates by transforming matrices via their Cholesky decomposition.

Usage

log_cholesky_log(sigma, lambda, validate = FALSE)

Arguments

Value

A symmetric matrix of classdspMatrix, representing the tangent space image oflambda atsigma.

Compute the Log-Cholesky Inverse Vectorization

Description

Compute the Log-Cholesky Inverse Vectorization

Usage

log_cholesky_unvec(sigma, w)

Arguments

Value

A symmetric matrix of classdspMatrix

Compute the Log-Cholesky Vectorization

Description

Compute the Log-Cholesky Vectorization

Usage

log_cholesky_vec(sigma, v)

Arguments

Value

A numeric vector representing the vectorized tangent image

Compute the Log-Euclidean Exponential

Description

This function computes the Euclidean exponential map.

Usage

log_euclidean_exp(ref_pt, v, validate = FALSE)

Arguments

Value

The point on the manifold corresponding to the tangent vector atref_pt.

Compute the Log-Euclidean Logarithm

Description

Compute the Log-Euclidean Logarithm

Usage

log_euclidean_log(sigma, lambda, validate = FALSE)

Arguments

Value

The tangent space image oflambda atsigma.

Compute the Inverse Vectorization (Euclidean)

Description

Converts a vector back into a tangent matrix relative to a reference point using Euclidean metric.

Usage

log_euclidean_unvec(sigma, w)

Arguments

Value

A symmetric matrix, representing the tangent vector.

Vectorize at Identity Matrix (Euclidean)

Description

Converts a symmetric matrix into a vector representation.

Usage

log_euclidean_vec(sigma, v)

Arguments

Value

A numeric vector, representing the vectorized tangent image.

Metric Object Constructor

Description

Constructs a metric object that contains the necessary functions for Riemannian operations.

Usage

metric(log, exp, vec, unvec)

Arguments

Value

An object of classrmetric containing the specified functions.

Pre-configured Riemannian metrics for SPD matrices

Description

Ready-to-use metric objects for various Riemannian geometries on the manifoldof symmetric positive definite matrices.

Usage

airmlog_euclideaneuclideanlog_choleskybures_wasserstein

Format

Objects of classrmetric containing four functions:

log

Computes the Riemannian logarithm

exp

Computes the Riemannian exponential

vec

Performs vectorization

unvec

Performs inverse vectorization

An object of classrmetric of length 4.

An object of classrmetric of length 4.

An object of classrmetric of length 4.

An object of classrmetric of length 4.

An object of classrmetric of length 4.

Parallel Processing Configuration for riemtan

Description

This module provides functions to configure and manage parallel processingusing the futureverse framework (future + furrr packages).

Progress Reporting Utilities for riemtan

Description

This module provides utilities for progress reporting duringcomputationally intensive operations, using the progressr package.

Relocate Tangent Representations to a New Reference Point

Description

Changes the reference point for tangent space representations on a Riemannian manifold.Supports parallel processing via the futureverse framework for improved performance on large datasets.

Usage

relocate(old_ref, new_ref, images, met, progress = FALSE)

Arguments

Details

This function uses parallel processing when the number of images exceeds a threshold andparallel processing is enabled viaset_parallel_plan(). For small datasets, sequentialprocessing is used automatically to avoid parallelization overhead.

Value

A list of tangent representations relative to the new reference point. Each element in the returned list will be an object of classdspMatrix.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {  library(Matrix)  data(airm)  old_ref <- diag(2) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  new_ref <- diag(c(2, 3)) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  images <- list(    diag(2) |> Matrix::symmpart() |> Matrix::pack(),    diag(c(1, 0.5)) |> Matrix::symmpart() |> Matrix::pack()  )  relocate(old_ref, new_ref, images, airm)}

Reset Parallel Plan to Sequential

Description

Convenience function to reset parallel processing to sequential mode.Equivalent toset_parallel_plan("sequential").

Usage

reset_parallel_plan()

Value

Invisibly returns the future plan object.

See Also

set_parallel_plan()

Examples

## Not run: # Enable parallel processingset_parallel_plan("multisession", workers = 4)# Reset to sequentialreset_parallel_plan()## End(Not run)

Generate Random Samples from a Riemannian Normal Distribution

Description

Simulates random samples from a Riemannian normal distribution on symmetric positive definite matrices.

Usage

rspdnorm(n, refpt, disp, met)

Arguments

Value

An object of classCSample containing the generated samples.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {  library(Matrix)  data(airm)  refpt <- diag(2) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  disp <- diag(3) |>    Matrix::nearPD() |>    _$mat |>    Matrix::pack()  rspdnorm(10, refpt, disp, airm)}

Wrapper for the matrix logarithm

Description

Wrapper for the matrix logarithm

Usage

safe_logm(x)

Arguments

Value

Its matrix logarithm

Set Parallel Processing Plan

Description

Configure the parallel processing strategy for riemtan operations.Uses the future package to manage parallel backends.

Usage

set_parallel_plan(strategy = "sequential", workers = NULL)

Arguments

Details

Themultisession strategy is recommended for most users as it works on all platforms.Themulticore strategy is faster on Unix-like systems but is not available on Windows.

To disable parallel processing, useset_parallel_plan("sequential").

Value

Invisibly returns the future plan object.

See Also

future::plan(),is_parallel_enabled(),should_parallelize()

Examples

## Not run: # Enable parallel processing with automatic worker detectionset_parallel_plan("multisession")# Use 4 parallel workersset_parallel_plan("multisession", workers = 4)# Disable parallel processingset_parallel_plan("sequential")## End(Not run)

Decide Whether to Use Parallel Processing

Description

Internal function to determine if an operation should use parallel processingbased on the number of items to process and current configuration.

Usage

should_parallelize(n, threshold = 10)

Arguments

Details

This function returnsTRUE only if:

1. Parallel processing is enabled (viaset_parallel_plan())

2. The number of itemsn is at leastthreshold

For small numbers of items, the overhead of parallelization typically outweighs the benefits,so sequential processing is used.

Value

Logical value:TRUE if parallel processing should be used,FALSE otherwise.

See Also

set_parallel_plan(),is_parallel_enabled()

Examples

## Not run: # With parallel processing enabledset_parallel_plan("multisession")should_parallelize(5)    # FALSE (below threshold)should_parallelize(20)   # TRUE (above threshold)# With parallel processing disabledset_parallel_plan("sequential")should_parallelize(100)  # FALSE (sequential plan)## End(Not run)

Reverse isometry from tangent space at identity to tangent space at P

Description

Reverse isometry from tangent space at identity to tangent space at P

Usage

spd_isometry_from_identity(sigma, v)

Arguments

Value

A symmetric matrix of classdspMatrix

Isometry from tangent space at P to tangent space at identity

Description

Isometry from tangent space at P to tangent space at identity

Usage

spd_isometry_to_identity(sigma, v)

Arguments

Value

A symmetric matrix of classdspMatrix

Validate Backend Object

Description

Validates that a backend object inherits from DataBackend and implements required methods.

Usage

validate_backend(backend)

Arguments

Value

None. Throws an error if validation fails.

Validate Connections

Description

Validates the connections input.

Usage

validate_conns(conns, tan_imgs, vec_imgs, centered)

Arguments

Value

None. Throws an error if the validation fails.

Validate arguments for Riemannian logarithms

Description

Validate arguments for Riemannian logarithms

Usage

validate_exp_args(sigma, v)

Arguments

Details

Error if sigma and lambda are not of the same dimensions

Value

None

Validate arguments for Riemannian logarithms

Description

Validate arguments for Riemannian logarithms

Usage

validate_log_args(sigma, lambda)

Arguments

Details

Error if sigma and lambda are not of the same dimensions

Value

None

Validate Metric

Description

Validates that the metric is not NULL.

Usage

validate_metric(metric)

Arguments

Value

None. Throws an error if the metric is NULL.

Validate Parquet Directory Structure

Description

Validate Parquet Directory Structure

Usage

validate_parquet_dir(data_dir, check_files = TRUE)

Arguments

Value

None. Throws an error if validation fails.

Validate Parquet Directory

Description

Validates that a directory contains properly formatted Parquet filesand metadata for use with ParquetBackend.

Usage

validate_parquet_directory(data_dir, verbose = TRUE)

Arguments

Details

Checks:

• Directory exists

• metadata.json exists and is valid

• All expected Parquet files exist

• Parquet files have correct dimensions

Value

Logical indicating whether the directory is valid

Examples

## Not run: validate_parquet_directory("my_connectomes")## End(Not run)

Validate Tangent Images

Description

Validates the tangent images input.

Usage

validate_tan_imgs(tan_imgs, vec_imgs, centered)

Arguments

Value

None. Throws an error if the validation fails.

Validate arguments for inverse vectorization

Description

Validate arguments for inverse vectorization

Usage

validate_unvec_args(sigma, w)

Arguments

Details

Error if the dimensionalities don't match

Value

None

Validate arguments for vectorization

Description

Validate arguments for vectorization

Usage

validate_vec_args(sigma, v)

Arguments

Details

Error if sigma and v are not of the same dimensions

Value

None

Validate Vector Images

Description

Validates the vector images input.

Usage

validate_vec_imgs(vec_imgs, centered)

Arguments

Value

None. Throws an error if the validation fails.

Vectorize at Identity Matrix

Description

Converts a symmetric matrix into a vector representation specific to operations at the identity matrix.

Usage

vec_at_id(v)

Arguments

Value

A numeric vector, representing the vectorized tangent image.

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {  library(Matrix)  v <- diag(c(1, sqrt(2))) |>    Matrix::symmpart() |>    Matrix::pack()  vec_at_id(v)}

Execute Expression with Progress Reporting

Description

Wrapper function that executes an expression with optional progress reporting.Integrates with the progressr package when available.

Usage

with_progress(expr, name = "Processing", enable = TRUE)

Arguments

Details

This function provides a consistent interface for progress reporting across riemtan.Progress handlers can be configured usingprogressr::handlers().

Whenenable = TRUE and progressr is installed, users can see progress by calling:

progressr::handlers("progress")  # or "txtprogressbar", "cli", etc.

Value

The result of evaluatingexpr.

See Also

progressr::with_progress(),progressr::progressor()

Examples

## Not run: # Enable progress reportingprogressr::handlers("progress")# Use within a functionresult <- with_progress({  p <- progressr::progressor(steps = 10)  lapply(1:10, function(i) {    Sys.sleep(0.1)    p()  # Signal progress    i^2  })}, name = "Computing squares")## End(Not run)

Execute Function with Progress Reporting for Each Item

Description

Helper function that wraps a function to report progress after each invocation.Useful for integrating progress reporting withpurrr::map() orfurrr::future_map().

Usage

with_progress_signal(.f, .p)

Arguments

Details

This is an internal utility function used by riemtan's parallel processing functions.

Value

A wrapped function that calls.f(x) and then signals progress via.p().

Examples

## Not run: progressr::handlers("progress")result <- with_progress({  p <- progressr::progressor(steps = 10)  wrapped_fn <- with_progress_signal(sqrt, p)  lapply(1:10, wrapped_fn)})## End(Not run)

Write Connectomes to Parquet Files

Description

Exports a list of SPD matrices (connectomes) to individual Parquet fileswith accompanying metadata.

Usage

write_connectomes_to_parquet(  connectomes,  output_dir,  file_pattern = "matrix_%04d.parquet",  subject_ids = NULL,  provenance = NULL,  overwrite = FALSE)

Arguments

Details

Creates a directory structure:

• Individual Parquet files (one per matrix)

• metadata.json with dimensions, file pattern, and optional metadata

The metadata.json file contains:

• n_matrices: Number of matrices

• matrix_dim: Dimension p (matrices are p x p)

• file_pattern: Naming pattern for Parquet files

• subject_ids: Optional subject identifiers

• provenance: Optional provenance information

Value

Invisibly returns the path to the output directory

Examples

## Not run: # Create sample datamats <- replicate(10, Matrix::pack(Matrix::Matrix(diag(5), sparse = FALSE)), simplify = FALSE)# Write to Parquetwrite_connectomes_to_parquet(  mats,  output_dir = "my_connectomes",  subject_ids = paste0("subj_", 1:10),  provenance = list(study = "Example Study", date = Sys.Date()))## End(Not run)