# czlwang/brain_treebank_code_release architecture

> Architecture diagram of the GitHub repository czlwang/brain_treebank_code_release, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/czlwang/brain_treebank_code_release
- Repository: https://github.com/czlwang/brain_treebank_code_release

## Overview

##### Project Type and Purpose
- This is a data-analysis/experiment orchestration tool for large-scale intracranial brain recordings.
- It provides multiple analysis “pipelines” (GLM fitting, word-onset t-tests, sentence-position F-tests, linear decoding) driven by Hydra config files.
- It is best characterized as an extensible CLI-based data-processing framework, with plugins for models, tasks, schedulers, criterions, and datasets.

##### File Structure
- Top-level scripts/entry points:
- run_glms.py, regression_runner.py, glm_runner.py, run_time_tests.py, runner.py, verify_frame_alignment.py
- Configuration:
- conf/ (Hydra config tree: data, exp, task, test, criterion)
- Data ingestion & representation:
- data/ (raw HDF5 readers, subject/trial/ timestamped data classes)
- datasets/ (wrappers that produce PyTorch-style datasets for GLM/regression)
- Preprocessing:
- preprocessors/ (e.g. wav_preprocessor)
- Modeling & training pipeline plugins:
- models/ (base_regression_model, classification_regression_model)
- criterions/ (base_criterion, empty_criterion)
- schedulers/ (base_scheduler, ramp_up, reduce_on_plateau)
- tasks/ (base_regression_task, classification_regression_task, batch_utils)
- Experiment orchestration:
- runner.py orchestrates instantiation of config, data, model, criterion, scheduler, task, trainer loops
- glm_runner.py and regression_runner.py specialize runner for GLM and regression pipelines
- Statistical analyses (post-hoc tests):
- stats/ (word_onset_tests.py, sentence_position_tests.py)
- Utilities:
- util/tensorboard_utils.py, data/utils.py, tasks/utils.py, verify_frame_alignment.py

##### README for Additional Insights
- Describes four main analysis types: GLM, word-responsiveness, sentence-position, linear decoding
- Shows that Hydra command-line arguments tie together config files (conf/data, conf/exp, conf/task, conf/test) with scripts
- External data source: braintreebank_data (raw HDF5, transcripts)

