Data Frame Variables

A data frame variable holds tabular data in a spreadsheet-like structure: rows are entries and columns are variables, each of which can hold string, numeric, boolean, or file values. Data frames are not populated through participant responses. You upload a .csv file to load data into them, and the experiment reads from them at runtime using the event system.

Data frames are the standard tool in Labvanced for managing structured input: lists of stimuli, counterbalancing schedules, file-to-image mappings, and any other scenario where you need to feed rows of prepared data into your experiment one trial at a time.

When to use a data frame

Use a data frame any time your experiment needs to load pre-prepared, structured data rather than collecting values from participants.

• You have a list of stimulus words, sentences, images, or audio files that should appear trial by trial
• You need to counterbalance conditions across participants
• You want to shuffle trial order at the start of an experiment and then read entries sequentially
• You are loading OpenAI prompts, custom messages, or other string data from a prepared file

Setting up a data frame

Creating a data frame takes three steps: prepare your CSV, create the variable, and import the file.

Formatting your CSV

Each column in your CSV becomes one variable (column) in the data frame. Each row is one entry. If your first row contains column names, enable Use first row as header on import.

For file-based stimuli (images, audio), put the filenames in the relevant column. You can then use Map strings to files on import to link those names to uploaded files in your study.

Creating the data frame variable

1. Open your study and go to the Variables tab in the left panel, or open the Variables panel tab in the task editor.
2. Click + New Variable and set the Data Type to Data Frame.
3. Click Save. The Data Frame Dialog opens.

Uploading your CSV

In the Data Frame Dialog, click Upload 2D CSV Data. A file picker opens. After you select your file, the Import Options dialog appears.

Click Ok to import. The data frame is populated with your CSV contents.

Editing a data frame

Once a data frame is created, you can extend it with new columns, edit individual cell values directly, or replace all contents with a fresh CSV upload.

Adding columns

To add a new column after the initial import, click Add variable / Column at the top of the Data Frame Dialog. This adds an empty column that you can name and configure. If the new column contains filenames, click Map all strings to files in the dialog afterward to link them to the uploaded files in your study.

Editing cell values

To edit individual cell values directly, enable the Edit Values checkbox in the Data Frame Dialog. Cells become editable in place. Disable the checkbox to return to the read-only view.

Using data frames in the event system

Data frames are read and written through the event system. Two actions in the Data Frame Operations category handle this.

Read from / Write to Data Frame Action

Use this action to read a row or column from the data frame into an array variable, or to write values back in.

Key parameters:

The most common pattern is: maintain a numeric counter variable that increments each trial, use it as the Index variable, and read the corresponding row into an array. Each element of the array then maps to one column of that row.

Shuffle Data Frame Entries Action

Use this action to randomize the order of rows or columns in the data frame. Run it once at the start of the experiment (triggered by a session-start event) before any trials begin.

Parameters:

A common workflow: stimulus list per trial

A typical setup for reading one row of stimuli per trial:

1. Upload a CSV with one row per trial and columns for each stimulus attribute (e.g., word, condition, correct_response).
2. Create a numeric variable trial_index with a start value of 0 and Reset at Trial Start disabled.
3. At experiment start, add a Shuffle Data Frame Entries action on your data frame (by rows).
4. On each trial start, add a Read from / Write to Data Frame action: read by row, Index variable = trial_index, Output variable = an array variable (e.g., current_trial_data).
5. After reading, increment trial_index by 1 using a Set / Record Variable arithmetic action.
6. Use the array variable elements to set object properties or drive event logic for that trial.

Further reading