Package 'deltabreedquery'

Validate BrAPI authentication credentials

Description

Checks if the user has credentials currently stored and validates them by performing a test call to the BrAPI endpoint. Also prints the remaining time until the access token expires, if applicable.

Usage

check_auth()

Value

No return value, called for side effects (printing status)

Examples

check_auth()
login_deltabreed("example", verbose = FALSE)
check_auth()

---

Retrieve a filtered list of observation data

Description

This function retrieves a foo filtered list of observation data using one or more filter values provided by the user, packaging the response into a data frame of the same format as get_observations().

This function is best used by calling get_experiments() first, in order to see what experiments are actually present in the target DeltaBreed instance.

Usage

filter_observations(
  year = NA,
  location = NA,
  exp_name = NA,
  env_name = NA,
  exp_type = NA,
  page_size = 10000,
  drop_empty_columns = FALSE,
  include_dbids = FALSE,
  case_correct = TRUE,
  verbose = TRUE
)

Arguments

year	A year or vector of years.
location	A location name or vector of locations.
exp_name	An experiment name or vector of names.
env_name	An environment name or vector of names.
exp_type	An experiment type or vector of types.
page_size	Page size to use for the response. Larger page sizes may decrease total retrieval time.
drop_empty_columns	If TRUE, all empty columns (including metadata columns) will be dropped from the retrieved data frame.
include_dbids	If TRUE, the alphanumeric DBIDs used by DeltaBreed will be included in the retrieved data frame.
case_correct	If FALSE, any categorical variables with case mismatches to the trait variable definition (e.g. a value of "Blue" in the observation data, when the defined trait categories are "red" and "blue") will be masked as NA instead of being case-corrected to the appropriate values.
verbose	If FALSE, all non-essential messages will be suppressed.

Value

A data frame of observations using the supplied filters.

Examples

login_deltabreed("example", verbose = FALSE)

# the available filters (and values to filter on) correspond to columns of get_experiments()
get_experiments()

all_obs <- get_observations(verbose = FALSE)
manitoba <- filter_observations(location = "Manitoba")
table(all_obs$Location)
table(manitoba$Location)

# all filters can take vectors as arguments
almtis <- filter_observations(location = c("Alma", "Tisdale"))
table(almtis$Year, almtis$Location)

# filters can be combined as needed
ayt_mb <- filter_observations(exp_type = "AYT", location = "Manitoba")
table(ayt_mb$ExpName, ayt_mb$EnvName)

---

Retrieve experiment/ summary

Description

Retrieves a summary of all experiments and environments in a given DeltaBreed program. This may include experiments for which no observations have been recorded yet.

Usage

get_experiments(verbose = TRUE, include_dbids = FALSE)

Arguments

verbose	If FALSE, all non-essential messages will be suppressed.
include_dbids	If TRUE, the alphanumeric DBIDs used by DeltaBreed for each experiment/environment will be included in the retrieved data frame. Typically used for debugging or merging data from other sources.

Value

Data frame of experiment/environment metadata.

Examples

login_deltabreed("example", verbose = FALSE)

expt <- get_experiments()
expt

---

Retrieve germplasm records

Description

Retrieves all germplasm data from the current DeltaBreed instance, reformatting it to match DeltaBreed layout.

Usage

get_germplasm(page_size = 10000)

Arguments

page_size

Page size to use for the response. Larger page sizes may decrease total retrieval time.

Value

Data frame of germplasm/accession/entry information.

Examples

login_deltabreed("example", verbose = FALSE)

germplasm <- get_germplasm()
head(germplasm)

---

Retrieve all observation data

Description

Retrieves all observation data from a DeltaBreed instance via BrAPI call. This includes observation units with no observations. converting it into a data frame that mimics the appearance of the data tables on the Experiments & Observations tab of DeltaBreed.

Usage

get_observations(
  page_size = 10000,
  drop_empty_columns = FALSE,
  include_dbids = FALSE,
  case_correct = TRUE,
  verbose = TRUE
)

Arguments

page_size	Page size to use for the response. Larger page sizes may decrease total retrieval time.
drop_empty_columns	If TRUE, all empty columns (including metadata columns) will be dropped from the retrieved data frame.
include_dbids	If TRUE, the alphanumeric DBIDs used by DeltaBreed will be included in the retrieved data frame.
case_correct	If FALSE, any categorical variables with case mismatches to the trait variable definition (e.g. a value of "Blue" in the observation data, when the defined trait categories are "red" and "blue") will be masked as NA instead of being case-corrected to the appropriate values.
verbose	If FALSE, all non-essential messages will be suppressed.

Value

A data frame of all observation units and any observations (phenotypes).

Examples

login_deltabreed("example", verbose = FALSE)
obs <- get_observations()

# phenotype columns will be typed according to the observation variables (trait definitions)
str(obs[,16:20])
get_variables()

---

Retrieve observation variables (trait definitions) from a DeltaBreed instance.

Description

Retrieves trait data from a DeltaBreed program via BrAPI, converting it into a data frame that mimics the appearance of the Ontology table in DeltaBreed itself.

Usage

get_variables(verbose = TRUE, include_archived = FALSE)

Arguments

verbose	If FALSE, all non-essential messages will be suppressed.
include_archived	If TRUE, archived (non-active) variables will be included in the retrieved data frame.

Value

Data frame of trait definitions drawn from BrAPI /variables endpoint.

Examples

login_deltabreed("example", verbose = FALSE)

vars <- get_variables()
vars

---

Log in to a DeltaBreed instance

Description

This function stores your authentication credentials for a target DeltaBreed instance. To log in, you will require the BrAPI Base URL and a valid authentication token, both of which can be found on the 'BrAPI' tab of DeltaBreed.

The URL and token can be given as arguments or supplied to function prompts. The function performs some basic checks, including verifying that the user has internet access and making some test calls to the BrAPI server.

Usage

login_deltabreed(base_url = NULL, access_token = NULL, verbose = TRUE)

Arguments

base_url	The BrAPI Base URL, found on the BrAPI tab of DeltaBreed in the BrAPI Information pane.
access_token	A valid Access Token, retrieved from the DeltaBreed user interface.
verbose	If FALSE, all non-essential messages will be suppressed.

Details

Access tokens are valid for 24 hours after generation. To check your authorization credentials at any time, use the check_auth() function.

Value

No return value, called for side effects (storing credentials)

Examples

## Not run: 
# function can be run with no arguments to bring up a prompt to enter the URL/token
login_deltabreed()

# since your program's URL will remain static, you can supply it as an argument, e.g.:
login_deltabreed("https://app.breedinginsight.net/v1/programs/f152169d-049f-4a7c-b5d8-c725b14e66f0")

## End(Not run)

---

Clear DeltaBreed authentication credentials

Description

Removes stored credentials (URL and access token) from the package environment. The access token will remain valid for as long as the DeltaBreed instance specifies, but in order to retrieve data the URL/token will need to be-entered with login_deltabreed().

Usage

logout_deltabreed()

Value

No return value, called for side effects (clearing credentials)

---