cisformer 1.0.0__tar.gz

cisformer-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+cisformer_config/
+dist/
+logs/
+output/
+preprocessed_dataset/
+save/
+cisformer/resource/gene_surround_enhancers_250kbp_idx.pkl
+cisformer/resource/gene_surround_enhancers_250kbp.pkl

cisformer-1.0.0/LICENCE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cisformer-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: cisformer
+Version: 1.0.0
+Summary: Cisformer command-line tools
+Project-URL: Homepage, https://github.com/wanglabtongji/Cisformer
+Project-URL: Issues, https://github.com/qihang-zou/Cisformer/issues
+Author-email: Chenfei Wang <08chenfeiwang@tongji.edu.cn>
+License-Expression: MIT
+License-File: LICENCE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Translation of Single-Cell Data Across Modalities with **Cisformer**
+![logo](figs/logo.png)
+
+## About
+**Cisformer** is a novel cross-modal deep learning model based on the Transformer architecture. It enables **bidirectional prediction and association between cis-regulatory elements and genes** at the single-cell level, with high efficiency and accuracy.
+
+To meet real-world application needs and improve model performance:
+- For the RNA2ATAC task, a trained Cisformer can generate high-quality scATAC-seq data from scRNA-seq inputs.
+- For the ATAC2RNA task, the model can generate pseudo-scRNA-seq data and construct a highly accurate cis-regulatory interaction matrix between cis-elements and genes.
+
+## Documentation
+For detailed usage and examples, see the [official documentation]().  
+If you encounter any issues, feel free to open an [issue](https://github.com/qihang-zou/Cisformer/issues).
+
+## Environment Setup
+
+### Miniconda3
+We recommend using [Miniconda3](https://www.anaconda.com/docs/getting-started/miniconda/main) or [Anaconda](https://www.anaconda.com/) as the environment manager. Make sure `conda` is installed.
+
+### Creating the Cisformer Environment
+To get started, copy `requirement.sh` to your local server and run:
+```bash
+conda create -n cisformer python=3.10
+conda activate cisformer
+bash ./requirement.sh
+```
+Alternatively, you can install dependencies manually:
+```bash
+conda create -n cisformer python=3.10
+conda activate cisformer
+conda install numpy=1.23
+conda install pytorch=2.2.1 torchvision=0.17.1 torchaudio=2.2.1 pytorch-cuda=12.1 -c pytorch -c nvidia
+conda install -c conda-forge accelerate==0.22.0
+conda install -c conda-forge scanpy python-igraph leidenalg
+pip install ninja
+pip install flash-attn --no-build-isolation
+pip install torcheval
+conda install tensorboard
+conda install pybedtools
+```
+
+## Install from PyPI
+```bash
+pip install cisformer
+```
+
+---
+
+# Quick Start
+
+## Generate Default Config Files
+```bash
+cisformer generate_default_config
+```
+This command will create a folder named `cisformer_config` in the current directory, containing the following config files:
+- `accelerate_config.yaml`
+- `atac2rna_config.yaml`
+- `rna2atac_config.yaml`
+
+Cisformer uses [Hugging Face Accelerate](https://huggingface.co/docs/accelerate/index) for distributed training. You may need to modify `cisformer_config/accelerate_config.yaml` based on your server setup. See [Accelerate launch docs](https://huggingface.co/docs/accelerate/basic_tutorials/launch) for more information.
+
+## RNA ➝ ATAC
+
+### 1. Configure Parameters (Optional)
+Edit the RNA2ATAC configuration file:
+- `cisformer_config/rna2atac_config.yaml`  
+Refer to the [documentation]() for parameter explanations.
+
+### 2. Data Preprocessing
+Cisformer requires raw scRNA-seq and scATAC-seq data in [Scanpy `.h5ad` format](https://scanpy.readthedocs.io/en/stable/tutorials/index.html).
+
+To preprocess:
+```bash
+cisformer data_preprocess -r test_data/rna.h5ad -a test_data/atac.h5ad -s preprocessed_dataset
+```
+- `-r`: path to RNA `.h5ad` file  
+- `-a`: path to ATAC `.h5ad` file  
+- `-s`: output directory  
+
+See the [documentation]() for additional options and output file details.
+
+### 3. Model Training
+```bash
+cisformer rna2atac_train -t preprocessed_dataset/cisformer_rna2atac_train_dataset -v preprocessed_dataset/cisformer_rna2atac_val_dataset -n rna2atac_test
+```
+- `-t`: path to training dataset  
+- `-v`: path to validation dataset  
+- `-n`: project name  
+
+A `save` directory will be created (or can be customized using `-s`). Inside, you'll find a folder like `2025-05-12_rna2atac_test`, which contains the trained models. Typically, the model from the last epoch performs best.
+
+Refer to the [documentation]() for more options and output explanations.
+
+### 4. Prediction
+```bash
+cisformer rna2atac_predict -r preprocessed_dataset/test_rna.h5ad -m save/2025-05-12_rna2atac_test/epoch34/pytorch_model.bin
+```
+- `-r`: RNA `.h5ad` file for prediction  
+- `-m`: trained model checkpoint
+
+The predicted ATAC matrix will be saved to `output/cisformer_predicted_atac.h5ad` by default.  
+See the [documentation]() for more.
+
+---
+
+## ATAC ➝ RNA
+
+### 1. Configure Parameters (Optional)
+Edit the ATAC2RNA configuration file:
+- `cisformer_config/atac2rna_config.yaml`
+
+See the [documentation]() for details.
+
+### 2. Data Preprocessing
+```bash
+cisformer data_preprocess -r test_data/rna.h5ad -a test_data/atac.h5ad -s preprocessed_dataset --atac2rna
+```
+- `--atac2rna` flag indicates this is for the ATAC2RNA direction  
+Other arguments are the same as in RNA2ATAC.
+
+### 3. Model Training
+```bash
+cisformer atac2rna_train -d preprocessed_dataset/cisformer_atac2rna_train_dataset -n atac2rna_test
+```
+- `-d`: path to ATAC2RNA training dataset  
+- `-n`: project name
+
+A `save` directory will be created (or customized with `-s`). The folder `2025-05-12_atac2rna_test` will contain the trained model, with the final epoch model usually performing best.
+
+### 4. Prediction (Optional)
+```bash
+cisformer atac2rna_predict -d preprocessed_dataset/cisformer_atac2rna_test_dataset/atac2rna_0.pt -m save/2025-05-12_atac2rna_test/epoch30/pytorch_model.bin
+```
+- `-d`: path to test dataset `.pt` file  
+- `-m`: trained model checkpoint
+
+Output will be saved to `output/cisformer_predicted_rna.h5ad`.
+
+### 5. Link cis-regulators and Genes
+```bash
+cisformer atac2rna_link -d preprocessed_dataset/cisformer_atac2rna_test_dataset/atac2rna_0.pt -m save/2025-05-12_atac2rna_test/epoch30/pytorch_model.bin -c test_data/celltype_info.tsv
+```
+- `-d`: test `.pt` file (must be accompanied by `cell_info.tsv` in the same folder)  
+- `-m`: trained model  
+- `-c`: TSV file mapping each cell barcode to a cell type (no header)
+
+Example of `celltype_info.tsv`:
+```
+GTACCGGGTATACTGG-1	CD14 Mono
+ACTGAATGTCACCAAA-1	cDC2
+AACCTTGCAAACTGTT-1	CD14 Mono
+...
+```
+
+The output folder `output/cisformer_link` will contain `.h5ad` files linking cis-regulators to genes for each cell type.
+
+---
+
+## Acknowledgements
+- [flash-attention2](https://github.com/Dao-AILab/flash-attention)
+- [Hugging Face](https://huggingface.co/)

cisformer-1.0.0/README.md

@@ -0,0 +1,161 @@
+# Translation of Single-Cell Data Across Modalities with **Cisformer**
+![logo](figs/logo.png)
+
+## About
+**Cisformer** is a novel cross-modal deep learning model based on the Transformer architecture. It enables **bidirectional prediction and association between cis-regulatory elements and genes** at the single-cell level, with high efficiency and accuracy.
+
+To meet real-world application needs and improve model performance:
+- For the RNA2ATAC task, a trained Cisformer can generate high-quality scATAC-seq data from scRNA-seq inputs.
+- For the ATAC2RNA task, the model can generate pseudo-scRNA-seq data and construct a highly accurate cis-regulatory interaction matrix between cis-elements and genes.
+
+## Documentation
+For detailed usage and examples, see the [official documentation]().  
+If you encounter any issues, feel free to open an [issue](https://github.com/qihang-zou/Cisformer/issues).
+
+## Environment Setup
+
+### Miniconda3
+We recommend using [Miniconda3](https://www.anaconda.com/docs/getting-started/miniconda/main) or [Anaconda](https://www.anaconda.com/) as the environment manager. Make sure `conda` is installed.
+
+### Creating the Cisformer Environment
+To get started, copy `requirement.sh` to your local server and run:
+```bash
+conda create -n cisformer python=3.10
+conda activate cisformer
+bash ./requirement.sh
+```
+Alternatively, you can install dependencies manually:
+```bash
+conda create -n cisformer python=3.10
+conda activate cisformer
+conda install numpy=1.23
+conda install pytorch=2.2.1 torchvision=0.17.1 torchaudio=2.2.1 pytorch-cuda=12.1 -c pytorch -c nvidia
+conda install -c conda-forge accelerate==0.22.0
+conda install -c conda-forge scanpy python-igraph leidenalg
+pip install ninja
+pip install flash-attn --no-build-isolation
+pip install torcheval
+conda install tensorboard
+conda install pybedtools
+```
+
+## Install from PyPI
+```bash
+pip install cisformer
+```
+
+---
+
+# Quick Start
+
+## Generate Default Config Files
+```bash
+cisformer generate_default_config
+```
+This command will create a folder named `cisformer_config` in the current directory, containing the following config files:
+- `accelerate_config.yaml`
+- `atac2rna_config.yaml`
+- `rna2atac_config.yaml`
+
+Cisformer uses [Hugging Face Accelerate](https://huggingface.co/docs/accelerate/index) for distributed training. You may need to modify `cisformer_config/accelerate_config.yaml` based on your server setup. See [Accelerate launch docs](https://huggingface.co/docs/accelerate/basic_tutorials/launch) for more information.
+
+## RNA ➝ ATAC
+
+### 1. Configure Parameters (Optional)
+Edit the RNA2ATAC configuration file:
+- `cisformer_config/rna2atac_config.yaml`  
+Refer to the [documentation]() for parameter explanations.
+
+### 2. Data Preprocessing
+Cisformer requires raw scRNA-seq and scATAC-seq data in [Scanpy `.h5ad` format](https://scanpy.readthedocs.io/en/stable/tutorials/index.html).
+
+To preprocess:
+```bash
+cisformer data_preprocess -r test_data/rna.h5ad -a test_data/atac.h5ad -s preprocessed_dataset
+```
+- `-r`: path to RNA `.h5ad` file  
+- `-a`: path to ATAC `.h5ad` file  
+- `-s`: output directory  
+
+See the [documentation]() for additional options and output file details.
+
+### 3. Model Training
+```bash
+cisformer rna2atac_train -t preprocessed_dataset/cisformer_rna2atac_train_dataset -v preprocessed_dataset/cisformer_rna2atac_val_dataset -n rna2atac_test
+```
+- `-t`: path to training dataset  
+- `-v`: path to validation dataset  
+- `-n`: project name  
+
+A `save` directory will be created (or can be customized using `-s`). Inside, you'll find a folder like `2025-05-12_rna2atac_test`, which contains the trained models. Typically, the model from the last epoch performs best.
+
+Refer to the [documentation]() for more options and output explanations.
+
+### 4. Prediction
+```bash
+cisformer rna2atac_predict -r preprocessed_dataset/test_rna.h5ad -m save/2025-05-12_rna2atac_test/epoch34/pytorch_model.bin
+```
+- `-r`: RNA `.h5ad` file for prediction  
+- `-m`: trained model checkpoint
+
+The predicted ATAC matrix will be saved to `output/cisformer_predicted_atac.h5ad` by default.  
+See the [documentation]() for more.
+
+---
+
+## ATAC ➝ RNA
+
+### 1. Configure Parameters (Optional)
+Edit the ATAC2RNA configuration file:
+- `cisformer_config/atac2rna_config.yaml`
+
+See the [documentation]() for details.
+
+### 2. Data Preprocessing
+```bash
+cisformer data_preprocess -r test_data/rna.h5ad -a test_data/atac.h5ad -s preprocessed_dataset --atac2rna
+```
+- `--atac2rna` flag indicates this is for the ATAC2RNA direction  
+Other arguments are the same as in RNA2ATAC.
+
+### 3. Model Training
+```bash
+cisformer atac2rna_train -d preprocessed_dataset/cisformer_atac2rna_train_dataset -n atac2rna_test
+```
+- `-d`: path to ATAC2RNA training dataset  
+- `-n`: project name
+
+A `save` directory will be created (or customized with `-s`). The folder `2025-05-12_atac2rna_test` will contain the trained model, with the final epoch model usually performing best.
+
+### 4. Prediction (Optional)
+```bash
+cisformer atac2rna_predict -d preprocessed_dataset/cisformer_atac2rna_test_dataset/atac2rna_0.pt -m save/2025-05-12_atac2rna_test/epoch30/pytorch_model.bin
+```
+- `-d`: path to test dataset `.pt` file  
+- `-m`: trained model checkpoint
+
+Output will be saved to `output/cisformer_predicted_rna.h5ad`.
+
+### 5. Link cis-regulators and Genes
+```bash
+cisformer atac2rna_link -d preprocessed_dataset/cisformer_atac2rna_test_dataset/atac2rna_0.pt -m save/2025-05-12_atac2rna_test/epoch30/pytorch_model.bin -c test_data/celltype_info.tsv
+```
+- `-d`: test `.pt` file (must be accompanied by `cell_info.tsv` in the same folder)  
+- `-m`: trained model  
+- `-c`: TSV file mapping each cell barcode to a cell type (no header)
+
+Example of `celltype_info.tsv`:
+```
+GTACCGGGTATACTGG-1	CD14 Mono
+ACTGAATGTCACCAAA-1	cDC2
+AACCTTGCAAACTGTT-1	CD14 Mono
+...
+```
+
+The output folder `output/cisformer_link` will contain `.h5ad` files linking cis-regulators to genes for each cell type.
+
+---
+
+## Acknowledgements
+- [flash-attention2](https://github.com/Dao-AILab/flash-attention)
+- [Hugging Face](https://huggingface.co/)