Package 'brapiR2'

Description

Retrieves genotype calls from the ⁠/allelematrix⁠ endpoint and returns a tidy tibble with one row per (variant, callSet) combination. The ⁠/allelematrix⁠ response has a unique structure (2-D pagination, no result$data envelope) so it cannot use the generic brapi_get().

Usage

brapi_allele_matrix(con, variantSetDbId = NULL, ...)

Arguments

Value

A tibble with columns variantDbId, callSetDbId, genotype.

BrAPI endpoint

GET /allelematrix - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

dimensionVariantPage, dimensionVariantPageSize, dimensionCallSetPage, dimensionCallSetPageSize.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_allele_matrix(con, variantSetDbId = "variantset1")
}

Description

Removes all cached responses from the cache directory.

Usage

brapi_cache_clear(con)

Arguments

Value

Invisibly returns con.

Examples

con <- brapi_connection("https://test-server.brapi.org")
con <- brapi_cache_enable(con, dir = tempdir())
brapi_cache_clear(con)

Description

Returns a new connection object with caching enabled. Cached responses are stored as JSON files in the specified directory, keyed by URL and query parameters.

Usage

brapi_cache_enable(con, dir = NULL, ttl = 3600)

Arguments

Value

A new brapi_con object with caching configured.

Examples

con <- brapi_connection("https://test-server.brapi.org")
con <- brapi_cache_enable(con, dir = tempdir(), ttl = 7200)
con

Description

List Call Sets (Samples with Genotype Data)

Usage

brapi_call_sets(con, ...)

Arguments

Value

A tibble with one row per call set.

BrAPI endpoint

GET /callsets - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

callSetDbId, callSetName, variantSetDbId, sampleDbId.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_call_sets(con)
}

Description

List Genotype Calls

Usage

brapi_calls(con, variantSetDbId = NULL, ...)

Arguments

Value

A tibble with one row per genotype call.

BrAPI endpoint

GET /calls - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

callSetDbId, variantDbId, variantSetDbId, expandHomozygotes, unknownString, sepPhased, sepUnphased.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_calls(con, variantSetDbId = "variantset1")
}

Description

Creates a connection object that holds server URL, authentication token, and configuration. This object is passed as the first argument to all brapiR2 functions. No global state is used.

Usage

brapi_connection(
  url,
  token = NULL,
  version = "v2",
  path = "brapi",
  user_agent = NULL,
  page_size = 1000L,
  timeout = 120
)

Arguments

Value

An S3 object of class "brapi_con" (a named list).

Examples

# Connect to the public BrAPI test server (no auth needed)
con <- brapi_connection("https://test-server.brapi.org")
con

# Connect with an existing token
con <- brapi_connection("https://my-breedbase.org", token = "my_token_here")

# Connect to a server that serves BrAPI under a different path
con <- brapi_connection("https://npgsweb.ars-grin.gov",
                        path = "gringlobal/brapi")

Description

List Crosses

Usage

brapi_crosses(con, ...)

Arguments

Value

A tibble with one row per cross.

BrAPI endpoint

GET /crosses - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

crossingProjectDbId, crossingProjectName, crossDbId, crossName.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_crosses(con)
}

Description

List Crossing Projects

Usage

brapi_crossing_projects(con, ...)

Arguments

Value

A tibble with one row per crossing project.

BrAPI endpoint

GET /crossingprojects - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

crossingProjectDbId, crossingProjectName, includePotentialParents.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_crossing_projects(con)
}

Description

Queries the ⁠/serverinfo⁠ endpoint to list which BrAPI calls the server supports, along with their HTTP methods and versions.

Usage

brapi_endpoints(con)

Arguments

Value

A tibble with columns for endpoint service, method(s), and version(s).

BrAPI endpoint

GET /serverinfo - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

contentType, dataType.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_endpoints(con)
}

Description

List Events

Usage

