Skip to contents

Create an MVPA Design Object

Source: R/design.R
mvpa_design.Rd

Creates a design object for MVPA analysis that encapsulates training and testing designs, response variables, and optional blocking and splitting factors.

Usage

mvpa_design(
  train_design,
  test_design = NULL,
  y_train = NULL,
  y_test = NULL,
  block_var = NULL,
  split_by = NULL,
  cv_labels = NULL,
  targets = NULL,
  targets_test = NULL,
  ...
)

Arguments

train_design

A data frame containing the training design matrix

test_design

Optional data frame containing the test design matrix (default: NULL)

y_train

Formula or vector specifying the training response variable (old path; mutually exclusive with cv_labels)

y_test

Optional formula or vector specifying the test response variable (default: NULL)

block_var

Optional formula, scalar column name, or row-aligned numeric, integer, character, logical, or factor vector specifying the blocking variable for cross-validation.

split_by

Optional formula, scalar column name, or row-aligned atomic vector specifying how to split analyses.

cv_labels

Optional vector of labels used for cross-validation fold construction (new path; mutually exclusive with y_train). If provided without targets, targets defaults to cv_labels.

targets

Optional vector or numeric matrix of model-specific training targets, with one element or row per training observation. Defaults to cv_labels when cv_labels is supplied, or to the parsed y_train when the old path is used.

targets_test

Optional vector or numeric matrix of model-specific test targets, with one element or row per test_design row. Requires test_design. When NULL, model_targets falls back to y_test.

...

Additional arguments (currently unused)

Value

An mvpa_design object (S3 class) containing:

train_design

Data frame of training design

test_design

Data frame of test design (if provided)

cv_labels

Labels used for cross-validation fold construction

targets

Model-specific training targets

targets_test

Model-specific test targets (if provided)

y_train

Alias for cv_labels (for backward compatibility)

y_test

Test response variable (if provided)

block_var

Blocking variable for cross-validation (if provided)

split_by

Splitting factor (if provided)

Details

The y_train and y_test can be specified either as formulas (e.g., ~ condition) or as vectors. If formulas are used, they are evaluated within the respective design matrices.

The block_var and split_by can be specified as formulas, scalar column names, or row-aligned atomic vectors. Formulas and column names are evaluated within the relevant design matrix; vectors must have exactly one value per design row.

The new cv_labels and targets parameters allow separating the labels used for fold construction from the actual training targets. When using the old y_train path, both cv_labels and targets are set to the parsed y_train value. Targets may be a numeric matrix with one row per observation; use model_targets to retrieve targets together with their meaning. y_train continues to return cv_labels.

See also

mvpa_dataset for creating the corresponding dataset object

Examples

# Basic design with only training data
train_df <- data.frame(condition = rep(c("A", "B"), each = 50),
                       block = rep(1:5, each = 20),
                       group = rep(c("Group1", "Group2"), 50))
design <- mvpa_design(train_df, y_train = ~ condition)

# Design with test data and blocking variable
test_df <- data.frame(condition = rep(c("A", "B"), each = 25))
design_with_test <- mvpa_design(
  train_df,
  test_df,
  y_train = ~ condition,
  y_test = ~ condition,
  block_var = ~ block
)

# Design with split_by factor
design_split <- mvpa_design(
  train_df,
  y_train = ~ condition,
  split_by = ~ group
)