BrAPI Connection Class

Details

An R6 Class representing a connection to a BrAPI server.

This Class provides all of the information needed for connecting to a BrAPI server. The host field is required. For all other fields, the default value will be used if one is not provided. Add the is_breedbase=TRUE argument to enable breedbase-specific functions.

This Class also provides helper functions for making requests to the BrAPI server. Use conn$get() to make a GET request, conn$post() to make a POST request, and conn$put() to make a PUT request.

The return value of a request function contains a named list with the properties of the Response(s).

For a singe-page request:

response = the httr response object
status = the parsed HTTP status
content = the full content of the body of the response
metadata = the metadata object from the body of the reponse, if returned
data = the data object from the body of the response, if returned

For a multi-page request (when page="all"):

response = a list of the httr response object by page
status = a list of the parsed HTTP status by page
content = a list of the full content of the body of the response by page
metadata = a list of the metadata object from the body of the response by page, if returned
data = a list of the data object from the body of the response by page, if returned
combined_data = a combined vector of the data from all of the pages, if returned

Public fields

protocol: The HTTP protocol - either 'http' or 'https' (Default: https)
host: The hostname of the BrAPI server
path: The base bath of the BrAPI endpoints (not including the version) (Default: /brapi/)
version: The BrAPI version (such as 'v1' or 'v2') (Default: v2)
is_breedbase: A flag to indicate this BrAPI connection is to a breedbase instance. This adds additional support for breedbase-specific functionality. (Default: FALSE)

Methods

Method `new()`

Create a new BrAPIConnection object

Usage

BrAPIConnection$new(
  host,
  protocol = "https",
  path = "/brapi/",
  version = "v2",
  is_breedbase = FALSE
)

Arguments

host: (required) The hostname of the BrAPI server
protocol: (optional) The HTTP protocol - either 'http' or 'https'
path: (optional) The base path of the BrAPI endpoints
version: (optional) The BrAPI version
is_breedbase: (optional) set to TRUE if the connection is to a breedbase instance

Returns

BrAPIConnection object

Method `get()`

Make a GET request

Usage

BrAPIConnection$get(call, ...)

Arguments

call: The BrAPI endpoint to request
...: (optional) Additional arguments passed to httr
query: (optional) A named list of query parameters
page: (optional) The index of the page of results (use 'all' to get all pages) (Default: 0)
pageSize: (optional) The max size of the result pages (Default: 10)
token: (optional) An Authorization token to add to the request
verbose: (optional) Set to true to include additional output to the console about the Response

Returns

A named list of Response properties

Examples

# Making a GET request
resp <- wheat$get("/germplasm", pageSize=100)
resp <- wheat$get("/studies", pageSize=1000, page="all")
resp <- wheat$get("/studies", query=list(programName="Cornell University"), pageSize=1000)

Method `post()`

Make a POST request

Usage

BrAPIConnection$post(call, ...)

Arguments

call: The BrAPI endpoint to request
...: (optional) Additional arguments passed to httr
query: (optional) A named list of query parameters
body: (optional) A named list or vector of the request body (will be converted to JSON)
page: (optional) The index of the page of results (use 'all' to get all pages) (Default: 0)
pageSize: (optional) The max size of the result pages (Default: 10)
token: (optional) An Authorization token to add to the request
verbose: (optional) Set to true to include additional output to the console about the Response

Returns

A named list of Response properties

Examples

# Make a POST request
\dontrun{
sandbox <- BrAPIConnection$new("wheat-sandbox.triticeaetoolbox.org")
d1 <- list(observationUnitDbId="ou1", observationVariableDbId="ov1", value=50)
d2 <- list(observationUnitDbId="ou2", observationVariableDbId="ov1", value=40)
data <- list(d1, d2)
resp <- sandbox$post("/token", query=list(username="testing", password="testing123"))
resp <- sandbox$post("/observations", body=data, token=resp$content$access_token)
}

Method `put()`

Make a PUT request

Usage

BrAPIConnection$put(call, ...)

Arguments

