# benkeel/vae_lung_lesion_bmvc architecture

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

- Interactive diagram: https://gitdiagram.com/benkeel/vae_lung_lesion_bmvc
- Repository: https://github.com/benkeel/vae_lung_lesion_bmvc

## Overview

##### Project type and purpose
- This is a research-oriented machine-learning pipeline for variational autoencoders (VAEs) applied to lung lesion images, followed by downstream tasks (latent-space clustering, MLP classification).
- The README stresses image preprocessing, VAE training (Gaussian & Dirichlet variants), latent extraction, clustering, and hyperparameter searches for MLPs.

##### File structure
Top-level directories:
- Preprocessing – Jupyter notebooks for converting DICOM→NumPy, data splitting, ROI cropping, metadata files.
- VAE – Python training scripts for various VAE architectures and joint-loss classifiers, plus an Excel hyperparameter log.
- Clustering and MLP – Notebooks and scripts for latent-space exploration, clustering, and MLP hyperparameter searches.
- data_2classes.npy / data_3classes.npy, labels2.npy / labels3.npy, meta CSVs – serialized data artifacts.
- interesting_examples – output artifacts (e.g., GIFs of latent traversals).
Configuration/build artifacts: minimal; research code uses notebooks and standalone Python scripts.

##### Extract additional insights from the README
- Preprocessing stage generates ROI-cropped 64×64 numpy arrays and metadata splits (malignant vs benign/non-malignant).
- VAE stage trains multiple flavors: Gaussian, Dirichlet, joint VAE+classifier.
- Clustering stage performs PCA/t-SNE, K-Means/CLASSIX, and MLP performance grids.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Preprocessing" 
        direction TB
        DICOM["DICOM to NumPy Conversion"]:::data
        split["Data Splitting & Metadata"]:::data
        roi["ROI Mask Sizing"]:::data
        metaCSV["Metadata CSVs"]:::artifact
    end

    raw["Raw DICOM CT Scans & Masks"]:::data
    arrays["Cropped 64×64 NumPy Arrays & Labels"]:::artifact

    raw --> DICOM
    DICOM --> roi
    roi --> split
    split --> arrays
    split --> metaCSV

    click DICOM "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Preprocessing/LIDC_DICOM_to_Numpy.ipynb"
    click split "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Preprocessing/LIDC_datasplit.ipynb"
    click split "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Preprocessing/Train_Test_Split.ipynb"
    click roi "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Preprocessing/mask_size.ipynb"
    click metaCSV "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Preprocessing/meta_mal_ben.csv"
    click metaCSV "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Preprocessing/meta_mal_nonmal.csv"

    %% VAE Training
    subgraph "VAE Training"
        direction TB
        searchG["Gaussian VAE HyperSearch"]:::model
        searchD["Dirichlet VAE HyperSearch"]:::model
        jointD["Dirichlet VAE Joint Loss"]:::model
        jointMLP1["Joint VAE+MLP Malignant-Nonmalignant"]:::model
        jointMLP2["Joint VAE+MLP Malignant-Benign"]:::model
        log["Hyperparameter Log (Excel)"]:::artifact
    end

    arrays --> searchG
    arrays --> searchD
    searchG --> latent
    searchD --> latent
    searchD --- jointD
    latent --> jointMLP1
    latent --> jointMLP2
    searchG --> log
    searchD --> log

    click searchG "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/VAE/RandomSearchVAE.py"
    click searchD "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/VAE/RandomSearch_Dirichlet_VAE.py"
    click jointD "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/VAE/VAE_Dirichlet_joint_loss.py"
    click jointMLP1 "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/VAE/VAE_MLP_joint_loss_mal_nonmal.py"
    click jointMLP2 "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/VAE/VAE_joint_loss_mal_benign.py"
    click log "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/VAE/VAE_hyperparam_training.xlsx"

    %% Latent Extraction
    latent["Latent Vectors & Reconstructions"]:::artifact

    latentExt["Latent Extraction & Reconstruction"]:::model
    latent --> latentExt
    click latentExt "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Clustering and MLP/Exploration_gaussian.ipynb"

    %% Clustering & Visualization
    subgraph "Clustering & Visualization"
        direction TB
        pca["PCA / t-SNE Exploration"]:::post
        cluster["K-Means & CLASSIX Clustering"]:::post
    end

    latent --> pca
    latent --> cluster
    pca --> viz
    cluster --> viz

    viz["Visualization & GIF Generation"]:::artifact

    click pca "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Clustering and MLP/Clustering.ipynb"
    click cluster "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Clustering and MLP/Clustering_initial.ipynb"

    %% MLP Classification
    subgraph "MLP Hyperparameter Search"
        direction TB
        mlpStd["Standard MLP Search"]:::post
        mlpDir["Dirichlet VAE MLP Search"]:::post
    end

    latent --> mlpStd
    latent --> mlpDir
    mlpStd --> results
    mlpDir --> results

    click mlpStd "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Clustering and MLP/RandomSearchMLP.py"
    click mlpDir "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/Clustering and MLP/Dirichlet_RandomSearchMLP.py"

    %% Artifacts & Reporting
    subgraph "Artifacts & Reporting"
        direction TB
        dataArr["Serialized Data Arrays"]:::artifact
        labelArr["Label Arrays"]:::artifact
        topMeta["Top-level Metadata CSVs"]:::artifact
        gifs["Latent Traversal GIFs"]:::artifact
        examples["interesting_examples/"]:::artifact
    end

    arrays --> dataArr
    arrays --> labelArr
    metaCSV --> topMeta
    viz --> gifs
    gifs --> examples

    click dataArr "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/data_2classes.npy"
    click dataArr "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/data_3classes.npy"
    click labelArr "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/labels2.npy"
    click labelArr "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/labels3.npy"
    click topMeta "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/meta_mal_ben.csv"
    click topMeta "https://github.com/benkeel/vae_lung_lesion_bmvc/blob/main/meta_mal_nonmal.csv"
    click examples "https://github.com/benkeel/vae_lung_lesion_bmvc/tree/main/interesting_examples/"

    %% Styles
    classDef data fill:#D6E9FE,stroke:#0366D6,color:#0366D6
    classDef model fill:#DFFFE0,stroke:#2E8B57,color:#2E8B57
    classDef post fill:#FFF5CC,stroke:#DAA520,color:#DAA520
    classDef artifact fill:#EFEFEF,stroke:#555555,color:#333333
```