brapi_events(con, studyDbId = NULL, ...)

Arguments

Value

A tibble with one row per event.

BrAPI endpoint

GET /events - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

observationUnitDbId, eventDbId, eventType, dateRangeStart, dateRangeEnd.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_events(con, studyDbId = "study1")
}

Description

Fetches data from multiple BrAPI endpoints or IDs in parallel using the furrr package. Useful for retrieving data across many studies, trials, or germplasm records simultaneously.

Usage

brapi_fetch_parallel(con, .fn, ids, .workers = NULL, ...)

Arguments

Details

This function uses whatever future plan is already active when it is called, and does not set or restore one itself. If you have not called future::plan(), furrr::future_map_dfr() falls back to future::sequential, so nothing runs in parallel until you set a plan yourself - call future::plan(future::multisession, workers = N) before this function to fetch in parallel, and future::plan(future::sequential) afterwards to shut the workers back down. Per the future package's best-practices vignette, choosing the parallel backend is the caller's decision: a package that sets and restores a plan on every call still mutates session-wide state the caller did not ask it to touch, and can silently replace a backend they configured deliberately.

Value

A tibble with results from all IDs combined.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  study_ids <- c("study1", "study2", "study3")

  # Set the parallel backend yourself before calling; brapi_fetch_parallel()
  # uses whatever plan is active rather than setting one for you.
  future::plan(future::multisession, workers = 2)
  all_data <- brapi_fetch_parallel(con, brapi_study_data, study_ids)
  future::plan(future::sequential) # shut the workers back down when done
}

Description

List Germplasm

Usage

brapi_germplasm(con, ...)

Arguments

Value

A tibble with one row per germplasm accession.

BrAPI endpoint

GET /germplasm - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

accessionNumber, collection, binomialName, genus, species, synonym, parentDbId, progenyDbId.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_germplasm(con)
}

Description

List Germplasm Attributes

Usage

brapi_germplasm_attributes(con, ...)

Arguments

Value

A tibble with one row per attribute definition.

BrAPI endpoint

GET /attributes - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

attributeCategory, attributeDbId, attributeName, attributePUI.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_germplasm_attributes(con)
}

Description

Get a Single Germplasm by ID

Usage

brapi_germplasm_detail(con, germplasmDbId)

Arguments

Value

A single-row tibble with germplasm details.

BrAPI endpoint

GET /germplasm/{germplasmDbId} - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_germplasm_detail(con, "germplasm1")
}

Description

The ⁠/germplasm/{germplasmDbId}/pedigree⁠ endpoint this function originally called was deprecated in BrAPI v2.1. It now queries ⁠/pedigree?germplasmDbId=⁠ instead, which returns a richer record.

Usage

brapi_germplasm_pedigree(con, germplasmDbId)

Arguments

Value

A single-row tibble of the germplasm's pedigree node, with parents, siblings and progeny as list-columns of tidy tibbles. See brapi_pedigree(), which this function calls.

BrAPI endpoint

GET /pedigree - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

accessionNumber, collection, familyCode, binomialName, genus, species, synonym, includeParents, includeSiblings, includeProgeny, includeFullTree, pedigreeDepth, progenyDepth.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_germplasm_pedigree(con, "germplasm1")
}

Description

Get Germplasm Progeny

Usage

brapi_germplasm_progeny(con, germplasmDbId)

Arguments

Value

A single-row tibble of the germplasm's pedigree node, with progeny as a list-column of a tidy tibble of descendants. See brapi_pedigree(), which this function calls.

BrAPI endpoint

GET /pedigree - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

accessionNumber, collection, familyCode, binomialName, genus, species, synonym, includeParents, includeSiblings, includeProgeny, includeFullTree, pedigreeDepth, progenyDepth.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_germplasm_progeny(con, "germplasm1")
}

Description