call: The BrAPI endpoint to request
...: (optional) Additional arguments passed to httr
query: (optional) A named list of query parameters
body: (optional) A named list or vector of the request body (will be converted to JSON)
page: (optional) The index of the page of results (use 'all' to get all pages) (Default: 0)
pageSize: (optional) The max size of the result pages (Default: 10)
token: (optional) An Authorization token to add to the request
verbose: (optional) Set to true to include additional output to the console about the Response

Returns

A named list of Response properties

Method `wizard()`

Make a Breedbase Search Wizard request.

This function returns all of the items of the specified data type, filtered by the data types and items included in the filters argument. For example, you can use this to find all field trials from a set of breeding programs in a specific year. If you don't provide any filters, the function will return the full set of all items in the database for the data type. The results only include the database IDs and names of the matching items. You can use the IDs in the general BrAPI endpoints to get additional data about the items.

Usage

BrAPIConnection$wizard(data_type, filters = list(), verbose = FALSE)

Arguments

data_type

The data type to return after filtering

filters

A list of the filters (up to 3) to apply to the search. The key should be the name of the data type and the value should be a vector of database ids or names of the items to include in the filter.

It is better to use IDs if you have them - when you use names, the function will make additional queries to lookup the IDs for the names you provide.

Supported data types include: accessions, organisms, breeding_programs, genotyping_protocols, genotyping_projects, locations, plants, plots, tissue_sample, seedlots, trait_components, traits, trials, trial_designs, trial_types, years

verbose

Set to TRUE to include logging information

Returns

A response with the matching data. The $content key contains the raw breedbase response. The $data key contains parsed data: a list parsed into ids, names and map (a named list of item names -> ids)

Examples

wheat <- createBrAPIConnection("wheat.triticeaetoolbox.org", is_breedbase = TRUE)

# find matching trials, filtered by two breeding programs (identified by ids) and one year
trials <- wheat$wizard("trials", list(breeding_programs = c(327,367), years = c(2023)))

# find matching accessions, filtered by field trials (identified by name)
accessions <- wheat$wizard("accessions", list(trials = c("CornellMaster_2024_Helfer", "CornellMaster_2025_McGowan")))

# find genotyping protocols that have data for the above set of accessions
geno_protocols <- wheat$wizard("genotyping_protocols", list(accessions = accessions$data$ids))

Method `vcf()`

Download a Breedbase VCF File

NOTE: Depending on the number of markers and accessions, this download may take a very long time to complete. You may want to use the conn$vcf_archived() function to download a static archived VCF file of a genotyping project, if one is available.

Usage

BrAPIConnection$vcf(
  output,
  genotyping_protocol_id,
  accessions = NULL,
  verbose = FALSE
)

Arguments

output: The path to the output VCF file
genotyping_protocol_id: The Database ID of the genotyping protocol to download
accessions: (optional) A list of Accession Database IDs to use as a filter for the VCF data
verbose: Set to TRUE to include logging information

Returns

Status information about the request. If successful, the genotype data will be downloaded to the VCF file specified by the output argument.

Examples

\dontrun{
wheat <- getBrAPIConnection("T3/WheatCAP")
wheat$vcf("~/Desktop/my_data.vcf", genotyping_protocol_id = 249)
wheat$vcf("~/Desktop/my_data.vcf", genotyping_protocol_id = 249, accessions = c(228677, 1666408))
}

Method `vcf_archived()`

Download an Archived Breedbase VCF File

This function will list all of the available archived VCF files available for the specified protocol and/or project. You can select one to download and save to the provided output file.

The archived files are saved at the project-level. So, if you specify a protocol, you'll get a list of all of the available files for each project in that protocol. If you're performing analysis at the protocol-level, you'll need to manually merge the VCF files from each project in that protocol.

Usage

BrAPIConnection$vcf_archived(
  output,
  genotyping_protocol_id = NULL,
  genotyping_project_id = NULL,
  verbose = FALSE
)

Arguments

output: The path to the output VCF file
genotyping_protocol_id: The Database ID of the genotyping protocol
genotyping_project_id: The Database ID of the genotyping project
verbose: Set to TRUE to include logging information

Returns

Status information about the request. If the download of an available archived VCF file is successful, the genotype data will be downloaded to the VCF file specified by the output argument.

Examples

