deeplife-toolkit 0.1.2

Official DeepLife Python toolkit on PyPI: TwinCell (`deeplife_toolkit.twincell`), pseudo-bulk (`deeplife_toolkit.pseudobulk`), differential expression (`deeplife_toolkit.differential_expression`). Optional `[notebook]` extra for Jupyter tutorials.

deeplife-toolkit

Official DeepLife Python toolkit for TwinCell and related analysis: call the Open API from Python, validate and preprocess AnnData (.h5ad) locally, aggregate to pseudo-bulk with deeplife_toolkit.pseudobulk, and run sample-level differential expression with deeplife_toolkit.differential_expression (suitable for pseudo-bulk, bulk, or other compatible count tables).

Source: github.com/deeplifeai/deeplife-toolkit · Documentation: docs index on GitHub · Python: 3.12+ (see pyproject.toml).

---

Install

pip install deeplife-toolkit

API key: you need a DeepLife key (usually dl_…). Create or copy one from the TwinCell console (sign in, then open API keys / Keys). In code, set DEEPLIFE_API_KEY in the environment or pass api_key= when constructing the client. API documentation for your deployment is usually at {base_url}/docs when enabled (the client defaults to the production Open API host; pass base_url= for another environment).

Network: the TwinCell Open API is not on the public Internet today. It runs in DeepLife’s cluster and is reachable only when your machine has access to that network—for example by being signed into your organization’s Tailscale tailnet (or whatever access path your team documents). Local-only features (twincell-validate-h5ad, pseudo-bulk, differential expression on .h5ad) do not require API connectivity.

From a git clone (contributors):

uv sync --group dev

---

Documentation

Long-form guides (same content as the Documentation link on PyPI):

Guide	Description
Installation	pip install, optional [notebook], API keys, verify imports
Pseudo-bulk & differential expression	AnnData → pseudo-bulk, sample-level DE, CLIs
TwinCell Open API	HTTP client, predictions, studies, datasets

Index: docs/README.md.

---

Package layout

Import	Role
deeplife_toolkit.twincell.api	HTTP client (OpenDeepLifeClient, async variant), predictions, datasets, TwinCell / TwinCellStudy workflows, data catalog helpers, plotting
deeplife_toolkit.twincell.validation	TwinCell-ready preprocessing and local validation (DeepLifePreprocessor, configs, CLI twincell-validate-h5ad)
deeplife_toolkit.pseudobulk, deeplife_toolkit.differential_expression	Pseudo-bulk from single-cell AnnData, and sample-level DE (CLIs twincell-pseudobulk, twincell-diffexpr)

Install with pip install deeplife-toolkit (PyPI project name, hyphen). Import deeplife_toolkit.twincell, deeplife_toolkit.pseudobulk, and deeplife_toolkit.differential_expression (nested packages inside the deeplife_toolkit distribution).

---

Minimal API usage

End-to-end flow: preprocess/validate .h5ad → create_prediction → poll or watch_prediction → read results (and optional influence / causal helpers). The toolkit validates uploads the same way the TwinCell API does.

import os
from deeplife_toolkit.twincell.api import OpenDeepLifeClient

client = OpenDeepLifeClient(api_key=os.environ["DEEPLIFE_API_KEY"])
prediction = client.create_prediction(dataset="twincell_ready.h5ad")
final = client.wait_for_prediction(prediction_id=prediction.prediction_id)
print(final.status)

Defaults: the client uses the toolkit’s configured API base URL; pass base_url= for another environment. You must be able to reach that host from your network (see Network under Install). Retries apply to safe GET-style calls (polling), not duplicate uploads on POST. For TLS/proxy issues, use tls_verify= and trust_env= on the client—see OpenDeepLifeClient in deeplife_toolkit.twincell.api.

For preprocessing options (raw layer, disease filter, gene symbol column, etc.), use deeplife_toolkit.twincell.validation or the example notebooks.

---

Example notebooks

Tutorial notebooks live in this repository under notebooks/ and are not inside the PyPI wheel. Install deeplife-toolkit from PyPI, then open the .ipynb from a git clone of this repo or from a single notebook file you downloaded from GitHub.

kang_pbmc.ipynb (Kang PBMC IFN-β): preprocess → pseudo-bulk PyDESeq2 → TwinCellStudy, scorecards, causal subgraphs, and simulate(), with an optional commented block for in-memory skin_atlas_2024.

Run the Kang tutorial (PyPI install)

1. Create and activate a virtual environment (recommended), then upgrade pip.

2. Install the library, Jupyter, the [notebook] extra, and seaborn (used in the notebook):

   pip install "deeplife-toolkit[notebook]" jupyterlab seaborn
   

3. Get the notebook on disk, for example:

   git clone https://github.com/deeplifeai/deeplife-toolkit.git
   cd deeplife-toolkit
   

4. Start Jupyter from the repository root so relative paths in the notebook resolve:

   jupyter lab
   

   Open notebooks/kang_pbmc.ipynb. In Kernel → Change kernel, pick the Python environment where you ran pip install (if it is missing from the list, run python -m ipykernel install --user --name deeplife-toolkit --display-name "Python (deeplife-toolkit)" inside that environment and choose that kernel).

The Kang dataset is fetched over HTTPS inside the notebook (get_adata_from_url). Part 2 (TwinCell HTTP) needs DEEPLIFE_API_KEY or a one-time getpass prompt.

Path	Role
notebooks/	Tutorial sources (kang_pbmc.ipynb).
notebooks/data/	Downloaded .h5ad and outputs (gitignored in the repo; created locally when you run cells).

Contributors who work from a git clone can use uv sync --group dev --extra notebook instead of pip if you prefer the locked lockfile.

Example dataset helpers live in deeplife_toolkit.twincell.api.datasets (EXAMPLE_DATASETS is empty until you add HTTP(S) links; download_example_dataset streams those URLs). In-memory demo atlas: get_adata(dataset_name="skin_atlas_2024") from deeplife_toolkit.twincell.api.data.

After pip install -U deeplife-toolkit, confirm imports match the layout you expect; the latest release is always on PyPI.

---

Development

uv sync --group dev
make check-all    # or: ruff, mypy, pytest — see Makefile

CI: .github/workflows/ci.yml runs on pushes and PRs to main / master: uv sync --frozen --group dev, Ruff, mypy, pytest, uv build, twine check --strict. .github/dependabot.yml bumps GitHub Actions weekly.

Releases to PyPI: .github/workflows/pypi-publish.yml runs the same checks, then publishes with OIDC trusted publishing (GitHub environment pypi, trusted publisher configured on the deeplife-toolkit PyPI project). Bump version in pyproject.toml, push to main, then either push a tag matching v* or run the workflow manually from the Actions tab.