The named functions in brapiR2 cover 32 of the 36 BrAPI v2.1 entities. This is the layer beneath them, for endpoints brapiR2 does not wrap, for servers with non-standard extensions, and for query parameters a named function does not expose. Pagination, caching, authentication and error reporting work exactly as they do for the named functions.

Usage

brapi_get(con, endpoint, query = list(), max_pages = Inf)

Arguments

Value

A tibble of results, or an empty tibble if the endpoint returned no data.

Return shape

The response passes through the same parser the named functions use, so a well-formed BrAPI collection returns one row per record. An endpoint returning something the parser does not recognise may come back with list-columns or a shape you need to reshape yourself. The named functions are the better choice wherever one exists.

See Also

brapi_post_search() for the POST search endpoints.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {

  # An endpoint brapiR2 does not wrap
  brapi_get(con, "/commoncropnames")

  # A query parameter no named function exposes
  brapi_get(con, "/studies", query = list(active = "true"))
}

Description

Fetches genotype data from a BrAPI server and converts it into a numeric dosage matrix (samples × markers) compatible with genomic selection packages like rrBLUP, BGLR, and sommer.

Usage

brapi_get_dosage_matrix(con, variantSetDbId, sep = "/", unknown_string = ".")

Arguments

Details

Allele dosage is computed by splitting each genotype string on sep (or "|" for phased calls) and counting how many alleles are non-reference (i.e. not "0"). Missing calls (unknown_string, ".", or "") become NA.

Value

A numeric matrix: rows = samples (callSetDbIds), columns = markers (variantDbIds). Values are integer dosages (0, 1, 2 for diploids; 0–N for polyploids). Missing calls are NA.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  dosage <- brapi_get_dosage_matrix(con, "variantset1")
  dim(dosage)
  # Use with rrBLUP:
  # library(rrBLUP)
  # result <- mixed.solve(y = pheno$yield, Z = dosage)
}

Description

Convenience function that retrieves marker positions on a genome map as a tidy tibble. Positions come from the Genome Maps entity (brapi_marker_positions() / ⁠/markerpositions⁠), which places a marker on a named brapi_map() - genetic (cM) or physical (bp), per the map's type and unit - not from brapi_variants()'s start/referenceName, which places a variant on a reference assembly instead. A server may populate either, both, or neither; the two are independent coordinate systems, not duplicates of each other.

Usage

brapi_get_marker_map(con, variantSetDbId = NULL, mapDbId = NULL)

Arguments

Details

Supply exactly one of mapDbId (every marker placed on that one map) or variantSetDbId (positions for every variant in that set, wherever they have been placed). The variantSetDbId path looks variant IDs up first via brapi_variants(), then retrieves their positions in one call via brapi_search_marker_positions() rather than the GET ⁠/markerpositions⁠ filter, which only accepts a single variantDbId.

If a marker is placed on more than one map, it contributes one row per placement - the result is never collapsed to one row per marker.

Value

A tibble with columns variantDbId, variantName, mapDbId, mapName, type, unit, linkageGroupName, and position - one row per marker-map placement, so a marker on several maps appears more than once. type and unit are joined in from brapi_maps() so a caller can tell a genetic (cM) map from a physical (bp) one.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_get_marker_map(con, mapDbId = "genome_map1")
  brapi_get_marker_map(con, variantSetDbId = "variantset1")
}

Description

List Images

Usage

brapi_images(con, ...)

Arguments

Value

A tibble with one row per image record.

BrAPI endpoint

GET /images - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

imageDbId, imageName, observationUnitDbId, observationDbId, descriptiveOntologyTerm.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_images(con)
}

Description

Unlike brapi_lists(), which returns only list metadata, this returns a single list together with its members in the data list-column. listType says what the members are (for example "germplasm").

Usage

brapi_list(con, listDbId)

Arguments

Value

A single-row tibble of list metadata, with the list's members as a character vector in the data list-column.

BrAPI endpoint

