Internal helper function to compute the Nyström extension basis for projecting voxel-level data into a parcel-defined spectral space. This function uses a k-nearest neighbors approach and a Gaussian kernel to create an affinity matrix between voxels and parcels, then applies the Nyström formula.
Usage
compute_voxel_basis_nystrom(
voxel_coords,
parcel_coords,
U_orig_parcel,
Lambda_orig_parcel,
n_nearest_parcels = 10,
kernel_sigma = 5,
row_normalize_W = TRUE,
eigenvalue_floor = 1e-08,
W_vox_parc = NULL,
...
)Arguments
- voxel_coords
A numeric matrix (V_v x 3) of voxel coordinates.
- parcel_coords
A numeric matrix (V_p x 3) of parcel centroid coordinates.
- U_orig_parcel
A numeric matrix (V_p x k) of the subject's original parcel-level eigenvectors (spectral sketch).
- Lambda_orig_parcel
A numeric vector of length k, representing the subject's original parcel-level eigenvalues. Values should be positive.
- n_nearest_parcels
An integer, the number of nearest parcels (k_nn) to consider for each voxel when constructing the affinity matrix *if* `W_vox_parc` is not provided. Must be at least 1 and cannot exceed the number of parcels (`nrow(parcel_coords)`). Ignored if `W_vox_parc` is provided.
- kernel_sigma
A numeric scalar, the bandwidth (sigma) for the Gaussian kernel, or the string \"auto\". Used only *if* `W_vox_parc` is not provided. If \"auto\", sigma is estimated as `median(dist_to_1st_nn_parcel) / sqrt(2)`, where `dist_to_1st_nn_parcel` are the Euclidean distances from each voxel to its closest parcel centroid. A fallback value (e.g., 1.0) is used if auto-estimation is not possible. Defaults to 5.0. Ignored if `W_vox_parc` is provided.
- row_normalize_W
A logical. Controls whether the effective affinity matrix (`W_vox_parc`, either computed internally or provided) is row-normalized before computing Phi_voxel. The core HATSA algorithm uses an alpha-lazy random-walk normalized Laplacian (`L_rw_lazy`), and for consistency, the standard Nyström extension involves row-normalizing the voxel-parcel affinities. Defaults to `TRUE`.
- eigenvalue_floor
A small positive numeric value to floor near-zero eigenvalues before inversion. Defaults to 1e-8.
- W_vox_parc
Optional. A pre-computed sparse matrix (dgCMatrix, V_v x V_p) representing voxel-to-parcel affinities or weights. If provided, the function will skip the internal k-NN search and Gaussian kernel calculation and use this matrix directly. It must have dimensions V_v x V_p. Default is `NULL`, triggering internal calculation.
- ...
Additional arguments (currently unused).
Value
A dense numeric matrix Phi_voxel (V_v x k), representing the
Nyström basis for voxels. Note: For large numbers of voxels (V_v) and/or
components (k), this matrix can be memory-intensive (e.g., V_v=400k, k=50
using 8-byte doubles is ~153MB).
Examples
# V_p <- 100; V_v <- 500; k <- 10; n_nearest <- 5; sigma <- 5
# p_coords <- matrix(rnorm(V_p*3), V_p, 3)
# v_coords <- matrix(rnorm(V_v*3), V_v, 3)
# U_p <- matrix(rnorm(V_p*k), V_p, k)
# L_p <- runif(k, 0.1, 1)
# if (requireNamespace("RANN", quietly = TRUE) &&
# requireNamespace("Matrix", quietly = TRUE)) {
# Phi_v <- compute_voxel_basis_nystrom(v_coords, p_coords, U_p, L_p,
# n_nearest, sigma)
# # dim(Phi_v) # Should be V_v x k
# }