Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synthesize.bio/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Baseline models generate synthetic gene expression data from metadata alone. You describe the biological conditions, such as tissue type, disease state, perturbations, and cell type, and the model generates realistic expression profiles matching those conditions. This is the most common use case: generating synthetic data for conditions where real data may be scarce or unavailable.

​
Available models

  • gem-1-bulk: Bulk RNA-seq baseline model
  • gem-1-sc: Single-cell RNA-seq baseline model
import pysynthbio

​
Creating a query

The structure of the query required by the API is specific to each model. Use get_example_query() to get a correctly structured example for your chosen model. 
example_query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
print(example_query)
The query consists of:
  1. sampling_strategy: The prediction mode that controls how expression data is generated
    • "sample generation": Generates realistic-looking synthetic data with measurement error (bulk only)
    • "mean estimation": Provides stable mean estimates of expression levels (bulk and single-cell)
  2. inputs: A list of biological conditions to generate data for
Each input contains metadata describing the biological sample and num_samples for how many samples to generate.

​
Making a prediction

Once your query is ready, send it to the API to generate gene expression data: 
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
result = pysynthbio.predict_query(query, model_id="gem-1-bulk")
The result is a dictionary containing two DataFrames: metadata and expression.

​
Single-cell example

sc_query = pysynthbio.get_example_query(model_id="gem-1-sc")["example_query"]
sc_result = pysynthbio.predict_query(sc_query, model_id="gem-1-sc")
Single-cell models only support "mean estimation" mode.

​
Query parameters

​
sampling_strategy (str, required)

Controls the type of prediction the model generates. Required in all queries. Available modes:
  • "sample generation": The model generates realistic-looking synthetic data that captures measurement error. Useful when you want data that mimics real experimental measurements. Bulk only
  • "mean estimation": The model creates a distribution capturing biological heterogeneity consistent with the supplied metadata, then returns the mean of that distribution. Useful when you want a stable estimate of expected expression levels. Bulk and single-cell
# Bulk query with sample generation
bulk_query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
bulk_query["sampling_strategy"] = "sample generation"

# Bulk query with mean estimation
bulk_query_mean = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
bulk_query_mean["sampling_strategy"] = "mean estimation"

# Single-cell query (must use mean estimation)
sc_query = pysynthbio.get_example_query(model_id="gem-1-sc")["example_query"]
sc_query["sampling_strategy"] = "mean estimation"

​
total_count (int, optional)

Library size used when converting predicted log CPM back to raw counts. Higher values scale counts up proportionally.
  • Default: 10,000,000 for bulk; 10,000 for single-cell
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
query["total_count"] = 5_000_000

​
deterministic_latents (bool, optional)

If True, the model uses the mean of each latent distribution (p(z|metadata)) instead of sampling. This removes randomness from latent sampling and produces deterministic outputs for the same inputs.
  • Default: False
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
query["deterministic_latents"] = True

​
seed (int, optional)

Random seed for reproducibility when using stochastic sampling. 
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
query["seed"] = 42

​
Combining parameters

You can combine multiple parameters in a single query: 
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]
query["total_count"] = 8_000_000
query["deterministic_latents"] = True
query["sampling_strategy"] = "mean estimation"

results = pysynthbio.predict_query(query, model_id="gem-1-bulk")

​
Valid metadata keys

The input metadata is a dictionary. Here are all valid keys.

​
Biological

  • age_years
  • cell_line_ontology_id
  • cell_type_ontology_id
  • developmental_stage
  • disease_ontology_id
  • ethnicity
  • genotype
  • race
  • sample_type: "cell line", "organoid", "other", "primary cells", "primary tissue", "xenograft"
  • sex: "male", "female"
  • tissue_ontology_id

​
Perturbational

  • perturbation_dose: number and unit separated by a space, for example "10 um"
  • perturbation_ontology_id
  • perturbation_time: number and unit separated by a space, for example "24 hours"
  • perturbation_type: one of "coculture", "compound", "control", "crispr", "genetic", "infection", "other", "overexpression", "peptide or biologic", "shrna", "sirna"

​
Technical

  • study: Bioproject ID
  • library_selection: for example "cDNA", "polyA", "Oligo-dT" (see the ENA documentation)
  • library_layout: "PAIRED" or "SINGLE"
  • platform: "illumina"

​
Valid metadata values

The following are the valid values or expected formats for selected metadata keys:
Metadata fieldRequirement / example
cell_line_ontology_idRequires a Cellosaurus ID
cell_type_ontology_idRequires a CL ID
disease_ontology_idRequires a MONDO ID
perturbation_ontology_idMust be a valid Ensembl gene ID, ChEBI ID, ChEMBL ID, or NCBI Taxonomy ID
tissue_ontology_idRequires a UBERON ID
We highly recommend the EMBL-EBI Ontology Lookup Service for finding valid IDs. Models have a limited acceptable range of metadata input values. If you provide a value outside the acceptable range, the API returns an error.

​
Modifying query inputs

Customize the query inputs to fit your specific research needs: 
# Get a base query
query = pysynthbio.get_example_query(model_id="gem-1-bulk")["example_query"]

# Adjust number of samples for the first input
query["inputs"][0]["num_samples"] = 10

# Add a new condition
query["inputs"].append({
    "metadata": {
        "sex": "male",
        "sample_type": "primary tissue",
        "tissue_ontology_id": "UBERON:0002371",
    },
    "num_samples": 5,
})

​
Working with results

# Access metadata and expression matrices
metadata = result["metadata"]
expression = result["expression"]

# Check dimensions
print(expression.shape)

# View metadata sample
print(metadata.head())
You may want to process the data or save it for later use: 
# Save results to files
expression.to_csv("expression_matrix.csv")
metadata.to_csv("sample_metadata.csv")

# Or save as pickle for later use
import pickle
with open("synthesize_results.pkl", "wb") as f:
    pickle.dump(result, f)