GET /lists/{listDbId} - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  lst <- brapi_list(con, "list1")
  lst$data[[1]]
}

Description

List Generic Lists

Usage

brapi_lists(con, ...)

Arguments

Value

A tibble with one row per list.

BrAPI endpoint

GET /lists - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

listType, listName, listDbId, listSource.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_lists(con)
}

Description

Get a Single Location by ID

Usage

brapi_location(con, locationDbId)

Arguments

Value

A single-row tibble with location metadata, including coordinates where the server provides them.

BrAPI endpoint

GET /locations/{locationDbId} - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_location(con, "location_01")
}

Description

List Locations

Usage

brapi_locations(con, ...)

Arguments

Value

A tibble with one row per location.

BrAPI endpoint

GET /locations - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

locationType, locationDbId, locationName, parentLocationDbId, parentLocationName.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_locations(con)
}

Description

Authenticates using the BrAPI ⁠/token⁠ endpoint and returns an updated connection object with the Bearer token set.

Usage

brapi_login(con, username, password)

Arguments

Value

A new brapi_con object with the token populated.

See Also

The "Handling Credentials Safely" section of vignette("brapiR2") for how to keep username/password out of your script, using .Renviron or the keyring package.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  con <- brapi_login(con, "brapi_reader", "brapi_reader")
  con
}

Description

Performs an OAuth 2.0 authorization code flow or client credentials flow. Returns an updated connection object with the Bearer token set.

Usage

brapi_login_oauth2(con, client_id, client_secret, authorize_url, access_url)

Arguments

Value

A new brapi_con object with the token populated.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  con <- brapi_login_oauth2(
    con,
    client_id = "brapi_client",
    client_secret = "brapi_secret",
    authorize_url = "https://test-server.brapi.org/brapi/v2/authorize",
    access_url = "https://test-server.brapi.org/brapi/v2/token"
  )
  con
}

Description

Get a Single Genome Map by ID

Usage

brapi_map(con, mapDbId)

Arguments

Value

A single-row tibble with genome map details, including type (e.g. "Genetic" or "Physical") and unit (e.g. "cM" or "bp").

BrAPI endpoint

GET /maps/{mapDbId} - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_map(con, "genome_map1")
}

Description

A linkage group is BrAPI's generic term for a named section of a map - it may represent a chromosome, a scaffold, or a generic linkage group.

Usage

brapi_map_linkage_groups(con, mapDbId)

Arguments

Value

A tibble with one row per linkage group on the map.

BrAPI endpoint

GET /maps/{mapDbId}/linkagegroups - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_map_linkage_groups(con, "genome_map1")
}

Description

List Genome Maps

Usage

brapi_maps(con, ...)

Arguments

Value

A tibble with one row per genome map.

BrAPI endpoint

GET /maps - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

mapDbId, mapPUI, scientificName, type.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_maps(con)
}

Description

Retrieves marker placements on genome maps from ⁠/markerpositions⁠. A position here is relative to a named brapi_map() (genetic, in cM, or physical, in bp) - a different coordinate system from brapi_variants()'s start/referenceName, which places a variant on a reference assembly instead. A server may populate either, both, or neither; one being empty does not imply the other is.

Usage

brapi_marker_positions(
  con,
  mapDbId = NULL,
  variantDbId = NULL,
  linkageGroupName = NULL,
  minPosition = NULL,
  maxPosition = NULL,
  ...
)

Arguments

Value

A tibble with one row per marker placement.

BrAPI endpoint

GET /markerpositions - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

mapDbId, linkageGroupName, variantDbId, minPosition, maxPosition.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_marker_positions(con, mapDbId = "genome_map1")
}

Description

List Methods

Usage

brapi_methods(con, ...)

Arguments

Value

A tibble with one row per measurement method.

BrAPI endpoint

GET /methods - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

methodDbId, observationVariableDbId.

See Also

