| Title: | Synthesize Bio API Wrapper |
|---|---|
| Description: | Access Synthesize Bio models from their API <https://app.synthesize.bio/> using this wrapper that provides a convenient interface to the 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, single-cell RNA-seq, microarray data, and more. |
| Authors: | Synthesize Bio [aut, cre] |
| Maintainer: | Synthesize Bio <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 4.1.0 |
| Built: | 2026-05-06 17:46:30 UTC |
| Source: | https://github.com/synthesizebio/rsynthbio |
Base URL for the Synthesize Bio API
API_BASE_URLAPI_BASE_URL
An object of class character of length 1.
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.
clear_synthesize_token(remove_from_keyring = FALSE)clear_synthesize_token(remove_from_keyring = FALSE)
remove_from_keyring |
Logical, whether to also remove the token from the system keyring if it's stored there. Defaults to FALSE. |
Invisibly returns TRUE.
## 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)## 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)
Default polling interval (seconds) for async model queries
DEFAULT_POLL_INTERVAL_SECONDSDEFAULT_POLL_INTERVAL_SECONDS
An object of class numeric of length 1.
Default maximum timeout (seconds) for async model queries
DEFAULT_POLL_TIMEOUT_SECONDSDEFAULT_POLL_TIMEOUT_SECONDS
An object of class numeric of length 1.
Default timeout (seconds) for outbound HTTP requests
DEFAULT_TIMEOUTDEFAULT_TIMEOUT
An object of class numeric of length 1.
Retrieves an example query structure for a specific model. This provides a template that can be modified for your specific needs.
get_example_query(model_id, api_base_url = API_BASE_URL)get_example_query(model_id, api_base_url = API_BASE_URL)
model_id |
Character string specifying the model ID (e.g., "gem-1-bulk", "gem-1-sc"). |
api_base_url |
The base URL for the API server. Default is API_BASE_URL. |
A list representing a valid query structure for the specified model.
## Not run: # Get example query for bulk RNA-seq model query <- get_example_query(model_id = "gem-1-bulk")$example_query # Get example query for single-cell model query_sc <- get_example_query(model_id = "gem-1-sc")$example_query # Modify the query structure query$inputs[[1]]$num_samples <- 10 ## End(Not run)## Not run: # Get example query for bulk RNA-seq model query <- get_example_query(model_id = "gem-1-bulk")$example_query # Get example query for single-cell model query_sc <- get_example_query(model_id = "gem-1-sc")$example_query # Modify the query structure query$inputs[[1]]$num_samples <- 10 ## End(Not run)
Checks whether a Synthesize Bio API token is currently set in the environment. Useful for conditional code that requires an API token.
has_synthesize_token()has_synthesize_token()
Logical, TRUE if token is set, FALSE otherwise.
## Not run: # Check if token is set if (!has_synthesize_token()) { # Prompt for token if not set set_synthesize_token() } ## End(Not run)## Not run: # Check if token is set if (!has_synthesize_token()) { # Prompt for token if not set set_synthesize_token() } ## End(Not run)
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().
list_models(api_base_url = API_BASE_URL)list_models(api_base_url = API_BASE_URL)
api_base_url |
The base URL for the API server. Default is API_BASE_URL. |
A list or data frame containing available models with their IDs and metadata.
## Not run: # Get all available models models <- list_models() print(models) ## End(Not run)## Not run: # Get all available models models <- list_models() print(models) ## End(Not run)
Loads the previously stored Synthesize Bio API token from the system keyring and sets it in the environment for the current session.
load_synthesize_token_from_keyring()load_synthesize_token_from_keyring()
Invisibly returns TRUE if successful, FALSE if token not found in keyring.
## Not run: # Load token from keyring load_synthesize_token_from_keyring() ## End(Not run)## Not run: # Load token from keyring load_synthesize_token_from_keyring() ## End(Not run)
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.
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, raw_response = FALSE, ... )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, raw_response = FALSE, ... )
query |
A list representing the query data to send to the API. Use 'get_example_query()' to generate an example. The query supports additional optional fields:
|
model_id |
Character string specifying the model ID (e.g., "gem-1-bulk", "gem-1-sc"). Use 'list_models()' to see available models. |
api_base_url |
The base URL for the API server. Default is API_BASE_URL. |
poll_interval_seconds |
Seconds between polling attempts of the status endpoint. Default is DEFAULT_POLL_INTERVAL_SECONDS (2). |
poll_timeout_seconds |
Maximum total seconds to wait before timing out. Default is DEFAULT_POLL_TIMEOUT_SECONDS (900 = 15 minutes). |
return_download_url |
Logical, if TRUE, returns a list containing the signed download URL instead of parsing into data frames. Default is FALSE. |
raw_response |
Logical, if TRUE, returns the raw (unformatted) JSON response from the API without applying any output transformers. Default is FALSE. |
... |
Additional parameters to include in the query body. These are passed directly to the API and validated server-side. |
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.
# 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")$example_query # 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 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")$example_query # 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)
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.
set_synthesize_token(use_keyring = FALSE, token = NULL)set_synthesize_token(use_keyring = FALSE, token = NULL)
use_keyring |
Logical, whether to also store the token securely in the system keyring for future sessions. Defaults to FALSE. |
token |
Character, optional. If provided, uses this token instead of prompting. This parameter should only be used in non-interactive scripts. |
Invisibly returns TRUE if successful.
# 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)# 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)