Overview

GARAGE

Graph-Attentive Rare-cell-Aware single-cell data GEneration

---

How to read these docs

GARAGE’s documentation follows the Diátaxis framework to serve different needs at different points in your journey:

• Getting Started — first-time setup and your first synthetic dataset.

• Tutorials — step-by-step, end-to-end walkthroughs for research use cases.

• How‑to Guides — focused recipes for specific tasks.

• Theoretical Background — understanding the architecture and methods.

• API Reference — function signatures, module-level documentation.

• Appendix — glossary, FAQ, troubleshooting, citation, and changelog.

---

Getting Started

• Summary
  • Workflow
  • Key Features
  • Repository Structure
  • Citation
  • License
• Installation
  • Prerequisites
  • Step 1: Clone the Repository
  • Step 2: Set Up the Environment
  • Step 3: Install Dependencies
  • Step 4: Verify Installation
  • Step 5: Run the Pipeline
• Quickstart
  • Prerequisites
  • 1. Activate the Environment
  • 2. Verify Your Setup
  • 3. Run GARAGE on a Small Dataset (Yan)
  • 4. Validate the Generated Data
  • 5. Check the Wasserstein Distance
  • 6. View the Results
  • Next Steps
  • Common First-Time Issues
• Preparing Your Data
  • Required Input Files
  • Expression Matrix Format
  • Cell-Type Labels Format
  • Registering Your Dataset
  • Setting the Rare Threshold
  • Placing Your Files
  • Running GARAGE on Your Data
  • Troubleshooting
  • Example: Adding the CBMC Dataset from Scratch

Tutorials

• Tutorial: End-to-End Guide
  • Step 1: Understand Your Dataset
  • Step 2: Run GARAGE (GAT + GAN)
  • Step 3: Compute Wasserstein Distance
  • Step 4: Feature Selection and Clustering Validation
  • Step 5: Biological Validation
  • Step 6: Benchmark Against SOTA Models
  • Step 7: Run Ablation Studies
  • Complete Workflow Script
  • What’s Next
• Tutorial: Biological Validation
  • What Biological Validation Measures
  • Step 1: Run the Main Biological Validation
  • Step 2: Interpret the Results
  • Step 3: Marker Gene Clustering
  • Step 4: Held-out Rare Cell Utility
  • Biological Interpretation for Papers
  • Customising for Your Own Dataset
• Tutorial: Rare Cell Experiment
  • Experimental Design
  • Step 1: Run the Experiment
  • Step 2: Interpret the Results
  • Step 3: Statistical Rigour
  • Customising the Experiment
  • Related Pages
• Tutorial: Benchmark Against SOTA
  • Why Benchmark?
  • Step 1: Generate Data with All Models
  • Step 2: Compute Distributional Metrics
  • Step 3: Compute Clustering Metrics
  • Step 4: Build Summary Tables
  • Step 5: Generate Publication-Quality Figures
  • Step 6: Interpret the Results
  • Reproducing the Paper’s Figures
  • Adding a New Baseline
  • Related Pages

How‑to Guides

• How-to: Run GARAGE
  • Goal
  • Prerequisites
  • Steps
  • Output
  • Troubleshooting
  • Related
• How-to: Feature Selection
  • Goal
  • Prerequisites
  • Steps
  • Choosing the right method
  • Output
  • Troubleshooting
  • Related
• How-to: Clustering Validation
  • Goal
  • Prerequisites
  • Steps
  • Using the Python API
  • Troubleshooting
  • Related
• How-to: Compute Wasserstein Distance
  • Goal
  • Prerequisites
  • Steps
  • Interpreting the Output
  • Related
• How-to: Biological Validation
  • Goal
  • Prerequisites
  • Steps
  • Related
• How-to: Benchmarking
  • Goal
  • Prerequisites
  • Steps
  • Related
• How-to: Run Ablation Studies
  • Goal
  • Prerequisites
  • Steps
  • Interpreting the Results
  • Related
• How-to: Interpret Outputs
  • Goal
  • The Metric Pyramid
  • Scenario 1: Everything Looks Good
  • Scenario 2: Good WD, Poor Clustering
  • Scenario 3: Poor WD, Good Clustering
  • Scenario 4: Good ARI, Low macro-F1
  • Scenario 5: Everything Is Bad
  • Quick Diagnosis Table
  • Related

Theoretical Background

• Motivation
  • Why Generate Synthetic scRNA‑seq Data?
  • The GARAGE Approach
  • Where GARAGE Fits in the Literature
  • Who Should Use GARAGE?
  • Next Steps
• scRNA-seq Data Challenges
  • The Structure of scRNA-seq Data
  • Rare Cell Collapse in Generative Models
  • Dimensionality Reduction for scRNA-seq
  • Common Pitfalls
  • Further Reading
• GARAGE Architecture
  • Overview
  • Stage 1: GAT-Based Cell Selection
  • Stage 2: GAN Generation with Attention-Guided Seeding
  • Why the Two-Stage Architecture Works
  • Hyper-parameter Reference
  • Datasets
• Generative Adversarial Networks in GARAGE
  • The GAN Framework
  • How GARAGE Uses GANs
  • Advantages of GANs for scRNA-seq Data
  • Common Challenges and GARAGE’s Countermeasures
  • Variants Used in Benchmarking
• Graph Attention Networks in GARAGE
  • GAT Overview
  • GCN vs. GAT
  • GAT in GARAGE: The Cell Selection Stage
  • Full Implementation
  • References
• Evaluation Metrics
  • Distributional Metrics
  • Clustering-Based Metrics
  • Visualisation
  • Feature Selection Methods
  • Leiden Clustering
  • Recommended Evaluation Workflow
