ROI-by-ROI similarity through a correlated model-RDM space

Projects ROI RDM vectors into the subspace spanned by one or more model RDMs, decorrelates that model space, and compares ROIs through their model-space fingerprints.

Usage

rdm_model_space_connectivity(
  roi_rdms,
  model_rdms,
  method = c("pearson", "spearman"),
  basis = c("pca", "qr"),
  use = c("complete.obs", "everything"),
  tol = 1e-08,
  return_projected = FALSE
)

Arguments

roi_rdms

ROI RDM vectors. Accepted forms are a matrix with RDM cells in rows and ROIs in columns, a named list of numeric vectors, a tibble/data frame with columns `roinum` and `rdm_vec` as returned by feature_rsa_rdm_vectors, or a `regional_mvpa_result` containing stored feature-RSA RDM vectors.

model_rdms

Named list of square symmetric model RDM matrices or `dist` objects, or a numeric matrix with RDM cells in rows and model RDMs in columns.

method

Similarity scale used before projection. `"pearson"` centers and scales numeric RDM values. `"spearman"` rank-transforms each RDM vector before centering and scaling.

basis

Basis for the model subspace. `"pca"` orders orthogonal axes by variance in the model-RDM correlation matrix. `"qr"` uses a QR basis tied to the supplied model order.

use

Missing-value policy. `"complete.obs"` removes RDM cells with any non-finite model or ROI value before fitting the subspace. `"everything"` requires all model and ROI vectors to be finite.

tol

Numerical tolerance for dropping near-zero model-space dimensions and detecting zero-norm ROI fingerprints.

return_projected

Logical; if `TRUE`, include the projected ROI RDM vectors and residual ROI RDM vectors in the returned object.

Value

An object of class `rdm_model_space_connectivity`, a list with:

similarity

Strength-sensitive ROI-by-ROI similarity through the full model-RDM subspace.

profile_similarity

Cosine similarity between ROI model-space fingerprints, ignoring overall model-alignment strength.

component_similarity

Named list of rank-1 ROI-by-ROI matrices, one per orthogonal model-space axis.

common_similarity

The first component matrix, useful for the shared model axis under `basis = "pca"`.

difference_similarity

Sum of all components after the first.

raw_similarity

Second-order ROI similarity before model projection.

residual_similarity

ROI similarity outside the model-RDM subspace.

scores

ROI-by-axis fingerprint matrix `F`.

raw_model_scores

ROI-by-original-model correlation matrix.

model_axis_cor

Correlation of orthogonal model axes with original model RDMs, used to interpret the axes.

Details

This helper implements a projection-based second-order RSA summary for the common situation where several model RDMs are correlated. Let `Y` be the lower-triangle ROI RDM matrix, with RDM cells in rows and ROIs in columns, and let `X` be the corresponding matrix of model RDM vectors. After optional rank transformation and column standardization, the function builds an orthonormal basis `Q` for the column space of `X` and computes

$$F = Y' Q / \sqrt{p - 1}$$

where `p` is the number of retained RDM cells. Rows of `F` are decorrelated ROI model-space fingerprints. The strength-sensitive ROI-by-ROI similarity is

$$S_{model} = F F'$$

which is equivalent to \(Y' P_X Y / (p - 1)\). The profile-only similarity is the cosine similarity between rows of `F`.

With `basis = "pca"`, the first component is often the common model axis when all model RDMs are positively correlated, and later components describe differentiating model contrasts. With `basis = "qr"`, the axes are an orthonormal basis generated by QR decomposition of the supplied model order.

Examples

set.seed(1)
n <- 8
p <- n * (n - 1) / 2
model_vecs <- matrix(rnorm(p * 4), p, 4)
colnames(model_vecs) <- paste0("A", 1:4)
roi_vecs <- model_vecs %*% matrix(rnorm(4 * 5), 4, 5) +
  matrix(rnorm(p * 5, sd = 0.2), p, 5)
colnames(roi_vecs) <- paste0("ROI", 1:5)

conn <- rdm_model_space_connectivity(roi_vecs, model_vecs)
conn$similarity
#>            ROI1       ROI2       ROI3       ROI4       ROI5
#> ROI1  0.9828789 -0.4215346 -0.5154275 -0.4050547 -0.4734135
#> ROI2 -0.4215346  0.9252946 -0.1675376 -0.2787804  0.7322710
#> ROI3 -0.5154275 -0.1675376  0.9770389  0.9094047  0.0851772
#> ROI4 -0.4050547 -0.2787804  0.9094047  0.8911083 -0.1190169
#> ROI5 -0.4734135  0.7322710  0.0851772 -0.1190169  0.9609832