Data Frame Patterns

Data frames are one of the most versatile tools in Labvanced for managing the input side of an experiment. This page covers how to apply them to three common research design scenarios. For the technical reference on creating and configuring data frames, see Data Frame Variables.

Sequential stimulus presentation

The most common use of a data frame is a stimulus list: one row per trial, columns for each attribute (word, image filename, condition, correct response). At session start, shuffle the rows to randomize trial order. Then on each trial, read the current row into an array variable and use its values to set object properties: the text shown, the image displayed, the expected response.

The key components:

• A data frame with one row per trial
• A numeric trial_index variable starting at 0, with Reset at Trial Start disabled
• A session-start event running Shuffle Data Frame Entries (by rows)
• A trial-start event running Read from / Write to Data Frame: read by row, Index variable = trial_index, output to an array variable
• An increment action after reading: add 1 to trial_index

Each element of the output array maps to one column of that row. A Set Object Property action then assigns each value to the relevant object on the frame.

Counterbalancing trial order

Because Shuffle Data Frame Entries runs at session start and the shuffle is different each time, every participant sees a unique trial order drawn from the same set. This is within-participant randomization without repetition.

For between-participant counterbalancing, where you want to ensure specific condition orders are equally distributed across participants, use Labvanced's group assignment in combination with a data frame. Create a separate group for each counterbalancing order, with each group's data frame pre-ordered for that condition sequence. Participants are assigned to groups in rotation, balancing orders across the sample.

For full documentation on group-based counterbalancing, see Randomization and Balanced Experimental Design.

File-based stimuli

When your stimuli are image or audio files rather than text, store the filenames in a data frame column and use Map strings to files on import to link each name to an uploaded file. At runtime, the Read from / Write to Data Frame action returns the filename, which a Set Object Property action uses to swap the file shown by an image or audio element.

This approach separates stimulus definition (the CSV) from stimulus delivery (the event logic), making it straightforward to update your stimulus set by uploading a new CSV without touching the event system.

Steps:

1. Prepare a CSV with a column containing filenames (e.g., image_file). Upload the image files to your study separately.
2. Create a data frame variable and upload the CSV. Enable Map strings to files and Use first row as header on import.
3. Use Read from / Write to Data Frame on each trial to read the filename into an array variable.
4. Add a Set Object Property action targeting the image element: set its source to the array element holding the filename.

Further reading