• Single Cell Clustering
  • What is single-cell clustering?
  • Key Steps
  • Applications
  • scRNA-seq vs. Bulk RNA-seq
• Wasserstein Distance
  • Overview
  • Wasserstein Distance in GARAGE
  • Related Metrics

API Reference

• config module
  • Constants
• data_generation module
  • GARAGE — Graph-Attentive Rare-cell-Aware single-cell data GEneration.
  • Discriminator
  • GATClassifier
  • Generator
  • gat_subsample()
  • generate_data()
  • load_dataset()
  • main()
  • run_garage()
  • sample_Z()
  • train_gan()
  • Wasserstein distance between real and generated scRNA-seq distributions.
  • load_generated()
  • load_real()
  • main()
  • wasserstein_distance()
  • Core Functions
• data_validation module
  • Data validation for GARAGE‑generated scRNA‑seq data.
  • cluster_and_evaluate()
  • cv2_selection()
  • load_generated()
  • load_labels()
  • load_real()
  • main()
  • plot_umap()
  • sweep_resolution()
  • Feature selection for scRNA-seq data (Python port of feature_selection.R).
  • cv2_selection()
  • fano_selection()
  • main()
  • pca_loading_selection()
  • run_feature_selection()
  • Core Functions
  • Resolution Sweep
  • Reference Notebook
• biological_analysis module
  • Biological validation of attention-prioritised cells.
  • enrichment_analysis()
  • load_cbmc()
  • main()
  • marker_expression_analysis()
  • per_celltype_positive_rate_analysis()
  • print_summary_interpretation()
  • run_gat_and_get_attention()
  • Held-out rare-cell utility experiment.
  • GATClassifier
  • GarageDiscriminator
  • GarageGenerator
  • LSHDiscriminator
  • LSHGenerator
  • VanillaDiscriminator
  • VanillaGenerator
  • evaluate_classifier()
  • evaluate_classifier_downgraded()
  • garage_gat_seeds()
  • generate_garage()
  • generate_lsh_gan()
  • generate_vanilla_gan()
  • knn_subsample()
  • load_data()
  • main()
  • sample_Z()
  • split_rare()
  • train_garage_gan()
  • train_lsh_gan()
  • train_vanilla_gan()
  • Fixed marker-gene clustering evaluation.
  • compute_ari_nmi()
  • evaluate_baseline()
  • evaluate_clustering()
  • evaluate_real_reference()
  • evaluate_sweep()
  • get_pseudo_labels()
  • load_garage_data()
  • load_gen_data()
  • load_real_data()
  • main()
  • select_markers_cbmc()
  • select_markers_muraro()
  • select_markers_pollen()
  • select_markers_yan()
  • Modules Overview
• ablation_study module
  • GAN training stability ablation study.
  • Discriminator
  • Generator
  • gat_subsample()
  • load_cbmc()
  • load_muraro()
  • load_pollen()
  • load_yan()
  • main()
  • sample_Z()
  • train_gan_with_leakage()
  • Critic
  • FDiscriminator
  • FGenerator
  • GATG_Discriminator
  • GATG_Generator
  • LSHDiscriminator
  • LSHGenerator
  • VanillaDiscriminator
  • VanillaGenerator
  • WGenerator
  • fisher_ratio()
  • gat_subsample()
  • knn_subsample()
  • load_labels()
  • load_real()
  • main()
  • sample_Z()
  • train_and_generate_fgan()
  • train_and_generate_gan()
  • train_and_generate_gatgan()
  • train_and_generate_lshgan()
  • train_and_generate_wgan()
  • Modules Overview
• analysis module
  • load_real()
  • load_synthetic()
  • main()
  • mmd_rbf()
  • sliced_wasserstein()
  • cluster_and_evaluate()
  • cv2()
  • evaluate_baseline()
  • evaluate_sweep()
  • load_gen()
  • load_labels()
  • load_real()
  • main()
  • fmt_mean_std()
  • main()
  • evaluate_ari()
  • fano_selection()
  • load_real()
  • main()
  • Fixed marker-gene clustering evaluation (grid sweep).
  • compute_ari_nmi()
  • evaluate_clustering()
  • evaluate_real_reference()
  • evaluate_sweep()
  • get_pseudo_labels()
  • load_garage_data()
  • load_gen_data()
  • load_real_data()
  • main()
  • select_markers_cbmc()
  • select_markers_muraro()
  • select_markers_pollen()
  • select_markers_yan()
  • load_gan_data()
  • load_garage_data()
  • load_lsh_gan_data()
  • load_real_data()
  • main()
  • mmd_rbf()
  • rbf_kernel()
  • load_gan_data()
  • load_garage_data()
  • load_lsh_gan_data()
  • load_real_data()
  • main()
  • sliced_wasserstein()
  • Modules Overview

Appendix

• Glossary
  • A
  • B
  • C
  • D
  • E
  • F
  • G
  • H
  • L
  • M
  • N
  • P
  • R
  • S
  • U
  • V
  • W
• FAQ
  • General
  • Generation
  • Validation
  • Troubleshooting
  • Citing GARAGE
  • Getting Help
• Troubleshooting
  • Installation issues
  • Runtime errors
  • Training problems
  • Validation problems
  • Build and docs
  • Still stuck?
• Citation
  • BibTeX
  • DOI
  • Citation File Format (CFF)
  • APA
  • License
• Changelog
  • [1.0.0] — 2025-09-28 (bioRxiv preprint)

Image credits: GARAGE architecture image by the authors; 10x Genomics scRNA-seq comparison used under fair-use for educational illustration.