##### Main Components and Their Interactions
a. Config Layer (Hydra)
- conf/ tree provides parameter sets for data ingestion, experiment settings, model selection, tasks, tests, schedulers, criterions
- CLI scripts load Hydra configs, driving the rest of the pipeline
b. CLI Scripts / Entry Points
- run_glms.py, run_time_tests.py, verify_frame_alignment.py
- Call into runner modules after Hydra config is composed
c. Data Ingestion
- data/*.py, data/h5_data_reader.py read raw .h5 files, subject metadata, transcripts
- data utils perform splitting, timestamp alignment
d. Dataset Construction
- datasets/*.py wrap ingested data into training/evaluation datasets for PyTorch or custom loops
e. Preprocessing
- preprocessors/*.py for on-the-fly signal processing (e.g. wav → features)
f. Tasks
- tasks/*.py implement the experiment logic (e.g. sliding-window definitions, batching, label generation)
g. Models, Criterions, Schedulers
- models define forward and backward passes (GLM fit vs classification/regression)
- criterions define loss or fitting functions (e.g. empty_criterion for analytical fits)
- schedulers manage learning-rate schedules or ramp-up strategies
h. Runner / Trainer
- runner.py and specialized runners (`glm_runner.py`, `regression_runner.py`) tie together Task, Model, Criterion, Scheduler in a training or fitting loop
i. Stats Post-Processing
- stats/*.py perform t-tests or F-tests on saved outputs, generating figures and tables
j. Outputs
- Results written to specified `out_dir` directories (e.g. glm_outputs, word_onset_tstat_results)
- Logs and TensorBoard summaries via util/tensorboard_utils

##### Architectural Patterns and Design Principles
- Plugin-based modularity: data / datasets / preprocessors / models / criterions / schedulers / tasks register themselves via directory structure and Hydra
- Pipeline pattern: data ingestion → dataset → preprocessing → task logic → model fitting or statistical analysis → output
- Separation of concerns: configuration vs code, experiment logic vs I/O, model definition vs training orchestration

##### Elements
- An “External” boundary for the raw data store (braintreebank_data)

##### Detail Without Overthinking
- How Hydra glues together the pieces
- Plugin directories (models, tasks, schedulers, criterions) as extension points

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% External Data
  subgraph "External Data Storage"
    style External fill:#dddddd,stroke:#888
    External["braintreebank_data (HDF5, transcripts)"]:::external
  end

  %% Config Layer
  subgraph "Config Layer (Hydra)"
    style Config fill:#ccccff,stroke:#888
    Config["conf/"]:::config
  end

  %% CLI & Runners
  subgraph "CLI & Runners" 
    style Runners fill:#e0b0ff,stroke:#888
    RunGLM["run_glms.py"]:::runners
    RunTime["run_time_tests.py"]:::runners
    VerifyFrames["verify_frame_alignment.py"]:::runners
    RunnerGen["runner.py"]:::runners
    RunnerGLM["glm_runner.py"]:::runners
    RunnerReg["regression_runner.py"]:::runners
  end

  %% Data Layer
  subgraph "Data Ingestion & Representation"
    style Data fill:#ccffcc,stroke:#888
    H5Reader["h5_data_reader.py"]:::data
    H5Data["h5_data.py"]:::data
    SubjectData["subject_data.py"]:::data
    TimeSubj["timestamped_subject_data.py"]:::data
    TrialReader["trial_data_reader.py"]:::data
    TrialData["trial_data.py"]:::data
    ElecData["electrode_subject_data.py"]:::data
    SpeechData["speech_nonspeech_subject_data.py"]:::data
    GLMSubj["glm_subject_data.py"]:::data
    DataUtils["data/utils.py"]:::util
  end

  %% Dataset Construction
  subgraph "Dataset Construction"
    style Dataset fill:#ccffcc,stroke:#888
    GLMDataset["glm_dataset.py"]:::data
    RegDataset["regression_datasets.py"]:::data
    DatasetUtils["datasets/utils.py"]:::util
  end

  %% Preprocessing & Utilities
  subgraph "Preprocessors & Utilities"
    style Util fill:#ffff9e,stroke:#888
    WavPrep["wav_preprocessor.py"]:::util
    TBUtils["tensorboard_utils.py"]:::util
  end

  %% Pipeline Plugins
  subgraph "Core Pipeline Plugins"
    style Pipeline fill:#fed8b1,stroke:#888
    BaseTask["base_regression_task.py"]:::pipeline
    ClassTask["classification_regression_task.py"]:::pipeline
    BatchUtils["tasks/batch_utils.py"]:::pipeline
    TaskUtils["tasks/utils.py"]:::pipeline
    BaseModel["base_regression_model.py"]:::pipeline
    ClassModel["classification_regression_model.py"]:::pipeline
    BaseCrit["base_criterion.py"]:::pipeline
    EmptyCrit["empty_criterion.py"]:::pipeline
    BaseSched["base_scheduler.py"]:::pipeline
    RampSched["ramp_up.py"]:::pipeline
    PlateauSched["reduce_on_plateau.py"]:::pipeline
  end

  %% Stats
  subgraph "Stats Post-Processing"
    style Stats fill:#ffcccc,stroke:#888
    WordTest["word_onset_tests.py"]:::stats
    SentTest["sentence_position_tests.py"]:::stats
  end

  %% Flows
  External -->|raw HDF5 & transcripts| H5Reader
  Config -.->|Hydra config object| RunGLM
  Config -.->|Hydra config object| RunTime
  Config -.->|Hydra config object| VerifyFrames
  Config -.->|Hydra config object| RunnerGen
  Config -.->|Hydra config object| RunnerGLM
  Config -.->|Hydra config object| RunnerReg

  RunGLM -->|calls| RunnerGLM
  RunTime -->|calls| RunnerGen
  VerifyFrames -->|executes| RunnerGen
  RunnerGen -->|orchestrates| H5Reader

  H5Reader -->|subject data| SubjectData
  H5Reader -->|timestamp data| TimeSubj
  H5Reader -->|trial raw| TrialReader
  TrialReader -->|trial data| TrialData
  H5Reader -->|electrode data| ElecData
  H5Reader -->|speech data| SpeechData
  H5Reader -->|glm raw| GLMSubj
  H5Reader -->|utils| DataUtils

  SubjectData --> GLMDataset
  TrialData --> RegDataset
  DataUtils --> DatasetUtils

  GLMDataset --> WavPrep
  RegDataset --> WavPrep
  DatasetUtils --> WavPrep

  WavPrep --> BaseTask
  WavPrep --> ClassTask
  BatchUtils --> BaseTask
  TaskUtils --> ClassTask

  BaseTask --> BaseModel
  ClassTask --> ClassModel
  BaseModel -.-> BaseCrit
  ClassModel -.-> EmptyCrit
  BaseCrit -.-> BaseSched
  EmptyCrit -.-> RampSched
  BaseSched -.-> PlateauSched

  RunnerReg -->|runs pipeline| BaseTask
  RunnerReg -->|runs pipeline| BaseModel
  RunnerReg -->|runs pipeline| BaseCrit
  RunnerReg -->|runs pipeline| BaseSched

  RunnerGLM -->|runs pipeline| BaseTask
  RunnerGLM -->|runs pipeline| BaseModel
  RunnerGLM -->|runs pipeline| BaseCrit
  RunnerGLM -->|runs pipeline| BaseSched

  RunnerGen -->|collects results| WordTest
  RunnerGen -->|collects results| SentTest

  WordTest -->|outputs| Stats
  SentTest -->|outputs| Stats

  RunnerReg -->|logs to| TBUtils
  RunnerGLM -->|logs to| TBUtils

  %% Click Events
  click Config "https://github.com/czlwang/brain_treebank_code_release/tree/master/conf/"
  click RunGLM "https://github.com/czlwang/brain_treebank_code_release/blob/master/run_glms.py"
  click RunTime "https://github.com/czlwang/brain_treebank_code_release/blob/master/run_time_tests.py"
  click VerifyFrames "https://github.com/czlwang/brain_treebank_code_release/blob/master/verify_frame_alignment.py"
  click RunnerGen "https://github.com/czlwang/brain_treebank_code_release/blob/master/runner.py"
  click RunnerGLM "https://github.com/czlwang/brain_treebank_code_release/blob/master/glm_runner.py"
  click RunnerReg "https://github.com/czlwang/brain_treebank_code_release/blob/master/regression_runner.py"
  click H5Reader "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/h5_data_reader.py"
  click H5Data "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/h5_data.py"
  click SubjectData "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/subject_data.py"
  click TimeSubj "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/timestamped_subject_data.py"
  click TrialReader "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/trial_data_reader.py"
  click TrialData "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/trial_data.py"
  click ElecData "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/electrode_subject_data.py"
  click SpeechData "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/speech_nonspeech_subject_data.py"
  click GLMSubj "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/glm_subject_data.py"
  click DataUtils "https://github.com/czlwang/brain_treebank_code_release/blob/master/data/utils.py"
  click GLMDataset "https://github.com/czlwang/brain_treebank_code_release/blob/master/datasets/glm_dataset.py"
  click RegDataset "https://github.com/czlwang/brain_treebank_code_release/blob/master/datasets/regression_datasets.py"
  click DatasetUtils "https://github.com/czlwang/brain_treebank_code_release/blob/master/datasets/utils.py"
  click WavPrep "https://github.com/czlwang/brain_treebank_code_release/blob/master/preprocessors/wav_preprocessor.py"
  click BaseTask "https://github.com/czlwang/brain_treebank_code_release/blob/master/tasks/base_regression_task.py"
  click ClassTask "https://github.com/czlwang/brain_treebank_code_release/blob/master/tasks/classification_regression_task.py"
  click BatchUtils "https://github.com/czlwang/brain_treebank_code_release/blob/master/tasks/batch_utils.py"
  click TaskUtils "https://github.com/czlwang/brain_treebank_code_release/blob/master/tasks/utils.py"
  click BaseModel "https://github.com/czlwang/brain_treebank_code_release/blob/master/models/base_regression_model.py"
  click ClassModel "https://github.com/czlwang/brain_treebank_code_release/blob/master/models/classification_regression_model.py"
  click BaseCrit "https://github.com/czlwang/brain_treebank_code_release/blob/master/criterions/base_criterion.py"
  click EmptyCrit "https://github.com/czlwang/brain_treebank_code_release/blob/master/criterions/empty_criterion.py"
  click BaseSched "https://github.com/czlwang/brain_treebank_code_release/blob/master/schedulers/base_scheduler.py"
  click RampSched "https://github.com/czlwang/brain_treebank_code_release/blob/master/schedulers/ramp_up.py"
  click PlateauSched "https://github.com/czlwang/brain_treebank_code_release/blob/master/schedulers/reduce_on_plateau.py"
  click WordTest "https://github.com/czlwang/brain_treebank_code_release/blob/master/stats/word_onset_tests.py"
  click SentTest "https://github.com/czlwang/brain_treebank_code_release/blob/master/stats/sentence_position_tests.py"
  click TBUtils "https://github.com/czlwang/brain_treebank_code_release/blob/master/util/tensorboard_utils.py"

  %% Styles
  classDef config fill:#ccccff,stroke:#333;
  classDef data fill:#ccffcc,stroke:#333;
  classDef pipeline fill:#fed8b1,stroke:#333;
  classDef runners fill:#e0b0ff,stroke:#333;
  classDef util fill:#ffff9e,stroke:#333;
  classDef stats fill:#ffcccc,stroke:#333;
  classDef external fill:#dddddd,stroke:#333;
```
