# Reference Conditioning

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

    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:

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

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

    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)

    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.

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

    query$deterministic_latents <- TRUE

### seed (integer, optional)

Random seed for reproducibility.

    query$seed <- 42

## Valid Perturbation Metadata

Field | Description / Format
--- | ---
`perturbation_ontology_id` | Ensembl gene ID (e.g., `ENSG00000141510`), ChEBI ID, ChEMBL ID, or NCBI Taxonomy ID
`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:

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

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