DOCSEARCHbyAlgolia
Submit Docs

TOSICA

repository·main·Indexed 41 days ago

https://github.com/jackiehanlab/tosica

A Transformer-based tool for interpretable cell-type annotation in single-cell RNA-seq data. TOSICA uses attention mechanisms to provide explainable annotations by mapping genes to biological pathways. It includes functions for training models via TOSICA.train() and predicting cell types using TOSICA.pre().

Tokens
912
Snippets
5
Records
5
Agent score
50%

What's inside TOSICA

  1. Install TOSICA

    main

    You can install the TOSICA package either from the local repository root or directly from GitHub.

    Local Installation

    If you have cloned the repository, run:

    pip install .

    GitHub Installation

    pip install git+https://github.com/JackieHanLab/TOSICA.git
    pip install git+https://github.com/JackieHanLab/TOSICA.git

  2. Configure the TOSICA environment

    main

    TOSICA requires Python >= 3.8 and torch == 1.7.1. It is recommended to use conda to create a clean environment with scanpy and the specific PyTorch version required.

    conda create -n TOSICA python=3.8 scanpy
conda activate TOSICA
conda install pytorch=1.7.1 torchvision=0.8.2 torchaudio=0.7.2 cudatoolkit=10.1 -c pytorch
    conda create -n TOSICA python=3.8 scanpy
conda activate TOSICA
conda install pytorch=1.7.1 torchvision=0.8.2 torchaudio=0.7.2 cudatoolkit=10.1 -c pytorch

  3. Reproduce Figure 4 from the TOSICA paper

    main

    To reproduce the analyses presented in Figure 4 of the TOSICA paper, use the Fig4.ipynb notebook provided in this repository.

    Note: You must manually download the required dataset Fig4_raw.h5ad from the Figshare website before running the notebook, as it is not included in the repository.

    # Download Fig4_raw.h5ad from:
# https://figshare.com/articles/online_resource/Fig4_raw_h5ad/22237507

  4. Predict cell types with the TOSICA model

    main

    Use TOSICA.pre() to annotate a query dataset using a trained model.

    Important Requirement: The var_names (genes) of the ref_adata used during training and the query_adata used for prediction must be consistent and in the same order. You should align them using:

    query_adata = query_adata[:, ref_adata.var_names]

    Parameters:

    • query_adata: An AnnData object of the query dataset.
    • model_weight_path: Path to the weights generated during training (e.g., './my_project/model-6.pth').
    • project: The name of the project folder created during training.

    Outputs (added to query_adata or saved to disk):

    • query_adata.X: The Attention matrix
    • query_adata.obs['Prediction']: Predicted labels
    • query_adata.obs['Probability']: Probability of the prediction
    • query_adata.var['pathway_index']: Gene set for each column
    • ./<project>/gene2token_weights.csv: Weights matrix of genes to tokens
    new_adata = TOSICA.pre(query_adata, model_weight_path=<path_to_weight>, project=<my_project>)

  5. Train the TOSICA model

    main

    Use TOSICA.train() to train the model on a reference dataset. This process generates a project folder containing masks, pathway lists, label dictionaries, and model weights.

    Parameters:

    • ref_adata: An AnnData object representing the reference dataset.
    • gmt_path: Path to a .gmt file or a pre-prepared mask string.
    • project: The name of the output folder. Defaults to <gmt_path>_20xxxxxx.
    • label_name: The name of the label column in ref_adata.obs.

    Pre-prepared mask options:

    • human_gobp: GO_bp.gmt
    • human_immune: immune.gmt
    • human_reactome: reactome.gmt
    • human_tf: TF.gmt
    • mouse_gobp: m_GO_bp.gmt
    • mouse_reactome: m_reactome.gmt
    • mouse_tf: m_TF.gmt

    Outputs (saved in the project folder):

    • ./<project>/mask.npy: Mask matrix
    • ./<project>/pathway.csv: Gene set list
    • ./<project>/label_dictionary.csv: Label list
    • ./<project>/model-n.pth: Model weights
    TOSICA.train(ref_adata, gmt_path, project=<my_project>, label_name=<label_key>)