> ## 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.

# Reference conditioning

> Generate expression data conditioned on a real reference sample.

## Overview

Reference conditioning models generate expression data **conditioned on a real reference sample**. This allows you to "anchor" to an existing expression profile while applying perturbations or modifications.

This is useful when you want to:

* Simulate the effect of a perturbation on a specific sample
* Generate expression profiles that preserve the biological and technical characteristics of a reference
* Create synthetic "treated vs. control" pairs

## Available Models

* **`gem-1-bulk_reference-conditioning`**: Bulk RNA-seq reference conditioning model
* **`gem-1-sc_reference-conditioning`**: Single-cell RNA-seq reference conditioning model

<Note>
  These endpoints may require 1-2 minutes of startup time if they have been scaled down. Plan accordingly for interactive use.
</Note>

```r theme={null}
library(rsynthbio)
```

## How It Works

Reference conditioning encodes the biological and technical characteristics from a real expression sample, then generates new expression data that:

1. Preserves the biological/technical latent space of the reference
2. Applies any perturbation metadata you specify
3. Returns synthetic expression that reflects the perturbation effect on that specific sample

## Creating a Query

Reference conditioning queries require different inputs than baseline models:

```r theme={null}
# Get the example query structure
example_query <- get_example_query(model_id = "gem-1-bulk_reference-conditioning")$example_query

# Inspect the query structure
str(example_query)
```

The query structure includes:

1. **`inputs`**: A list where each input contains:
   * **`counts`**: The reference expression counts (a numeric vector)
   * **`metadata`**: Perturbation-only metadata (see below)
   * **`num_samples`**: How many samples to generate

2. **`conditioning`**: Which latent spaces to condition on (typically `["biological", "technical"]`)

3. **`sampling_strategy`**: `"mean estimation"` or `"sample generation"`

### Perturbation-Only Metadata

Unlike baseline models, reference conditioning queries only accept perturbation metadata fields:

* `perturbation_ontology_id`
* `perturbation_type`
* `perturbation_time`
* `perturbation_dose`

All other biological and technical metadata is inferred from the reference expression.

## Example: Simulating a Drug Treatment

Here's a complete example simulating a drug treatment effect on a reference sample:

```r theme={null}
# Start with example query structure
query <- get_example_query(model_id = "gem-1-bulk_reference-conditioning")$example_query

# Replace with your actual reference counts
# The counts vector must match the model's expected gene order and length
query$inputs[[1]]$counts <- your_reference_counts

# Specify the perturbation
query$inputs[[1]]$metadata <- list(
  perturbation_ontology_id = "CHEMBL25", # Aspirin (ChEMBL ID)
  perturbation_type = "compound",
  perturbation_time = "24 hours",
  perturbation_dose = "10 um"
)

query$inputs[[1]]$num_samples <- 3

# Set the sampling strategy
query$sampling_strategy <- "mean estimation"

# Submit the query
result <- predict_query(query, model_id = "gem-1-bulk_reference-conditioning")
```

## Example: CRISPR Knockout Simulation

Simulate the effect of knocking out a specific gene:

```r theme={null}
query <- get_example_query(model_id = "gem-1-bulk_reference-conditioning")$example_query

# Your reference sample counts
query$inputs[[1]]$counts <- control_sample_counts

# CRISPR knockout of TP53
query$inputs[[1]]$metadata <- list(
  perturbation_ontology_id = "ENSG00000141510", # TP53 Ensembl ID
  perturbation_type = "crispr"
)

query$inputs[[1]]$num_samples <- 5

result <- predict_query(query, model_id = "gem-1-bulk_reference-conditioning")
```

## Query Parameters

### conditioning (list, optional)

Controls which latent spaces are conditioned on the reference. Default is `["biological", "technical"]`.

When both are conditioned, the model preserves both biological identity and technical characteristics from the reference sample.

### sampling\_strategy (character, required)

Controls the type of prediction:

* **"sample generation"**: Generates realistic-looking synthetic data with measurement error. **(Bulk only)**
* **"mean estimation"**: Provides stable mean estimates. **(Bulk and single-cell)**

```r theme={null}
query$sampling_strategy <- "mean estimation"
```

### fixed\_total\_count (logical, optional)

Controls whether to preserve the reference's library size:

* **`FALSE`** (default): The output's total count is taken from the reference expression (sum of its counts). Use this when you want the synthetic sample to preserve the reference's library size.
* **`TRUE`**: Forces the model to use the `total_count` parameter value (or default) instead of the reference's library size.

```r theme={null}
# Preserve reference library size (default)
query$fixed_total_count <- FALSE

# Or force a specific library size
query$fixed_total_count <- TRUE
query$total_count <- 10000000
```

### total\_count (integer, optional)

Library size used when converting predicted log CPM back to raw counts. Only effective when `fixed_total_count = TRUE`.

* Default: 10,000,000 for bulk; 10,000 for single-cell

### deterministic\_latents (logical, optional)

If `TRUE`, the model uses the mean of each latent distribution (`p(z|metadata)` for perturbation, `q(z|x)` for conditioned components) instead of sampling. This produces deterministic, reproducible outputs.

* Default: `FALSE`

```r theme={null}
query$deterministic_latents <- TRUE
```

### seed (integer, optional)

Random seed for reproducibility.

```r theme={null}
query$seed <- 42
```

## Valid Perturbation Metadata

| Field                      | Description / Format                                                                                                                                                                          |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `perturbation_ontology_id` | Ensembl gene ID (e.g., `ENSG00000141510`), [ChEBI ID](https://www.ebi.ac.uk/chebi/), [ChEMBL ID](https://www.ebi.ac.uk/chembl/), or [NCBI Taxonomy ID](https://www.ncbi.nlm.nih.gov/taxonomy) |
| `perturbation_type`        | One of: "coculture", "compound", "control", "crispr", "genetic", "infection", "other", "overexpression", "peptide or biologic", "shrna", "sirna"                                              |
| `perturbation_time`        | Time since perturbation, as a number and unit separated by a space (e.g., "24 hours", "48 hours")                                                                                             |
| `perturbation_dose`        | Dose of perturbation, as a number and unit separated by a space (e.g., "10 um", "1 mg/kg")                                                                                                    |

## Working with Results

The result structure is similar to baseline models:

```r theme={null}
# Access metadata and expression matrices
metadata <- result$metadata
expression <- result$expression

# Compare to your reference
dim(expression)
head(metadata)
```

### Differential Expression

When conditioning on both biological and technical latents, you can directly compare the generated expression to your reference to identify perturbation effects:

```r theme={null}
# Your reference (input) counts
reference_cpm <- your_reference_counts / sum(your_reference_counts) * 1e6

# Generated (perturbed) counts
generated_cpm <- expression[1, ] / sum(expression[1, ]) * 1e6

# Log fold change
log2fc <- log2(generated_cpm + 1) - log2(reference_cpm + 1)

# Identify top changed genes
head(sort(log2fc, decreasing = TRUE), 20)
```

## Important Notes

### Counts Vector Length

The reference counts vector must match the model's expected number of genes. If the length doesn't match, the API will return a validation error.

Use `get_example_query()` to see the expected structure and ensure your counts vector has the correct length.

### Gene Order

Ensure your reference counts are in the same gene order expected by the model. The response includes a `gene_order` field that specifies the expected order.