Package 'fmrilatent'

Description

Extract elements from a LatentNeuroVec. Use [[ to extract a single volume as a SparseNeuroVol, or [ for 4D subsetting.

Usage

## S4 method for signature 'LatentNeuroVec,numeric'
x[[i]]

## S4 method for signature 'LatentNeuroVec,numeric,numeric,ANY'
x[i, j, k, l, ..., drop = TRUE]

## S4 method for signature 'LatentNeuroVec,matrix,missing,ANY'
x[i, j, k, l, ..., drop = TRUE]

## S4 method for signature 'LatentNeuroVec,ANY,ANY,ANY'
x[i, j, k, l, ..., drop = TRUE]

Arguments

Value

For [[: A SparseNeuroVol-class containing the computed volume. For [: An array of extracted values.

Examples

mask <- neuroim2::LogicalNeuroVol(
  array(TRUE, dim = c(2, 2, 1)),
  neuroim2::NeuroSpace(c(2, 2, 1))
)
lvec <- LatentNeuroVec(
  basis = matrix(1:6, nrow = 3),
  loadings = matrix(seq_len(8) / 10, nrow = 4),
  space = neuroim2::NeuroSpace(c(2, 2, 1, 3)),
  mask = mask,
  expect_dense = TRUE
)
# Extract volumes
vol1 <- lvec[[1]]
vol_mid <- lvec[[2]]
vol_last <- lvec[[dim(lvec)[4]]]

Description

Describe the transform from raw to analysis coordinates

Usage

analysis_transform(x, ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
analysis_transform(x, ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
analysis_transform(x, ...)

## S4 method for signature 'ImplicitLatent'
analysis_transform(x, ...)

## S4 method for signature 'LatentNeuroVec'
analysis_transform(x, ...)

## S4 method for signature 'BlockLatentNeuroVector'
analysis_transform(x, ...)

Arguments

Value

Transform descriptor or NULL. Downstream model-fitting code should ordinarily consume coef_time(x, "analysis") rather than reasoning about raw coordinates directly.

Description

This helper lets the standalone BOLDZip-SR codec consume matrix-like shared basis assets without registering BOLDZip as an 'encode()' family. Matrix and template inputs are used as the detail basis by default and are orthonormalized because BOLDZip projection currently uses the transpose as the analysis operator.

Usage

as_boldzip_spatial_basis(x, ...)

Arguments

Value

A 'BoldZipSRSpatialBasis' object.

Description

Bridges the neuroim2::ClusteredNeuroVol parcellation representation to fmrilatent's ClusterReduction class, preserving label metadata.

Usage

as_cluster_reduction(cvol)

Arguments

Value

A ClusterReduction object with label metadata in info.

Description

Convert to HaarLatent class

Usage

as_haar_latent(obj)

Arguments

Value

Object with HaarLatent class added

Description

Attach HRBF metadata to an existing LatentNeuroVec

Usage

as_hrbf_latent(lvec, params, centres = NULL, sigmas = NULL)

Arguments

Value

The LatentNeuroVec with HRBF metadata attached

Description

Coerce an object to an ImplicitLatent decoder

Usage

as_implicit_latent(x, ...)

Arguments

Value

An object of class 'ImplicitLatent'.

Description

Coerce a BOLDZip-SR payload to an ImplicitLatent

Usage

## S3 method for class 'BoldZipSR'
as_implicit_latent(x, mask = NULL, domain = NULL, support = NULL, ...)

Arguments

Value

An 'ImplicitLatent' whose decoder returns matrices as 'time x voxels', matching the rest of the implicit latent API.

Description

Normalizes an incoming object to the canonical portable_linear_map representation used internally by encode_operator(), decoder(), and related routines. Matrices and Matrix::Matrix objects are wrapped with closure-based forward/adjoint_apply callbacks; list inputs are validated and re-normalized with top-level source_support / target_support preferred over provenance$* fallbacks.

Usage

as_portable_linear_map(
  x,
  source_domain_id = "",
  target_domain_id = "",
  source_support = NULL,
  target_support = NULL,
  provenance = list(),
  context = "portable linear map"
)

Arguments

Value

A list in the canonical portable-linear-map form.

See Also

portable_linear_map, validate_portable_linear_map.

Examples

m <- matrix(1:6, nrow = 2)
op <- as_portable_linear_map(m, target_domain_id = "native")
op$forward(c(1, 1, 1))

Description

Reconstruct LatentNeuroVec as a 4D array

Usage

## S4 method for signature 'LatentNeuroVec'
as.array(x, ...)

Arguments

Value

A 4D numeric array with dimensions (x, y, z, time).

Description

Reconstruct an ImplicitLatent as an array

Usage

## S3 method for class 'ImplicitLatent'
as.array(x, time_idx = NULL, roi_mask = NULL, ...)

Arguments

Value

A numeric array with dimensions c(x, y, z, time).

Description

Reconstruct LatentNeuroVec as a matrix (time x voxels)

Usage

## S4 method for signature 'LatentNeuroSurfaceVector'
as.matrix(x, ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
as.matrix(x, ...)

## S4 method for signature 'BlockLatentNeuroVector'
as.matrix(x, ...)

## S4 method for signature 'LatentNeuroVec'
as.matrix(x, ...)

Arguments

Value

A numeric matrix with rows = time points, columns = mask voxels.

Description

Coerce group-plus-delta loadings to a dense matrix

Usage

## S3 method for class 'GroupDeltaLoadings'
as.matrix(x, ...)

Arguments

Value

Dense matrix of materialized loadings.

Description

Convert HaarLatent to matrix

Usage

## S3 method for class 'HaarLatent'
as.matrix(x, ...)

Arguments

Value

Matrix of reconstructed values

Description

Reconstruct an ImplicitLatent as a matrix

Usage

## S3 method for class 'ImplicitLatent'
as.matrix(x, time_idx = NULL, roi_mask = NULL, ...)

Arguments

Value

A numeric matrix with rows = time and columns = voxels within the requested mask support.

Description

Build an AWPT basis template

Usage

awpt_basis_template(
  parcellation,
  basis_spec = basis_awpt_wavelet(),
  loadings = NULL,
  anatomical_operator = NULL,
  conductance = NULL,
  coefficient_roughness = NULL,
  center = FALSE,
  ridge = 1e-08,
  label = "awpt_wavelet",
  ...
)

Arguments

Value

An AWPTBasisTemplate.

Description

Average subject conductance matrices on a shared template graph

Usage

awpt_mean_conductance(
  conductances,
  method = c("log_euclidean", "arithmetic"),
  shrinkage = 0,
  enforce_psd = TRUE,
  tol = 1e-08
)

Arguments

Value

A symmetric averaged conductance matrix.

Description

Build an AWPT field operator from a conductance matrix

Usage

awpt_operator_from_conductance(
  conductance,
  normalize = c("none", "sym", "rw"),
  tol = 1e-08
)

Arguments

Value

A field-space roughness operator.

Description

Build an AWPT field operator from subject conductance summaries

Usage

awpt_operator_from_subject_conductances(
  conductances,
  mean_method = c("log_euclidean", "arithmetic"),
  normalize = c("none", "sym", "rw"),
  shrinkage = 0,
  enforce_psd = TRUE,
  tol = 1e-08
)

Arguments

Value

A list with conductance_mean and operator.

Description

Build a surface AWPT basis template

Usage

awpt_surface_basis_template(
  geometry,
  basis_spec = basis_awpt_wavelet(),
  support = NULL,
  loadings = NULL,
  centers = NULL,
  anatomical_operator = NULL,
  conductance = NULL,
  coefficient_roughness = NULL,
  measure = NULL,
  center = FALSE,
  ridge = 1e-08,
  label = "surface_awpt_wavelet"
)

Arguments

Value

A SurfaceAWPTBasisTemplate.

Description

Extract the basis matrix from a latent space representation. For LatentNeuroVec objects, this returns the temporal basis matrix with dimensions (nTime x k) where k is the number of components.

Usage

basis(x, ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
basis(x)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
basis(x)

## S4 method for signature 'BlockLatentNeuroVector'
basis(x)

## S4 method for signature 'LatentNeuroVec'
basis(x)

Arguments

Value

The basis matrix (typically time x components)

Examples

mask <- neuroim2::LogicalNeuroVol(
  array(TRUE, dim = c(2, 2, 1)),
  neuroim2::NeuroSpace(c(2, 2, 1))
)
lvec <- LatentNeuroVec(
  basis = matrix(1:6, nrow = 3),
  loadings = matrix(seq_len(8) / 10, nrow = 4),
  space = neuroim2::NeuroSpace(c(2, 2, 1, 3)),
  mask = mask,
  expect_dense = TRUE
)
b_matrix <- basis(lvec)
dim(b_matrix)

Description

Extract the basis asset behind a latent object

Usage

basis_asset(x, ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
basis_asset(x, ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
basis_asset(x, ...)

## S4 method for signature 'ImplicitLatent'
basis_asset(x, ...)

## S4 method for signature 'LatentNeuroVec'
basis_asset(x, ...)

## S4 method for signature 'BlockLatentNeuroVector'
basis_asset(x, ...)

Arguments

Value

Basis asset object or NULL.

Description

AWPT wave-packet basis specification

Usage

basis_awpt_wavelet(
  scales = c(1, 2, 4, 8),
  order = 30L,
  threshold = 1e-06,
  k_neighbors = 6L,
  penalty_rule = c("inverse_scale", "inverse_scale_sq", "scale", "none", "custom"),
  custom_weights = NULL
)

Arguments

Value

A spec_awpt_wavelet object.

Description

Extract a basis decoder from a template asset

Usage

basis_decoder(template, ...)

## S4 method for signature 'SurfaceAWPTBasisTemplate'
basis_decoder(template, ...)

## S4 method for signature 'AWPTBasisTemplate'
basis_decoder(template, ...)

## S4 method for signature 'HierarchicalBasisTemplate'
basis_decoder(template, ...)

## S4 method for signature 'ParcelBasisTemplate'
basis_decoder(template, ...)

## S4 method for signature 'SurfaceBasisTemplate'
basis_decoder(template, ...)

Arguments

Value

Basis decoder view object.

Description

Diffusion wavelet basis specification

Usage

basis_diffusion_wavelet(
  target_rank = 2000L,
  oversample = 20L,
  threshold = NULL,
  max_scales = 1L,
  epsilon = NULL,
  seed = 1L,
  sparsify_eps = NULL
)

Arguments

Value

A 'spec_diffusion_wavelet' basis specification descriptor.

Description

'basis_flat()' creates a descriptor for methods that should lift a reduction without estimating local components, typically as a simple parcel/cluster indicator basis.

Usage

basis_flat()

Value

An empty list with class 'spec_flat'.

Description

Heat wavelet basis specification

Usage

basis_heat_wavelet(scales = c(1, 2, 4, 8), order = 30, threshold = 1e-06)

Arguments

Value

A 'spec_heat_wavelet' object for 'lift()'.

Description

'basis_pca()' creates a lightweight descriptor for parcel- or cluster-local PCA bases. The descriptor is consumed by 'lift(ClusterReduction, spec_pca, data = ...)', where 'data' supplies the time-by-voxel matrix used to estimate the components.

Usage

basis_pca(k = 3, whiten = FALSE)

Arguments

Value

A list with class 'spec_pca' containing 'k' and 'whiten'.

Description

'basis_slepian()' creates a lightweight descriptor for graph/Slepian basis construction during 'lift()' or spatial encoding. It records the requested component count and Slepian flavor; the actual basis is computed later by a 'lift()' method for the supplied reduction.

Usage

basis_slepian(k = 3, type = "laplacian")

Arguments

Value

A list with class 'spec_slepian' containing 'k' and 'type'.

Description

Benchmark encode/decode round-trips

Usage

benchmark_roundtrip(
  mask_dims = c(16, 16, 8),
  n_time = 10L,
  methods = c("slepian_space", "hrbf", "wavelet_active", "bspline_hrbf_st"),
  iterations = 1L
)

Arguments

Value

A data.frame/tibble with timings and reconstruction error.

Description

Construct a bilateral surface latent object

Usage

BilatLatentNeuroSurfaceVector(left, right, label = "", meta = list())

Arguments

Value

A BilatLatentNeuroSurfaceVector.

Description

An explicit bilateral surface latent representation composed of left and right LatentNeuroSurfaceVector objects.

Slots

left

Left-hemisphere latent surface object.

right

Right-hemisphere latent surface object.

label

Character label.

meta

Lightweight metadata list.

Description

Construct a block-domain latent object

Usage

BlockLatentNeuroVector(blocks, label = "", meta = list())

Arguments

Value

A BlockLatentNeuroVector.

Description

An explicit block-domain latent representation composed of multiple named latent blocks sharing a common coefficient basis. Intended for hybrid domains such as bilateral cortical surfaces plus volumetric subcortex.

Slots

blocks

Named list of explicit latent objects.

label

Character label.

meta

Lightweight metadata list.

Description

Construct sparse innovation event settings for BOLDZip-SR

Usage

boldzip_events(max_events = 256L, threshold_sd = 3, paired_fraction = 0.25)

Arguments

Value

A 'BoldZipSREvents' settings object.

Description

Constructs an experimental graph-adapted spatial basis from a symmetric adjacency matrix. Low-frequency graph Laplacian eigenvectors become coarse carrier support functions and the following higher-frequency eigenvectors become detail atoms. This is a materialized small-to-medium graph MVP, not a production graph-wavelet operator.

Usage

boldzip_graph_spatial_basis(
  adjacency,
  n_coarse = 8L,
  n_detail = NULL,
  normalized = TRUE,
  label = NULL
)

Arguments

Value

A 'BoldZipSRSpatialBasis' object.

Description

Reconstruct a matrix from parcel-average time series

Usage

boldzip_parcel_reconstruct(X, parcels)

Arguments

Value

Matrix with the same dimensions as 'X', expanded from parcel means.

Description

Construct reliability-aware quantization settings for BOLDZip-SR

Usage

boldzip_quantization(base_step = 0, epsilon = 1e-06)

Arguments

Value

A 'BoldZipSRQuantization' settings object.

Description

Construct split-half reliability settings for BOLDZip-SR

Usage

boldzip_reliability(
  split = c("odd_even", "halves"),
  min_texture_reliability = 0,
  min_temporal_reliability = 0
)

Arguments

Value

A 'BoldZipSRReliability' settings object.

Description

Build a matrix spatial basis descriptor for BOLDZip-SR

Usage

boldzip_spatial_basis(
  phi_c = NULL,
  phi_d = NULL,
  label = NULL,
  basis_asset = NULL
)

Arguments

Value

A 'BoldZipSRSpatialBasis' object.

Description

Decode an experimental BOLDZip-SR object

Usage

boldzip_sr_decode(object, time_idx = NULL, roi = NULL)

Arguments

Value

Reconstructed matrix with rows as voxels/grayordinates and columns as time points.

Description

'boldzip_sr_encode()' is an experimental matrix-level implementation of Split-Reliable Graph Carrier Compression. It expects a matrix with rows as voxels or grayordinates and columns as time points. The implementation stores temporally compressed carriers, sparse high-resolution texture loadings, and sparse split-reliable residual events. It is intended as a research prototype, not a production binary codec.

Usage

boldzip_sr_encode(
  X,
  spatial_basis = NULL,
  k_carriers = 96L,
  temporal_k = NULL,
  temporal_spec = NULL,
  q_texture = 2L,
  texture_lags = 0L,
  reliability = boldzip_reliability(),
  quantization = boldzip_quantization(),
  events = boldzip_events(),
  center = TRUE,
  label = NULL
)

Arguments

Value

A 'BoldZipSR' object.

Description

Summarize an experimental BOLDZip-SR payload

Usage

boldzip_sr_payload_summary(object)

Arguments

Value

Data frame with component counts and approximate object bytes.

Description

Simulate data with BOLDZip-SR carrier, texture, and event structure

Usage

boldzip_sr_simulate(
  n_voxels = 40L,
  n_time = 80L,
  k_carriers = 3L,
  q_texture = 1L,
  n_events = 8L,
  noise_sd = 0.05,
  seed = NULL
)

Arguments

Value

List containing 'X', 'mu', 'carriers', 'texture', and 'events'.

Description

Reconstruct a matrix from a low-rank SVD baseline

Usage

boldzip_svd_reconstruct(X, rank, center = TRUE)

Arguments

Value

Matrix with the same dimensions as 'X'.

Description

Create a BasisHandle for a B-spline temporal basis

Usage

bspline_basis_handle(
  n_time,
  k,
  degree = 3L,
  knots = NULL,
  boundary_knots = NULL,
  include_intercept = FALSE,
  orthonormalize = TRUE,
  id = NULL,
  label = NULL
)

Arguments

Value

A BasisHandle.

Description

Constructs a multi-level spatial basis from nested parcellations using graph Laplacian eigenvectors. The resulting template can be reused to efficiently encode multiple datasets that share the same mask geometry.

Usage

build_hierarchical_template(
  mask,
  parcellations,
  k_per_level,
  k_neighbors = 6L,
  ridge = 1e-08,
  solver = c("chol", "qr"),
  label = "hierarchical_laplacian"
)

Arguments

Value

HierarchicalBasisTemplate (primal basis B + cached solver and metadata).

Description

Convenience wrapper that combines 'build_schaefer_levels()' with 'build_hierarchical_template()' to produce a ready-to-use template with geodesic-informed parcel clustering.

Usage

build_schaefer_hierarchical_template(
  mask,
  parcels = 400,
  networks = 17,
  space = "fsaverage6",
  k_levels = c(16, 32, 64),
  k_per_level = c(8, 5, 3, 1),
  vol_atlas = NULL,
  alpha = 0.5,
  beta = 0.3,
  gamma = 0.2,
  d0 = 30,
  component_policy = "largest",
  cache = TRUE,
  k_neighbors = 6L,
  ridge = 1e-08,
  solver = c("chol", "qr")
)

Arguments

Value

HierarchicalBasisTemplate object.

See Also

build_hierarchical_template, build_schaefer_levels

Description

Constructs nested parcellation levels for the hierarchical template by: 1. Loading Schaefer surface atlas from neuroatlas 2. Computing geodesic distances and boundary contacts via neurosurf 3. Building a parcel similarity matrix (geodesic + boundary + network) 4. Performing spectral Ward clustering to create coarser levels 5. Mapping surface parcels back to volumetric voxel labels

Real-data glue to finish: - Provide fsaverage Schaefer surfaces (via 'neuroatlas::schaefer_surf') so we can compute geodesic/boundary terms. - Provide the volumetric Schaefer atlas aligned to the MNI mask (via 'neuroatlas::get_schaefer_atlas'). - Ensure mask and volumetric atlas share resolution/origin/spacing; this function assumes 2 mm MNI unless you pass a custom 'vol_atlas'. - Subcortex is **not** handled here; add it separately when assembling the full template.

Usage

build_schaefer_levels(
  mask,
  parcels = 400,
  networks = 17,
  space = "fsaverage6",
  k_levels = c(16, 32, 64),
  vol_atlas = NULL,
  alpha = 0.5,
  beta = 0.3,
  gamma = 0.2,
  d0 = 30,
  component_policy = c("largest", "error", "each", "merge"),
  cache = TRUE
)

Arguments

Details

Requires 'neuroatlas' and 'neurosurf' packages. The surface atlas provides geodesic distances and boundary topology; the volumetric atlas maps parcels to mask voxels.

Value

A list with components:

Description

Cluster-based reduction (e.g., supervoxels or atlas)

Slots

map

Integer vector (voxel order) mapping each voxel to a cluster id.

cluster_ids

Unique cluster ids present in 'map'.

Description

Coarsened graph reduction (e.g., prolongation from coarse to fine)

Slots

P_matrix

Sparse prolongation matrix (fine x coarse).

coarse_adj

Optional sparse adjacency on the coarse graph.

Description

Extract coefficient-space metric from a latent object

Usage

coef_metric(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
coef_metric(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
coef_metric(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'ImplicitLatent'
coef_metric(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'LatentNeuroVec'
coef_metric(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'BlockLatentNeuroVector'
coef_metric(x, coordinates = c("analysis", "raw"), ...)

Arguments

Value

Matrix-like metric representation or NULL. For transport-backed latent objects, analysis coordinates are Euclidean by contract in v1. Raw-coordinate metrics are returned when the raw-to-analysis transform exposes a linear matrix representation.

Description

Extract coefficient time series from a latent object

Usage

coef_time(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
coef_time(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
coef_time(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'ImplicitLatent'
coef_time(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'LatentNeuroVec'
coef_time(x, coordinates = c("analysis", "raw"), ...)

## S4 method for signature 'BlockLatentNeuroVector'
coef_time(x, coordinates = c("analysis", "raw"), ...)

Arguments

Value

Numeric matrix with rows = time and columns = latent coefficients.

Description

Compare BOLDZip-SR against simple reconstruction baselines

Usage

compare_boldzip_sr(X, fit, parcels = NULL, svd_ranks = NULL)

Arguments

Value

Data frame with method, MSE, RMSE, correlation, and scalar payload estimates.

Description

Concatenates two or more LatentNeuroVec objects along the temporal dimension.

Usage

## S4 method for signature 'LatentNeuroVec,LatentNeuroVec'
concat(x, y, ...)

Arguments

Value

A new LatentNeuroVec if all objects are compatible, otherwise a NeuroVecSeq-class.

Examples

mask <- neuroim2::LogicalNeuroVol(
  array(TRUE, dim = c(2, 2, 1)),
  neuroim2::NeuroSpace(c(2, 2, 1))
)
lvec <- LatentNeuroVec(
  basis = matrix(1:6, nrow = 3),
  loadings = matrix(seq_len(8) / 10, nrow = 4),
  space = neuroim2::NeuroSpace(c(2, 2, 1, 3)),
  mask = mask,
  expect_dense = TRUE
)
combined <- concat(lvec, lvec)
dim(combined)

Description

Utility to turn a hierarchical clustering (on parcels) into a nested set of parcel label vectors that downstream code can lift into voxel space. Real data glue: you will pass the hclust built on a parcel-level similarity graph (e.g., Schaefer-400 parcel graph constructed from surface geodesics and boundary contacts); then map these parcel labels back to voxels using the volumetric atlas.

Usage

cut_hclust_nested(hc, k_levels)

Arguments

Value

List of integer label vectors (same length as hc$labels), one per level, nested by construction.

Description

Create a BasisHandle for a DCT temporal basis

Usage

dct_basis_handle(n_time, k, norm = c("ortho", "none"), id = NULL, label = NULL)

Arguments

Value

A BasisHandle object.

Description

Decode coefficient-space vectors into an output space

Usage

decode_coefficients(
  x,
  gamma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  wrap = c("none", "auto"),
  ...
)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
decode_coefficients(
  x,
  gamma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  wrap = c("none", "auto"),
  ...
)

## S4 method for signature 'ImplicitLatent'
decode_coefficients(
  x,
  gamma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  wrap = c("none", "auto"),
  ...
)

## S4 method for signature 'LatentNeuroSurfaceVector'
decode_coefficients(
  x,
  gamma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  wrap = c("none", "auto"),
  ...
)

## S4 method for signature 'LatentNeuroVec'
decode_coefficients(
  x,
  gamma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  wrap = c("none", "auto"),
  ...
)

## S4 method for signature 'BlockLatentNeuroVector'
decode_coefficients(
  x,
  gamma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  wrap = c("none", "auto"),
  ...
)

Arguments

Value

Numeric vector or matrix in the requested output space, or a domain-aware wrapper when wrap = "auto".

Description

Push coefficient covariance into an output space

Usage

decode_covariance(
  x,
  Sigma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  diag_only = TRUE,
  ...
)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
decode_covariance(
  x,
  Sigma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  diag_only = TRUE,
  ...
)

## S4 method for signature 'ImplicitLatent'
decode_covariance(
  x,
  Sigma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  diag_only = TRUE,
  ...
)

## S4 method for signature 'LatentNeuroSurfaceVector'
decode_covariance(
  x,
  Sigma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  diag_only = TRUE,
  ...
)

## S4 method for signature 'LatentNeuroVec'
decode_covariance(
  x,
  Sigma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  diag_only = TRUE,
  ...
)

## S4 method for signature 'BlockLatentNeuroVector'
decode_covariance(
  x,
  Sigma,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  diag_only = TRUE,
  ...
)

Arguments

Value

Numeric vector or matrix in the requested output space.

Description

Get a decoder view for a latent object

Usage

decoder(
  x,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  ...
)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
decoder(
  x,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  ...
)

## S4 method for signature 'ImplicitLatent'
decoder(
  x,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  ...
)

## S4 method for signature 'LatentNeuroSurfaceVector'
decoder(
  x,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  ...
)

## S4 method for signature 'LatentNeuroVec'
decoder(
  x,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  ...
)

## S4 method for signature 'BlockLatentNeuroVector'
decoder(
  x,
  space = c("native", "template"),
  coordinates = c("analysis", "raw"),
  ...
)

Arguments

Value

Decoder view object.

Description

Diffusion wavelet latent constructor (explicit basis)

Usage

diffusion_wavelet_latent(
  X,
  mask,
  reduction = NULL,
  spec = basis_diffusion_wavelet(),
  k_neighbors = 6L,
  label = ""
)

Arguments

Value

A 'LatentNeuroVec' object.

Description

Wraps a diffusion-wavelet 'lift()' call so multiple 'LatentNeuroVec' instances can share the same spatial dictionary without embedding the full matrix in each object.

Usage

diffusion_wavelet_loadings_handle(
  reduction,
  basis_spec = basis_diffusion_wavelet(),
  data = NULL,
  k_neighbors = 6L,
  id = NULL,
  label = "diffusion-wavelet"
)

Arguments

Value

A LoadingsHandle.

Description

Generates Discrete Prolate Spheroidal Sequences (DPSS) for a given series length and bandwidth. Uses an internal RcppEigen solver over the prolate matrix; suitable for moderate 'n_time'. For very long series, a tridiagonal solver can replace the backend with the same interface.

Usage

dpss_time_basis(
  n_time,
  tr,
  bandwidth,
  k = NULL,
  backend = c("tridiag", "dense")
)

Arguments

Value

Numeric matrix (n_time x k) with orthonormal columns.

Description

Encode data into a latent representation using a spec

Usage

encode(
  x,
  spec,
  mask,
  reduction = NULL,
  materialize = c("auto", "handle", "matrix"),
  label = "",
  ...
)

Arguments

Value

The return class depends on the spec family:

Explicit spatial families

'spec_space_slepian', 'spec_space_heat', 'spec_space_hrbf', 'spec_space_pca', and 'spec_space_wavelet_active' return a [LatentNeuroVec], which is a concrete 'ExplicitLatent' (the virtual marker defined at 'R/all_class.R'). It stores an explicit 'basis x loadings + offset' factorization.

Explicit temporal families

'spec_time_slepian', 'spec_time_dct', and 'spec_time_bspline' likewise return a [LatentNeuroVec] ('ExplicitLatent').

Spatiotemporal ('spec_st')

**Always** returns an 'ImplicitLatent' (a decoder-only / separable representation), even when both the time and space factors are fully explicit dense bases. 'ImplicitLatent' is *not* an 'ExplicitLatent'.

Transport ('spec_transport' / AWPT encoders)

return a 'TransportLatent', which is also *not* an 'ExplicitLatent'.

In short: 'ExplicitLatent' is the virtual S4 marker inherited by [LatentNeuroVec]; 'ImplicitLatent' and 'TransportLatent' are S3 classes that deliberately do not inherit it.

Dispatch model

For standard in-mask matrix encoders, 'encode()' routes to the S3 generic [encode_spec()], which dispatches on the spec class and builds the latent object directly. Transport-backed AWPT is the explicit exception: an AWPT basis spec is used to build a shared template, while the subject fit also requires a 'basis_asset' and 'field_operator'. Those assets are not part of the standard 'encode_spec()' signature, so AWPT enters through [encode_awpt()] or [encode_operator()] instead of [encode()].

Offset and centering contract

A [LatentNeuroVec] reconstructs its data as 'basis (length = number of in-mask voxels) added back after the low-rank term. The offset is owned by the encoder's *lift* step, which is the single place that decides whether and how to center:

Families that populate 'offset'

Only 'spec_space_pca' produces a non-empty offset, and only when 'center = TRUE' (the default): the per-voxel column means are removed before the PCA and stored in the 'offset' slot so reconstruction restores them. The mean removal is performed exactly once, inside 'lift.basis_pca' (see the 'fmrilatent.mean_scores' attribute it returns); the encode caller does not re-center. With 'center = FALSE', PCA stores 'offset = numeric(0)'.

Families that never center

All other explicit families ('spec_space_slepian', 'spec_space_heat', 'spec_space_hrbf', 'spec_time_slepian', 'spec_time_dct', 'spec_time_bspline') store 'offset = numeric(0)', i.e. no offset.

By convention 'offset = numeric(0)' means "no offset" and reconstruction treats it as a zero vector; a populated 'offset' always has one entry per in-mask voxel. The shared '.encode_center()' helper is the single implementation of column-mean centering used by the offset-producing paths.

Description

Encode data using the AWPT model

Usage

encode_awpt(
  x,
  basis_asset,
  field_operator = NULL,
  observation_operator = NULL,
  mask = NULL,
  domain = NULL,
  support = NULL,
  spatial_lambda = 0,
  temporal_lambda = 0,
  temporal_order = 1L,
  sparse_lambda = 0,
  sparse_mode = c("none", "group_l2", "lasso"),
  max_iter = 200L,
  tol = 1e-06,
  center = TRUE,
  run_info = NULL,
  label = "",
  ...
)

Arguments

Details

AWPT does not expose a separate ridge penalty. The returned metadata records lambda = 0; the anatomical roughness penalty is recorded separately as spatial_lambda.

Value

A TransportLatent object with AWPT metadata.

Description

Note: unlike parcel and AWPT encoding, hierarchical encoding does not center the data. The returned offset is always numeric(0).

Usage

encode_hierarchical(
  X,
  template,
  label = NULL,
  mask = NULL,
  materialize = c("handle", "auto", "matrix")
)

Arguments

Value

LatentNeuroVec with basis = time x atoms coefficients, loadings = template loadings

Description

Encode data using a shared basis asset and subject field operator

Usage

encode_operator(
  x,
  template,
  field_operator = NULL,
  observation_operator = NULL,
  mask = NULL,
  domain = NULL,
  support = NULL,
  lambda = 0,
  center = TRUE,
  run_info = NULL,
  spatial_lambda = lambda,
  spatial_penalty = NULL,
  temporal_lambda = 0,
  temporal_order = 1L,
  sparse_lambda = 0,
  sparse_mode = c("none", "group_l2", "lasso"),
  max_iter = 200L,
  tol = 1e-06,
  label = "",
  ...
)

Arguments

Details

The external field-operator contract is intentionally narrow. 'fmrilatent' consumes an operator-like object with:

n_source, n_target

Source and target dimensions.

source_domain_id, target_domain_id

Stable domain identifiers.

forward(z)

Applies the operator to template field samples.

adjoint_apply(y)

Applies the adjoint map.

provenance$target_mask

Optional target-domain mask when the caller does not pass mask explicitly.

On the main quadratic and sparse transport/AWPT paths, coefficient recovery is matrix-free: ‘fmrilatent' uses the operator’s forward and adjoint methods rather than materializing the full subject decoder.

Value

A TransportLatent object.

Description

Dispatch standard encoding based on spec type

Usage

encode_spec(x, spec, ...)

Arguments

Details

'encode_spec()' is the S3 dispatch seam for standard 'encode()' specs: temporal, spatial, hierarchical, parcel, and spatiotemporal specs. AWPT's 'basis_awpt_wavelet()' object is a template-construction spec, not a complete subject-encoding spec, because AWPT fitting additionally needs a shared template/basis asset and subject field or observation operators. AWPT therefore uses the parallel transport API [encode_awpt()] / [encode_operator()].

Value

Encoded representation.

Description

Encode data using transport-backed latent semantics

Usage

encode_transport(
  x,
  basis_asset,
  field_operator = NULL,
  observation_operator = NULL,
  mask = NULL,
  domain = NULL,
  support = NULL,
  lambda = 0,
  center = TRUE,
  run_info = NULL,
  spatial_lambda = lambda,
  spatial_penalty = NULL,
  temporal_lambda = 0,
  temporal_order = 1L,
  sparse_lambda = 0,
  sparse_mode = c("none", "group_l2", "lasso"),
  max_iter = 200L,
  tol = 1e-06,
  label = "",
  ...
)

Arguments

Value

A TransportLatent object.

Description

Evaluate BOLDZip-SR reconstruction quality

Usage

evaluate_boldzip_sr(X, object, reliability_weights = NULL)

Arguments

Value

Named numeric vector with reconstruction metrics.

Description

Returns the active fmrilatent compatibility profile. This is used to opt into strict behavior for external packages that require historical semantics.

Usage

fmrilatent_compat_profile(profile = NULL)

Arguments

Value

A single character string profile identifier.

Description

Removes cached materialized matrices from the internal registry. Use this to free memory or force re-materialization of handles.

Usage

fmrilatent_registry_clear(type = c("all", "basis", "loadings"))

Arguments

Value

Invisibly, the number of entries removed.

Examples

# Clear all cached matrices
fmrilatent_registry_clear()

# Clear only basis matrices
fmrilatent_registry_clear("basis")

Description

The handle registry caches materialized matrices for BasisHandle and LoadingsHandle objects. This can improve performance and reduce memory duplication when multiple LatentNeuroVec objects share the same handle IDs.

Usage

fmrilatent_registry_enable()

fmrilatent_registry_disable()

fmrilatent_registry_enabled()

Details

Set fmrilatent_registry_disable() to turn off caching (useful for deterministic benchmarking or to avoid retaining large matrices).

Value

Invisibly, TRUE.

Capacity

The cache is bounded. Each registry (basis and loadings) holds at most getOption("fmrilatent.registry.max_entries", 256) materialized matrices; once full, the least-recently-used entry is evicted on the next registration. Both registration and retrieval count as a use. Set the option to Inf (or a non-positive value) to restore an unbounded cache, or call fmrilatent_registry_clear() to drop everything immediately.

Examples

fmrilatent_registry_disable()
fmrilatent_registry_enable()

Description

Returns the IDs of all cached matrices in the registry.

Usage

fmrilatent_registry_list(type = c("all", "basis", "loadings"))

Arguments

Value

Character vector of registered IDs.

Examples

# See what's cached
fmrilatent_registry_list()

Description

Returns count and approximate memory usage of cached matrices.

Usage

fmrilatent_registry_stats(type = c("all", "basis", "loadings"))

Arguments

Value

A list with count and bytes for each registry type.

Examples

fmrilatent_registry_stats()

Description

Creates a small synthetic dataset suitable for testing encode_spec methods. Useful for extension packages that implement custom encoders.

Usage

fmrilatent_test_data(dims = c(3L, 3L, 2L), n_time = 8L)

Arguments

Value

A list with elements:

Examples

td <- fmrilatent_test_data()
dim(td$X)        # 8 x 18
dim(td$mask)     # 3 x 3 x 2

Description

Retrieves the registration entry for a given encoder family.

Usage

get_encoder(family)

Arguments

Value

A list with elements spec_fn, description, and package.

Examples

enc <- get_encoder("time_dct")
spec <- enc$spec_fn(k = 5)

Description

These classes describe how voxels are grouped or coarsened before a basis is computed and lifted back to ambient space. Implementations of 'lift()' for specific combinations (e.g., supervoxel + Slepian, parcel PCA) live in external packages or downstream code; fmrilatent ships only the contracts.

Slots

mask

'LogicalNeuroVol' defining the ambient domain.

info

Optional list for implementation-specific metadata.

Description

Represent subject loadings as group shared loadings plus a delta

Usage

group_delta_loadings(group, delta = NULL, scale = 1, id = NULL, meta = list())

Arguments

Value

A 'GroupDeltaLoadings' object.

Description

Build Haar latent representation

Usage

haar_latent(
  X,
  mask,
  levels = NULL,
  z_seed = 42L,
  threshold = list(type = "none", value = 0)
)

Arguments

Value

An object of class 'HaarLatent' containing coefficients and metadata.

Description

Get metadata from Haar latent object

Usage

haar_meta(x)

Arguments

Value

Metadata list or NULL

Description

Forward Haar wavelet transform (mask-adaptive, Morton order)

Usage

haar_wavelet_forward(
  X,
  mask,
  levels = NULL,
  z_seed = 42L,
  threshold = list(type = "none", value = 0)
)

Arguments

Value

List with elements 'coeff' (list(root, detail)), 'meta' (counts, Morton hash, etc.).

Description

Inverse Haar wavelet transform

Usage

haar_wavelet_inverse(
  coeff,
  mask,
  levels = NULL,
  z_seed = NULL,
  roi_mask = NULL,
  time_idx = NULL,
  levels_keep = NULL
)

Arguments

Value

Matrix (time x voxels) reconstructed (or subsetted if ROI/time specified).

Description

Heat wavelet latent constructor (explicit basis)

Usage

heat_wavelet_latent(
  X,
  mask,
  reduction = NULL,
  spec = basis_heat_wavelet(),
  k_neighbors = 6L,
  label = ""
)

Arguments

Value

A 'LatentNeuroVec' object.

Description

Wraps a heat-wavelet 'lift()' call so multiple 'LatentNeuroVec' instances can share the same spatial dictionary without embedding the full matrix in each object.

Usage

heat_wavelet_loadings_handle(
  reduction,
  basis_spec = basis_heat_wavelet(),
  data = NULL,
  k_neighbors = 6L,
  id = NULL,
  label = "heat-wavelet"
)

Arguments

Value

A LoadingsHandle.

Description

A template-only, data-agnostic container for hierarchical Laplacian frames. Stores the sparse spatial dictionary (primal basis), a cached solver for the Gram matrix, and the parcellation hierarchy metadata. Intended to be built offline for a fixed template (e.g., MNI) and reused for encoding fMRI data.

Slots

mask

LogicalNeuroVol defining the domain (3D).

space

NeuroSpace (typically 4D with a singleton time dim) matching the mask.

levels

List of integer vectors (one per level) giving parcel ids per voxel (mask order).

parents

List mapping child parcel ids to parent ids for each level > 1.

loadings

Sparse Matrix (voxels x atoms) containing concatenated atoms B.

gram_factor

Cached factorization of $G = t(B) \%*\% B$ (e.g., dCHMsimpl from Matrix::Cholesky).

atoms

data.frame describing each atom (col_id, level, parcel_id, parent_id, mode, label).

meta

List for auxiliary metadata (atlas names, k_per_level, ridge, version).

Description

Utilities to generate analytic HRBF bases, project data, reconstruct, and build 'LatentNeuroVec' objects. Parameters are kept simple and in-R only (no descriptors or HDF5).

Usage

hrbf_generate_basis(params, mask)

hrbf_project_matrix(X, mask, params)

hrbf_reconstruct_matrix(coeff, mask, params)

Arguments

Value

For 'hrbf_generate_basis', a sparse matrix with one row per HRBF atom and columns matching mask voxels.

Description

Build a LatentNeuroVec using an HRBF basis

Usage

hrbf_latent(X, mask, params = list(), label = "")

Arguments

Value

A 'LatentNeuroVec' with 'basis = coefficients', 'loadings = t(HRBF_basis)'.

Description

Retrieve HRBF metadata if present

Usage

hrbf_meta(x)

Arguments

Value

HRBF metadata list or NULL if not HRBF-tagged

Description

Computes only the requested voxels (and optional timepoints) without materializing the full dense volume. Useful for fast indexed access.

Usage

hrbf_reconstruct_partial(coeff, mask, params, voxel_idx, time_idx = NULL)

Arguments

Value

Matrix of shape length(time_idx) x length(voxel_idx).

Description

Construct an ImplicitLatent object

Usage

implicit_latent(
  coeff,
  decoder,
  meta,
  mask = NULL,
  domain = NULL,
  support = NULL
)

Arguments

Value

An object of class 'ImplicitLatent'.

Description

Get metadata from ImplicitLatent object

Usage

implicit_meta(x)

Arguments

Value

Metadata list or NULL

Description

Test whether a latent object is explicit

Usage

is_explicit_latent(x, ...)

## S4 method for signature 'ExplicitLatent'
is_explicit_latent(x, ...)

## S4 method for signature 'ImplicitLatent'
is_explicit_latent(x, ...)

Arguments

Value

Logical scalar; TRUE when the object stores explicit basis and loadings matrices.

Description

Test if object is a Haar latent representation

Usage

is_haar_latent(x)

Arguments

Value

Logical indicating if x is a Haar latent

Description

Check whether an object is a HierarchicalBasisTemplate

Usage

is_hierarchical_template(x)

Arguments

Value

Logical scalar.

Description

Check if latent object carries HRBF metadata

Usage

is_hrbf_latent(x)

Arguments

Value

Logical indicating if x has HRBF metadata

Description

Test if object is an ImplicitLatent

Usage

is_implicit_latent(x)

Arguments

Value

Logical indicating if x is an ImplicitLatent

Description

Test whether an object is a shared reference

Usage

is_shared_reference(x)

Arguments

Value

Logical scalar.

Description

Test whether an object is a surface basis template

Usage

is_surface_template(x)

Arguments

Value

Logical scalar.

Description

Test whether an object is a supported template

Usage

is_template(x)

Arguments

Value

Logical scalar.

Description

Test whether an object is a transport-backed latent object

Usage

is_transport_latent(x)

Arguments

Value

Logical scalar.

Description

Builds a LatentNeuroVec whose loadings are a heat-wavelet LoadingsHandle and whose basis is a placeholder zero matrix of n_time x k (where k is determined by the heat-wavelet loadings, not by the caller). The caller is expected to overwrite lvec@basis with real coefficients (e.g. fitted from data) before the object represents a valid factorization.

Usage

latent_dct_heatwavelet(
  n_time,
  k_time = NULL,
  mask,
  cluster_map = NULL,
  reduction = NULL,
  hw_basis_spec = NULL,
  offset = numeric(0),
  label = "DCT + heat-wavelet"
)

Arguments

Details

Despite the name, no DCT basis is constructed: the "dct" reference predates the spec/encoder pipeline and is retained for API compatibility. For an encoded DCT-temporal + heat-wavelet-spatial pipeline see spec_st(time = spec_time_dct(...), space = spec_space_heat(...)) passed to encode.

Value

A LatentNeuroVec with placeholder basis matrix.

Description

Extract the decoded domain associated with a latent object

Usage

latent_domain(x, ...)

## S4 method for signature 'ImplicitLatent'
latent_domain(x, ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
latent_domain(x, ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
latent_domain(x, ...)

## S4 method for signature 'BlockLatentNeuroVector'
latent_domain(x, ...)

## S4 method for signature 'LatentNeuroVec'
latent_domain(x, ...)

Arguments

Value

Domain object or identifier.

Description

Simple factory to build a spec and encode in one call

Usage

latent_factory(
  family,
  x,
  mask,
  reduction = NULL,
  ...,
  materialize = "auto",
  label = ""
)

Arguments

Value

The class follows the same per-family contract as [encode()]: explicit spatial families and explicit temporal families return a [LatentNeuroVec] (a concrete 'ExplicitLatent'); the spatiotemporal families ('st_slepian', 'st_bspline_hrbf') build a 'spec_st' and therefore always return an 'ImplicitLatent'. See the '@return' section of [encode()] for the full taxonomy.

Accepted family names

Canonical names are listed first; aliases in parentheses are accepted for compatibility.

Temporal

'time_dct' ('dct_time'), 'time_slepian' ('slepian_time').

Spatial

'space_slepian' ('slepian_space'), 'space_pca' ('pca_space'), 'space_parcel' ('parcel_space'), 'space_heat' ('heat_space'), 'space_hrbf' ('hrbf_space'), 'space_wavelet_active' ('wavelet_active'), and 'hierarchical'.

Spatiotemporal

'st' (requires explicit 'time' and 'space' specs), 'st_slepian' ('slepian_st'), and 'st_bspline_hrbf' ('bspline_hrbf_st').

AWPT is intentionally not a 'latent_factory()' family because it requires a shared 'basis_asset' and a subject 'field_operator'; use [encode_awpt()] or [encode_operator()] for AWPT subject fitting.

Description

Get lightweight metadata from a latent object

Usage

latent_meta(x, ...)

## S4 method for signature 'ImplicitLatent'
latent_meta(x, ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
latent_meta(x, ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
latent_meta(x, ...)

## S4 method for signature 'BlockLatentNeuroVector'
latent_meta(x, ...)

## S4 method for signature 'LatentNeuroVec'
latent_meta(x, ...)

Arguments

Value

Metadata list.

Description

Runs a user-supplied function 'fun' for each neighborhood using only latent quantities. 'fun' is called with arguments '(B, L_V, M_V, idx, ...)', where: - 'B' is the basis matrix (time x k) - 'L_V' is the loadings restricted to the neighborhood (|V| x k) - 'M_V = t(L_V) - 'idx' is the voxel indices of the neighborhood 'fun' should return any R object; results are collected in a list.

Usage

latent_searchlight(basis, loadings, neighborhoods, fun, ...)

Arguments

Value

List of results, one per neighborhood.

Description

Extract the decoded support associated with a latent object

Usage

latent_support(x, ...)

## S4 method for signature 'ImplicitLatent'
latent_support(x, ...)

## S4 method for signature 'LatentNeuroSurfaceVector'
latent_support(x, ...)

## S4 method for signature 'BilatLatentNeuroSurfaceVector'
latent_support(x, ...)

## S4 method for signature 'BlockLatentNeuroVector'
latent_support(x, ...)

## S4 method for signature 'LatentNeuroVec'
latent_support(x, ...)

Arguments

Value

Support object for the latent representation.

Description

Construct a LatentNeuroSurfaceVector

Usage

LatentNeuroSurfaceVector(
  basis,
  loadings,
  geometry,
  support = NULL,
  offset = NULL,
  label = "",
  meta = list()
)

Arguments

Value

A LatentNeuroSurfaceVector.

Description

An explicit latent representation for surface-domain neuroimaging data. The data are stored as a temporal basis matrix and a surface loadings matrix over a supported set of vertices on a neurosurf geometry.

Slots

basis

A Matrix or BasisHandle with dimensions (nTime x k).

loadings

A Matrix or LoadingsHandle with dimensions (nVerticesInSupport x k).

offset

Optional numeric vector of length nVerticesInSupport.

geometry

Surface domain object, typically a neurosurf::SurfaceGeometry or neurosurf::SurfaceSet.

support

Integer vector of vertex indices within geometry.

label

Character label.

meta

Lightweight metadata list.

Description

Constructs a LatentNeuroVec-class object, which provides a memory-efficient representation of neuroimaging data using matrix factorization. This is particularly useful for dimensionality reduction techniques (e.g., PCA or ICA).

Usage

LatentNeuroVec(
  basis,
  loadings,
  space,
  mask,
  offset = NULL,
  label = "",
  meta = list(),
  expect_dense = FALSE
)

Arguments

Details

Construct a LatentNeuroVec Object

The data is represented as the product:

$X = B \times L^T + c$

where:

• B is the basis matrix ($n \times k$)

• L is the loadings matrix ($p \times k$)

• c is an optional offset vector (length p)

• n is the number of time points

• p is the number of voxels in the mask

• k is the number of components

Value

A new LatentNeuroVec-class instance.

Examples

# Example data
n_timepoints <- 4
n_components <- 2
mask_array <- array(TRUE, dim = c(2, 2, 1))
n_voxels <- sum(mask_array)

# Create basis & loadings
basis <- Matrix::Matrix(seq_len(n_timepoints * n_components),
  nrow = n_timepoints,
  ncol = n_components
)
loadings <- Matrix::Matrix(seq_len(n_voxels * n_components) / 10,
  nrow = n_voxels,
  ncol = n_components,
  sparse = TRUE
)

# Create space (2x2x1 volume, 4 timepoints)
spc <- neuroim2::NeuroSpace(c(2, 2, 1, n_timepoints))

# Create mask
mask_vol <- neuroim2::LogicalNeuroVol(mask_array, neuroim2::NeuroSpace(c(2, 2, 1)))

# Construct LatentNeuroVec
lvec <- LatentNeuroVec(
  basis = basis,
  loadings = loadings,
  space = spc,
  mask = mask_vol,
  expect_dense = TRUE
)
dim(lvec)

Description

A class that represents a 4-dimensional neuroimaging array using a latent space decomposition. It stores the data as a set of basis functions (dictionary) and a corresponding set of loadings (coefficients), enabling efficient representation and manipulation of high-dimensional data.

Details

LatentNeuroVec inherits from NeuroVec-class and AbstractSparseNeuroVec-class. The original 4D data can be reconstructed as:

$data[v,t] = \sum_k \bigl(basis[t,k] \times loadings[v,k]\bigr) + offset[v]$

where v indexes voxels within the mask and t indexes time points.

This approach is especially useful for large datasets where storing the full 4D array is expensive. Common use cases include:

• PCA-reduced fMRI data

• ICA decompositions

• Dictionary learning representations

• Any matrix factorization of neuroimaging data

Slots

basis

A Matrix or BasisHandle where each column represents a basis vector in the latent space. Dimensions are (nTime x k) where k is the number of components.

loadings

A Matrix or LoadingsHandle (often sparse) containing the coefficients for each basis vector across the spatial dimensions. Dimensions are (nVoxels x k).

offset

A numeric vector representing a constant offset term for each voxel or spatial location. Length is nVoxels (within mask).

map

A IndexLookupVol object representing the mapping from 3D coordinates to linear indices within the mask.

label

A character string representing the label for the latent vector.

meta

A list storing lightweight metadata (e.g., HRBF params, centers).

Inheritance

LatentNeuroVec inherits from:

• NeuroVec-class - base 4D neuroimaging class

• AbstractSparseNeuroVec-class - sparse representation framework

See Also

NeuroVec-class, AbstractSparseNeuroVec-class, LatentNeuroVec constructor function.

Examples

n_timepoints <- 4
n_components <- 2
mask_array <- array(TRUE, dim = c(2, 2, 1))
n_voxels <- sum(mask_array)

# Create basis (temporal) & loadings (spatial)
basis <- Matrix::Matrix(seq_len(n_timepoints * n_components),
  nrow = n_timepoints, ncol = n_components
)
loadings <- Matrix::Matrix(seq_len(n_voxels * n_components) / 10,
  nrow = n_voxels, ncol = n_components, sparse = TRUE
)

# Create space (2x2x1 volume, 4 timepoints)
spc <- neuroim2::NeuroSpace(c(2, 2, 1, n_timepoints))

# Create mask
mask_vol <- neuroim2::LogicalNeuroVol(mask_array, neuroim2::NeuroSpace(c(2, 2, 1)))

# Construct LatentNeuroVec
lvec <- LatentNeuroVec(
  basis = basis,
  loadings = loadings,
  space = spc,
  mask = mask_vol,
  expect_dense = TRUE
)

dim(lvec)

Description

Lift reduced bases back to voxel space (abstract generic)

Usage

lift(reduction, basis_spec, data = NULL, ...)

Arguments

Value

Typically a voxel x components 'Matrix' (often sparse) or an implementation-defined object for implicit decoders.

Description

Lift diffusion wavelets for clustered reduction

Usage

## S4 method for signature 'ClusterReduction,spec_diffusion_wavelet'
lift(reduction, basis_spec, data = NULL, k_neighbors = 6L, ...)

Arguments

Value

Matrix of loadings (voxels x components) concatenating scaling bases across scales.

Description

Lift heat wavelets for clustered reduction

Usage

## S4 method for signature 'ClusterReduction,spec_heat_wavelet'
lift(reduction, basis_spec, data = NULL, k_neighbors = 6L, ...)

Arguments

Value

Sparse Matrix (voxels x components).

Description

Computes PCA eigenvectors within each cluster and assembles a global block-sparse loadings matrix (voxels x components). This is typically used with 'encode(..., spec_space_pca(...), reduction = ...)'.

Usage

## S4 method for signature 'ClusterReduction,spec_pca'
lift(
  reduction,
  basis_spec,
  data = NULL,
  center = TRUE,
  scale = FALSE,
  offset = NULL,
  backend = c("auto", "svds", "svd"),
  ...
)

Arguments

Details

'lift(ClusterReduction, spec_pca)' always returns unwhitened spatial loadings. If 'basis_spec$whiten' is 'TRUE', the method emits a classed warning because whitening requires the projected temporal scores and is therefore the caller's responsibility. The standard 'encode(..., spec_space_pca(whiten = TRUE))' path handles this post-lift whitening using the 'fmrilatent.singular_values' attribute attached here.

Value

A sparse Matrix (voxels x components) with attribute 'fmrilatent.singular_values' giving per-component singular values.

Description

Lift spatial Slepians for clustered reduction

Usage

## S4 method for signature 'ClusterReduction,spec_slepian'
lift(reduction, basis_spec, data = NULL, k_neighbors = 6L, ...)