brapi_ontologies() and brapi_ontology() to resolve the ontology a method's ontologyDbId/ontologyReference points to.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_methods(con)
}

Description

List Observation Units

Usage

brapi_observation_units(con, studyDbId = NULL, ...)

Arguments

Value

A tibble with one row per observation unit (plot/plant/sample).

BrAPI endpoint

GET /observationunits - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

observationUnitDbId, observationUnitName, locationDbId, seasonDbId, includeObservations.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_observation_units(con, studyDbId = "study1")
}

Description

Returns the ontology of observation variables (trait + method + scale).

Usage

brapi_observation_variables(con, ...)

Arguments

Value

A tibble with one row per variable definition.

BrAPI endpoint

GET /variables - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

observationVariableDbId, observationVariableName, observationVariablePUI, traitClass.

See Also

brapi_ontologies() and brapi_ontology() to resolve the ontology a variable's ontologyDbId/ontologyReference points to.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_observation_variables(con)
}

Description

List Observations

Usage

brapi_observations(con, studyDbId = NULL, ...)

Arguments

Value

A tibble with one row per observation (trait measurement).

BrAPI endpoint

GET /observations - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

observationDbId, observationUnitDbId, observationVariableDbId, locationDbId, seasonDbId, observationTimeStampRangeStart, observationTimeStampRangeEnd.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_observations(con, studyDbId = "study1")
}

Description

Retrieves the ontologies registered on the server: metadata about each ontology (name, version, authors, description, ...), not the trait terms that belong to it. brapi_traits(), brapi_scales(), brapi_methods(), and brapi_observation_variables() each carry an ontology reference back to one of these records.

Usage

brapi_ontologies(con, ...)

Arguments

Value

A tibble with one row per ontology.

BrAPI endpoint

GET /ontologies - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

ontologyName.

See Also

brapi_ontology() for a single ontology by ID; brapi_traits(), brapi_scales(), brapi_methods(), and brapi_observation_variables() for the records that reference these ontologies.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_ontologies(con)
}

Description

Get a Single Ontology by ID

Usage

brapi_ontology(con, ontologyDbId)

Arguments

Value

A single-row tibble with ontology details.

BrAPI endpoint

GET /ontologies/{ontologyDbId} - see the v2.1 specification.

See Also

brapi_ontologies(); brapi_traits(), brapi_scales(), brapi_methods(), and brapi_observation_variables() for the records that reference ontologies.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_ontology(con, "O_001")
}

Description

Retrieves a filtered subset of a pedigree tree via ⁠/pedigree⁠ - a batch endpoint for pulling pedigree records across many germplasm in one call. This is different from brapi_germplasm_pedigree(), which retrieves one germplasm's immediate pedigree via the germplasm sub-resource (⁠/germplasm/{germplasmDbId}/pedigree⁠) and must be called once per germplasm. Use brapi_pedigree() (or brapi_search_pedigree()) to pull pedigree records for many germplasm at once - e.g. everything in a crop, program, or family - in one or a few requests; use brapi_germplasm_pedigree() when you already have a single germplasm ID in hand.

Usage

brapi_pedigree(
  con,
  germplasmDbId = NULL,
  includeParents = NULL,
  includeSiblings = NULL,
  includeProgeny = NULL,
  includeFullTree = NULL,
  pedigreeDepth = NULL,
  progenyDepth = NULL,
  ...
)

Arguments

Details

Each row is one pedigree node (one germplasm). The server only includes a node's relatives if asked: set includeParents, includeSiblings, and/or includeProgeny to TRUE to populate the parents, siblings, and progeny list-columns, each holding a small tibble of related germplasm (germplasmDbId, germplasmName, and parentType - NA for siblings, which have none) that you can tidyr::unnest() when you need one row per relationship rather than one row per node. Nodes are never collapsed or flattened by default: a pedigree is graph-shaped (each node has its own parents, siblings, and progeny edges), and the three relation types don't share a common row shape, so there is no lossless single flat table to fall back to.

