scstate 0.1.2

scState: A pathway-informed graph transformer framework for decoding stem cell state transitions from scRNA-seq data

scState: Decoding stem cell state transitions through pathway-informed heterogeneous graph representations

Note: This project is for internal testing purposes only. Do not use it in a production environment.

We developed scState, a pathway-informed graph transformer framework for identifying stem cells and resolving quiescent and activated stem cell states from scRNA-seq data. By integrating pathway activity with adversarial representation learning in a heterogeneous graph architecture, scState enables stem cell identification, cell state discrimination, pathway-level interpretation, and trajectory inference.

Keywords: scRNA-seq, graph transformer, adversarial learning, stem cell, cell state transition

---

Installation

System requirements

• Python 3.8.x
• Linux system is recommended
• GPU is recommended for faster model training, but CPU installation is also supported

---

Installation steps

1. Create a new conda environment

conda create --name scState python=3.8 -y
conda activate scState

---

2. Install PyTorch and PyTorch Geometric

PyTorch and PyTorch Geometric should be installed manually according to the user's CPU/GPU and CUDA configuration.

GPU version with CUDA 11.8

pip install torch==2.4.1+cu118 torchvision==0.19.1+cu118 torchaudio==2.4.1+cu118 \
  --index-url https://download.pytorch.org/whl/cu118

pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv \
  -f https://data.pyg.org/whl/torch-2.4.0+cu118.html

pip install torch-geometric==2.6.1

Alternatively, the required wheels can be installed explicitly:

pip install https://download.pytorch.org/whl/cu118/torch-2.4.1%2Bcu118-cp38-cp38-linux_x86_64.whl
pip install https://data.pyg.org/whl/torch-2.4.0%2Bcu118/torch_scatter-2.1.2%2Bpt24cu118-cp38-cp38-linux_x86_64.whl
pip install https://data.pyg.org/whl/torch-2.4.0%2Bcu118/torch_sparse-0.6.18%2Bpt24cu118-cp38-cp38-linux_x86_64.whl
pip install https://data.pyg.org/whl/torch-2.4.0%2Bcu118/torch_cluster-1.6.3%2Bpt24cu118-cp38-cp38-linux_x86_64.whl
pip install torch-geometric==2.6.1

CPU version

pip install torch==2.4.1+cpu torchvision==0.19.1+cpu torchaudio==2.4.1+cpu \
  --index-url https://download.pytorch.org/whl/cpu

pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv \
  -f https://data.pyg.org/whl/torch-2.4.0+cpu.html

pip install torch-geometric==2.6.1

Alternatively, the required CPU wheels can be installed explicitly:

pip install https://download.pytorch.org/whl/cpu/torch-2.4.1%2Bcpu-cp38-cp38-linux_x86_64.whl
pip install https://data.pyg.org/whl/torch-2.4.0%2Bcpu/torch_scatter-2.1.2%2Bpt24cpu-cp38-cp38-linux_x86_64.whl
pip install https://data.pyg.org/whl/torch-2.4.0%2Bcpu/torch_sparse-0.6.18%2Bpt24cpu-cp38-cp38-linux_x86_64.whl
pip install https://data.pyg.org/whl/torch-2.4.0%2Bcpu/torch_cluster-1.6.3%2Bpt24cpu-cp38-cp38-linux_x86_64.whl
pip install torch-geometric==2.6.1

---

3. Install scState

The package name on PyPI is scstate:

pip install scstate

To install or upgrade to the latest version:

pip install --upgrade scstate

To install a specific version:

pip install scstate==0.1.2

Although the package is installed from PyPI as scstate, it should be imported in Python as scState:

import scState

---

4. Optional: install model-related dependency

The basic installation of scState does not automatically install torchmetrics. If model evaluation utilities are needed, install the optional model dependency:

pip install "scstate[model]"

This installs:

torchmetrics==0.9.3

PyTorch, PyTorch Geometric, and PyG extension packages should still be installed manually according to the user's CPU/GPU and CUDA configuration.

---

5. Optional: install trajectory-related dependencies

The basic installation of scState does not automatically install Palantir-related dependencies. If trajectory-related analysis is needed, install:

pip install "scstate[trajectory]"

This installs:

PhenoGraph==1.5.7
fcsparser==0.2.8

---

6. Optional: install Palantir manually

palantir==1.0.0 may require MulticoreTSNE. Since MulticoreTSNE can fail during pip-based compilation on some Linux or HPC systems, Palantir is not included in the automatic dependencies of scState.

We recommend installing MulticoreTSNE with conda first:

conda install -c conda-forge multicore-tsne=0.1 -y

Then install Palantir without triggering dependency re-resolution:

pip install palantir==1.0.0 --no-deps

A quick test can be performed with:

python - <<'PY'
import MulticoreTSNE
import palantir
import phenograph
import fcsparser

print("Trajectory-related dependencies imported successfully")
PY

---

7. Add the environment to Jupyter Notebook

pip install ipykernel
python -m ipykernel install --user --name scState --display-name "Python (scState)"

---

Dependencies

scState was tested under Python 3.8.x.

Main dependencies

The following dependencies are installed by default with:

pip install scstate

• anndata==0.8.0
• dill==0.3.4
• matplotlib==3.5.2
• numpy==1.22.3
• pandas>=1.5.3,<2.0
• scipy==1.10.1
• seaborn==0.11.2
• scikit-learn==1.1.2
• xlwt==1.3.0
• tqdm==4.64.0
• scanpy==1.9.1
• leidenalg==0.8.10
• ipywidgets==8.0.6

Model-related dependencies

For model training and graph neural network modules, the following packages are required and should be installed according to the user's CPU/GPU and CUDA configuration:

• torch==2.4.1+cu118 or torch==2.4.1+cpu
• torch-geometric==2.6.1
• torch-scatter==2.1.2+pt24cu118
• torch-sparse==0.6.18+pt24cu118
• torch-cluster==1.6.3+pt24cu118
• torch-spline-conv
• pyg-lib
• torchmetrics==0.9.3

The tested GPU environment is:

• Python==3.8.x
• PyTorch==2.4.1+cu118
• CUDA used by PyTorch==11.8
• PyTorch Geometric==2.6.1

Trajectory-related optional dependencies

The following optional dependencies can be installed with:

pip install "scstate[trajectory]"

• PhenoGraph==1.5.7
• fcsparser==0.2.8

For Palantir-based trajectory analysis, install the following packages manually:

• palantir==1.0.0
• MulticoreTSNE==0.1

Recommended installation:

conda install -c conda-forge multicore-tsne=0.1 -y
pip install palantir==1.0.0 --no-deps

---

Usage

After installation, scState modules can be imported as follows:

from scState.conv import *
from scState.scState_model import *
from scState.utils import *

License

This project is released under the MIT License.