Ilustración de un archivo CSV siendo importado a una estructura de marco de datos tabular con columnas que mapean a nombres de variables

Variables del Marco de Datos

Una variable del marco de datos contiene datos tabulares en una estructura similar a una hoja de cálculo: las filas son entradas y las columnas son variables, cada una de las cuales puede contener valores de cadena, numéricos, booleanos o de archivo. Los marcos de datos no se poblan a través de las respuestas de los participantes. Subes un .csv archivo para cargar datos en ellos, y el experimento lee de ellos en tiempo de ejecución utilizando el sistema de eventos.

Los marcos de datos son la herramienta estándar en Labvanced para gestionar entradas estructuradas: listas de estímulos, horarios de contrabalanceo, asignaciones de archivos a imágenes y cualquier otro escenario en el que necesites alimentar filas de datos preparados en tu experimento un ensayo a la vez.

Cuándo usar un marco de datos

Usa un marco de datos siempre que tu experimento necesite cargar datos estructurados pre-preparados en lugar de recopilar valores de los participantes.

Tienes una lista de palabras, oraciones, imágenes o archivos de audio de estímulos que deben aparecer ensayo por ensayo.
Necesitas contrabalancear condiciones entre participantes.
Quieres mezclar el orden de los ensayos al inicio de un experimento y luego leer entradas secuencialmente.
Estás cargando mensajes de OpenAI, mensajes personalizados u otros datos en cadena desde un archivo preparado.

Configurando un marco de datos

Crear un marco de datos requiere tres pasos: preparar tu CSV, crear la variable e importar el archivo.

Formateando tu CSV

Cada columna en tu CSV se convierte en una variable (columna) en el marco de datos. Cada fila es una entrada. Si tu primera fila contiene nombres de columnas, habilita Use first row as header en la importación.

Para estímulos basados en archivos (imágenes, audio), coloca los nombres de archivo en la columna relevante. Luego puedes usar Map strings to files en la importación para vincular esos nombres a archivos subidos en tu estudio.

Creando la variable del marco de datos

Abre tu estudio y ve a la pestaña Variables en el panel izquierdo, o abre la pestaña Variables en el editor de tareas.
Haz clic en + New Variable y establece Data Type a Data Frame.
Haz clic en Save. Se abre el Diálogo del Marco de Datos.

El Diálogo del Marco de Datos en Labvanced, mostrando un marco de datos con cuatro columnas y cuatro filas de datos numéricos.

Subiendo tu CSV

En el Diálogo del Marco de Datos, haz clic en Upload 2D CSV Data. Se abre un selector de archivos. Después de seleccionar tu archivo, aparece el diálogo de Opciones de Importación.

El diálogo de Opciones de Importación en Labvanced, mostrando casillas de verificación para Mapear cadenas a archivos, Usar la primera fila como encabezado y Transponer datos.

Opción	Qué hace
`Map strings to files`	Trata los valores de cadena en el CSV como nombres de archivo y los vincula a archivos subidos a tu estudio
`Use first row as header`	Utiliza la primera fila de tu CSV como nombres de columna en lugar de datos
`Transpose data`	Sube los datos sin transponer filas y columnas

Haz clic en Ok para importar. El marco de datos se pobla con el contenido de tu CSV.

Editando un marco de datos

Una vez que se crea un marco de datos, puedes extenderlo con nuevas columnas, editar valores individuales de celdas directamente o reemplazar todo el contenido con una nueva carga de CSV.

Agregando columnas

Para agregar una nueva columna después de la importación inicial, haz clic en Add variable / Column en la parte superior del Diálogo del Marco de Datos. Esto agrega una columna vacía que puedes nombrar y configurar. Si la nueva columna contiene nombres de archivo, haz clic en Map all strings to files en el diálogo posteriormente para vincularlos a los archivos subidos en tu estudio.

Editando valores de celdas

Para editar valores individuales de celdas directamente, habilita la casilla de verificación Edit Values en el Diálogo del Marco de Datos. Las celdas se vuelven editables en su lugar. Desactiva la casilla para volver a la vista de solo lectura.

Usando marcos de datos en el sistema de eventos

Los marcos de datos son leídos y escritos a través del sistema de eventos. Dos acciones en la categoría Operaciones del Marco de Datos manejan esto.

Leer de / Escribir en Acción del Marco de Datos

Usa esta acción para leer una fila o columna del marco de datos en una variable de matriz, o para escribir valores nuevamente.

Parámetros clave:

Parámetro	Descripción
Variable del marco de datos	El marco de datos desde el cual leer o escribir
Leer o Escribir	Dirección de la operación
Por fila o columna	Si leer una fila completa o una columna completa
Tipo de índice	Cómo se selecciona la fila o columna: valor fijo, variable o última fila
Variable de índice	La variable utilizada como índice cuando el Tipo de índice está configurado en variable
Variable de salida	La variable de matriz donde se almacena el resultado

El patrón más común es: mantener una variable numérica de contador que incremente cada ensayo, usarla como la Variable de índice y leer la fila correspondiente en una matriz. Cada elemento de la matriz se asigna entonces a una columna de esa fila.

Acción Mezclar Entradas del Marco de Datos

Usa esta acción para aleatorizar el orden de las filas o columnas en el marco de datos. Ejecútala una vez al inicio del experimento (activado por un evento de inicio de sesión) antes de que comiencen los ensayos.

Parámetros:

Parámetro	Descripción
Marco de datos	El marco de datos a mezclar
Por filas o columnas	Si mezclar el orden de filas o columnas

Un flujo de trabajo común: lista de estímulos por ensayo

Una configuración típica para leer una fila de estímulos por ensayo:

Sube un CSV con una fila por ensayo y columnas para cada atributo de estímulo (por ejemplo, word, condition, correct_response).
Crea una variable numérica trial_index con un valor inicial de 1 y Reset at Trial Start desactivada.
Al inicio del experimento, agrega una acción Shuffle Data Frame Entries en tu marco de datos (por filas).
Al inicio de cada ensayo, agrega una acción Read from / Write to Data Frame: leer por fila, Variable de índice = trial_index, Variable de salida = una variable de matriz (por ejemplo, current_trial_data).
Después de leer, incrementa trial_index por 1 usando una acción aritmética Set / Record Variable.
Usa los elementos de la variable de matriz para establecer propiedades de objetos o dirigir la lógica de eventos para ese ensayo.