deeplife

Official DeepLife Python toolkit for TwinCell and related analysis: call the Open API from Python, pseudo-bulk with deeplife.pseudobulk, and run sample-level differential expression with deeplife.differential_expression (suitable for pseudo-bulk, bulk, or other compatible count tables). TwinCell code is split into focused subpackages under deeplife.twincell (HTTP client, workflows, preprocess, validation); deeplife.twincell itself still exposes a flat import surface for notebooks.

Source: github.com/deeplifeai/deeplife · Documentation: twincell.deeplife.co/docs · Python: 3.12+ (see pyproject.toml).

Install

pip install deeplife

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; the client sends it as the X-API-Key header on every request (not Authorization: Bearer).

Network: the TwinCell Open API is public. The client defaults to https://open-deeplife-api.deeplife.co, reachable over the Internet. Interactive REST docs are at /docs and the schema at /openapi.json; pass base_url= to target another environment. Local-only features (pseudo-bulk, differential expression on .h5ad) do not require API connectivity.

From a git clone (contributors):

uv sync --group dev

Documentation

Hosted docs (same content as the Documentation link on PyPI):

Source: docs/index.md.

Package layout

TwinCell (deeplife.twincell)

Other packages

Install with pip install deeplife. Import deeplife.twincell (flat or by submodule), deeplife.pseudobulk, and deeplife.differential_expression.

Minimal API usage

End-to-end flow: build a control and a perturbed AnnData plus a DEG list yourself → submit them as a split target-validation run → poll → read the target score and causal mechanism.

The notebook-oriented TwinCell class is the shortest path. It validates the split inputs locally, checks API connectivity on construction, and submits with job_type="target_validation":

import os
from deeplife.twincell import TwinCell

tc = TwinCell(
    pdata_control=pdata_control,  # AnnData, raw counts in .X
    pdata_pert=pdata_pert,        # AnnData, raw counts in .X
    degs=degs,                    # list[str] of HGNC-style symbols
    api_key=os.environ["DEEPLIFE_API_KEY"],
)
prediction_id = tc.target_validation(target="TYK2|PROTEIN")
print(tc.get_target_score(prediction_id=prediction_id))

The same run through the HTTP client, when you want to manage polling yourself:

import os
from deeplife.twincell.http import DeepLifeClient

client = DeepLifeClient(api_key=os.environ["DEEPLIFE_API_KEY"])
prediction = client.create_prediction_split(
    pdata_control=pdata_control,
    pdata_pert=pdata_pert,
    degs=degs,
    job_type="target_validation",
    target="TYK2|PROTEIN",
)
final = client.wait_for_prediction(prediction_id=prediction.prediction_id)
print(final.status)

External API keys are limited to split target validation. A merged single-file upload via create_prediction(dataset=…) returns 403 (prediction_external_split_required), and leaving job_type at its default "target_id" returns 403 (prediction_external_target_validation_only). Both paths are internal-only; use create_prediction_split(..., job_type="target_validation") as above.

The Python arguments are pdata_control / pdata_pert; the underlying multipart REST fields on POST /v1/predictions are named dataset_control / dataset_pert. Don't pass the REST names to the SDK.

Defaults: the client targets https://open-deeplife-api.deeplife.co; pass base_url= for another environment. Retries apply to safe GET-style calls (polling), not duplicate uploads on POST. Polling waits 5s between status requests (poll_interval_seconds) to stay well inside the edge rate limit of 30 requests/minute per IP — lower it only if you know the address isn't shared. For TLS/proxy issues, use tls_verify= and trust_env= on the client—see DeepLifeClient in deeplife.twincell.http.client.

For richer AnnData preparation (QC, column mapping, pseudo-bulk), use deeplife.twincell.preprocess or the tutorial notebooks.

Tutorials

Tutorial .ipynb files are published on the docs site (interactive + download). target-validation-deucravacitinib-psoriasis.ipynb is the end-to-end walkthrough: it loads a public psoriasis skin atlas (GSE162183), builds pseudo-bulk profiles for psoriatic vs. normal dendritic cells, derives the disease signature with PyDESeq2, then uses TwinCell to test whether Deucravacitinib's target (TYK2) causally explains it.

Run locally from a git clone:

pip install "deeplife[notebook]" jupyterlab
git clone https://github.com/deeplifeai/deeplife
cd deeplife
jupyter lab tutorials/

Set DEEPLIFE_API_KEY (or use the notebook getpass prompt) before the TwinCell API steps. Everything up to that point runs locally; the API cells need an Internet connection.

Contributors can use uv sync --group dev --extra notebook instead of pip if you prefer the locked lockfile.

After pip install -U deeplife, 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 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.