scTenifoldXct

A semi-supervised method for predicting cell-cell interactions and mapping cellular communication graphs via manifold learning. [Paper]

🆕 New: a local web UI. Run scTenifoldXct from your browser — no code required.

pip install "scTenifoldXct[web]"
sctenifoldxct-ui

Upload a .h5ad (or use the bundled example dataset), pick sender/receiver cell types, and get ranked ligand-receptor pairs in a few clicks — everything runs locally, no data leaves your machine. See Web UI below.

Prefer a hosted, always-on option instead? Try the standalone Streamlit demo.

Install

Install scTenifoldXct from PyPI:

pip install scTenifoldXct

Install from source (for development or the latest unreleased changes):

git clone https://github.com/cailab-tamu/scTenifoldXct.git
cd scTenifoldXct
pip install .

Example Data

Two real, ready-to-use datasets are bundled under data/ so you can try scTenifoldXct immediately, with no data of your own required:

Both are log-normalised and ready to feed straight into the Quick Start, CLI, or Web UI examples below — jump to whichever one you're most comfortable with and give it a try. See data/README.md for additional/larger datasets.

Usages

Quick Start

The following code runs scTenifoldXct on the bundled example data set:

import logging
import scanpy as sc
import scTenifoldXct as st

# scTenifoldXct logs progress via the logging module. Configure a handler
# to see messages when verbose=True (e.g. in a script or notebook):
logging.basicConfig(level=logging.INFO, format="%(message)s")

adata = sc.read_h5ad('data/adata_short_example.h5ad') # load data
xct = st.scTenifoldXct(data = adata, # an AnnData
                    source_celltype = 'Inflam. FIB', # sender cell type
                    target_celltype = 'Inflam. DC', # receiver cell type
                    obs_label = 'ident', # colname in adata.obs indicating cell types
                    rebuild_GRN = True, # whether to build GRNs
                    GRN_file_dir = 'Net_example_dev',  # folder path to GRNs
                    verbose = True, # whether to log the processing
                    n_cpus = -1) # CPU multiprocessing, -1 to use all
emb = xct.get_embeds(train = True) # Manifold alignment to project data to low-dimensional embeddings
xct_pairs = xct.null_test() # non-parametric test to get significant interactions
print(xct_pairs)

Command line

Two console scripts are installed with the package:

# single-sample interaction analysis
sctenifoldxct data/adata_short_example.h5ad --rebuild \
    -s "Inflam. FIB" -r "Inflam. DC" --n_cpus 8 -v

# two-sample differential interaction analysis
sctenifoldxct-merge data/adata_merge_example.h5ad NormalvsTumor N T \
    --rebuild -s "B cells" -r "Fibroblasts" --n_cpus 8 -v

Run sctenifoldxct --help or sctenifoldxct-merge --help for all options.

Web UI

Prefer clicking over scripting? Install the web extra and launch a local, point-and-click interface — no Python knowledge required:

pip install "scTenifoldXct[web]"
sctenifoldxct-ui
# opens http://127.0.0.1:8000

From a git checkout, the UI's "Use bundled example dataset" button loads data/adata_short_example.h5ad directly — no upload needed, so you can go from pip install to results in under a minute. Otherwise, upload your own .h5ad.

Pick a cell-metadata column plus sender/receiver cell types, tune the analysis options if you like (or just leave the defaults), and hit Run analysis. The UI shows the top-ranked ligand-receptor pairs as they finish, with a full CSV download for the complete ranked list. Everything — data, computation, results — stays on your machine.

Run sctenifoldxct-ui --help for options (host/port/GRN cache directory).

Tutorial

We have included two tutorial notebooks on scTenifoldXct usage and results visualization.

Single-sample interaction analysis:
https://github.com/cailab-tamu/scTenifoldXct/blob/main/tutorials/tutorial-short_example.ipynb
Two-sample differential interaction analysis:
https://github.com/cailab-tamu/scTenifoldXct/blob/main/tutorials/tutorial-merge_short_example.ipynb

Run scTenifoldXct from command-line by Docker

scTenifoldXct provides command-line utilities for users who are not familiar with Python.
A Docker image of scTenifoldXct can be built from the repository. The Docker image has all required packages and databases included.

docker build -t sctenifold .
docker run -it --name xct --shm-size=8gb sctenifold

If successful, a Bash terminal will be present in the newly created container.
An example for running single-sample analysis:

sctenifoldxct data/adata_short_example.h5ad \
--rebuild \
-s "Inflam. FIB" \
-r "Inflam. DC" \
--n_cpus 8 \
-v

For running two-sample analysis:

sctenifoldxct-merge data/adata_merge_example.h5ad \
NormalvsTumor N T \
--rebuild \
-s "B cells" \
-r "Fibroblasts" \
--n_cpus 8 \
-v

Users should copy their own data to the container for their analyses.

When analysis completes, hit Ctrl + p and Ctrl + q to detach from the container and then copy the result to the host:

docker cp xct:/app/xct_results/ .