# ivysun14/project-perturb architecture

> Architecture diagram of the GitHub repository ivysun14/project-perturb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ivysun14/project-perturb
- Repository: https://github.com/ivysun14/project-perturb

## Overview

This repository is a research benchmark for classifying differential-expression outcomes in single-cell perturbation data, with eight alternative methods and post-prediction calibration. The documented data workflow is DE-label generation, train/test splitting, and an optional calibration split; model-specific training and prediction scripts then produce results for analysis. The README establishes the broad benchmark and calibration relationships, while sampled source confirms selected implementation links. Many method-specific internals are unsampled, so the graph keeps those branches at their documented subsystem level.

Main entry points: [`majority_vote/calibration_split.py`](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/calibration_split.py) (Calibration split), [`Scouter/scouter_train_full.py`](https://github.com/ivysun14/project-perturb/blob/main/Scouter/scouter_train_full.py) (Scouter), [`majority_vote/DE_DOC_stats.py`](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/DE_DOC_stats.py) (DE label calling), [`majority_vote/train_test_split.py`](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/train_test_split.py) (Train/test splits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_rawdata[("Perturbation data")]
  node_de_labels["DE label calling<br/>[DE_DOC_stats.py]"]
  node_splits["Train/test splits"]
  node_cal_split["Calibration split"]
end

subgraph group_baselines["Classification methods"]
  node_majority["Majority vote"]
  node_knn["KNN classifier<br/>[knn_classifier.py]"]
  node_logreg["Logistic regression<br/>[logistic_reg.py]"]
end

subgraph group_models["Expression models"]
  node_scouter["Scouter"]
  node_transcouter["TranScouter"]
  node_state["STATE"]
  node_vae["Perturbation VAE<br/>[main.py]"]
  node_scvi["scVI<br/>[_model.py]"]
end

subgraph group_cal["Calibration"]
  node_sparsity_cal["Sparsity calibration"]
  node_variance_cal["Variance calibration<br/>[calibrate_var.py]"]
  node_logreg_cal["DE logreg calibration"]
end

subgraph group_analysis["Analysis"]
  node_predictions["Model predictions"]
  node_metric_eval["Benchmark metrics<br/>[perturb_metrics.py]"]
  node_error_analysis["Error analysis<br/>[error_utility.py]"]
  node_eda["Exploratory analysis"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_de_labels
node_rawdata -->|"tests for DE"| node_de_labels
node_de_labels -->|"labels perturbations"| node_splits
node_splits -->|"carves calibration set"| node_cal_split
node_cal_split -->|"supplies split data"| node_majority
node_cal_split -->|"supplies split data"| node_knn
node_cal_split -->|"supplies split data"| node_logreg
node_cal_split -->|"supplies split data"| node_scouter
node_cal_split -->|"supplies split data"| node_transcouter
node_cal_split -->|"supplies split data"| node_state
node_cal_split -->|"supplies split data"| node_vae
node_cal_split -->|"supplies split data"| node_scvi
node_majority -->|"produces"| node_predictions
node_knn -->|"produces"| node_predictions
node_logreg -->|"produces"| node_predictions
node_scouter -->|"produces"| node_predictions
node_transcouter -->|"produces"| node_predictions
node_state -->|"produces"| node_predictions
node_vae -->|"produces"| node_predictions
node_scvi -->|"produces"| node_predictions
node_predictions -->|"calibrates zeros"| node_sparsity_cal
node_predictions -->|"calibrates variance"| node_variance_cal
node_predictions -->|"calibrates DE"| node_logreg_cal
node_predictions -->|"evaluated by"| node_metric_eval
node_predictions -->|"analyzed for errors"| node_error_analysis
node_predictions -->|"visualized by"| node_eda
node_scouter -->|"metric calls"| node_metric_eval

click node_de_labels "https://github.com/ivysun14/project-perturb/blob/main/majority_vote/DE_DOC_stats.py"
click node_splits "https://github.com/ivysun14/project-perturb/blob/main/majority_vote/train_test_split.py"
click node_cal_split "https://github.com/ivysun14/project-perturb/blob/main/majority_vote/calibration_split.py"
click node_majority "https://github.com/ivysun14/project-perturb/blob/main/majority_vote/majority_transfer_full.py"
click node_knn "https://github.com/ivysun14/project-perturb/blob/main/KNN_vote/knn_classifier.py"
click node_logreg "https://github.com/ivysun14/project-perturb/blob/main/logistic_reg/logistic_reg.py"
click node_scouter "https://github.com/ivysun14/project-perturb/blob/main/Scouter/scouter_train_full.py"
click node_transcouter "https://github.com/ivysun14/project-perturb/blob/main/TranScouter/step2_train_full.py"
click node_state "https://github.com/ivysun14/project-perturb/blob/main/STATE/step2_train_full.py"
click node_vae "https://github.com/ivysun14/project-perturb/blob/main/VAE/main.py"
click node_scvi "https://github.com/ivysun14/project-perturb/blob/main/scVI/scVI_src/models/scvi/_model.py"
click node_sparsity_cal "https://github.com/ivysun14/project-perturb/blob/main/calibration/calibrate_sparsity.py"
click node_variance_cal "https://github.com/ivysun14/project-perturb/blob/main/calibration/var_calibration/calibrate_var.py"
click node_logreg_cal "https://github.com/ivysun14/project-perturb/blob/main/calibration/logreg_calibration/calibrate_de_logreg_within.py"
click node_metric_eval "https://github.com/ivysun14/project-perturb/blob/main/perturb_metrics.py"
click node_error_analysis "https://github.com/ivysun14/project-perturb/blob/main/majority_vote/error_utility.py"
click node_eda "https://github.com/ivysun14/project-perturb/blob/main/EDA/plot_model_prediction_eda.py"

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_rawdata,node_de_labels,node_splits,node_cal_split toneBlue
class node_majority,node_knn,node_logreg toneAmber
class node_scouter,node_transcouter,node_state,node_vae,node_scvi toneMint
class node_sparsity_cal,node_variance_cal,node_logreg_cal toneRose
class node_predictions,node_metric_eval,node_error_analysis,node_eda,node_researcher toneIndigo
```

## Components

### Data preparation

- **Perturbation data**
- [DE label calling](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/DE_DOC_stats.py): `majority_vote/DE_DOC_stats.py`
- [Train/test splits](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/train_test_split.py): `majority_vote/train_test_split.py`
- [Calibration split](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/calibration_split.py): `majority_vote/calibration_split.py`

### Classification methods

- [Majority vote](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/majority_transfer_full.py): `majority_vote/majority_transfer_full.py`
- [KNN classifier](https://github.com/ivysun14/project-perturb/blob/main/KNN_vote/knn_classifier.py): `KNN_vote/knn_classifier.py`
- [Logistic regression](https://github.com/ivysun14/project-perturb/blob/main/logistic_reg/logistic_reg.py): `logistic_reg/logistic_reg.py`

### Expression models

- [Scouter](https://github.com/ivysun14/project-perturb/blob/main/Scouter/scouter_train_full.py): `Scouter/scouter_train_full.py`
- [TranScouter](https://github.com/ivysun14/project-perturb/blob/main/TranScouter/step2_train_full.py): `TranScouter/step2_train_full.py`
- [STATE](https://github.com/ivysun14/project-perturb/blob/main/STATE/step2_train_full.py): `STATE/step2_train_full.py`
- [Perturbation VAE](https://github.com/ivysun14/project-perturb/blob/main/VAE/main.py): `VAE/main.py`
- [scVI](https://github.com/ivysun14/project-perturb/blob/main/scVI/scVI_src/models/scvi/_model.py): `scVI/scVI_src/models/scvi/_model.py`

### Calibration

- [Sparsity calibration](https://github.com/ivysun14/project-perturb/blob/main/calibration/calibrate_sparsity.py): `calibration/calibrate_sparsity.py`
- [Variance calibration](https://github.com/ivysun14/project-perturb/blob/main/calibration/var_calibration/calibrate_var.py): `calibration/var_calibration/calibrate_var.py`
- [DE logreg calibration](https://github.com/ivysun14/project-perturb/blob/main/calibration/logreg_calibration/calibrate_de_logreg_within.py): `calibration/logreg_calibration/calibrate_de_logreg_within.py`

### Analysis

- **Model predictions**
- [Benchmark metrics](https://github.com/ivysun14/project-perturb/blob/main/perturb_metrics.py): `perturb_metrics.py`
- [Error analysis](https://github.com/ivysun14/project-perturb/blob/main/majority_vote/error_utility.py): `majority_vote/error_utility.py`
- [Exploratory analysis](https://github.com/ivysun14/project-perturb/blob/main/EDA/plot_model_prediction_eda.py): `EDA/plot_model_prediction_eda.py`

### Other components

- **Researcher**

## Connections

- Researcher → DE label calling: runs (evidence: `README.md`)
- Perturbation data → DE label calling: tests for DE (evidence: `README.md`)
- DE label calling → Train/test splits: labels perturbations (evidence: `README.md`)
- Train/test splits → Calibration split: carves calibration set (evidence: `README.md`)
- Calibration split → Majority vote: supplies split data (evidence: `README.md`)
- Calibration split → KNN classifier: supplies split data (evidence: `README.md`)
- Calibration split → Logistic regression: supplies split data (evidence: `README.md`)
- Calibration split → Scouter: supplies split data (evidence: `README.md`)
- Calibration split → TranScouter: supplies split data (evidence: `README.md`)
- Calibration split → STATE: supplies split data (evidence: `README.md`)
- Calibration split → Perturbation VAE: supplies split data (evidence: `README.md`)
- Calibration split → scVI: supplies split data (evidence: `README.md`)
- Majority vote → Model predictions: produces (evidence: `README.md`)
- KNN classifier → Model predictions: produces (evidence: `README.md`)
- Logistic regression → Model predictions: produces (evidence: `README.md`)
- Scouter → Model predictions: produces (evidence: `README.md`)
- TranScouter → Model predictions: produces (evidence: `README.md`)
- STATE → Model predictions: produces (evidence: `README.md`)
- Perturbation VAE → Model predictions: produces (evidence: `README.md`)
- scVI → Model predictions: produces (evidence: `README.md`)
- Model predictions → Sparsity calibration: calibrates zeros (evidence: `calibration/calibrate_sparsity.py`)
- Model predictions → Variance calibration: calibrates variance (evidence: `README.md`)
- Model predictions → DE logreg calibration: calibrates DE (evidence: `README.md`)
- Model predictions → Benchmark metrics: evaluated by (evidence: `perturb_metrics.py`)
- Model predictions → Error analysis: analyzed for errors (evidence: `majority_vote/error_utility.py`)
- Model predictions → Exploratory analysis: visualized by (evidence: `EDA/plot_model_prediction_eda.py`)
- Scouter → Benchmark metrics: metric calls