Value

A tibble with one row per pedigree node. parents, siblings, and progeny, when requested, are list-columns of small tibbles (one row per relative) rather than raw nested lists or a flattened table.

BrAPI endpoint

GET /pedigree - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

accessionNumber, collection, familyCode, binomialName, genus, species, synonym, includeParents, includeSiblings, includeProgeny, includeFullTree, pedigreeDepth, progenyDepth.

See Also

brapi_germplasm_pedigree() for one germplasm's pedigree via the germplasm sub-resource; brapi_search_pedigree() for the same batch retrieval via POST, with a fuller set of filters.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_pedigree(con, includeParents = TRUE, includeProgeny = TRUE)
}

Description

List People

Usage

brapi_people(con, ...)

Arguments

Value

A tibble with one row per person.

BrAPI endpoint

GET /people - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

firstName, lastName, personDbId, userID.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_people(con)
}

Description

Tests whether the BrAPI server is reachable and responding.

Usage

brapi_ping(con)

Arguments

Value

Logical. TRUE if the server responds, FALSE otherwise.

BrAPI endpoint

GET /serverinfo - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

contentType, dataType.

Examples

con <- brapi_connection("https://test-server.brapi.org")
brapi_ping(con)

Description

The companion to brapi_get() for the POST ⁠/search/{entity}⁠ endpoints, which take a filter body rather than query parameters and may run asynchronously. Use it for search endpoints brapiR2 does not wrap, or for filter fields a named search function does not expose.

Usage

brapi_post_search(
  con,
  endpoint,
  body = list(),
  poll_interval = 2,
  max_polls = 30L
)

Arguments

Value

A tibble of search results.

Asynchronous searches

A server may answer immediately with the results, or with HTTP 202 and a searchResultsDbId to be polled until the results are ready. Both are handled here; the polling happens inside the call and you get the finished results either way.

Return shape

As with brapi_get(), the response passes through the same parser the named functions use. A well-formed BrAPI result returns one row per record; an unusual one may need reshaping yourself.

See Also

brapi_get() for the GET endpoints.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_post_search(con, "/search/germplasm",
                    body = list(germplasmNames = "Tomatillo Fantastico"))
}

Description

Get a Single Program by ID

Usage

brapi_program(con, programDbId)

Arguments

Value

A single-row tibble with program details.

BrAPI endpoint

GET /programs/{programDbId} - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_program(con, "program1")
}

Description

Retrieves a list of breeding programs from the BrAPI server.

Usage

brapi_programs(con, ...)

Arguments

Value

A tibble with one row per program.

BrAPI endpoint

GET /programs - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

abbreviation, programType.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_programs(con)
  brapi_programs(con, commonCropName = "rice")
}

Description

List Reference Sets (Genome Assemblies)

Usage

brapi_reference_sets(con, ...)

Arguments

Value

A tibble with one row per reference set.

BrAPI endpoint

GET /referencesets - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

referenceSetDbId, accession, assemblyPUI, md5checksum.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_reference_sets(con)
}

Description

List References (Chromosomes/Contigs)

Usage

brapi_references(con, ...)

Arguments

Value

A tibble with one row per reference sequence.

BrAPI endpoint

GET /references - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

referenceDbId, referenceSetDbId, accession, md5checksum, isDerived, minLength, maxLength.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_references(con)
}

Description

List Samples

Usage

brapi_samples(con, ...)

Arguments

Value

A tibble with one row per sample.

BrAPI endpoint

GET /samples - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

sampleDbId, sampleName, sampleGroupDbId, observationUnitDbId, plateDbId, plateName.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_samples(con)
}

Description

List Scales

Usage

brapi_scales(con, ...)

Arguments

Value

A tibble with one row per scale definition.

BrAPI endpoint

GET /scales - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

scaleDbId, observationVariableDbId.

See Also

