# ppwangyc/wave architecture

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

- Interactive diagram: https://gitdiagram.com/ppwangyc/wave
- Repository: https://github.com/ppwangyc/wave

## Overview

##### Main Components
- Environment & Setup: The project uses scripts (in the script/ folder) for setting up the conda environment, downloading datasets and model checkpoints via git-lfs. The env.yaml and setup.py scripts play a key role.
- Data Handling:
- Dataset: In src/dataset (e.g., bold5000.py), data loaders are implemented to process the BOLD5000 fMRI dataset.
- Batcher: In src/batcher, specialized batchers (including one based on BERT) prepare data for training.
- Model Components:
- Embedder: (src/embedder) for mapping fMRI data to a representation space using models like CSM and possibly unembedding.
- Model: In src/model, multiple modules (clip, diffusion, fid_wrapper, fvl) are available, with an emphasis on a diffusion model and a couple of contrastive learning models.
- Decoder: (src/decoder) which includes a GPT-based decoder, perhaps used for generating or interpreting latent representations.
- Trainer: (src/trainer) encapsulates training routines such as prior_trainer and general trainer that manage the training loop.
- Reconstruction & Evaluation:
- The src/reconstruct.py script aggregates model outputs to generate reconstructed visuals and computes relevant metrics (see src/util/metrics.py and src/util/utils.py).

##### Relationships & Data Flow
- The initial data (BOLD5000 fMRI images) is loaded via the dataset components; batcher modules process them into mini-batches.
- In the contrastive branch, the embedder maps data into embedding space, which is then used by the contrastive model that is trained via train scripts (src/train_bold5000_contrastive.py).
- The diffusion branch (in src/train_bold5000_decode.py) takes the outputs (or embeddings) from the contrastive model as a prior and performs the decoding/reconstruction.
- Reconstruction operations in src/reconstruct.py then integrate these components, use external metrics (from src/util), and finally output visual reconstructions.
- Scripts in the script/ directory act as the orchestrators by calling appropriate training and reconstruction commands, managing parameters like subject names and mask usages.

##### Architectural Patterns and Design Principles
- Modularity: The project is divided into clear modules for dataset, batcher, embedder, model, decoder, trainer, and utility functions.
- Pipeline-based design: There is a clear sequential flow—from loading and preprocessing the data, to training and embedding via contrastive learning, followed by decoding through diffusion.
- Separation of concerns: The training, reconstruction, and environment setup codes are clearly separated into different directories and scripts.
- Extensibility: Use of “make.py” modules in several subdirectories (batcher, decoder, embedder, model) implies a factory design pattern to simplify component instantiation.

- Split into two pipelines:
- Pipeline A (Contrastive Learning):
o Embedder: processes fMRI data into latent representations (src/embedder).
o Contrastive Model Training: using src/train_bold5000_contrastive.py, and components in src/model.
- Pipeline B (Diffusion Decoding):
o Diffusion Model: processes the learned representations to decode the fMRI data (src/model/diffusion.py).
o Decoder: further refines the output (src/decoder) to generate the final visual reconstruction.
- Both pipelines converge at the Reconstruction module (src/reconstruct.py) that evaluates and refines outputs.
- An "Experiment/Logging" block to represent integration with logging tools (such as wandb) and metrics (src/util/metrics.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Source
    BOLD("BOLD5000 fMRI Data"):::data

    %% Environment & Setup
    subgraph "Environment & Setup"
        EF("Environment File"):::env
        ES("Setup Script"):::env
        SP("Setup Python Script"):::env
    end

    %% Data Handling
    subgraph "Data Handling"
        DL("Dataset Loader"):::data
        BT("Batcher"):::data
    end

    %% Contrastive Pipeline
    subgraph "Contrastive Pipeline"
        EMB("Embedder"):::contrast
        CM("Contrastive Model"):::contrast
        CTS("Contrastive Training Script"):::contrast
    end

    %% Diffusion Pipeline
    subgraph "Diffusion Pipeline"
        DM("Diffusion Model"):::diffusion
        DS("Diffusion Training Script"):::diffusion
        DEC("Decoder"):::diffusion
    end

    %% Reconstruction & Evaluation
    subgraph "Reconstruction & Evaluation"
        RECON("Reconstruction Module"):::recon
        METRICS("Metrics & Utils"):::recon
    end

    %% Orchestration Scripts
    subgraph "Orchestration Scripts"
        DL_S("Download Script"):::orch
        RECON_S("Reconstruction Orchestration"):::orch
        CT_S("Contrastive Train Orchestration"):::orch
        DT_S("Diffusion Train Orchestration"):::orch
    end

    %% Data Flow
    BOLD -->|"loads"| DL
    SP -->|"initializes"| DL
    DL_S -->|"triggers"| DL
    DL -->|"prepares"| BT
    BT -->|"sends to"| EMB
    BT -->|"sends to"| DM
    EMB -->|"encodes"| CM
    CM -->|"trains with"| CTS
    CT_S -->|"orchestrates"| CTS
    DM -->|"trains via"| DS
    DT_S -->|"orchestrates"| DS
    DS -->|"decodes into"| DEC
    CTS -->|"feeds"| RECON
    DEC -->|"feeds"| RECON
    RECON -->|"evaluates with"| METRICS
    RECON_S -->|"orchestrates"| RECON

    %% Styles
    classDef env fill:#f9c2ff,stroke:#333,stroke-width:2px;
    classDef data fill:#bbf,stroke:#333,stroke-width:2px;
    classDef contrast fill:#cfc,stroke:#333,stroke-width:2px;
    classDef diffusion fill:#fcf,stroke:#333,stroke-width:2px;
    classDef recon fill:#cff,stroke:#333,stroke-width:2px;
    classDef orch fill:#ffc,stroke:#333,stroke-width:2px;

    %% Click Events
    click EF "https://github.com/ppwangyc/wave/blob/main/env.yaml"
    click ES "https://github.com/ppwangyc/wave/blob/main/script/setup.sh"
    click SP "https://github.com/ppwangyc/wave/blob/main/setup.py"
    click DL "https://github.com/ppwangyc/wave/blob/main/src/dataset/bold5000.py"
    click BT "https://github.com/ppwangyc/wave/blob/main/src/batcher/bert.py"
    click EMB "https://github.com/ppwangyc/wave/blob/main/src/embedder/csm.py"
    click CM "https://github.com/ppwangyc/wave/blob/main/src/model/clip.py"
    click CTS "https://github.com/ppwangyc/wave/blob/main/src/train_bold5000_contrastive.py"
    click DM "https://github.com/ppwangyc/wave/blob/main/src/model/diffusion.py"
    click DS "https://github.com/ppwangyc/wave/blob/main/src/train_bold5000_decode.py"
    click DEC "https://github.com/ppwangyc/wave/blob/main/src/decoder/gpt.py"
    click RECON "https://github.com/ppwangyc/wave/blob/main/src/reconstruct.py"
    click METRICS "https://github.com/ppwangyc/wave/blob/main/src/util/metrics.py"
    click DL_S "https://github.com/ppwangyc/wave/blob/main/script/download.sh"
    click RECON_S "https://github.com/ppwangyc/wave/blob/main/script/reconstruct.sh"
    click CT_S "https://github.com/ppwangyc/wave/blob/main/script/train_contrastive.sh"
    click DT_S "https://github.com/ppwangyc/wave/blob/main/script/train_decode.sh"
```
