# your-profile/neuroloop-classification architecture

> Architecture diagram of the GitHub repository your-profile/neuroloop-classification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/your-profile/neuroloop-classification
- Repository: https://github.com/your-profile/neuroloop-classification

## Overview

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: [`experiment/results/models`](https://github.com/your-profile/neuroloop-classification/tree/main/experiment/results/models) (Fitted models), [`experiment/results/data`](https://github.com/your-profile/neuroloop-classification/tree/main/experiment/results/data) (Prepared data), [`experiment/EXP_classical_models.ipynb`](https://github.com/your-profile/neuroloop-classification/blob/main/experiment/EXP_classical_models.ipynb) (Classical models), [`games/flappy_bird.py`](https://github.com/your-profile/neuroloop-classification/blob/main/games/flappy_bird.py) (Flappy Bird)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis & experiments"]
  node_root_utils["Shared utils<br/>helper layer<br/>[utils.py]"]
  node_root_create_agents["Create agents<br/>agent builder<br/>[create_agents.py]"]
  node_root_demonstrations["Demonstrations<br/>demo builder<br/>[demonstrations.py]"]
  node_exp_notebook["Classical models<br/>analysis notebook"]
  node_exp_runs["Run helpers<br/>execution helper<br/>[runs.py]"]
  node_exp_multi["Multi-subject utils<br/>aggregation helper"]
  node_labels_notebook["Label design<br/>label notebook<br/>[data_labels.ipynb]"]
  node_fig_scores["Model scores<br/>figure notebook"]
  node_fig_heatmaps["Optimality maps<br/>figure notebook"]
end

subgraph group_runtime["Domains & agents"]
  node_proc_flappy["Flappy procedure<br/>experiment procedure"]
  node_proc_lunar["Lunar procedure<br/>experiment procedure"]
  node_proc_robot["Robot procedure<br/>experiment procedure<br/>[procedure_robot.py]"]
  node_game_flappy["Flappy Bird<br/>environment<br/>[flappy_bird.py]"]
  node_game_lunar["Lunar Lander<br/>environment<br/>[lunar_lander.py]"]
  node_net_dqn["DQN Lunar<br/>RL agent<br/>[dqn_lunarlander.py]"]
  node_net_ddpg["DDPG Robot<br/>RL agent<br/>[ddpg_fetchrobot.py]"]
  node_pol_flappy[("Flappy policies<br/>policy set")]
  node_pol_lunar[("Lunar policies<br/>policy set")]
  node_pol_robot[("Robot policies<br/>policy set")]
  node_assets_audio[("Audio assets<br/>runtime assets")]
  node_assets_models[("Game models<br/>runtime assets")]
end

subgraph group_artifacts["Stored outputs"]
  node_results_data[("Prepared data<br/>experiment data")]
  node_results_models[("Fitted models<br/>model outputs")]
  node_results_tlx["NASA TLX<br/>summary csv"]
end

node_root_utils -->|"shared helpers"| node_exp_notebook
node_root_utils -->|"shared helpers"| node_exp_runs
node_root_create_agents -->|"produces"| node_pol_robot
node_root_demonstrations -->|"generates"| node_results_data
node_labels_notebook -->|"defines labels"| node_results_data
node_exp_runs -->|"reads"| node_results_data
node_exp_multi -->|"aggregates"| node_results_models
node_exp_notebook -->|"trains on"| node_results_data
node_exp_notebook -->|"writes"| node_results_models
node_exp_notebook -->|"compares with"| node_results_tlx
node_proc_flappy -->|"controls"| node_game_flappy
node_proc_flappy -->|"selects policy"| node_pol_flappy
node_proc_lunar -->|"controls"| node_game_lunar
node_proc_lunar -->|"selects policy"| node_pol_lunar
node_proc_robot -->|"selects policy"| node_pol_robot
node_proc_robot -->|"uses agent"| node_net_ddpg
node_game_flappy -->|"loads"| node_assets_audio
node_game_flappy -->|"loads"| node_assets_models
node_game_lunar -->|"loads"| node_assets_models
node_net_dqn -->|"agent for"| node_game_lunar
node_net_ddpg -->|"source of"| node_pol_robot
node_results_data -->|"feeds"| node_results_models
node_results_models -->|"visualized by"| node_fig_scores
node_results_models -->|"visualized by"| node_fig_heatmaps

click node_root_utils "https://github.com/your-profile/neuroloop-classification/blob/main/utils.py"
click node_root_create_agents "https://github.com/your-profile/neuroloop-classification/blob/main/create_agents.py"
click node_root_demonstrations "https://github.com/your-profile/neuroloop-classification/blob/main/demonstrations.py"
click node_exp_notebook "https://github.com/your-profile/neuroloop-classification/blob/main/experiment/EXP_classical_models.ipynb"
click node_exp_runs "https://github.com/your-profile/neuroloop-classification/blob/main/experiment/runs.py"
click node_exp_multi "https://github.com/your-profile/neuroloop-classification/blob/main/experiment/utils_multisubject.py"
click node_labels_notebook "https://github.com/your-profile/neuroloop-classification/blob/main/data_labels.ipynb"
click node_fig_scores "https://github.com/your-profile/neuroloop-classification/blob/main/FIGURES_classicalmodel_scores.ipynb"
click node_fig_heatmaps "https://github.com/your-profile/neuroloop-classification/blob/main/FIGURES_optimality_heatmaps.ipynb"
click node_proc_flappy "https://github.com/your-profile/neuroloop-classification/blob/main/procedure_flappybird.py"
click node_proc_lunar "https://github.com/your-profile/neuroloop-classification/blob/main/procedure_lunarlander.py"
click node_proc_robot "https://github.com/your-profile/neuroloop-classification/blob/main/procedure_robot.py"
click node_game_flappy "https://github.com/your-profile/neuroloop-classification/blob/main/games/flappy_bird.py"
click node_game_lunar "https://github.com/your-profile/neuroloop-classification/blob/main/games/lunar_lander.py"
click node_net_dqn "https://github.com/your-profile/neuroloop-classification/blob/main/networks/dqn_lunarlander.py"
click node_net_ddpg "https://github.com/your-profile/neuroloop-classification/blob/main/networks/ddpg_fetchrobot.py"
click node_pol_flappy "https://github.com/your-profile/neuroloop-classification/tree/main/policies/FlappyBirdPolicies"
click node_pol_lunar "https://github.com/your-profile/neuroloop-classification/tree/main/policies/LunarLanderPolicies"
click node_pol_robot "https://github.com/your-profile/neuroloop-classification/tree/main/policies/RobotPolicies"
click node_assets_audio "https://github.com/your-profile/neuroloop-classification/tree/main/games/assets/audio"
click node_assets_models "https://github.com/your-profile/neuroloop-classification/tree/main/games/assets/model"
click node_results_data "https://github.com/your-profile/neuroloop-classification/tree/main/experiment/results/data"
click node_results_models "https://github.com/your-profile/neuroloop-classification/tree/main/experiment/results/models"
click node_results_tlx "https://github.com/your-profile/neuroloop-classification/blob/main/experiment/results/NASATLX_Averages.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_utils,node_root_create_agents,node_root_demonstrations,node_exp_notebook,node_exp_runs,node_exp_multi,node_labels_notebook,node_fig_scores,node_fig_heatmaps toneBlue
class node_proc_flappy,node_proc_lunar,node_proc_robot,node_game_flappy,node_game_lunar,node_net_dqn,node_net_ddpg,node_pol_flappy,node_pol_lunar,node_pol_robot,node_assets_audio,node_assets_models toneAmber
class node_results_data,node_results_models,node_results_tlx toneMint
```

## Components

### Analysis & experiments

Notebooks and scripts for label preparation, classical model training, and result aggregation.

- [Shared utils](https://github.com/your-profile/neuroloop-classification/blob/main/utils.py): helper layer · Common experiment and data-handling helpers used across domains and analysis. · `utils.py`
- [Create agents](https://github.com/your-profile/neuroloop-classification/blob/main/create_agents.py): agent builder · Script for generating or assembling agent instances and policy artifacts. · `create_agents.py`
- [Demonstrations](https://github.com/your-profile/neuroloop-classification/blob/main/demonstrations.py): demo builder · Support script for generating demonstrations or trace data. · `demonstrations.py`
- [Classical models](https://github.com/your-profile/neuroloop-classification/blob/main/experiment/EXP_classical_models.ipynb): analysis notebook · Central notebook for classical classification experiments and comparisons. · `experiment/EXP_classical_models.ipynb`
- [Run helpers](https://github.com/your-profile/neuroloop-classification/blob/main/experiment/runs.py): execution helper · Orchestrates experiment runs and multi-subject execution flows. · `experiment/runs.py`
- [Multi-subject utils](https://github.com/your-profile/neuroloop-classification/blob/main/experiment/utils_multisubject.py): aggregation helper · Utilities for subject grouping, aggregation, and result postprocessing. · `experiment/utils_multisubject.py`
- [Label design](https://github.com/your-profile/neuroloop-classification/blob/main/data_labels.ipynb): label notebook · Notebook used to define or inspect label schemes for experiments. · `data_labels.ipynb`
- [Model scores](https://github.com/your-profile/neuroloop-classification/blob/main/FIGURES_classicalmodel_scores.ipynb): figure notebook · Postprocessing notebook for score visualizations and comparisons. · `FIGURES_classicalmodel_scores.ipynb`
- [Optimality maps](https://github.com/your-profile/neuroloop-classification/blob/main/FIGURES_optimality_heatmaps.ipynb): figure notebook · 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](https://github.com/your-profile/neuroloop-classification/blob/main/procedure_flappybird.py): experiment procedure · Participant-facing procedure for the Flappy Bird domain. · `procedure_flappybird.py`
- [Lunar procedure](https://github.com/your-profile/neuroloop-classification/blob/main/procedure_lunarlander.py): experiment procedure · Participant-facing procedure for the Lunar Lander domain. · `procedure_lunarlander.py`
- [Robot procedure](https://github.com/your-profile/neuroloop-classification/blob/main/procedure_robot.py): experiment procedure · Participant-facing procedure for the robot domain. · `procedure_robot.py`
- [Flappy Bird](https://github.com/your-profile/neuroloop-classification/blob/main/games/flappy_bird.py): environment · Game/runtime implementation for the Flappy Bird domain. · `games/flappy_bird.py`
- [Lunar Lander](https://github.com/your-profile/neuroloop-classification/blob/main/games/lunar_lander.py): environment · Game/runtime implementation for the Lunar Lander domain. · `games/lunar_lander.py`
- [DQN Lunar](https://github.com/your-profile/neuroloop-classification/blob/main/networks/dqn_lunarlander.py): RL agent · Deep Q-network implementation for Lunar Lander-style agents. · `networks/dqn_lunarlander.py`
- [DDPG Robot](https://github.com/your-profile/neuroloop-classification/blob/main/networks/ddpg_fetchrobot.py): RL agent · DDPG implementation for Fetch robot control tasks. · `networks/ddpg_fetchrobot.py`
- [Flappy policies](https://github.com/your-profile/neuroloop-classification/tree/main/policies/FlappyBirdPolicies): policy set · Precomputed policy variants for the Flappy Bird domain. · `policies/FlappyBirdPolicies`
- [Lunar policies](https://github.com/your-profile/neuroloop-classification/tree/main/policies/LunarLanderPolicies): policy set · Precomputed policy variants for the Lunar Lander domain. · `policies/LunarLanderPolicies`
- [Robot policies](https://github.com/your-profile/neuroloop-classification/tree/main/policies/RobotPolicies): policy set · Trained robot policies for the Fetch Pick-and-Place domain. · `policies/RobotPolicies`
- [Audio assets](https://github.com/your-profile/neuroloop-classification/tree/main/games/assets/audio): runtime assets · Sound effects used by game environments. · `games/assets/audio`
- [Game models](https://github.com/your-profile/neuroloop-classification/tree/main/games/assets/model): runtime assets · 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](https://github.com/your-profile/neuroloop-classification/tree/main/experiment/results/data): experiment data · Labeled experiment tables for binary, discrete, regression, and cross-validation variants. · `experiment/results/data`
- [Fitted models](https://github.com/your-profile/neuroloop-classification/tree/main/experiment/results/models): model outputs · Saved model artifacts and summaries for multi-subject experiment conditions. · `experiment/results/models`
- [NASA TLX](https://github.com/your-profile/neuroloop-classification/blob/main/experiment/results/NASATLX_Averages.csv): summary csv · Subjective workload summary accompanying model results. · `experiment/results/NASATLX_Averages.csv`

## Connections

- 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.