brapi_ontologies() and brapi_ontology() to resolve the ontology a scale's ontologyDbId/ontologyReference points to.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_scales(con)
}

Description

Search Genotype Calls

Usage

brapi_search_calls(con, variantSetDbIds = NULL, callSetDbIds = NULL, ...)

Arguments

Value

A tibble of matching genotype calls.

BrAPI endpoint

POST /search/calls - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_search_calls(con, variantSetDbIds = "variantset1")
}

Description

Performs a BrAPI search for germplasm records matching the given criteria.

Usage

brapi_search_germplasm(
  con,
  germplasmNames = NULL,
  germplasmDbIds = NULL,
  commonCropNames = NULL,
  ...
)

Arguments

Value

A tibble of matching germplasm records.

BrAPI endpoint

POST /search/germplasm - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_search_germplasm(con, commonCropNames = "Tomatillo")
}

Description

The ⁠/markerpositions⁠ GET filter (see brapi_marker_positions()) takes a single variantDbId; this search endpoint accepts many IDs at once, which is what brapi_get_marker_map() uses internally when looking up positions for an entire variant set.

Usage

brapi_search_marker_positions(
  con,
  mapDbIds = NULL,
  variantDbIds = NULL,
  linkageGroupNames = NULL,
  minPosition = NULL,
  maxPosition = NULL,
  ...
)

Arguments

Value

A tibble of matching marker positions.

BrAPI endpoint

POST /search/markerpositions - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_search_marker_positions(con, variantDbIds = c("variant01", "variant02"))
}

Description

Search Observations

Usage

brapi_search_observations(
  con,
  studyDbIds = NULL,
  observationVariableDbIds = NULL,
  ...
)

Arguments

Value

A tibble of matching observations.

BrAPI endpoint

POST /search/observations - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_search_observations(con, studyDbIds = "study1")
}

Description

The POST equivalent of brapi_pedigree(), taking the same tree-shaping parameters plus the fuller set of filters ⁠/search/pedigree⁠ accepts (crop, program, trial, study, accession number, collection, family code, genus/species, and more - pass any of these through ...). See brapi_pedigree() for the shape of the returned tibble and its relationship to brapi_germplasm_pedigree().

Usage

brapi_search_pedigree(
  con,
  germplasmDbIds = NULL,
  includeParents = NULL,
  includeSiblings = NULL,
  includeProgeny = NULL,
  includeFullTree = NULL,
  pedigreeDepth = NULL,
  progenyDepth = NULL,
  ...
)

Arguments

Value

A tibble with one row per pedigree node; see brapi_pedigree() for column details.

BrAPI endpoint

POST /search/pedigree - see the v2.1 specification.

See Also

brapi_pedigree(), brapi_germplasm_pedigree()

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_search_pedigree(con, includeParents = TRUE)
}

Description

Search Observation Variables

Usage

brapi_search_variables(con, traitClasses = NULL, ...)

Arguments

Value

A tibble of matching observation variables.

BrAPI endpoint

POST /search/variables - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_search_variables(con, traitClasses = "agronomic")
}

Description

Search Variants

Usage

brapi_search_variants(con, variantSetDbIds = NULL, ...)

Arguments

Value

A tibble of matching variants.

BrAPI endpoint

POST /search/variants - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_search_variants(con, variantSetDbIds = "variantset1")
}

Description

List Seasons

Usage

brapi_seasons(con, ...)

Arguments

Value

A tibble with one row per season.

BrAPI endpoint

GET /seasons - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

seasonDbId, season, seasonName, year.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_seasons(con)
}

Description

List Seed Lots

Usage

brapi_seed_lots(con, ...)

Arguments

Value

A tibble with one row per seed lot.

BrAPI endpoint

GET /seedlots - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

seedLotDbId, crossDbId, crossName.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_seed_lots(con)
}

Description

