A meta-interaction basis for cell-cell communication in tissues
SpiderNet is an interpretable deep learning framework for learning directional cell-cell meta-interactions (MIs) from spatial omics data.
SpiderNet takes gene expression profiles and a spatial cell-cell graph as input. For each directed neighboring cell pair, the encoder maps sender and receiver expression into a non-negative vector of MI strengths. The decoder uses these MIs to reconstruct ligand-receptor co-expression on cell-cell pairs and gene expression in cells. The non-negative model components make the learned MIs interpretable through intrinsic, ligand-receptor, sender-regulator, and receiver-target gene loadings.
The inferred MIs provide a compact representation of multicellular communication programs, supporting MI-associated pathway inference, cell-type-pair enrichment, cell subtype discovery, MI cascade detection, in silico spatial perturbation, and phenotype prediction.
This repository provides the Python package, eight study workflows, and the SpiderNet-Interactive application. Prepared data and saved results are distributed separately through Zenodo.
SpiderNet requires Python 3.11. We recommend creating a clean conda environment:
conda create -n SpiderNet_env python=3.11.8
conda activate SpiderNet_env
python -c "import sys; print(sys.executable); print(sys.version)"Confirm that the interpreter belongs to SpiderNet_env and reports Python 3.11 before installing packages. Activate this environment again whenever you open a new terminal; a new terminal may otherwise use a different system Python. If you chose another environment name, substitute it for SpiderNet_env throughout this guide. On Windows, use Anaconda Prompt or a terminal already configured for conda.
Install PyTorch and PyG before SpiderNet. Their installation depends on the operating system and CPU/CUDA environment. The recorded CUDA 11.7 setup uses:
python -m pip install torch==2.0.0 torchvision==0.15.1 --index-url https://download.pytorch.org/whl/cu117
python -m pip install torch-geometric==2.7.0
python -m pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.0+cu117.htmlFor a different CUDA version or a CPU-only environment, install the matching PyTorch and PyG builds. Saved data and checkpoints also need compatible library versions; see the reproduction instructions.
Clone the repository and install from its root:
git clone https://github.com/ma-compbio-lab/SpiderNet.git
cd SpiderNet
python -m pip install .For development or running the repository workflows, use editable installation:
python -m pip install -e .The installable source is under SpiderNet/SpiderNet/; the root pyproject.toml locates it automatically. The Python package can be installed without downloading study data.
The following commands work from either the repository root (containing Tutorial/ and scripts/data.py) or the inner SpiderNet/ project directory. The root requirements files forward to the maintained lists inside SpiderNet/, so dependency versions are maintained in one place. Install only the optional dependencies needed for your workflows:
# Notebook and tutorial dependencies
python -m pip install -r requirements-tutorial.txt
# Interactive application dependencies
python -m pip install -r requirements-UI.txt
# Optional external-method benchmark dependencies
python -m pip install -r requirements-benchmark.txtRun these commands from a directory containing requirements-UI.txt, not from the Python source directory or the application directory. If you are already inside SpiderNet-interactive/ beside app.py, use python -m pip install -r ../requirements-UI.txt instead.
To install both UI and external-method benchmark dependencies together from either the repository root or the inner project directory:
python -m pip install -r requirements-UI.txt -r requirements-benchmark.txt
python -m pip checkThe optional graph stack uses igraph==0.11.9, leidenalg==0.10.2, and louvain==0.8.2. COMMOT additionally uses numpy==1.26.4, python-igraph==0.11.9, pysal==25.7, and tobler==0.12.1. These constraints avoid the NumPy 2.x and igraph 1.x conflicts observed when installing unconstrained optional dependencies. The package extras also carry these constraints: python -m pip install ".[interactive,benchmark]".
Some R/R Markdown analyses require separate R packages; see R requirements and the relevant study README. The former requirements-full-freeze.txt copies are preserved as a single historical environment record, outside the installation requirements. That snapshot contains conflicting optional dependency versions and must not be used as an installation file or a validated lockfile.
For Jupyter, register the environment as a notebook kernel:
python -m ipykernel install --user --name SpiderNet_env --display-name "Python (SpiderNet_env)"Check the package, deep-learning dependencies, and packaged ligand-receptor resources:
python -c "import SpiderNet; print(SpiderNet.__file__)"
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
python -c "import torch_geometric, torch_scatter, torch_sparse; print('PyG OK')"
python -c "from SpiderNet.utils import get_default_cellchat_db; print(get_default_cellchat_db('human'))"
python -m pip checkAfter installing optional dependencies, also check the imports you need:
# UI dependencies
python -c "import flask, igraph, louvain, leidenalg; print('UI dependencies OK')"
# External-method benchmarks
python -c "import commot; print('COMMOT import OK')"The compatible optional versions above passed dependency and import checks in a Windows Python 3.11 environment. These checks do not replace running the study workflows. Louvain may emit a non-fatal pkg_resources deprecation warning with setuptools 81.0.0.
A typical SpiderNet workflow consists of preparing spatial omics data and a spatial cell-cell graph, training the model, inferring MI strengths for directed neighboring cell pairs, and performing downstream analyses.
The example below illustrates the training API using an existing processed-data bundle. Set the paths and training configuration for your dataset. For reproducing saved-result figures, go directly to Reproduce the study results.
from pathlib import Path
from SpiderNet.config import TrainingConfig
from SpiderNet.io import load_processed_data
from SpiderNet.api import (
build_model,
run_training,
infer_meta_interactions,
normalize_outputs,
export_results,
)
processed_data_dir = Path("path/to/ProcessedData")
output_dir = Path("path/to/SpiderNet_Result_dim15")
processed = load_processed_data(processed_data_dir)
training_config = TrainingConfig(
dim_envir=15,
max_epoch=50000,
n_jobs=5,
optimizer="adam",
)
model = build_model(processed, training_config)
trained_model = run_training(
model=model,
processed=processed,
train_cfg=training_config,
model_dir=output_dir / "Model",
)
outputs = infer_meta_interactions(trained_model, processed)
outputs = normalize_outputs(outputs)
export_results(
results=outputs,
processed=processed,
precessed_data_dir=processed_data_dir,
output_dir=output_dir,
)The precessed_data_dir keyword follows the current public API spelling. Dataset-specific preprocessing, MI dimension selection, and analysis settings are described in the study notebooks and READMEs.
All study workflows are in Tutorial/. Each study provides a README and a run_benchmarks.py command-line entry point alongside its analysis notebooks or helper scripts.
| Study | Analyses | Data profile |
|---|---|---|
| AgingBrain | Age-associated cell interactions, spatial MI patterns, and transfer to sagittal/hippocampal samples | plot-agingbrain |
| HGSOC | Malignant subtypes, CAF signaling, MI cascades, and cell-cell communication comparisons | plot-hgsoc |
| PerturbFISH | Perturbation responses, held-out predictions, and spatial perturbation analyses | plot-perturbfish |
| Pancancer | Cross-cancer MI patterns, cascades, bulk projection, survival, and immunotherapy associations | plot-pancancer |
| Simulation | Synthetic-data benchmarks and a representative spatial-interaction example | plot-simulation |
| Coupling benchmark | Directionality, cell-similarity concordance, and spatial specificity | plot-coupling-benchmark |
| Ablation study | Contributions of model components to coupling and perturbation prediction | plot-ablation-study |
| Robustness and stability | MI alignment, annotation errors, resampling, and stability analyses | plot-robustness-stability |
See the study guide for how these workflows connect to model outputs and the training benchmark for optional implementation-performance comparisons.
The data supporting the documented SpiderNet reproduction workflows have been uploaded to Zenodo and are currently shared privately for peer review. Editors and reviewers can access the files through the private link supplied in the review manuscript and journal submission materials. The dataset will be made publicly available upon publication of the paper; the dataset DOI and public download links will then be added here and to data/manifest.json.
The data collection contains saved results, plotting inputs, interactive datasets, detailed result tables, and training-benchmark outputs. The data guide lists the bundles, sizes, and workflow profiles. The manifest records archive and file-level SHA-256 checksums and restoration paths.
During peer review, download the ZIP archives using the supplied reviewer link and keep their filenames unchanged. Activate the installed SpiderNet_env environment and work from the repository root. Replace /path/to/archives below with the actual directory containing the downloaded ZIPs, keeping the quotation marks around paths that contain spaces. For example, a Windows path can be written as "D:/SpiderNet data/archives".
List the required bundles and restore one study:
python scripts/data.py list
# Replace /path/to/archives with the folder containing the downloaded ZIPs.
python scripts/data.py restore --profile plot-agingbrain --archive-dir "/path/to/archives"
python scripts/data.py verify --profile plot-agingbrain
# Check the required inputs before rendering the saved-result figures.
python scripts/run_study.py AgingBrain --check --plot-only
python scripts/run_study.py AgingBrain --plot-onlyTo restore all eight default plot-only workflows, use --profile all-plots with restore and verify. Use the restore tool rather than manually extracting ZIPs: identical archived content may need to be placed at multiple workflow paths. Existing identical files are preserved; different existing data are not overwritten by default.
The original study commands remain available after activating the reproduction paths. In PowerShell, from the repository root:
. ./scripts/activate_reproduction.ps1
cd Tutorial/AgingBrain
python run_benchmarks.py --check --plot-only
python run_benchmarks.py --plot-onlyIn Bash, use source scripts/activate_reproduction.sh before entering the study folder. These helpers point the workflows to data restored inside this checkout. See reproduction instructions for details.
Automated python scripts/data.py fetch --profile plot-agingbrain downloads will become available when public Zenodo URLs are configured.
Reproduction scope. These profiles support the documented default saved-result plotting workflows. Some steps redraw figures from saved numerical inputs; others retain archived figures. The Simulation profile includes a representative saved experiment. The archives are not a complete raw-data training collection for every analysis or external comparator. Full analysis and retraining require the inputs and settings described in each study README. Direct notebook execution may require its own path overrides. --check validates declared inputs and relevant cache signatures; it does not perform a complete numerical reproduction or render all figures.
SpiderNet-Interactive is a local Flask application for exploring trained SpiderNet runs in a browser. Four modules connect saved model outputs to interactive analyses:
| Module | Purpose |
|---|---|
| M1: Basic analysis | Spatial MI activity, ligand-receptor and sender/receiver loadings, pathways, and cell-type-pair enrichment |
| M2: Subtype discovery | MI-guided cell clustering, differential expression, and GO/KEGG enrichment |
| M3: MI cascades | Permutation-tested MI cascades, cell-type triplets, spatial displays, and associated gene programs |
| M4: Spatial perturbation | In silico gene knockdown or cell-type replacement using the trained model |
First complete the package and PyTorch/PyG installation above. Start from the repository root, identified by Tutorial/ and scripts/data.py. If you are in the inner SpiderNet/ project directory, run cd .. first.
In a newly opened terminal, navigate to your checkout and reactivate the installed environment. On Windows CMD/Anaconda Prompt, use cd /d "D:\path\to\SpiderNet" to change both drive and directory; replace that example with your actual checkout path. In PowerShell, macOS, or Linux, use cd "path/to/SpiderNet" with your actual path.
Run the following commands one at a time. Confirm that the interpreter is in your intended environment and reports Python 3.11 before continuing; stop and inspect any error before running the next command. Replace /path/to/archives with the actual ZIP directory, for example "D:/SpiderNet data/archives" on Windows. Keep the path quoted.
conda activate SpiderNet_env
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip install -r requirements-UI.txt
python -m pip check
python scripts/data.py restore --profile interactive --archive-dir "/path/to/archives"
python scripts/data.py verify --profile interactive
cd SpiderNet/SpiderNet-interactive
python app.pyAfter the server reports that it is running, open http://localhost:8000 in your browser. Keep the terminal open while using the application; press Ctrl+C in that terminal to stop the server.
The application discovers prepared _UI datasets under SpiderNet/Interactivetool/SpiderNet-interactive_V2/; restart after adding a dataset. Analyses use saved data and caches, while some requests compute additional results or run inference. See the application guide for dataset requirements, caching, and configuration.
| Module | Purpose |
|---|---|
SpiderNet.config |
Configuration for paths, preprocessing, and training |
SpiderNet.io |
Loading and saving processed data |
SpiderNet.api |
Model construction, training, inference, normalization, and export |
SpiderNet.model |
Model architecture |
SpiderNet.analysis |
MI enrichment, cascades, perturbation, and phenotype-related analyses |
SpiderNet.visualization |
Visualization utilities |
SpiderNet.MI_dimension_selection |
MI dimension selection |
SpiderNet.dataloading_unified |
Data loading and preprocessing |
SpiderNet.utils |
Utilities and default ligand-receptor resource paths |
Four human/mouse ligand-receptor tables derived from CellChatDB and scSeqComm are included under SpiderNet/SpiderNet/resources/ and installed with the package. Access them with:
from SpiderNet.utils import get_default_cellchat_db, get_default_scseqcomm_db
cellchat_human = get_default_cellchat_db("human")
scseqcomm_human = get_default_scseqcomm_db("human")SpiderNet/
SpiderNet/ Python package and ligand-receptor resources
SpiderNet-interactive/ Flask application and static assets
Tutorial/ Eight study workflows and documentation
benchmarks/training_speed/ Optional training-performance benchmarks
data/ Archive manifest and data instructions
scripts/ Data restoration and study launch utilities
docs/ Study, data, and reproduction guides
pyproject.toml Package installation configuration
Large datasets, trained-run bundles, and complete result collections are distributed separately from Git. Restored data are ignored by Git.
If you use SpiderNet, please cite the corresponding manuscript, SpiderNet: A meta-interaction basis for cell-cell communication in tissues. The manuscript citation and public dataset DOI will be added when available.
The source code is distributed under the MIT License. Data and third-party resources are subject to their respective licenses and attribution requirements.