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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.