View source: R/contrast_rsa_model.R
contrast_rsa_model | R Documentation |
Creates a contrast_rsa_model specification object, which encapsulates the necessary parameters and design information for a Multi-Dimensional Signed Representational Voxel Encoding (MS-ReVE) style analysis.
contrast_rsa_model(
dataset,
design,
estimation_method = "average",
regression_type = "lm",
output_metric = c("beta_delta"),
check_collinearity = FALSE,
normalize_delta = FALSE,
allow_nonorth_composite = FALSE,
calc_reliability = FALSE,
whitening_matrix_W = NULL,
...
)
dataset |
An object of class |
design |
An object of class |
estimation_method |
Character string specifying the method to estimate
cross-validated condition means (
Passed to |
regression_type |
Character string specifying the method for the RSA regression
(regressing empirical RDM/Second Moment Matrix onto contrast RDMs). Options align
with |
output_metric |
Character vector specifying one or more output metrics to compute. Multiple metrics can be requested simultaneously and will be returned in a named list. Duplicates are removed while preserving the order of first occurrence. Supported options:
Default is |
check_collinearity |
Logical, whether to check for collinearity among contrast RDMs
when using |
normalize_delta |
Logical. If TRUE, the voxel contribution vector (delta_q,v)
is normalized to unit L2 norm before being potentially multiplied by beta_q
for the "beta_delta" output metric. Default is |
allow_nonorth_composite |
Logical. If FALSE (default) the composite metric will return NA when the contrast matrix is not orthonormal, to avoid mis-interpretation. If TRUE, the composite score is returned regardless, but a warning is still emitted. |
calc_reliability |
Logical. If TRUE, voxel-wise contribution reliability (ρ
values) are estimated across cross-validation folds during training and can
be incorporated into the output metrics. Default is |
whitening_matrix_W |
Optional V x V numeric matrix (voxels x voxels). Required if
'estimation_method = "crossnobis"' and Mahalanobis (rather than Euclidean)
distances are desired. This matrix (e.g., |
... |
Additional arguments passed to |
This model is designed for MS-ReVE style analyses where the goal is to understand how different predefined contrasts contribute to the representational structure observed in neural data, particularly at a fine-grained (e.g., voxel) level. It involves: 1. Estimating cross-validated condition mean patterns (Û) or distances (for Crossnobis). 2. Constructing an empirical second-moment matrix (Ĝ) from Û or using the Crossnobis distances directly. 3. Creating theoretical second-moment matrices (RDMs) from each contrast vector. 4. Regressing the vectorized empirical RDM/distances onto the vectorized contrast RDMs to get β coefficients. 5. Projecting voxel patterns (from Û) onto the contrast space to get Δ (delta) values. 6. Combining β and Δ to form the final output metric (e.g., beta_delta).
**Cross-Validation Compatibility:** The 'estimation_method' relies on 'compute_crossvalidated_means_sl' which, in turn, requires the cross-validation specification ('cv_spec' derived from 'mvpa_design$crossval') to provide a deterministic, partition-based set of training indices for each fold. Therefore, cross-validation schemes like 'bootstrap_blocked_cross_validation' (which use resampling with replacement for training folds) are **not suitable** for use with this model, as they do not align with the assumptions of 'compute_crossvalidated_means_sl'. Schemes like 'blocked_cross_validation', 'kfold_cross_validation', and 'custom_cross_validation' (that define clear partitions) are appropriate. For 'twofold_blocked_cross_validation' and 'sequential_blocked_cross_validation', their compatibility also depends on whether their 'train_indices' methods can deterministically define training sets for each fold iterated by 'compute_crossvalidated_means_sl'.
An object of class contrast_rsa_model
, mvpa_model_spec
,
model_spec
, and list
.
\link{msreve_design}
, \link{train_model.contrast_rsa_model}
, \link{run_searchlight}
# --- Minimal Setup ---
# 1. Create dummy data and an mvpa_dataset
# Dummy data: 16 samples, 10 voxels, 4 conditions, 2 runs
set.seed(123)
n_samples <- 16
n_voxels <- 10
n_conditions <- 4 # condA, condB, condC, condD
n_runs <- 2
dummy_sl_data <- matrix(rnorm(n_samples * n_voxels), n_samples, n_voxels)
colnames(dummy_sl_data) <- paste0("V", 1:n_voxels)
dummy_mask <- neuroim2::NeuroVol(array(1, c(2,2,2)), neuroim2::NeuroSpace(c(2,2,2)))
condition_labels <- factor(rep(paste0("cond", LETTERS[1:n_conditions]), each = n_samples / n_conditions))
run_labels <- factor(rep(1:n_runs, each = n_samples / n_runs))
# Create mvpa_dataset (without Y and block_var)
mvpa_dat <- rMVPA::mvpa_dataset(
train_data = dummy_sl_data,
mask = dummy_mask
)
# Create mvpa_design
mvpa_des <- rMVPA::mvpa_design(
train_design = data.frame(condition = condition_labels, run = run_labels),
y_train = ~condition,
block_var = ~run
)
K <- mvpa_des$ncond # Use mvpa_des here
C_mat <- matrix(0, nrow = K, ncol = 2)
rownames(C_mat) <- levels(mvpa_des$Y) # Use mvpa_des here
C_mat["condA", 1] <- 1; C_mat["condB", 1] <- 1
C_mat["condC", 1] <- -1; C_mat["condD", 1] <- -1
C_mat["condA", 2] <- 1; C_mat["condB", 2] <- -1
C_mat <- scale(C_mat, center = TRUE, scale = FALSE)
colnames(C_mat) <- c("AB_vs_CD", "A_vs_B")
msreve_des <- rMVPA::msreve_design(
mvpa_design = mvpa_des, # Use mvpa_des here
contrast_matrix = C_mat
)
# --- Example 1: Basic contrast_rsa_model ---
model_basic <- contrast_rsa_model(
dataset = mvpa_dat,
design = msreve_des
)
print(model_basic)
# --- Example 1b: Requesting multiple metrics ---
model_multi_metric <- contrast_rsa_model(
dataset = mvpa_dat,
design = msreve_des,
output_metric = c("beta_delta", "recon_score", "beta_only")
)
print(model_multi_metric)
# --- Example 2: Using L2_norm for U_hat and normalize_delta ---
model_l2_norm_delta <- contrast_rsa_model(
dataset = mvpa_dat,
design = msreve_des,
estimation_method = "L2_norm",
normalize_delta = TRUE,
output_metric = "beta_delta_norm"
)
print(model_l2_norm_delta)
# --- Example 3: Ridge Regression (HKB) ---
model_ridge <- contrast_rsa_model(
dataset = mvpa_dat,
design = msreve_des,
regression_type = "ridge_hkb"
)
print(model_ridge)
# --- Example 4: Reconstruction Score Output ---
model_recon <- contrast_rsa_model(
dataset = mvpa_dat,
design = msreve_des,
output_metric = "recon_score"
)
print(model_recon)
# --- Example 5: Composite Score Output ---
C_mat_ortho <- rMVPA::orthogonalize_contrasts(C_mat)
msreve_des_ortho <- rMVPA::msreve_design(
mvpa_design = mvpa_des, # Use mvpa_des here
contrast_matrix = C_mat_ortho
)
print(paste("Is contrast matrix orthonormal:", attr(msreve_des_ortho, "is_orthonormal")))
model_composite <- contrast_rsa_model(
dataset = mvpa_dat,
design = msreve_des_ortho,
output_metric = "composite",
normalize_delta = TRUE
)
print(model_composite)
# --- Example 6: Crossnobis estimation_method ---
# This only shows setting the method. Actual training would require passing
# a pre-computed whitening_matrix_W to compute_crossvalidated_means_sl,
# which is called by train_model.contrast_rsa_model.
model_crossnobis <- contrast_rsa_model(
dataset = mvpa_dat,
design = msreve_des,
estimation_method = "crossnobis"
)
print(model_crossnobis)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.