Metadata-Version: 2.4
Name: mechanochat
Version: 0.2.0
Summary: Inference and visualization of mechanical cell-cell communication from spatial transcriptomics data
Home-page: https://github.com/XiangyuKuang/mechanochat
Author: Xiangyu Kuang
Author-email: xykuang1@gmail.com
License: MIT License
Project-URL: Documentation, https://xiangyukuang.github.io/mechanochat/
Project-URL: Source, https://github.com/XiangyuKuang/mechanochat
Project-URL: Bug Tracker, https://github.com/XiangyuKuang/mechanochat/issues
Keywords: spatial transcriptomics,cell-cell communication,mechanobiology,subcellular element method
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.12,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata<0.12,>=0.10.9
Requires-Dist: matplotlib<4,>=3.9.4
Requires-Dist: numba>=0.60.0
Requires-Dist: numpy<2,>=1.24.3
Requires-Dist: pandas<3,>=2.0.3
Requires-Dist: pyvista>=0.46.1
Requires-Dist: plotly>=6.3.0
Requires-Dist: scanpy<2,>=1.10.3
Requires-Dist: scikit_learn>=1.3.0
Requires-Dist: scipy>=1.10.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: python-igraph>=0.11.9
Requires-Dist: torch<2,>=1.13.1
Requires-Dist: xgboost<3,>=2.1.4
Requires-Dist: dhg<0.10,>=0.9.4
Provides-Extra: cuda11
Requires-Dist: cuda-python<12,>=11.8; extra == "cuda11"
Provides-Extra: cuda12
Requires-Dist: cuda-python<13,>=12; extra == "cuda12"
Dynamic: license-file

# MechanoChat

**MechanoChat** infers and visualizes **mechanical cell–cell communication** from spatial transcriptomics data.

**Tutorial notebook** can be found in Github repository https://github.com/XiangyuKuang/mechanochat-tutorials

![MechanoChat overview](https://raw.githubusercontent.com/XiangyuKuang/mechanochat/main/docs/images/overview.png)

MechanoChat is built on the subcellular element method : each cell is represented by a collection of subcellular elements interacting through Lennard-Jones potentials, with per-cell adhesion and stiffness derived from gene expression. Relaxing this system reconstructs cell shapes and cell–cell contacts from spot/cell coordinates, and generates the forces acting between neighboring cells. These  mechanical quantities are then coupled with expression of mechanosensitive genes (ion channels, transcription factors, ligand–receptor) to compute signaling between every pair of contacting cells.

- **Simulate**: GPU-accelerated (`numba.cuda`) 2D/3D SEM dynamics (`mechanochat.SEM2`, `mechanochat.SEM3`).
- **MechanoChatDB**: prior knowledge of mechanotransduction related genes (`mechanochat.preprocessing`).
- **Infer**: cell–cell contacts, forces, mechanical cell-cell communication, and crosstalk (`mechanochat.tools`).
- **Visualize**: reconstructed cell shapes (alpha-shapes), spatial distributions of mechanical cell-cell communication(`mechanochat.plotting`).

Everything is written into the AnnData object (`.obsp` / `.obsm` / `.uns`), so MechanoChat can be integrated into a standard Scanpy workflow.

# Installation

MechanoChat requires Python >= 3.9 and an NVIDIA GPU.

We recommend using Conda or Mamba for environment management. To install Mamba, see https://github.com/conda-forge/miniforge.

**Step 1: Create and activate a virtual environment**
```bash
mamba create -n mc_39 python=3.9
mamba activate mc_39
```

**Step 2: Install the CUDA toolkit**
```bash
mamba install cudatoolkit -c conda-forge   # installs CUDA 11.8 by default
```

**Step 3: Install MechanoChat (with the matching GPU bindings)**

You can check your driver / CUDA version with `nvidia-smi`. Choose the extra according to your **CUDA toolkit major version** (step 2 installs 11.x):
```bash
pip install "mechanochat[cuda11]"     # for CUDA 11.x toolkit (default)
# pip install "mechanochat[cuda12]"   # for CUDA 12.x toolkit
```

**Do not omit the extra.** It pulls in NVIDIA's official `cuda-python` bindings, which numba
needs on recent NVIDIA drivers (CUDA 13 / driver 580+) — without them, numba 0.60's built-in
ctypes driver bindings cause a segfault when initializing the CUDA context. `cuda-python` is
shipped as an extra rather than a regular dependency only because its major version has to match
the CUDA version on your machine, which cannot be decided at packaging time.

To install the development version from source:
```bash
git clone https://github.com/XiangyuKuang/mechanochat.git
cd mechanochat
pip install -e ".[cuda11]"
```

# Usage

> ⚠️ **Before running simulation (`sem.sim_gpu(...)`), make sure `NUMBA_CUDA_USE_NVIDIA_BINDING=1` is set** . Without it, on CUDA 13 / driver 580+ the kernel crashes (segfault) on the first CUDA call, with no Python traceback.
>
> Do it in the **very first cell, before any other import** (including `scanpy`):
>
> ```python
> import os
> os.environ["NUMBA_CUDA_USE_NVIDIA_BINDING"] = "1"
> # — must run before importing scanpy / numba —
> import mechanochat as mc
> import scanpy as sc
> ```
>
> Quick self-check:
> ```python
> import numba.cuda as c
> assert c.cudadrv.driver.USE_NV_BINDING == 1, "env var not in effect — restart the kernel"
> ```

<details>
<summary><b>Optional — set <code>NUMBA_CUDA_USE_NVIDIA_BINDING</code> once at the environment level</b></summary>

Setting the variable at the environment level saves you from repeating the two `os.environ` lines
at the top of every script and notebook. The effect is exactly the same; it is only a convenience.

```bash
# conda activation hook — applies on every `mamba activate mc_39`
mkdir -p "$CONDA_PREFIX/etc/conda/activate.d"
echo 'export NUMBA_CUDA_USE_NVIDIA_BINDING=1' \
    > "$CONDA_PREFIX/etc/conda/activate.d/numba_cuda_binding.sh"
mamba activate mc_39   # re-activate for it to take effect
```

For Jupyter / VSCode notebooks, also set it in the kernel, so it applies even when the kernel is
launched without shell activation. Add an `"env"` block to the kernel's `kernel.json` (locate it
with `jupyter kernelspec list`):

```json
{
  "argv": ["...python", "-m", "ipykernel_launcher", "-f", "{connection_file}"],
  "env": { "NUMBA_CUDA_USE_NVIDIA_BINDING": "1" }
}
```

</details>

# Documentation

See detailed documentation at https://xiangyukuang.github.io/mechanochat/.