\dontrun{
wheat <- getBrAPIConnection("T3/WheatCAP")
wheat$vcf_archived("~/Desktop/my_data.vcf", genotyping_protocol_id=233)
wheat$vcf_archived("~/Desktop/my_data.vcf", genotyping_project_id=10371)
}

Method `clone()`

The objects of this class are cloneable with this method.

Usage

BrAPIConnection$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

# Directly Creating a new BrAPIConnection Object
wheat <- BrAPIConnection$new("wheat.triticeaetoolbox.org", is_breedbase=TRUE)
wheatv1 <- BrAPIConnection$new("wheat.triticeaetoolbox.org", version="v1")

# Using the createBrAPIConnection function
barley <- createBrAPIConnection("barley.triticeaetoolbox.org")
barleyv1 <- createBrAPIConnection("barley.triticeaetoolbox.org", version="v1")


## ------------------------------------------------
## Method `BrAPIConnection$get`
## ------------------------------------------------

# Making a GET request
resp <- wheat$get("/germplasm", pageSize=100)
resp <- wheat$get("/studies", pageSize=1000, page="all")
resp <- wheat$get("/studies", query=list(programName="Cornell University"), pageSize=1000)

## ------------------------------------------------
## Method `BrAPIConnection$post`
## ------------------------------------------------

# Make a POST request
if (FALSE) { # \dontrun{
sandbox <- BrAPIConnection$new("wheat-sandbox.triticeaetoolbox.org")
d1 <- list(observationUnitDbId="ou1", observationVariableDbId="ov1", value=50)
d2 <- list(observationUnitDbId="ou2", observationVariableDbId="ov1", value=40)
data <- list(d1, d2)
resp <- sandbox$post("/token", query=list(username="testing", password="testing123"))
resp <- sandbox$post("/observations", body=data, token=resp$content$access_token)
} # }


## ------------------------------------------------
## Method `BrAPIConnection$wizard`
## ------------------------------------------------

wheat <- createBrAPIConnection("wheat.triticeaetoolbox.org", is_breedbase = TRUE)

# find matching trials, filtered by two breeding programs (identified by ids) and one year
trials <- wheat$wizard("trials", list(breeding_programs = c(327,367), years = c(2023)))

# find matching accessions, filtered by field trials (identified by name)
accessions <- wheat$wizard("accessions", list(trials = c("CornellMaster_2024_Helfer", "CornellMaster_2025_McGowan")))
#> Warning: There is no matching item of type trials with the name CornellMaster_2024_Helfer
#> Warning: There is no matching item of type trials with the name CornellMaster_2025_McGowan

# find genotyping protocols that have data for the above set of accessions
geno_protocols <- wheat$wizard("genotyping_protocols", list(accessions = accessions$data$ids))

## ------------------------------------------------
## Method `BrAPIConnection$vcf`
## ------------------------------------------------

if (FALSE) { # \dontrun{
wheat <- getBrAPIConnection("T3/WheatCAP")
wheat$vcf("~/Desktop/my_data.vcf", genotyping_protocol_id = 249)
wheat$vcf("~/Desktop/my_data.vcf", genotyping_protocol_id = 249, accessions = c(228677, 1666408))
} # }

## ------------------------------------------------
## Method `BrAPIConnection$vcf_archived`
## ------------------------------------------------

if (FALSE) { # \dontrun{
wheat <- getBrAPIConnection("T3/WheatCAP")
wheat$vcf_archived("~/Desktop/my_data.vcf", genotyping_protocol_id=233)
wheat$vcf_archived("~/Desktop/my_data.vcf", genotyping_project_id=10371)
} # }

BrAPI Connection Class

Details

Public fields

Methods

Public methods

Method new()

Usage

Arguments

Returns

Method get()

Usage

Arguments

Returns

Examples

Method post()

Usage

Arguments

Returns

Examples

Method put()

Usage

Arguments

Returns

Method wizard()

Usage

Arguments

Returns

Examples

Method vcf()

Usage

Arguments

Returns

Examples

Method vcf_archived()

Usage

Arguments

Returns

Examples

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `get()`

Method `post()`

Method `put()`

Method `wizard()`

Method `vcf()`

Method `vcf_archived()`

Method `clone()`