# qihang-zou/cisformer architecture

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

- Interactive diagram: https://gitdiagram.com/qihang-zou/cisformer
- Repository: https://github.com/qihang-zou/cisformer

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "cisformer Package"
        runner["runner.py"]:::cli
        generate["generate_default_config.py"]:::data
        preprocess["data_preprocess.py"]:::data
        r2a_train["rna2atac_train.py"]:::core
        a2r_train["atac2rna_train.py"]:::core
        r2a_pred["rna2atac_predict.py"]:::core
        a2r_pred["atac2rna_predict.py"]:::core
        linker["map_rna_atac.py"]:::core
        subgraph "M2Mmodel"
            m2m["M2M.py"]:::core
            block["block.py"]:::core
            utils["utils.py"]:::core
        end
        resource["resource/"]:::data
    end

    pyproject["pyproject.toml"]:::data

    ext_libs["External Libraries: PyTorch/Flash-Attention/Accelerate\nScanpy/Igraph/Leidenalg\npybedtools"]:::external

    config["config.yaml"]:::artifact
    dataset["dataset (.h5ad)"]:::artifact
    checkpoint["checkpoint"]:::artifact
    predicted["predicted (.h5ad)"]:::artifact
    celltsv["cell-types.tsv"]:::artifact
    interaction["interaction matrix"]:::artifact

    runner -->|entry points| pyproject
    runner -->|invoke| generate
    generate -->|outputs| config
    resource -->|feeds into| preprocess
    generate -->|uses| resource
    config -->|read by| preprocess
    preprocess -->|produces| dataset
    dataset -->|input to| r2a_train
    dataset -->|input to| a2r_train
    r2a_train -->|uses| ext_libs
    a2r_train -->|uses| ext_libs
    r2a_train -->|trains| m2m
    a2r_train -->|trains| m2m
    r2a_train -->|saves| checkpoint
    a2r_train -->|saves| checkpoint
    checkpoint -->|loaded by| r2a_pred
    checkpoint -->|loaded by| a2r_pred
    dataset -->|also input to| r2a_pred
    dataset -->|also input to| a2r_pred
    r2a_pred -->|writes| predicted
    a2r_pred -->|writes| predicted
    predicted -->|with| celltsv
    celltsv -->|annotation for| linker
    checkpoint -->|with| linker
    linker -->|generates| interaction

    click runner "https://github.com/qihang-zou/cisformer/blob/main/cisformer/runner.py"
    click generate "https://github.com/qihang-zou/cisformer/blob/main/cisformer/generate_default_config.py"
    click preprocess "https://github.com/qihang-zou/cisformer/blob/main/cisformer/data_preprocess.py"
    click m2m "https://github.com/qihang-zou/cisformer/blob/main/cisformer/M2Mmodel/M2M.py"
    click block "https://github.com/qihang-zou/cisformer/blob/main/cisformer/M2Mmodel/block.py"
    click utils "https://github.com/qihang-zou/cisformer/blob/main/cisformer/M2Mmodel/utils.py"
    click r2a_train "https://github.com/qihang-zou/cisformer/blob/main/cisformer/rna2atac_train.py"
    click a2r_train "https://github.com/qihang-zou/cisformer/blob/main/cisformer/atac2rna_train.py"
    click r2a_pred "https://github.com/qihang-zou/cisformer/blob/main/cisformer/rna2atac_predict.py"
    click a2r_pred "https://github.com/qihang-zou/cisformer/blob/main/cisformer/atac2rna_predict.py"
    click linker "https://github.com/qihang-zou/cisformer/blob/main/cisformer/map_rna_atac.py"
    click resource "https://github.com/qihang-zou/cisformer/tree/main/cisformer/resource/"
    click pyproject "https://github.com/qihang-zou/cisformer/blob/main/pyproject.toml"
    click testdata "https://github.com/qihang-zou/cisformer/tree/main/test_data/"

    classDef cli fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef data fill:#fc9,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef artifact fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
