TransGCN a spatial transcript expression imputation tool

Read full text Summarise with VIRAT
Authors: Steven Yan
Cited by: 0

Summary

No summary yet. VIRAT can read this paper and write a plain-language summary of its aim, methods, key findings and limitations.

Summarise with VIRAT Free to try with your Science Catalogs account.

Abstract

Note: this record is outdated please refer to v5: TransGCN:latest Spatial Gene Imputation Toolkit TransGCN TransGCN is a graph-based spatial gene imputation pipeline with dataset processing, TransGCN training and inference, and baseline benchmark wrappers for SpaGE, STPlus, GraphST, Tangram, and Seurat. Dataset processing TransGCN training Custom graph priors Benchmark wrappers Quick Start Use setup_linux_env.sh for the main CPU Python workflow. Use setup_linux_gpu_env.sh for CUDA Python workflows. Use setup_seurat_env.sh only for the Seurat benchmark. Use setup_plot_env.sh if you want the plotting workflow under plot/. The shell wrappers activate the chosen conda env internally. Contents Repository Layout Linux Setup Operating System & Hardware Dataset Processing Training Inference Custom Train/Test Shell Wrappers Notes Repository Layout setup_linux_env.sh: recreate the main CPU Python environment (transgcn). setup_linux_gpu_env.sh: recreate the CUDA Python environment (transgcn-gpu). setup_seurat_env.sh: recreate the Seurat R environment (transgcn-seurat). model/process_datasets.py: generates model/data/scRNAseq_with_inferred_coords.hvg2000.h5ad. model/train_transgcn.py: generates training samples and trains TransGCN. model/test_transgcn.py: runs inference from saved training artifacts. model/run_transgcn.sh: example train-plus-test shell wrapper. model/benchmark_tools.sh: example baseline benchmark wrapper. Linux Environment Setup Main CPU Environment chmod +x setup_linux_env.sh bash ./setup_linux_env.sh conda activate transgcn Separate GPU Environment bash ./setup_linux_gpu_env.sh conda activate transgcn-gpu Separate Seurat Environment bash ./setup_seurat_env.sh conda activate transgcn-seurat The setup scripts expect micromamba, mamba, or conda to already be installed. Each setup script recreates its target environment from scratch. setup_linux_env.sh installs the main CPU Python stack and skips Seurat by default. setup_linux_gpu_env.sh is the CUDA path for Python workflows. setup_seurat_env.sh is only needed for the Seurat benchmark. Operating System And Hardware The provided setup scripts target x86 Linux. The shell wrappers and package installation steps assume a Linux environment. The main transgcn environment is the CPU path and can run the Python workflows without a GPU, although training and large benchmark runs may be slower on bigger datasets. The transgcn-gpu environment is intended for NVIDIA GPU systems with a working CUDA software stack. Use it when you want faster TransGCN training or GPU-enabled Python benchmarks. The transgcn-seurat environment is a separate R environment for the Seurat benchmark and is also intended to be created on Linux. The setup_plot_env.sh workflow also targets x86 Linux. Dataset Processing The dataset processing wrapper runs two steps: infer scRNA spatial coordinates with Tangram, then select highly variable genes from the inferred-coordinate scRNA object. python model/process_datasets.py Default outputs: model/data/scRNAseq_with_inferred_coords.h5ad model/data/scRNAseq_with_inferred_coords.hvg2000.h5ad TransGCN Training python model/train_transgcn.py \ --xenium_h5ad model/data/Xenium_V1_hSkin_Melanoma_Base_FFPE_outs.h5ad \ --scrna_h5ad model/data/scRNAseq_with_inferred_coords.hvg2000.h5ad \ --device cpu \ --epochs 300 \ --mask_frac 0.2 \ --pre_normalized_sc \ --out_dir model/results_transgcn \ --edge_cov_gene_list \ model/data/human_cell_atlas_covariance.npy.gz \ model/data/human_cell_atlas_genes.txt Important arguments: --xenium_h5ad specifies the spatial dataset to train against. --scrna_h5ad specifies the scRNA reference used to define predictor and target genes. --mask_frac specifies the ratio of held-out common genes used for evaluation. --edge_cov_gene_list takes alternating covariance-matrix and matching gene-list files. --n_sample_train auto lets the generator choose the training sample count automatically. Training runs generate_samples_multi_edges.py first and then spatial_set_transformer_mem_efficient.py. If no valid graph edges are generated, sample generation now fails fast with an error. Expected outputs in --out_dir include: spatial_set_transformer.pt gene_edge_index.pt train_knn_samples/ *.predictor.h5ad *.predicted.h5ad TransGCN Inference python model/test_transgcn.py \ --xenium_h5ad model/data/Xenium_V1_hSkin_Melanoma_Base_FFPE_outs.h5ad \ --scrna_h5ad model/data/scRNAseq_with_inferred_coords.hvg2000.h5ad \ --device cpu \ --pre_normalized_xe \ --out_dir model/results_transgcn \ --n_sample_test 1000 \ --full_output \ --hvg_file model/data/scRNAseq_with_inferred_coords.hvg2000.h5ad --full_output writes all imputable genes. Full output files start with pred_full. --hvg_file writes a targeted subset using genes from a custom .h5ad. Selected-gene files start with pred_selected. --output_variance writes Monte Carlo uncertainty estimates. --n_sample_test subsamples target cells or spots for inference. Held-out evaluation outputs start with X_pred_masked and X_true_masked. Custom Train/Test Example A common workflow is to train TransGCN on one custom dataset and then impute a different custom spatial dataset using the saved model and custom graph prior. python model/train_transgcn.py \ --xenium_h5ad model/data/custom_train_spatial.h5ad \ --scrna_h5ad model/data/custom_reference_scrna.h5ad \ --device cpu \ --epochs 300 \ --mask_frac 0 \ --out_dir model/results_transgcn_custom \ --edge_cov_gene_list \ model/data/custom_edge_matrix1.npy.gz \ model/data/custom_edge_genes1.txt \ model/data/custom_edge_matrix2.npy.gz \ model/data/custom_edge_genes2.txt The gene order in each custom edge matrix and matching gene list must match custom_reference_scrna exactly. You are encouraged to provide your own edge matrix and gene list when they better match your custom training gene set. Set --mask_frac 0 if you do not want held-out evaluation. In that case, test_transgcn.py will not write masked-gene outputs. python model/test_transgcn.py \ --xenium_h5ad model/data/custom_test_spatial.h5ad \ --scrna_h5ad model/data/custom_reference_scrna.h5ad \ --device cpu \ --out_dir model/results_transgcn_custom \ --hvg_file model/data/custom_target_genes.h5ad Only genes present in custom_reference_scrna can be written to the selected-gene output file. Shell Wrappers bash model/run_transgcn.sh CONDA_ENV_NAME=transgcn bash model/benchmark_tools.sh model/run_transgcn.sh activates CONDA_ENV_NAME internally and then runs the example train and test commands. model/benchmark_tools.sh activates CONDA_ENV_NAME internally and runs the Python baseline benchmarks. Use CONDA_ENV_NAME=transgcn-gpu bash model/benchmark_tools.sh if you want the Python benchmarks to run inside the GPU environment. Run the Seurat benchmark separately from transgcn-seurat. Notes The wrappers assume the referenced data files exist under model/data/ unless you pass explicit paths. generate_samples_multi_edges.py throws an error if no graph edges are generated. The GraphST benchmark wrapper builds a square neighborhood matrix so it is compatible with the current GraphST package. Use the CPU or GPU Python environment for TransGCN, SpaGE, STPlus, GraphST, and Tangram. Use the Seurat environment only for the Seurat benchmark. To explore the plots, run bash ./setup_plot_env.sh, activate transgcn-plot, and then work from plot/. Datasets Description: Datasets with name containing "scRNAseq" or "Combined_union" are scRNA-seq datasets used for model training, datasets with name containing "Xenium" or "visium" are 10x Xenium or Visium HD datasets used for model testing.

Fields of Study & Subjects

Single-cell and spatial transcriptomics Gene expression and cancer classification Genomics and Phylogenetic Studies

Publication details

Journal / source
Zenodo (CERN European Organization for Nuclear Research)
Publication date
20 March 2026
Language
EN
Document type
Dataset