Skip to contents

CSample Class

Source: R/sample.R
CSample.Rd

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

Active bindings

connectomes

Connectomes data

tangent_images

Tangent images data

vector_images

Vector images data

sample_size

Sample size

matrix_size

Matrix size

mfd_dim

Manifold dimension

is_centered

Centering status

frechet_mean

Frechet mean

riem_metric

Riemannian Metric used

variation

Variation of the sample

sample_cov

Sample covariance

ref_point

Reference point for tangent or vectorized images

distances

Distances to the Frechet mean

batch_size

Batch size for compute_fmean

Methods

Public methods

Method new()

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

conns

A list of connectomes (default is NULL).

tan_imgs

A list of tangent images (default is NULL).

vec_imgs

A matrix whose rows are vectorized images (default is NULL).

centered

Boolean indicating whether tangent or vectorized images are centered (default is NULL).

ref_pt

A connectome (default is identity)

metric_obj

Object of class rmetric representing the Riemannian metric used.

batch_size

The batch size for compute_fmean (default is 32).

backend

A DataBackend object (ListBackend or ParquetBackend). If NULL and conns is provided, a ListBackend will be created automatically.

Returns

A new CSample object.

Method load_connectomes_batched()

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

Usage

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

Arguments

indices

Optional vector of indices to load. If NULL (default), loads all matrices.

batch_size

Number of matrices to load per batch (default: 50). Larger batches use more memory but may be faster.

progress

Logical indicating whether to show progress (default: FALSE).

Details

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

Returns

A list of dppMatrix objects.

Examples

\dontrun{
# Create CSample with ParquetBackend
backend <- create_parquet_backend("my_data")
sample <- CSample$new(backend = backend, metric_obj = airm)

# Load first 100 matrices in batches of 20
conns <- sample$load_connectomes_batched(indices = 1:100, batch_size = 20)
}

Method compute_tangents()

This function computes the tangent images from the connectomes.

Usage

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

Arguments

ref_pt

A reference point, which must be a dppMatrix object (default is default_ref_pt).

progress

Logical indicating whether to show progress (default: FALSE).

Details

Error if ref_pt is not a dppMatrix object or if conns is not specified.

Returns

None

Method compute_conns()

This function computes the connectomes from the tangent images.

Usage

CSample$compute_conns(progress = FALSE)

Arguments

progress

Logical indicating whether to show progress (default: FALSE).

Details

Error if tangent images are not specified.

Returns

None

Method compute_vecs()

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

Usage

CSample$compute_vecs(progress = FALSE)

Arguments

progress

Logical indicating whether to show progress (default: FALSE).

Details

Error if tangent images are not specified.

Returns

None

Method compute_unvecs()

This function computes the tangent images from the vector images.

Usage

CSample$compute_unvecs(progress = FALSE)

Arguments

progress

Logical indicating whether to show progress (default: FALSE).

Details

Error if vec_imgs is not specified.

Returns

None

Method compute_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

tol

Tolerance for the convergence of the mean (default is 0.05).

max_iter

Maximum number of iterations for the computation (default is 20).

lr

Learning rate for the optimization algorithm (default is 0.2).

batch_size

The batch size (default is the instance's batch_size).

progress

Logical indicating whether to show progress (default: FALSE).

Returns

None

Method change_ref_pt()

This function changes the reference point for the tangent images.

Usage

CSample$change_ref_pt(new_ref_pt, progress = FALSE)

Arguments

new_ref_pt

A new reference point, which must be a dppMatrix object.

progress

Logical indicating whether to show progress (default: FALSE).

Details

Error if tangent images have not been computed or if new_ref_pt is not a dppMatrix object.

Returns

None

Method center()

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.

Method compute_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 if vec_imgs is not specified.

Returns

None. This function is called for its side effects.

Method compute_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 if vec_imgs is not specified.

Returns

None. This function is called for its side effects.

Method compute_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.

Method clone()

The objects of this class are cloneable with this method.

Usage

CSample$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples


## ------------------------------------------------
## Method `CSample$load_connectomes_batched`
## ------------------------------------------------

if (FALSE) { # \dontrun{
# Create CSample with ParquetBackend
backend <- create_parquet_backend("my_data")
sample <- CSample$new(backend = backend, metric_obj = airm)

# Load first 100 matrices in batches of 20
conns <- sample$load_connectomes_batched(indices = 1:100, batch_size = 20)
} # }