Metadata-Version: 2.4
Name: pysynthbio
Version: 4.3.0
Summary: A package to retrieve data and models from Synthesize Bio's API
Author: Alex David, Candace Savonen
License-Expression: MIT
Project-URL: Homepage, https://github.com/synthesizebio/pysynthbio
Project-URL: Issues, https://github.com/synthesizebio/pysynthbio/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.2.5
Requires-Dist: pandas>=2.2.3
Requires-Dist: requests
Requires-Dist: keyring>=23.0.0
Provides-Extra: verdict
Requires-Dist: matplotlib<4,>=3.9; extra == "verdict"
Requires-Dist: ipython>=8; extra == "verdict"
Provides-Extra: secure
Requires-Dist: keyring>=23.0.0; extra == "secure"
Provides-Extra: self-hosted
Requires-Dist: pyarrow>=15.0.0; extra == "self-hosted"
Provides-Extra: all
Requires-Dist: matplotlib<4,>=3.9; extra == "all"
Requires-Dist: ipython>=8; extra == "all"
Requires-Dist: keyring>=23.0.0; extra == "all"
Requires-Dist: pyarrow>=15.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: black>=26.3.1; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# <img src="https://assets.synthesize.bio/logomark.png" style="width: 30px; height: 30px;" alt="Logomark">&nbsp;pysynthbio

`pysynthbio` is an Python package that provides a convenient interface to the [Synthesize Bio](https://www.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](https://app.synthesize.bio/datasets/).

## Prerequisites

Create a [Synthesize Bio](https://app.synthesize.bio/) account and generate an [API Key](https://app.synthesize.bio/account/api-keys).

## Installation

```
pip install pysynthbio
```

## Quickstart

```python
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](https://docs.synthesize.bio/pysynthbio).

- [Get started](https://docs.synthesize.bio/pysynthbio/getting-started)
- [Installation](https://docs.synthesize.bio/pysynthbio/installation)
- [Models](https://docs.synthesize.bio/pysynthbio/models/baseline)

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/`](./docs-external) and is aggregated into [`docs-external`](https://github.com/synthesizebio/docs-external) by the Mintlify multirepo workflow.

## Questions? Suggestions? Support?

Email us at [support@synthesize.bio](mailto:support@synthesize.bio). We'd love to hear from you!

## VERDICT models and trials

Sign in to [VERDICT API docs](https://verdict.synthesize.bio/app/api-docs/python)
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.

```python
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)

```python
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](https://verdict.synthesize.bio/app/api-docs/trial-import) 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()`.

```python
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.
