Jean-Paul Noel Neuroscience Lab Human Tetris Experiment

A neuroscience experiment exploring how neural reprentations of visual objects may vary depending on the context that surrounds an object, and possible actions or rewards an object encodes.

Table of Contents

• Overview
• Repository Structure
• Requirements
• Installation
• Usage
• Scripts & Functions
• Data Output
• Contributing
• License

Overview

This repository contains the code for a four-part experimental paradigm that integrates:

• EEG recording: via BioSemi parallel port triggers.
• Eye-tracking: using Tobii SDK.
• Task presentation: built with Psychtoolbox.

An overall theme of this experiment is that is increases in complexity throughout. In scripts and functions (LINK HERE) see p1.m, p2.m, p4.m and p5.m for more detail on each section.

Repository Structure

/  
├── code/  
│   ├── humanTetrisWrapper.m # handles running entire experiment
│   ├── helperScripts/   # support functions to run experiment 
│       |── initExperiment.m 
│       |── p1.m
│       |── etc...
├── data/                # Generated data folders per subject  
└── README.md            # This file  

Requirements

• MATLAB R2023a or later
• Psychtoolbox-3.0.19 installed
  • PTB requires GStreamer 1.22.5 (or later) to be installed
• Tobii Pro SDK on the MATLAB path
• BioSemi parallel port hardware (if demoMode is off)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/human-tetris-eeg.git

2. Add subfolders to MATLAB path:

   addpath(genpath('path/to/human-tetris-eeg/code'));

Usage

Each participant is run with one single function call to a wrapper. This will run all experiment sections, give instructions, save data, and close everything at the end.

The experimenter should only have to enter the room if the participant requests it.

For running with demoMode ON...

humanTetrisWrapper("P01")

OR

humanTetrisWrapper("P01", 1)

For running with demoMode OFF...

humanTetrisWrapper("P01",0)

NOTE: Wrapper function defaults to demoMode == 1. This will bypass EEG/eye‑tracker data collection and run the behavioral portion of the experiment. This will still save .csv data files.

Experiment Function Reference

initExperiment

Inputs: subjID, demoMode
Outputs: window, windowRect, expParams, ioObj, address, eyetracker
Description: Location of all experiment settings and options. Initializing the eyetracker & EEG, timing, trial/block numbers, data saving, and more is all handled within this script.

pathsAndPlaces

Inputs: id
Outputs: p
Description: Helper function for getting paths back to initExperiment. Function ID Map (input): 0=root, 1=code, 2=data, 3=tools.

p5instruct

Inputs: window, expParams
Outputs: None.
Description: Gives participant instructions for p5 of the experiment.

p5

Inputs: subjID, demoMode, window, windowRect, expParams, ioObj, address, eyetracker Outputs: None Description: P5 acts as a wrapper for the active play/watch section of the experiment. Within P5, playOneTetrisGame and playBackGame are called.

p2

Inputs: subjID, demoMode, expParams, ioObj, address, eyetracker
Outputs: None
Description: Presents P2, Tetris pieces with tableaus, or contexts. Here our focus is on capturing the different evoked response to each unique tableau.

p1

Inputs: subjID, demoMode, window, windowRect, expParams, ioObj, address, eyetracker Outputs: None
Description: Handles P1 of the Tetris experiment. This section is focused on obtaining evoked responses from each of the seven Tetris pieces.

p1instruct

Inputs: window, expParams
Outputs: None.
Description: Displays participant instructions for P1 of the experiment.

p2instruct

Inputs: window, expParams
Outputs: None.
Description: Displays participant instructions for P2 of the experiment.

waitForSpace

Inputs: None.
Outputs: None.
Description: Helper script I wrote for a key binding issue we had in the experiment.

take5Brubeck

Inputs: window, params
Outputs: None.
Description: Handles timing brief participant breaks, such as blocks. Forces break time by hiding spacebar.

showScore

Inputs: window,score, expParams
Outputs: None
Description: Displays the players current score.

showEndScreen

Inputs: window, expParams
Outputs: None.
Description: Thanks the participant for their time and ends the experiment.

saveDat

Inputs: section, subjID, data, params, demoMode
Outputs: None.
Description: Centralized saving function for all experiment sections. Saves behavioral data, experiment parameters, and other needed information from the session.

playOneTetrisGame

Inputs: expParams
Outputs: snapshotFile, activInfo, eventLog
Description: Handles playing one Tetris game. Records and saves pupillometry data, handles EEG triggers. Supported by multiple local helper functions within this function itself. Handles all control and logic for playing a game of Tetris.

handlePause

Inputs: window,keys
Outputs: pauseDuration
Description: Checks for p to be pressed during the experiment. If a pause request is detected, this function will pause the experiment and record the length of the break which is returned in pauseDuration.

getTrig

Inputs: piece,eventType
Outputs: trig
Description: Uses piece ID and event type as a method for getting the correct EEG trigger. Applies needed offset for events.

getTetrino

Inputs: expParams
Outputs: pieces
Description: Returns a simple strucuture for each of the seven Tetris pieces. Piece IDs are constant throughout the experiment.

getTableaus

Inputs: window, expParams
Outputs: tableaus
Description: Returns a .mat data structure of unique tableau sets for each of the seven Tetris pieces. Three conditions results in 21 unique tableaus, plus a shared common garbage tableau.

getBoardSnapshot

Inputs:boardMatrix,currentTrigger
Outputs: snapShot
Description: Records a unit64 matrix of the Tetris board, along the current EEG trigger for the frame (if it exists), and a timestamp.

drawFixation

Inputs:window, windowRect,expParams
Outputs: None
Description: Draws a simple fixation cross on the screen.

humanTetrisWrapper

Inputs: subjID, demoMode
Outputs:: None.
Purpose: Full Tetris experiment wrapper. Handles initializing the experiment, and then running all subsequent experiment sections (P5,P1,P2).
Notes: Facilitates breaks and some master timing.

calibrateTobii

Inputs:window, windowRect, eyeTracker,expParams
Outputs:calibrationData
Description: A binocular calibration for the Tobii Pro Spectrum. Modeled off Tobii SDK example calibration code and modified for my experiment.

playBackGame

Inputs:playBackGame
Outputs: None.
Description: Plays back Tetris games for players to watch.

betweenSectionBreakScreen

Inputs:window, expParams
Outputs: None.
Description: Handles giving the participant a break between experiment sections, forces break and locks keys.

## Data Output
Each section saves `.mat` data files in participant specific directories:

data/subjID/
├── eyeData/
├── behavioralData/
├── misc/
└──

Contributing

Please open issues or pull requests for enhancements, bug fixes, or documentation improvements.

Don't hesitate to reach out! I can be contacted at two different emails, chish071@umn.edu or bmc@brady-c.cc.

License

This project is licensed under the MIT License. See LICENSE for details.