Construct a design for an RSA (Representational Similarity Analysis) model

This function constructs a design for an RSA model using the provided formula, data, and optional parameters.

Usage

rsa_design(
  formula,
  data,
  block_var = NULL,
  split_by = NULL,
  keep_intra_run = FALSE,
  nuisance = list(),
  pair_mask = NULL,
  condition_ids = NULL
)

Arguments

formula: A formula expression specifying the dissimilarity-based regression function.
data: A named list containing the dissimilarity matrices and any other auxiliary variables.
block_var: An optional formula, character name or integer vector designating the block structure.
split_by: An optional formula indicating grouping structure for evaluating test performance.
keep_intra_run: A logical indicating whether to include within-run comparisons (default: FALSE).
nuisance: Optional named list of nuisance RDMs or item-level variables using the same accepted forms as entries in data. These predictors are appended to the RSA model matrix, included in regression fits, and tagged as nuisance so rsa_model(..., return_fingerprint = TRUE) excludes them from model-space fingerprints.
pair_mask: Optional logical vector in dist/lower-triangle order, or symmetric item-by-item logical matrix with a FALSE diagonal. TRUE retains that distinct-item pair. Missing values, wrong dimensions and empty selections are rejected. Intersects the existing block_var exclusion and applies identically to neural responses, predictors, nuisance terms and diagnostics. Included predictor/nuisance cells must be finite. split_by does not restrict fitted pairs. For within-recording comparisons, use a mask built from recording equality; block_var alone excludes same-block pairs.
condition_ids: Optional unique IDs in the exact order of design items. Required for crossvalidated Euclidean RSA. Named RDMs and masks must match this order; these IDs identify conditions, not runs or repeated observations.

Value

A list with class attributes "rsa_design" and "list", containing:

formula: The input formula
data: The input data
split_by: The split_by formula
split_groups: Grouping structure for split_by
block_var: Block structure
include: Logical vector for including/excluding comparisons
model_mat: Model matrix generated by rsa_model_mat
model_predictors: Sanitized names of formula predictors
nuisance_predictors: Sanitized names of nuisance predictors

Details

The function creates an RSA design based on the input parameters. It checks the validity of the input data and handles splitting conditions for evaluation of test performance. It also processes optional block structures and within-run comparisons.

Examples

dismat <- dist(matrix(rnorm(100*100), 100, 100))
rdes <- rsa_design(~ dismat, list(dismat=dismat))