Skip to main content

Logomark pysynthbio

pysynthbio is an Python package that provides a convenient interface to the Synthesize Bio API, allowing users to generate realistic gene expression data based on specified biological conditions. This package enables researchers to easily access AI-generated transcriptomic data for various modalities including bulk RNA-seq and single-cell RNA-seq.

If you'd prefer 1-click dataset generation and analysis, try our web platform.

Prerequisites

Create a Synthesize Bio account and generate an API Key.

Installation

pip install pysynthbio

Quickstart

import pysynthbio

# Set your API token (or use environment variable SYNTHESIZE_API_KEY)
pysynthbio.set_synthesize_token(use_keyring=True)

# Get an example query for the bulk RNA-seq baseline model
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]

# Generate synthetic expression data
result = pysynthbio.predict_query(query, model_id="gem-1-bulk")

# Access the results
metadata = result["metadata"]
expression = result["expression"]

Documentation

The canonical pysynthbio docs live at docs.synthesize.bio/pysynthbio.

The legacy GitHub Pages site at synthesizebio.github.io/pysynthbio redirects to the new URLs and is no longer updated. The MDX source for the customer-facing docs lives in docs-external/ and is aggregated into docs-external by the Mintlify multirepo workflow.

Questions? Suggestions? Support?

Email us at support@synthesize.bio. We'd love to hear from you!

VERDICT models and trials

Sign in to VERDICT API docs for the Python client guide, API keys, model calls, and trial workflows. An approved VERDICT account is required.

Hosted GEM-2 operations

Use predict_query(..., model_id="gem-2") for a release that supports the requested operation. GEM-2 uses operation to select predict-expression, predict-expression-from-reference, predict-metadata, or autoencode. The server checks support for the selected release and modality.

import pysynthbio

query = {
    "operation": "predict-expression",
    "inputs": {
        "modality": "bulk",
        "items": [{
            "metadata": {
                "sample_type": "primary tissue",
                "library_layout": "PAIRED",
                "library_selection": "cDNA",
                "tissue": "liver",
                "bioactive_entity_perturbations": [{"smiles": "CCO"}],
                "gene_perturbations": [],
                "infection_perturbations": [],
            },
            "num_samples": 1,
            "output_total": {"type": "custom", "value": 8478},
        }],
    },
    "options": {"seed": 42, "sampling_strategy": "mean estimation"},
}
result = pysynthbio.predict_query(query, model_id="gem-2")

SMILES and direct ChEMBL IDs require an enabled molecule release. For a ChEMBL ID, replace {"smiles": "CCO"} with {"entity_ontology_id": "CHEMBL3261331"}. Supply exactly one of entity, entity_ontology_id, or smiles per molecule; entity retains the supported-name lookup. Pin a release with the optional request field release when testing a candidate.

Expression results contain expression, metadata, and latents DataFrames. Metadata prediction contains predicted metadata, classifier_probs, and latents with the encoded column; its expression has one row per result and no columns because this operation does not generate counts. Reconstruction (autoencode) retains counts and returns a provenance DataFrame with each row's model_release_id and vae_run_id. Its latents has no columns. Existing GEM-2 compatibility model names also use these operation-aware formats. raw_response=True continues to return the original response unchanged.

Trial Import (preview)

from pysynthbio import VerdictClient
client = VerdictClient()  # VERDICT_API_KEY, optionally VERDICT_API_BASE_URL
proposal = client.import_trial(nct_id="NCT01945775")
# Or: proposal = client.import_trial(document="protocol.pdf")
print(proposal["metadata"]["fields"])

Use an API-enabled VERDICT deployment with Trial Import support. Imports accept exactly one NCT ID or local PDF/DOCX/TXT file, up to 5 MiB, and return an editable form draft plus provenance and review metadata. They do not submit an analysis. Review flagged fields before constructing a workflow input; the draft is not itself a workflow request. The import timeout defaults to 210 seconds. Extraction errors raise the normal API error even when the streamed response has HTTP 200. Retrying starts fresh extraction, so save successful proposals locally.

See the VERDICT Trial Import guide for review semantics and limits. These helpers are on the app-2924-trial-import development branch and are not yet a published release.

Trial designs (preview)

Build, inspect and edit a VERDICT trial design in Python, then review and run it. Nothing contacts the API until review() or run().

from pysynthbio import Trial, VerdictClient, trial_vocabulary

trial_vocabulary()   # every allowed value, offline
Trial.describe()     # every editable field, as a table

trial = Trial("HCC phase 3")
trial.population.set_disease("hepatocellular carcinoma")
trial.edit(phase="phase 3", allocation="randomized", blinding="open label", min_age=18)
trial.arms.add("Durvalumab", type="experimental", treatments=["durvalumab"])
trial.arms.add("Sorafenib", type="active comparator", treatments=["sorafenib"])
trial.endpoints.add("Overall survival", family="overall_survival",
                    effect_measure="hazard ratio", hypothesis="superiority")
trial                # renders the design in a notebook; print(trial) in a terminal

client = VerdictClient()
trial.review(client)                               # what will run; runs nothing
result = trial.run(client, idempotency_key="hcc-phase3-v1")
result.efficacy.table                              # readable DataFrames
result.safety.table

# Variations: every combination, run together and compared side by side
trial.vary(enrollment=[200, 600, 1200]).run(client, idempotency_prefix="hcc-size").table

# Screen drugs: one variant per drug swapped into an arm
trial.screen("Durvalumab", ["durvalumab", "atezolizumab", "nivolumab"]).run(
    client, idempotency_prefix="hcc-screen"
).table

Start from an import with Trial.from_import(client.import_trial(nct_id=...)), or save and reload a design with trial.save(path) / Trial.load(path). Arms, endpoints, comparisons and treatments each support add, remove, edit, list and lookup by name or position. Analyses the deployed models cannot score are skipped and named in the review instead of refusing the run.

Metadata

Release files for pysynthbio 4.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pysynthbio 4.3.0
File Size Uploaded Provenance Actions
pysynthbio-4.3.0.tar.gz 81.8 kB With provenance Details for pysynthbio-4.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pysynthbio 4.3.0
File Interpreter ABI Platform Actions
pysynthbio-4.3.0-py3-none-any.whl Python 3 none any Details for pysynthbio-4.3.0-py3-none-any.whl

Total release size: 149.9 kB

Release files / pysynthbio-4.3.0.tar.gz

Download URL pysynthbio-4.3.0.tar.gz
Size 81.8 kB
Tags Source
SHA-256 checksum
How to use checksums
94eed0af27a4e2a7b0f6ed3fc83db02c6f3ead023baf41150781e6d4cc5fdbc5
BLAKE2b-256 checksum
How to use checksums
d69471af8a284ed72835a5d04463f38fe56927ad71092a50cb48122b815ea6fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / pysynthbio-4.3.0-py3-none-any.whl

Download URL pysynthbio-4.3.0-py3-none-any.whl
Size 68.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
250cb6cb70f7cfd632d1255ac7ae91b1dbb959bcc54e3ca2435cc4df48da3476
BLAKE2b-256 checksum
How to use checksums
8aa47984e4304a4fe48b34535ab2cbccbb2453d369419cebda0b200c5645c08a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for pysynthbio 4.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pysynthbio-4.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page