Metadata-Version: 2.5
Name: embpy
Version: 9
Summary: A package for biological embeddings in the perturbation experimental space
Project-URL: Documentation, https://embpy.readthedocs.io/
Project-URL: Homepage, https://github.com/theislab/embpy
Project-URL: Source, https://github.com/theislab/embpy
Author: Goncalo Rei Pinto
Maintainer-email: Goncalo Rei Pinto <goncalo.pinto@helmholtz-munich.de>
License: MIT License
        
        Copyright (c) 2025, Goncalo Rei Pinto
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: anndata
Requires-Dist: broad-babel>=0.1
Requires-Dist: cirpy
Requires-Dist: huggingface-hub>=0.36
Requires-Dist: ipywidgets
Requires-Dist: matplotlib
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=14.0.2
Requires-Dist: rdkit
Requires-Dist: requests
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: seaborn
Requires-Dist: session-info
Provides-Extra: all
Requires-Dist: biopython; extra == 'all'
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'all'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'all'
Requires-Dist: h5py; extra == 'all'
Requires-Dist: jump-portrait>=0.0.7; extra == 'all'
Requires-Dist: lamindb; extra == 'all'
Requires-Dist: pertpy; extra == 'all'
Requires-Dist: pillow>=10; extra == 'all'
Requires-Dist: protobuf>=3.20; extra == 'all'
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'all'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'all'
Requires-Dist: scanpy>=1.10; extra == 'all'
Requires-Dist: scib>=1.1.5; extra == 'all'
Requires-Dist: sentencepiece>=0.1.99; extra == 'all'
Requires-Dist: torch-geometric>=2.5; extra == 'all'
Requires-Dist: torch>=2.5.1; extra == 'all'
Requires-Dist: transformers>=4.45.0; extra == 'all'
Requires-Dist: xgboost>=2.0; extra == 'all'
Provides-Extra: all-cpu
Requires-Dist: biopython; extra == 'all-cpu'
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'all-cpu'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'all-cpu'
Requires-Dist: h5py; extra == 'all-cpu'
Requires-Dist: jump-portrait>=0.0.7; extra == 'all-cpu'
Requires-Dist: lamindb; extra == 'all-cpu'
Requires-Dist: pertpy; extra == 'all-cpu'
Requires-Dist: pillow>=10; extra == 'all-cpu'
Requires-Dist: protobuf>=3.20; extra == 'all-cpu'
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'all-cpu'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'all-cpu'
Requires-Dist: scanpy>=1.10; extra == 'all-cpu'
Requires-Dist: scib>=1.1.5; extra == 'all-cpu'
Requires-Dist: sentencepiece>=0.1.99; extra == 'all-cpu'
Requires-Dist: torch-geometric>=2.5; extra == 'all-cpu'
Requires-Dist: torch>=2.5.1; extra == 'all-cpu'
Requires-Dist: transformers>=4.45.0; extra == 'all-cpu'
Requires-Dist: xgboost>=2.0; extra == 'all-cpu'
Provides-Extra: all-cu121
Requires-Dist: biopython; extra == 'all-cu121'
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'all-cu121'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'all-cu121'
Requires-Dist: h5py; extra == 'all-cu121'
Requires-Dist: jump-portrait>=0.0.7; extra == 'all-cu121'
Requires-Dist: lamindb; extra == 'all-cu121'
Requires-Dist: pertpy; extra == 'all-cu121'
Requires-Dist: pillow>=10; extra == 'all-cu121'
Requires-Dist: protobuf>=3.20; extra == 'all-cu121'
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'all-cu121'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'all-cu121'
Requires-Dist: scanpy>=1.10; extra == 'all-cu121'
Requires-Dist: scib>=1.1.5; extra == 'all-cu121'
Requires-Dist: sentencepiece>=0.1.99; extra == 'all-cu121'
Requires-Dist: torch-geometric>=2.5; extra == 'all-cu121'
Requires-Dist: torch>=2.5.1; extra == 'all-cu121'
Requires-Dist: transformers>=4.45.0; extra == 'all-cu121'
Requires-Dist: xgboost>=2.0; extra == 'all-cu121'
Provides-Extra: all-cu124
Requires-Dist: biopython; extra == 'all-cu124'
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'all-cu124'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'all-cu124'
Requires-Dist: h5py; extra == 'all-cu124'
Requires-Dist: jump-portrait>=0.0.7; extra == 'all-cu124'
Requires-Dist: lamindb; extra == 'all-cu124'
Requires-Dist: pertpy; extra == 'all-cu124'
Requires-Dist: pillow>=10; extra == 'all-cu124'
Requires-Dist: protobuf>=3.20; extra == 'all-cu124'
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'all-cu124'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'all-cu124'
Requires-Dist: scanpy>=1.10; extra == 'all-cu124'
Requires-Dist: scib>=1.1.5; extra == 'all-cu124'
Requires-Dist: sentencepiece>=0.1.99; extra == 'all-cu124'
Requires-Dist: torch-geometric>=2.5; extra == 'all-cu124'
Requires-Dist: torch>=2.5.1; extra == 'all-cu124'
Requires-Dist: transformers>=4.45.0; extra == 'all-cu124'
Requires-Dist: xgboost>=2.0; extra == 'all-cu124'
Provides-Extra: all-cu128
Requires-Dist: biopython; extra == 'all-cu128'
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'all-cu128'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'all-cu128'
Requires-Dist: h5py; extra == 'all-cu128'
Requires-Dist: jump-portrait>=0.0.7; extra == 'all-cu128'
Requires-Dist: lamindb; extra == 'all-cu128'
Requires-Dist: pertpy; extra == 'all-cu128'
Requires-Dist: pillow>=10; extra == 'all-cu128'
Requires-Dist: protobuf>=3.20; extra == 'all-cu128'
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'all-cu128'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'all-cu128'
Requires-Dist: scanpy>=1.10; extra == 'all-cu128'
Requires-Dist: scib>=1.1.5; extra == 'all-cu128'
Requires-Dist: sentencepiece>=0.1.99; extra == 'all-cu128'
Requires-Dist: torch-geometric>=2.5; extra == 'all-cu128'
Requires-Dist: torch>=2.5.1; extra == 'all-cu128'
Requires-Dist: transformers>=4.45.0; extra == 'all-cu128'
Requires-Dist: xgboost>=2.0; extra == 'all-cu128'
Provides-Extra: alphagenome
Requires-Dist: alphagenome>=0.7; extra == 'alphagenome'
Provides-Extra: benchmark
Requires-Dist: xgboost>=2.0; extra == 'benchmark'
Provides-Extra: bio
Requires-Dist: biopython; extra == 'bio'
Provides-Extra: boltz
Requires-Dist: boltz>=2.0; extra == 'boltz'
Provides-Extra: caduceus
Requires-Dist: mamba-ssm>=2.0; extra == 'caduceus'
Provides-Extra: cpu
Requires-Dist: biopython; extra == 'cpu'
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'cpu'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'cpu'
Requires-Dist: h5py; extra == 'cpu'
Requires-Dist: igraph>=0.11; extra == 'cpu'
Requires-Dist: leidenalg>=0.10; extra == 'cpu'
Requires-Dist: pertpy; extra == 'cpu'
Requires-Dist: pillow>=10; extra == 'cpu'
Requires-Dist: protobuf>=3.20; extra == 'cpu'
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'cpu'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'cpu'
Requires-Dist: scanpy>=1.10; extra == 'cpu'
Requires-Dist: scib>=1.1.5; extra == 'cpu'
Requires-Dist: sentencepiece>=0.1.99; extra == 'cpu'
Requires-Dist: torch-geometric>=2.5; extra == 'cpu'
Requires-Dist: torch>=2.5.1; extra == 'cpu'
Requires-Dist: transformers>=4.45.0; extra == 'cpu'
Requires-Dist: xgboost>=2.0; extra == 'cpu'
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Provides-Extra: doc
Requires-Dist: docutils!=0.18.*,!=0.19.*,>=0.8; extra == 'doc'
Requires-Dist: ipykernel; extra == 'doc'
Requires-Dist: ipython; extra == 'doc'
Requires-Dist: myst-nb>=1.1; extra == 'doc'
Requires-Dist: setuptools; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-book-theme>=1; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-tabs; extra == 'doc'
Requires-Dist: sphinx>=4; extra == 'doc'
Requires-Dist: sphinxcontrib-bibtex>=1; extra == 'doc'
Requires-Dist: sphinxext-opengraph; extra == 'doc'
Provides-Extra: esm3
Requires-Dist: esm>=3.2.0; extra == 'esm3'
Provides-Extra: eval
Requires-Dist: cell-eval>=0.7.2; extra == 'eval'
Provides-Extra: evo
Requires-Dist: evo-model>=0.3; extra == 'evo'
Provides-Extra: evo2
Requires-Dist: evo2; extra == 'evo2'
Provides-Extra: flashzoi
Requires-Dist: borzoi-pytorch[flash]>=0.4.3; extra == 'flashzoi'
Provides-Extra: genome
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'genome'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'genome'
Provides-Extra: gpu
Requires-Dist: biopython; extra == 'gpu'
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'gpu'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'gpu'
Requires-Dist: h5py; extra == 'gpu'
Requires-Dist: igraph>=0.11; extra == 'gpu'
Requires-Dist: leidenalg>=0.10; extra == 'gpu'
Requires-Dist: pertpy; extra == 'gpu'
Requires-Dist: pillow>=10; extra == 'gpu'
Requires-Dist: protobuf>=3.20; extra == 'gpu'
Requires-Dist: pyensembl>=2.3.13; (platform_system != 'Windows') and extra == 'gpu'
Requires-Dist: pysam>=0.22; (sys_platform != 'win32') and extra == 'gpu'
Requires-Dist: scanpy>=1.10; extra == 'gpu'
Requires-Dist: scib>=1.1.5; extra == 'gpu'
Requires-Dist: sentencepiece>=0.1.99; extra == 'gpu'
Requires-Dist: torch-geometric>=2.5; extra == 'gpu'
Requires-Dist: torch>=2.5.1; extra == 'gpu'
Requires-Dist: transformers>=4.45.0; extra == 'gpu'
Requires-Dist: xgboost>=2.0; extra == 'gpu'
Provides-Extra: helical
Requires-Dist: helical; extra == 'helical'
Provides-Extra: lamindb
Requires-Dist: lamindb; extra == 'lamindb'
Provides-Extra: minimol
Requires-Dist: minimol; extra == 'minimol'
Provides-Extra: models
Requires-Dist: protobuf>=3.20; extra == 'models'
Requires-Dist: sentencepiece>=0.1.99; extra == 'models'
Requires-Dist: torch-geometric>=2.5; extra == 'models'
Requires-Dist: torch>=2.5.1; extra == 'models'
Requires-Dist: transformers>=4.45.0; extra == 'models'
Provides-Extra: morphology
Requires-Dist: jump-portrait>=0.0.7; extra == 'morphology'
Requires-Dist: pillow>=10; extra == 'morphology'
Provides-Extra: ntv3
Requires-Dist: transformers<5.0.0,>=4.45.0; extra == 'ntv3'
Provides-Extra: pertpy
Requires-Dist: pertpy; extra == 'pertpy'
Provides-Extra: ppi
Requires-Dist: h5py; extra == 'ppi'
Provides-Extra: scanpy
Requires-Dist: scanpy>=1.10; extra == 'scanpy'
Provides-Extra: scib
Requires-Dist: scanpy>=1.10; extra == 'scib'
Requires-Dist: scib>=1.1.5; extra == 'scib'
Provides-Extra: scooby
Requires-Dist: snapatac2-scooby; extra == 'scooby'
Provides-Extra: seqmodels
Requires-Dist: borzoi-pytorch>=0.4.3; extra == 'seqmodels'
Requires-Dist: enformer-pytorch>=0.8.10; extra == 'seqmodels'
Provides-Extra: stack
Requires-Dist: arc-stack>=0.1.3; extra == 'stack'
Provides-Extra: state
Requires-Dist: arc-state>=0.10; extra == 'state'
Provides-Extra: test
Requires-Dist: biopython; extra == 'test'
Requires-Dist: coverage; extra == 'test'
Requires-Dist: igraph>=0.11; extra == 'test'
Requires-Dist: leidenalg>=0.10; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Requires-Dist: scanpy>=1.10; extra == 'test'
Requires-Dist: xgboost; extra == 'test'
Provides-Extra: torch
Requires-Dist: torch>=2.5.1; extra == 'torch'
Provides-Extra: torch-cpu
Requires-Dist: torch>=2.5.1; extra == 'torch-cpu'
Provides-Extra: torch-cu121
Requires-Dist: torch>=2.5.1; extra == 'torch-cu121'
Provides-Extra: torch-cu124
Requires-Dist: torch>=2.5.1; extra == 'torch-cu124'
Provides-Extra: torch-cu128
Requires-Dist: torch>=2.5.1; extra == 'torch-cu128'
Provides-Extra: torch-cu130
Requires-Dist: torch>=2.5.1; extra == 'torch-cu130'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/_static/embpy_logo.svg" alt="embpy" width="660">
</p>

