https://github.com/bchisholm08/neural-tetris
Repository for the Noel neuroscience laboratory Tetris project.
https://github.com/bchisholm08/neural-tetris
matlab matlabgui neuroscience psychtoolbox
Last synced: 8 months ago
JSON representation
Repository for the Noel neuroscience laboratory Tetris project.
- Host: GitHub
- URL: https://github.com/bchisholm08/neural-tetris
- Owner: bchisholm08
- Created: 2025-02-21T13:34:19.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-08-08T20:01:48.000Z (10 months ago)
- Last Synced: 2025-08-08T22:10:13.492Z (10 months ago)
- Topics: matlab, matlabgui, neuroscience, psychtoolbox
- Language: MATLAB
- Homepage:
- Size: 72.3 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# **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](#overview)
- [Repository Structure](#repository-structure)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Scripts & Functions](#scripts--functions)
- [Data Output](#data-output)
- [Contributing](#contributing)
- [License](#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:
```bash
git clone https://github.com/yourusername/human-tetris-eeg.git
```
2. Add subfolders to MATLAB path:
```matlab
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...
```matlab
humanTetrisWrapper("P01")
```
**OR**
```matlab
humanTetrisWrapper("P01", 1)
```
For running with demoMode OFF...
```matlab
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.
```markdown
## 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.