How your-profile/neuroloop-classification works
1. Repository purpose
- This project is an analysis and experimentation codebase for mapping fNIRS-derived features to agent performance / optimality classes.
- The emphasis is on classical classification experiments first; the README frames this as a precursor to using neural feedback in an RL loop.
2. Core workflow
- Data appears to flow from participant/domain/task recordings into labeled experiment datasets.
- Those datasets are then used to train and evaluate classical models, with outputs written to experiment/results/.
- The repository is also set up to compare across domains (Robot, Lunar Lander, Flappy Bird), task modes (watch/play), and label granularities (binary, discrete, regression).
3. Experiment layer
- experiment/ is the main analytics workspace.
- EXP_classical_models.ipynb is likely the central notebook for running model comparisons and analysis.
- runs.py and utils_multisubject.py suggest helper logic for multi-subject experiment execution, aggregation, and result handling.
4. Stored experiment artifacts
- experiment/results/data/ contains prepared datasets for multiple experimental variants: binary, discrete, regression, plus cross-validation variants (*CV.csv).
- experiment/results/models/ stores fitted model artifacts or summaries, organized by subject set and condition.
- NASATLX_Averages.csv indicates the repository also keeps subjective workload metrics alongside model results.
5. Modeling subsystem
- networks/ contains deeper learning implementations for specific environments, such as dqn_lunarlander.py and ddpg_fetchrobot.py.
- Even though the README emphasizes classical ML, this folder shows the project also includes RL policy/network code used either as baselines, source policies, or environment-specific agents.
6. Environment/domain subsystem
- games/ contains runnable environment implementations for the game-like domains, specifically flappy_bird.py and lunar_lander.py.
- The games/assets/ tree bundles runtime dependencies such as sprites, sound effects, and saved TensorFlow/Keras models (.h5) used by the game logic or embedded agents.
7. Policy library
- policies/ contains precomputed or trained policies for each domain.
- There are separate policy collections for Flappy Bird, Lunar Lander, and Robot, including many numbered policy variants; this suggests the experiments compare participant responses against multiple agent skill levels or behaviors.
8. Procedure scripts as domain entry points
- procedure_flappybird.py, procedure_lunarlander.py, and procedure_robot.py likely define the participant-facing experimental procedures for each domain.
- These scripts probably coordinate the environment, the selected policy, and the participant interaction mode, acting as the bridge between the domain implementations and the data collection pipeline.
9. Shared utilities
- utils.py is the likely common helper layer for loading data, encoding labels, managing agents/policies, or standardizing experiment logic across domains.
- create_agents.py, demonstrations.py, and data_labels.ipynb indicate supporting scripts/notebooks for generating agents, demonstrations, and label definitions.
10. Notebook-driven analysis and figures
- The root-level FIGURES_*.ipynb notebooks are dedicated to postprocessing and visualization, not core runtime.
- Their presence suggests the repo separates experiment execution from publication-quality figure generation, with figure notebooks consuming saved CSV/model outputs rather than recomputing everything.
11. Boundaries to preserve in an architecture diagram
- Treat the repo as three main zones: domain/runtime code (games/, procedure_*.py, networks/, policies/), analysis/training code (experiment/, notebooks, utils), and persistent artifacts (experiment/results/, games/assets/model/).
- The main data boundary is from raw or preprocessed fNIRS/behavioral data into labeled experiment tables, then into model training/evaluation, then into saved results and figures.
12. External/runtime dependencies implied by the repo
- Saved .h5 models and .pth policies indicate reliance on TensorFlow/Keras and PyTorch assets.
- The file names and structure imply offline experimentation in notebooks and scripts, rather than a deployed service or web application.
Main entry points: models Fitted models · data Prepared data · EXP_classical_models.ipynb Classical models · flappy_bird.py Flappy Bird
Components 24
Analysis & experiments
Notebooks and scripts for label preparation, classical model training, and result aggregation.
- Shared utils · Common experiment and data-handling helpers used across domains and analysis.
utils.py - Create agents · Script for generating or assembling agent instances and policy artifacts.
create_agents.py - Demonstrations · Support script for generating demonstrations or trace data.
demonstrations.py - Classical models · Central notebook for classical classification experiments and comparisons.
experiment/EXP_classical_models.ipynb - Run helpers · Orchestrates experiment runs and multi-subject execution flows.
experiment/runs.py - Multi-subject utils · Utilities for subject grouping, aggregation, and result postprocessing.
experiment/utils_multisubject.py - Label design · Notebook used to define or inspect label schemes for experiments.
data_labels.ipynb - Model scores · Postprocessing notebook for score visualizations and comparisons.
FIGURES_classicalmodel_scores.ipynb - Optimality maps · Notebook for heatmap-style visualizations of optimality or class structure.
FIGURES_optimality_heatmaps.ipynb
Domains & agents
Environment implementations, procedure entry points, policies, and learned agent assets.
- Flappy procedure · Participant-facing procedure for the Flappy Bird domain.
procedure_flappybird.py - Lunar procedure · Participant-facing procedure for the Lunar Lander domain.
procedure_lunarlander.py - Robot procedure · Participant-facing procedure for the robot domain.
procedure_robot.py - Flappy Bird · Game/runtime implementation for the Flappy Bird domain.
games/flappy_bird.py - Lunar Lander · Game/runtime implementation for the Lunar Lander domain.
games/lunar_lander.py - DQN Lunar · Deep Q-network implementation for Lunar Lander-style agents.
networks/dqn_lunarlander.py - DDPG Robot · DDPG implementation for Fetch robot control tasks.
networks/ddpg_fetchrobot.py - Flappy policies · Precomputed policy variants for the Flappy Bird domain.
policies/FlappyBirdPolicies - Lunar policies · Precomputed policy variants for the Lunar Lander domain.
policies/LunarLanderPolicies - Robot policies · Trained robot policies for the Fetch Pick-and-Place domain.
policies/RobotPolicies - Audio assets · Sound effects used by game environments.
games/assets/audio - Game models · Saved TensorFlow/Keras models used by game logic or embedded agents.
games/assets/model
Stored outputs
Saved datasets, fitted models, and summary results produced by experiments.
- Prepared data · Labeled experiment tables for binary, discrete, regression, and cross-validation variants.
experiment/results/data - Fitted models · Saved model artifacts and summaries for multi-subject experiment conditions.
experiment/results/models - NASA TLX · Subjective workload summary accompanying model results.
experiment/results/NASATLX_Averages.csv
Connections 24
- Shared utils → Classical models: shared helpers · Reusable data loading and analysis utilities support the main experiment notebook.
- Shared utils → Run helpers: shared helpers · Common utilities support run orchestration and aggregation.
- Create agents → Robot policies: produces · Agent creation feeds robot policy artifacts.
- Demonstrations → Prepared data: generates · Demonstration generation supports dataset preparation.
- Label design → Prepared data: defines labels · Label schemes inform the prepared experiment tables.
- Run helpers → Prepared data: reads · Experiment execution consumes prepared labeled datasets.
- Multi-subject utils → Fitted models: aggregates · Multi-subject helpers collect and summarize fitted model outputs.
- Classical models → Prepared data: trains on · Classical experiments read prepared datasets.
- Classical models → Fitted models: writes · Notebook stores fitted models and evaluation summaries.
- Classical models → NASA TLX: compares with · Model analysis can be compared against workload summaries.
- Flappy procedure → Flappy Bird: controls · Procedure script drives the Flappy Bird environment.
- Flappy procedure → Flappy policies: selects policy · Procedure chooses among Flappy Bird policies.
- Lunar procedure → Lunar Lander: controls · Procedure script drives the Lunar Lander environment.
- Lunar procedure → Lunar policies: selects policy · Procedure chooses among Lunar Lander policies.
- Robot procedure → Robot policies: selects policy · Procedure chooses among robot policies.
- Robot procedure → DDPG Robot: uses agent · Robot procedure can rely on the DDPG agent implementation.
- Flappy Bird → Audio assets: loads · Game runtime uses bundled sound assets.
- Flappy Bird → Game models: loads · Game runtime can load bundled model assets.
- Lunar Lander → Game models: loads · Lunar Lander runtime can load bundled model assets.
- DQN Lunar → Lunar Lander: agent for · DQN implementation targets the Lunar Lander domain.
- DDPG Robot → Robot policies: source of · DDPG implementation underlies robot policies.
- Prepared data → Fitted models: feeds · Prepared datasets are used to train and evaluate models.
- Fitted models → Model scores: visualized by · Model outputs are consumed by score visualization notebooks.
- Fitted models → Optimality maps: visualized by · Model outputs are also used for heatmap-style analysis.