[![Tests][badge-tests]][tests]
[![Documentation][badge-docs]][documentation]
[![Docs: MkDocs](https://img.shields.io/badge/docs-MkDocs%20Material-526cfe?logo=materialformkdocs&logoColor=white)](docs/)

[badge-tests]: https://img.shields.io/github/actions/workflow/status/theislab/embpy/test.yaml?branch=main
[badge-docs]: https://img.shields.io/github/actions/workflow/status/theislab/embpy/docs.yaml?branch=main&label=docs
[tests]: https://github.com/theislab/embpy/actions/workflows/test.yaml?query=branch%3Amain
[documentation]: https://theislab.github.io/embpy/

**embpy** is a Python toolkit for generating biological embeddings with one
unified API.

Use it to embed genes, proteins, small molecules, morphology perturbations, and
single cells; annotate the resulting objects; and compare embeddings with
scverse-friendly plotting and analysis utilities.

<p align="center">
  <img src="docs/embpy_architecture.svg" alt="embpy architecture" width="900"/>
</p>

## What embpy Does

- Embeds biological entities through `BioEmbedder.embed(...)`.
- Resolves biological identifiers into model-ready inputs, such as gene
  sequences, protein sequences, SMILES strings, and morphology images.
- Returns AnnData, tables, or payloads with provenance and canonical IDs.
- Stores generated embeddings outside `.X`, using `.obsm`, `.varm`, or `.uns`
  according to the entity type.
- Adds real metadata annotations for genes, proteins, molecules, and cell
  lines.
- Provides plotting and comparison helpers for embedding quality checks.

## 📖 Documentation

Complete, interactive documentation and API references are available:

- 🌐 **[Online Documentation](https://theislab.github.io/embpy/)** | **[ReadTheDocs](https://embpy.readthedocs.io/)**
- 📂 **Documentation Guides in this Repository**:
  - [📘 **Overview & Architecture**](docs/index.md)
  - [🚀 **Getting Started & Installation**](docs/getting-started.md)
  - [🧪 **Hands-On Workflows & Practical Recipes**](docs/hands-on.md)
  - [💻 **Cross-Platform & Hardware Guide**](docs/cross-platform.md)
  - [🏛️ **Architecture & Technical Design**](docs/technical.md)
  - [📚 **API Reference**](docs/api-reference.md)
  - [🤝 **Contributing Guide**](docs/contributing.md)

### Running Documentation Locally
```bash
pip install mkdocs-material "mkdocstrings[python]"
mkdocs serve
```
Open **[http://127.0.0.1:8000](http://127.0.0.1:8000)** in your browser for live-reloaded documentation.

## Install

> **Requires Python ≥ 3.11.** Check with `python --version` or `python3 --version` before starting.

There are **two main install flavours** — pick one based on your hardware:

| Flavour | When to use |
| --- | --- |
| `embpy[cpu]` | No NVIDIA GPU, or just getting started |
| `embpy[gpu]` | NVIDIA GPU with CUDA available |

A bare install gives the lightweight core (resolvers, IO, annotation, plotting) but **no embedding backends**. For real use, always pick `[cpu]` or `[gpu]`.

> **GPU note (V100 / Volta):** the default `[gpu]` install gets PyTorch's CUDA 13 build, which supports GPUs from the Turing generation onwards (`sm_75` and newer, e.g. A100, H100) but not Volta (`sm_70`). On a V100 it reports CUDA as available, then every operation fails with `no kernel image is available`. Install the CUDA 12.6 build instead, which still supports Volta:
> ```bash
> # pip: install that torch first; embpy then keeps it
> pip install torch --index-url https://download.pytorch.org/whl/cu126
> pip install "embpy[gpu]"
>
> # uv: one line
> uv pip install "embpy[gpu]" --torch-backend=cu126
> ```

---

### 🐧 Linux / macOS

**Option A — with `pip` (standard):**

```bash
# CPU-only (Note: On Linux pip, you must install torch first to avoid the CUDA bundle)
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install "embpy[cpu]"

# GPU (NVIDIA CUDA)
pip install "embpy[gpu]"
```

**Option B — with `uv` (faster resolver, recommended):**

```bash
# Create and activate an environment first (uv installs into it)
uv venv --python 3.12 && source .venv/bin/activate

# CPU-only
uv pip install "embpy[cpu]"

# GPU (NVIDIA CUDA)
uv pip install "embpy[gpu]"
```

**Quick verification:**

```bash
python -c "import embpy, torch; from embpy import BioEmbedder; print(embpy.__version__, torch.__version__, torch.cuda.is_available())"
```

---

### 🪟 Windows

On Windows, `pip` is tied to a specific Python version. Use `py -3.12` (or whichever Python ≥ 3.11 you have installed) to be explicit:

**Step 1 — Check your Python version:**

```powershell
py --list          # shows all installed Python versions
py -3.12 --version # confirm 3.12 is available
```

**Step 2 — Install embpy:**

```powershell
# CPU-only (recommended for most Windows users)
py -3.12 -m pip install "embpy[cpu]"

# GPU (only if you have an NVIDIA GPU with CUDA)
py -3.12 -m pip install "embpy[gpu]"
```

**Step 3 — Verify:**

```powershell
py -3.12 -c "import embpy, torch; from embpy import BioEmbedder; print(embpy.__version__, torch.__version__, torch.cuda.is_available())"
```

> **Note:** `pysam` and `pyensembl` (genome access) are **not available on Windows** — these are Linux/macOS only. All other backends work natively on Windows.

---

### 🧪 Installing from Source (for development / contributors)

If you are developing `embpy` or running the test suite, clone the repository and install in editable mode:

**🐧 Linux / macOS:**

```bash
# With test dependencies + run tests
git clone https://github.com/theislab/embpy.git
cd embpy
pip install -e ".[test]"
python -m pytest tests/ -v

# Core only (no ML backends)
pip install -e .
```

**🪟 Windows:**

```powershell
# With test dependencies + run tests
git clone https://github.com/theislab/embpy.git
cd embpy
py -3.12 -m pip install -e ".[test]"
py -3.12 -m pytest tests/ -v

# Core only (no ML backends)
py -3.12 -m pip install -e .
```

**Verify the install:**

```bash
# Linux / macOS -- core or [test] install (no PyTorch)
python -c "import embpy; print(embpy.__version__)"
# Linux / macOS -- [cpu] or [gpu] install
python -c "import embpy, torch; print(embpy.__version__, torch.__version__)"

# Windows -- core or [test] install (no PyTorch)
py -3.12 -c "import embpy; print(embpy.__version__)"
# Windows -- [cpu] or [gpu] install
py -3.12 -c "import embpy, torch; print(embpy.__version__, torch.__version__)"
```

> Once this branch is merged into `main` and a new version is published to PyPI,
> the same commands work without the `@ git+...` part, e.g. `pip install "embpy[gpu]"`.

---

### 🖥️ On an HPC cluster (Slurm)

A cluster node is a Linux machine, so **the Linux / macOS commands above work unchanged**. This section
only adds what is specific to a shared cluster: where to run them, where the caches go, and which GPUs the
default build supports. Verified on the Helmholtz Munich HPC; adjust partition/QoS names for your site.

**1. Work on a compute node, not the login node.** The tutorials are small enough for CPU:

```bash
srun --partition=interactive_cpu_p --qos=interactive_cpu --cpus-per-task=8 --mem=16G --time=04:00:00 --pty bash
```

If you see `QOSMaxMemoryPerJob`, that is a **policy cap, not a shortage** — ask for less memory, not more. 16G is enough here.

**2. Keep caches out of your home directory.** pip, uv and Hugging Face cache downloads under `~/.cache`,
and home quotas are usually small: each install leaves 1–3 GB of wheels there, and model weights add more.
Point the caches at project storage (replace the path):

```bash
export PROJECT=/path/to/your/project/space
export PIP_CACHE_DIR=$PROJECT/.cache/pip UV_CACHE_DIR=$PROJECT/.cache/uv HF_HOME=$PROJECT/.cache/huggingface
export UV_LINK_MODE=copy   # the uv cache and the environment are often on different filesystems
```

**3. Create an environment and install, exactly as on Linux:**

```bash
uv venv .venv --python 3.12 && source .venv/bin/activate
uv pip install "embpy[cpu]"   # CPU node
uv pip install "embpy[gpu]"   # GPU node
```

The default `[gpu]` build runs on GPUs from the Turing generation onwards (`sm_75` and newer, e.g. A100,
H100). Older **V100** (Volta) GPUs report CUDA as available, but every operation then fails with
`no kernel image is available`. On those nodes, ask uv for the CUDA 12.6 build instead:

```bash
uv pip install "embpy[gpu]" --torch-backend=cu126
```

**4. Run the notebooks.** They live in the repository, so clone it first:

```bash
git clone https://github.com/theislab/embpy.git && cd embpy
uv pip install ipykernel jupyter
jupyter nbconvert --to notebook --execute docs/notebooks/01_embed_any_model.ipynb --output /tmp/out.ipynb
```

To work on embpy itself, install the clone instead of the git URL: `uv pip install -e ".[cpu]"`.

**Or run them interactively.** Start a server on the compute node:

```bash
jupyter lab --no-browser --ip=0.0.0.0 --port=8899
```

Jupyter prints a URL with a random token. Open it as `http://<compute-node>:8899/lab?token=<token>`
(`hostname` gives the node), through an SSH tunnel from your laptop if the node is not directly reachable:
`ssh -N -L 8899:<compute-node>:8899 <login-node>`, then use `localhost:8899`. Do not set a fixed token such
as `embpy`: anyone who can reach the node could then open your session, and with it a shell under your
account. Do not background the server with `Ctrl+Z` — use `nohup ... &` if you need the prompt back.

---

<details>
<summary>Backends that must be installed separately</summary>

A few backends cannot be installed by pip on an arbitrary machine, so they are in
neither extra. embpy degrades gracefully without them, and asking for one of their
models raises a typed `DependencyError` naming the command to run.

Every line below was checked by resolving it with `uv pip compile`; the "Status"
column says what actually happens today rather than what is intended.

| Backend | Install | Status / why it is separate |
| --- | --- | --- |
| Caduceus | `uv pip install "embpy[caduceus]"` | resolves cleanly (`mamba-ssm`), but the wheel builds against your installed torch — install the matching torch first. Needs a CUDA toolchain if no wheel matches. |
| Scooby | `uv pip install "embpy[scooby]" "scooby @ git+https://github.com/gagneurlab/scooby.git"` | the `scooby` model package is published on GitHub only, so it is installed by URL next to the extra. (The `scooby` on PyPI is an unrelated project.) |
| Evo (v1/v1.5) | `uv pip install "embpy[evo]"` | **Linux only.** Depends on `triton`, which publishes no macOS wheels, so this is unsatisfiable on macOS. |
| Evo 2 | `uv pip install "embpy[evo2]"` | **needs Python 3.11 or 3.12** — `evo2` declares `requires-python >=3.11,<3.13`, so it cannot install into a 3.13 environment at all. Needs its own venv (below). |
| Flashzoi | `uv pip install "embpy[flashzoi]" --no-build-isolation` | the four `flashzoi_*` keys set `flashed=true` and need `flash_attn`, which is NVIDIA-only and builds against your installed torch. The eight plain `borzoi_*` keys need none of it. |
| Boltz-2 | `uv pip install "embpy[boltz]"` | **downgrades numpy to 1.26** (boltz pins `numpy<2`). Everything compiled against numpy 2 in the same environment is at risk — prefer a dedicated environment. |
| MiniMol | `uv pip install "embpy[minimol]"` | needs `--no-build-isolation`: `torch-sparse`/`torch-scatter` build against an already-installed torch. Install torch first, then this extra with that flag. |
| ESM-C / ESM3 | `uv pip install "embpy[cpu]"` then `uv pip install esm --no-deps` | installing the extra normally **caps transformers at 4.48.1** (the `esm` SDK pins `<4.48.2`), which also silently moves borzoi-pytorch onto a 0.4.x release. `--no-deps` avoids both — `esm` works with newer transformers. ESM3 weights are additionally licence-gated. |
| NT v3 | `uv pip install "embpy[ntv3]"` | needs no extra package; the barrier is **access**. The `InstaDeepAI/NTv3_*` repositories are gated, so accept the licence on the model page and `huggingface-cli login` (or set `HF_TOKEN`). |
| AlphaGenome | `uv pip install "embpy[alphagenome]"` | API client, needs a key — no local weights |
| single-cell FMs | `uv pip install "embpy[helical]"` | pins torch/transformers and needs the igraph C library. Cannot coexist with `arc-state` or `cell-eval` through a resolver — see the single-cell recipe below. |

**Gated weights are not a packaging problem.** NT v3 and ESM3 install fine and then
fail at download with a 401 until you have accepted the licence and authenticated.
embpy reports this as an access error naming the model page, not as a missing
package, so the two cases are distinguishable.

**Some extras move shared pins.** `[esm3]` and `[boltz]` change `transformers` and
`numpy` for the whole environment. uv will not warn you: both are *legal*
resolutions rather than conflicts, so the downgrade is silent even if the extras
are declared as conflicting. The remedies are per-case, below.

#### Backends that want their own environment

Four cases cannot share an environment with the standard install. Give each its
own venv — embpy is identical in all of them, only the affected models differ.

**Evo 2 — forced by the interpreter.** `evo2` requires Python `>=3.11,<3.13`, so
no flag makes it install into a 3.13 environment:

```bash
uv venv --python 3.12 .venv-evo2
uv pip install --python .venv-evo2/bin/python "embpy[evo2]"
```

**Flashzoi — forced by the build.** `flash-attn` ships no wheels and compiles
against an already-installed torch, so it is two steps and NVIDIA-only:

```bash
uv venv --python 3.12 .venv-flashzoi
uv pip install --python .venv-flashzoi/bin/python "embpy[gpu]"
uv pip install --python .venv-flashzoi/bin/python "embpy[flashzoi]" --no-build-isolation
```

**Boltz-2 — forced by numpy.** `boltz` pins `numpy<2`, putting every package
compiled against numpy 2 in the same environment at risk:

```bash
uv venv --python 3.12 .venv-boltz
uv pip install --python .venv-boltz/bin/python "embpy[boltz]"
```

**Single-cell foundation models — forced by three mutually exclusive pins.**
`helical` (scGPT, Geneformer, UCE) declares `numpy>=2.1.3,<2.3` and
`transformers<=4.51.3`; `arc-state` (STATE) needs `transformers>=4.52.3`; and
`cell-eval` pulls `pdex`, which needs `numpy>=2.4.2`. No Python version
satisfies all three, so a resolver rejects the combination outright rather than
picking badly. The helical ceilings turn out to be stale, though, so
`--no-deps` plus its real runtime dependencies gets one environment with all of
them (verified on linux-64: scGPT, Geneformer, scVI, STATE and PCA all embed):

```bash
uv venv --python 3.13 .venv-sc
uv pip install --python .venv-sc/bin/python \
    arc-state arc-stack scvi-tools scib scib-metrics "cell-eval>=0.7.2" scanpy
uv pip install --python .venv-sc/bin/python -e .        # embpy *with* its deps
uv pip install --python .venv-sc/bin/python --no-deps helical
uv pip install --python .venv-sc/bin/python \
    "datasets==3.6.0" einops sentencepiece biopython catalogue \
    pybiomart requests-cache
uv pip install --python .venv-sc/bin/python "transformers==4.57.6"
```

Five details are load-bearing, each of which fails in its own way:

| Detail | What breaks without it |
| --- | --- |
| `--no-deps helical` | resolution fails, or numpy is dragged below 2.3 |
| `datasets==3.6.0` exactly | Geneformer: `'Column' object has no attribute 'device'` |
| `transformers==4.57.6`, not 5.x | embpy pins `huggingface-hub<1.0.0`, which lacks the `is_offline_mode` transformers 5 imports |
| `-e .` *without* `--no-deps` | embpy's own light core (rdkit, sklearn) is missing, and the import errors look like model problems |
| `scib` *and* `scib-metrics` | different packages; `tl.compute_scib_metrics` imports the first, so only installing the second raises `DependencyError` |

`stack` installs and loads but then fails inside arc-stack's own h5ad reader
(`Could not find gene names in the file`) even when `gene_name_col` is
supplied — upstream, not embpy. `state` fetches ~12 GB of weights on first use
unless you pass `model_kwargs={"state": {"checkpoint": ...}}`.

**ESM-C / ESM3 does *not* need its own environment.** Install `[cpu]` or `[gpu]`
normally and add `esm` with `--no-deps`, as in the table above.

Asking for a model whose backend is absent raises a typed `DependencyError` naming
the install line, so a missing backend stays distinguishable from a broken
checkpoint or a gated repository.

</details>

## Quick Start

```python
from embpy import BioEmbedder

embedder = BioEmbedder(device="auto", organism="human")
```

Embed genes with multiple model families:

```python
gene_adata = embedder.embed(
    ["TP53", "EGFR", "MYC"],
    entity_type="gene",
    id_type="symbol",
    model=["hyenadna_tiny_1k", "esm2_8M", "minilm_l6_v2"],
    output="anndata",
)

gene_adata.varm.keys()
gene_adata.uns["embeddings"].keys()
```

Embed gene perturbation labels as row-aligned action embeddings:

```python
# pert_adata.obs["perturbation"] contains symbols such as TP53/MYC.
pert_adata = embedder.embed(
    pert_adata,
    entity_type="gene",
    obs_column="perturbation",
    id_type="symbol",
    model="esm2_650M",
    output="anndata",
    is_perturbation=True,
    key="X_pert_esm2_650M",
)

pert_adata.obsm["X_pert_esm2_650M"]
```

Embed proteins:

```python
protein_adata = embedder.embed(
    ["TP53", "EGFR", "BRCA1"],
    entity_type="protein",
    id_type="symbol",
    model="esm2_8M",
    output="anndata",
)
```

Embed small molecules:

```python
smiles = [
    "CC(=O)OC1=CC=CC=C1C(=O)O",  # aspirin
    "Cn1cnc2c1c(=O)n(C)c(=O)n2C",  # caffeine
]

molecule_adata = embedder.embed(
    smiles,
    entity_type="molecule",
    id_type="smiles",
    model="morgan_fp",
    output="anndata",
    key="X_morgan_fp",
)
```

Embed cells from AnnData with model-aware preprocessing:

```python
cell_adata = embedder.embed(
    adata,
    entity_type="cell",
    model="pca",
    preprocessing="auto",
    output="anndata",
    key="X_pca",
)

cell_adata.obsm["X_pca"]
cell_adata.uns["embpy_cell_embeddings"]
```

Annotate and plot:

```python
from embpy import tl, pl

molecule_adata.obs["smiles"] = molecule_adata.obs_names
molecule_adata = tl.annotate_molecules(
    molecule_adata,
    column="smiles",
    sources=["structural", "bioactivity", "ontology"],
)

pl.plot_embedding_space(
    molecule_adata,
    obsm_key="X_morgan_fp",
    method="pca",
    color="mol_logp",
)
```

## Tutorials

**Start here** — a short, goal-oriented path:

1. [Embed with any model](docs/notebooks/01_embed_any_model.ipynb) — the full model
   catalog, then one embedding call per family (DNA, protein, molecule, text, …).
2. [Where embeddings live](docs/notebooks/02_output_contract.ipynb) — the
   `.obsm` / `.varm` / `.uns` storage contract and provenance.
3. [Comparing embeddings](docs/notebooks/03_compare_embeddings.ipynb) — every metric
   for asking whether two models encode the same structure, and which to use when.
4. [Which model captures *my* biology?](docs/notebooks/04_benchmark_models.ipynb) —
   rank models on your own labelled task.
5. [What else does embpy know about your entities?](docs/notebooks/05_annotate_entities.ipynb) —
   the annotation layer: physicochemical properties, the ChEMBL clinical record
   (phase, indications, safety, ATC, mechanism, targets), gene pathways and
   protein function. Network-bound, no weights, and the source of labels your
   analysis did not choose.
6. [Reading a model's attention](docs/notebooks/06_attention_weights.ipynb) —
   extract per-layer attention and reduce it to AnnData-ready summaries.

**By modality** — deeper, domain-specific workflows:

- [Genes](docs/notebooks/genes.ipynb)
- [Proteins](docs/notebooks/proteins.ipynb)
- [Small molecules](docs/notebooks/small_molecules.ipynb)
- [Cells](docs/notebooks/cells.ipynb)
- [Variant effects](docs/notebooks/variant_effects.ipynb)

Each notebook uses real `BioEmbedder.embed(...)` calls, real annotation APIs,
and embpy plotting/comparison utilities.

## Model Families

embpy supports models across:

- DNA and regulatory sequence models
- protein language and structure models
- small-molecule fingerprints and chemical language models
- single-cell foundation models and classical baselines
- morphology models for HPA and JUMP-style images
- text models for biological descriptions

Use:

```python
embedder.list_available_models()
```

for the model keys available in your environment.

## Output Contract

`BioEmbedder.embed(...)` follows a scverse-friendly output contract:

- genes are feature-like and live in `.varm` by default
- gene perturbation labels use `is_perturbation=True` and live in `.obsm`
- proteins are feature-like and live in `.varm`
- molecules, text, sequences, and cells are observation-like and live in `.obsm`
- perturbation/action embeddings can be kept entity-aligned in `.uns`
- `.X` remains expression/count-like data or a sparse placeholder

See the [Architecture & Technical Guide](docs/technical.md#standardized-output-contracts) for
the full contract.

## Citation

If you use embpy in your work, please cite the repository for now. A formal
citation will be added when the package is released.

## Contact

For questions, issues, or feature requests, open a GitHub issue or contact the
maintainers listed in the package metadata.
