wittgen-b2sc

Thin Python client for the WittGen B2SC API — submit a bulk RNA-seq job, poll it to completion, and pull per-sample single-cell type proportions as a dataframe. Built to the OpenAPI contract at https://www.wittgenbio.com/api/v1/openapi.json.

Install

pip install wittgen-b2sc            # core
pip install "wittgen-b2sc[pandas]"  # + DataFrame support

If that 404s, this build has not been published to PyPI yet — install the wheel we sent you:

pip install ./wittgen_b2sc-0.1.1-py3-none-any.whl
pip install pandas          # optional, for as_dataframe=True

Installing from git requires access to the private platform repo, so it only works for WittGen staff and partners who have been granted it:

pip install "wittgen-b2sc[pandas] @ git+ssh://git@github.com/WittGen-Inc/wittgen-b2sc-platform.git#subdirectory=clients/wittgen-b2sc-python"

Authenticate

Create a per-user API key in the WittGen dashboard (it is shown once — store it as a secret).

from wittgen_b2sc import B2SCClient
client = B2SCClient(api_key="wgk_...")

Quickstart

# 1. Submit a job against a built-in reference dataset
job = client.submit_job("breast_cancer_cell_type3", source="reference_dataset")
job_id = job["job_id"]

# 2. Wait for the generative pipeline, then for the R analysis stage
#    (a full run takes ~30 minutes — the GPU generates single cells from your bulk profile)
client.wait_for_completion(job_id, poll_interval=15, timeout=3600, wait_for_report=True)

# 3. Per-sample cell-type proportions as a tidy DataFrame
df = client.get_proportions(job_id, as_dataframe=True)   # columns: sample, cell_type, proportion
print(df.head())

# 4. Ask for the AI clinical report, then wait for the PDF.
#    This step is explicit because it is the most expensive operation in the pipeline —
#    it is not generated unless you ask for it.
client.generate_report(job_id)
client.wait_for_report(job_id)
client.download_report(job_id, "report.pdf")

Databricks quickstart

Run inside a Databricks notebook. Store the key in a secret scope, never inline.

# Cell 1 — install
# Until the package is on PyPI, upload the wheel to DBFS and install that instead:
#   %pip install /dbfs/FileStore/wittgen_b2sc-0.1.1-py3-none-any.whl
%pip install "wittgen-b2sc[pandas]"

# Cell 2 — client (key from a Databricks secret scope)
from wittgen_b2sc import B2SCClient
api_key = dbutils.secrets.get(scope="wittgen", key="b2sc_api_key")
client = B2SCClient(api_key=api_key)

# Cell 3 — submit + await + load as a Spark-ready pandas DataFrame
job = client.submit_job("breast_cancer_cell_type3", source="reference_dataset")
client.wait_for_completion(job["job_id"])
pdf = client.get_proportions(job["job_id"], as_dataframe=True)
sdf = spark.createDataFrame(pdf)      # -> a Spark DataFrame you can join/aggregate/save to Delta
sdf.display()

API surface

wait_for_completion returns as soon as the job is COMPLETED (proportions are ready then); the AI report is generated server-side shortly after — poll get_report() for it. Errors raise B2SCError (.status, .code); a poll timeout raises B2SCTimeout. A 409 from get_proportions means the results are not produced yet — retry.

Data residency / BAA: genomic expression data is PHI. Confirm your BAA and the API region with WittGen before sending patient-derived data. See the data-residency one-pager.

License

Apache-2.0 — see LICENSE. This client SDK is open source; the WittGen B2SC model and service it talks to remain proprietary. Copyright 2026 WittGen Biotechnologies.