Returns a tibble of BrAPI calls supported by the server. Each row is one supported endpoint with columns for service name, HTTP methods, BrAPI versions, and content/data types.

Usage

brapi_server_info(con)

Arguments

Value

A tibble of supported endpoints and their methods.

BrAPI endpoint

GET /serverinfo - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

contentType, dataType.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_server_info(con)
}

Description

If you already have a token (e.g. from a web browser session), you can set it directly without going through a login flow.

Usage

brapi_set_token(con, token)

Arguments

Value

A new brapi_con object with the token populated.

See Also

The "Handling Credentials Safely" section of vignette("brapiR2") for how to keep token out of your script, using .Renviron or the keyring package.

Examples

con <- brapi_connection("https://test-server.brapi.org")
con <- brapi_set_token(con, "my_existing_token")

Description

Retrieves studies (occurrences/environments), optionally filtered by trial.

Usage

brapi_studies(con, trialDbId = NULL, ...)

Arguments

Value

A tibble with one row per study.

BrAPI endpoint

GET /studies - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

studyType, locationDbId, seasonDbId, studyCode, studyPUI, observationVariableDbId, active, sortBy, sortOrder.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_studies(con)
  brapi_studies(con, trialDbId = "trial1")
}

Description

Get a Single Study by ID

Usage

brapi_study(con, studyDbId)

Arguments

Value

A single-row tibble with study metadata.

BrAPI endpoint

GET /studies/{studyDbId} - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_study(con, "study1")
}

Description

A convenience function that fetches observation units and observations for a given study and pivots them into a wide-format tibble with one row per observation unit and one column per trait — ready for analysis.

Usage

brapi_study_data(con, studyDbId)

Arguments

Value

A wide-format tibble with columns for plot metadata and one column per observed trait containing the measurement values.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  data <- brapi_study_data(con, "study1")
  head(data)
}

Description

List Traits

Usage

brapi_traits(con, ...)

Arguments

Value

A tibble with one row per trait.

BrAPI endpoint

GET /traits - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

traitDbId, observationVariableDbId.

See Also

brapi_ontologies() and brapi_ontology() to resolve the ontology a trait's ontologyDbId/ontologyReference points to.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_traits(con)
}

Description

Get a Single Trial by ID

Usage

brapi_trial(con, trialDbId)

Arguments

Value

A single-row tibble with trial details.

BrAPI endpoint

GET /trials/{trialDbId} - see the v2.1 specification.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_trial(con, "trial1")
}

Description

Retrieves trials, optionally filtered by program.

Usage

brapi_trials(con, programDbId = NULL, ...)

Arguments

Value

A tibble with one row per trial.

BrAPI endpoint

GET /trials - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

active, contactDbId, locationDbId, searchDateRangeStart, searchDateRangeEnd, trialPUI, sortBy, sortOrder.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_trials(con)
}

Description

List Variant Sets (Datasets)

Usage

brapi_variant_sets(con, studyDbId = NULL, ...)

Arguments

Value

A tibble with one row per variant set.

BrAPI endpoint

GET /variantsets - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

variantSetDbId, variantDbId, callSetDbId, referenceSetDbId.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_variant_sets(con)
}

Description

List Variants (Markers/SNPs)

Usage

brapi_variants(con, variantSetDbId = NULL, ...)

Arguments

Value

A tibble with one row per variant.

BrAPI endpoint

GET /variants - see the v2.1 specification.

Query parameters the specification defines, which may be passed through ...:

variantDbId, variantSetDbId, referenceDbId, referenceSetDbId.

Examples

con <- brapi_connection("https://test-server.brapi.org")
if (brapi_ping(con)) {
  brapi_variants(con, variantSetDbId = "variantset1")
}

Description

Print a BrAPI Connection Object

Usage

## S3 method for class 'brapi_con'
print(x, ...)

Arguments

Value

Invisibly returns x.

Examples

con <- brapi_connection("https://test-server.brapi.org")
print(con)