Metadata-Version: 2.1
Name: scstate
Version: 0.1.2
Summary: scState: A pathway-informed graph transformer framework for decoding stem cell state transitions from scRNA-seq data
Author: DuanMaoteng, LiuXue
License: MIT
Keywords: scRNA-seq,graph transformer,heterogeneous graph,stem cell,cell state,trajectory inference,bioinformatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.8.0, <3.9
Description-Content-Type: text/markdown
Requires-Dist: anndata ==0.8.0
Requires-Dist: dill ==0.3.4
Requires-Dist: matplotlib ==3.5.2
Requires-Dist: numpy ==1.22.3
Requires-Dist: pandas <2.0,>=1.5.3
Requires-Dist: scipy ==1.10.1
Requires-Dist: seaborn ==0.11.2
Requires-Dist: scikit-learn ==1.1.2
Requires-Dist: xlwt ==1.3.0
Requires-Dist: tqdm ==4.64.0
Requires-Dist: scanpy ==1.9.1
Requires-Dist: leidenalg ==0.8.10
Requires-Dist: ipywidgets ==8.0.6
Provides-Extra: dev
Requires-Dist: build ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Provides-Extra: model
Requires-Dist: torchmetrics ==0.9.3 ; extra == 'model'
Provides-Extra: trajectory
Requires-Dist: PhenoGraph ==1.5.7 ; extra == 'trajectory'
Requires-Dist: fcsparser ==0.2.8 ; extra == 'trajectory'

# 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

```bash
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

```bash
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:

```bash
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

```bash
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:

```bash
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**:

```bash
pip install scstate
```

To install or upgrade to the latest version:

```bash
pip install --upgrade scstate
```

To install a specific version:

```bash
pip install scstate==0.1.2
```

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

```python
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:

```bash
pip install "scstate[model]"
```

This installs:

```text
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:

```bash
pip install "scstate[trajectory]"
```

This installs:

```text
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:

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

Then install Palantir without triggering dependency re-resolution:

```bash
pip install palantir==1.0.0 --no-deps
```

A quick test can be performed with:

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

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

---

### 7. Add the environment to Jupyter Notebook

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

## License

This project is released under the MIT License.
