How qihang-zou/cisformer works
Project Type and Purpose
• Cisformer is a Python-based CLI tool and library for bidirectional translation between scRNA-seq and scATAC-seq data using a transformer-based deep learning model.
• It provides commands to generate configs, preprocess data, train models, run predictions, and link cis-regulatory elements to genes.
High-Level Components
a. CLI Front-End
• runner.py registers subcommands (generate_default_config, data_preprocess, rna2atac_train, atac2rna_train, predict, link).
• Entry points defined in pyproject.toml for installation via pip.
b. Configuration Layer
• Default YAML templates in cisformer_config (accelerate, rna2atac, atac2rna).
• generate_default_config populates a local cisformer_config folder.
c. Data Preprocessing
• data_preprocess.py uses Scanpy to load .h5ad, applies filtering, normalization, and outputs training/validation datasets.
• Utilizes pybedtools for genomic region operations, existing cis-element and gene resources in cisformer/resource.
d. Core Model Library
• cisformer.M2Mmodel package:
– M2M.py defines the main Transformer encoder-decoder model.
– block.py contains attention, feed-forward, positional encoding modules.
– utils.py has helper functions (masking, batching, metrics).
e. Training and Prediction Workflows
• atac2rna_train.py & rna2atac_train.py load preprocessed datasets, configure Hugging Face Accelerate for distributed training, instantiate M2M model, run training loop, save checkpoints.
• atac2rna_predict.py & rna2atac_predict.py load a trained model checkpoint to perform inference and write .h5ad outputs.
f. Post-processing / Linking
• atac2rna_link.py generates cis-regulatory interaction matrices per cell type using trained model outputs and cell-type annotations.
External Dependencies & Data Resources
• PyTorch + Flash-Attention + Hugging Face Accelerate for model execution.
• Scanpy, python-igraph, leidenalg for single-cell preprocessing.
• pybedtools for genomic interval operations.
• Resources under cisformer/resource (GTF, BED, gene listings).
• Test data in test_data/ for CI and quickstart.
Relationships & Data Flow
• CLI → Config Loader → Data Preprocessor → Dataset Files
• Dataset Files → Training Script → M2Mmodel → Checkpoints
• Checkpoints + Dataset Files → Prediction Script → Predicted .h5ad
• Checkpoints + Predicted Data + Cell-Type TSV → Linking Script → Interaction Matrices
• Throughout: File system I/O, external libs invoked at each step.
Architectural Patterns & Design Principles
• Separation of concerns: distinct modules for CLI, preprocessing, model definition, training, prediction, linking.
• Modular Transformer blocks in cisformer.M2Mmodel following standard encoder-decoder pattern.
• Use of external configuration for flexibility (YAML files, Hugging Face Accelerate integration).
• Resource encapsulation: static reference datasets bundled under cisformer/resource.
Elements
• Clear, unique labels for all components and scripts.
• Arrowheads to show invocation order and data transformations.