API Base URL

Description

Base URL for the Synthesize Bio API

Usage

API_BASE_URL

Format

An object of class character of length 1.

Default Poll Interval

Description

Default polling interval (seconds) for async model queries

Usage

DEFAULT_POLL_INTERVAL_SECONDS

Format

An object of class numeric of length 1.

Default Poll Timeout

Description

Default maximum timeout (seconds) for async model queries

Usage

DEFAULT_POLL_TIMEOUT_SECONDS

Format

An object of class numeric of length 1.

Default Timeout

Description

Default timeout (seconds) for outbound HTTP requests

Usage

DEFAULT_TIMEOUT

Format

An object of class numeric of length 1.

Output Transformer Registry

Description

A registry mapping model IDs to their corresponding output transformer functions. Models not in the registry will use the default standard transformer.

Usage

OUTPUT_TRANSFORMERS

Format

An object of class list of length 4.

Clear Synthesize Bio API Token

Description

Clears the Synthesize Bio API token from the environment for the current R session. This is useful for security purposes when you've finished working with the API or when switching between different accounts.

Usage

clear_synthesize_token(remove_from_keyring = FALSE)

Arguments

Value

Invisibly returns TRUE.

Examples

## Not run: 
# Clear token from current session only
clear_synthesize_token()

# Clear token from both session and keyring
clear_synthesize_token(remove_from_keyring = TRUE)

## End(Not run)

Transform Metadata Model Output (Internal)

Description

Default output transformer, does not modify the response from the server.

Usage

default_output_transformer(final_json)

Arguments

Value

the same final_json

Get Example Query for Model

Description

Retrieves an example query structure for a specific model. This provides a template that can be modified for your specific needs.

Usage

get_example_query(model_id, api_base_url = API_BASE_URL)

Arguments

Value

A list representing a valid query structure for the specified model.

Examples

## Not run: 
# Get example query for bulk RNA-seq model
query <- get_example_query(model_id = "gem-1-bulk")

# Get example query for single-cell model
query_sc <- get_example_query(model_id = "gem-1-sc")

# Modify the query structure
query$inputs[[1]]$num_samples <- 10

## End(Not run)

Get JSON from URL

Description

Internal function to fetch JSON from a URL

Usage

get_json(url)

Arguments

Value

The parsed JSON content

Get Output Transformer for Model (Internal)

Description

Looks up the appropriate output transformer for a given model ID. Returns the standard transformer as the default if no specific transformer is registered.

Usage

get_output_transformer(model_id)

Arguments

Value

A transformer function that accepts (final_json) and returns a list with metadata, expression, and optionally latents

Check if Synthesize Bio API Token is Set

Description

Checks whether a Synthesize Bio API token is currently set in the environment. Useful for conditional code that requires an API token.

Usage

has_synthesize_token()

Value

Logical, TRUE if token is set, FALSE otherwise.

Examples

 ## Not run: 
# Check if token is set
if (!has_synthesize_token()) {
  # Prompt for token if not set
  set_synthesize_token()
}

## End(Not run)

List Available Models

Description

Returns a list of all models available in the Synthesize Bio API. Each model has a unique ID that can be used with predict_query() and get_example_query().

Usage

list_models(api_base_url = API_BASE_URL)

Arguments

Value

A list or data frame containing available models with their IDs and metadata.

Examples

## Not run: 
# Get all available models
models <- list_models()
print(models)

## End(Not run)

Load Synthesize Bio API Token from Keyring

Description

Loads the previously stored Synthesize Bio API token from the system keyring and sets it in the environment for the current session.

Usage

load_synthesize_token_from_keyring()

Value

Invisibly returns TRUE if successful, FALSE if token not found in keyring.

Examples

## Not run: 
# Load token from keyring
load_synthesize_token_from_keyring()

## End(Not run)

Make Authenticated API Request

Description

Internal helper to make authenticated GET requests

Usage

make_api_request(url, context_msg)

Arguments

Value

The parsed JSON content

Poll Model Query

Description

Internal function to poll the status endpoint until ready/failed or timeout

Usage

poll_model_query(api_base_url, model_query_id, poll_interval, timeout_seconds)

Arguments

Value

A list with status and payload

Predict Gene Expression

Description

Sends a query to the Synthesize Bio API for prediction and retrieves gene expression samples. This function sends the query to the API and processes the response into usable data frames.

Usage

predict_query(
  query,
  model_id,
  api_base_url = API_BASE_URL,
  poll_interval_seconds = DEFAULT_POLL_INTERVAL_SECONDS,
  poll_timeout_seconds = DEFAULT_POLL_TIMEOUT_SECONDS,
  return_download_url = FALSE
)

Arguments

Value

A list. If 'return_download_url' is 'FALSE' (default), the list contains two data frames: 'metadata' and 'expression'. If 'TRUE', the list contains 'download_url' and empty 'metadata' and 'expression' data frames.

Examples

# Set your API key (in practice, use a more secure method)
## Not run: 

# To start using rsynthbio, first you need to have an account with synthesize.bio.
# Go here to create one: https://app.synthesize.bio/

set_synthesize_token()

# Get available models
models <- list_models()

# Create a query for a specific model
query <- get_example_query(model_id = "gem-1-bulk")

# Request raw counts
result <- predict_query(query, model_id = "gem-1-bulk")

# Access the results
metadata <- result$metadata
expression <- result$expression

# Explore the top expressed genes in the first sample
head(sort(expression[1, ], decreasing = TRUE))

# Use deterministic latents for reproducible results
query$deterministic_latents <- TRUE
result_det <- predict_query(query, model_id = "gem-1-bulk")

# Specify a custom total count (library size)
query$total_count <- 5000000
result_custom <- predict_query(query, model_id = "gem-1-bulk")

## End(Not run)

Set Synthesize Bio API Token

Description

Securely prompts for and stores the Synthesize Bio API token in the environment. This function uses getPass to securely handle the token input without displaying it in the console. The token is stored in the SYNTHESIZE_API_KEY environment variable for the current R session.

Usage

set_synthesize_token(use_keyring = FALSE, token = NULL)

Arguments

Value

Invisibly returns TRUE if successful.

Examples

# Interactive prompt for token
## Not run: 
set_synthesize_token()

# Provide token directly (less secure, not recommended for interactive use)
set_synthesize_token(token = "your-token-here")

# Store in system keyring for future sessions
set_synthesize_token(use_keyring = TRUE)

## End(Not run)

Start Model Query

Description

Internal function to start an async model query

Usage

start_model_query(api_base_url, model_id, query)

Arguments

Value

The model query ID

Transform Standard Model Output (Internal)

Description

Extracts and combines gene expression data from a standard API response (e.g., gem-1-bulk, gem-1-sc models).

Usage

transform_baseline_output(final_json)

Arguments

Value

A list with: - metadata: data.frame containing sample metadata - expression: data.frame containing combined gene expression data - latents: data.frame containing embeddings (if requested)