get_labresults_epiwindow: Import lab results from Go.Data within a specific date range

In WorldHealthOrganization/godataR: Connecting R with the Go.Data Application

Import lab results from Go.Data within a specific date range

Description

This function imports lab results to R from Go.Data with sample dates that fall within a specific date range. There are three options for specifying the date ranges:

1. "date range": user specifies a minimum and maximum date

2. "epiwindow": user specifies the last x days to return

3. "sample dates": user provides a vector of sample dates to search for

Users can also specify whether to return "all" available columns in the lab results export API, or only "identifiers" (a subset of columns needed to match lab results to be updated with existing lab records in Go.Data). The second option is recommended if the user wishes to identifiers existing lab results and will include patient identifier columns for record linkage. Note that some of the columns to match on are derived from case data.

Usage

get_labresults_epiwindow(
  url,
  username,
  password,
  outbreak = "active",
  cols2return = c("identifiers", "all"),
  datequery = c("date range", "epiwindow", "sample dates"),
  epiwindow = NULL,
  daterangeformat = c("ymd", "dmy", "mdy"),
  mindate = NULL,
  maxdate = NULL,
  sampledates = NULL
)

Arguments

url	URL (web address) for Go.Data instance
username	User email address used to log in to Go.Data
password	User password used to log in to Go.Data
outbreak	Outbreak to use; "active" (default) or other outbreak ID
cols2return	Set of columns to return; either "identifiers" or "all"
datequery	Date query method; "date range", "epiwindow", "sample dates"
epiwindow	User-defined illness episode window in days (integer)
daterangeformat	Min & max date element order; "ymd", "dmy" or "mdy"
mindate	Minimum date for date range
maxdate	Maximum date for date range
sampledates	Vector of specimen dates to search for

Details

Defining the epiwindow: The user first specifies a suitable illness episode window in days (the number of days beyond which a case still producing positive samples is likely to have been reinfected). The episode window to use should be determined with reference to the pathogen characteristics, as well as national and international case definitions and criteria for defining reinfections. The episode window is then applied to a date range, and cases are returned if they are within the episode window of the minimum and maximum dates provided.

Defining date element orders If minimum and maximum dates or a vector of sample dates are supplied to define the date range, the date element order must be defined (which order is the year, month and day in). For example, for a mindate of "15/08/2022" and maxdate of "30/08/2022" the order is first day, then month, then year and the option to select is "dmy". Options are as follows:

• "ymd" select this for year first, then month, then date

• "dmy" select this for day first, then month, then year

• "mdy" select this for month first, then day, then year Note that any separator can be used between the date elements.

Prerequisites: Note that this function requires Go.Data user credentials (username, password and the URL or web address of the Go.Data instance). Users must have permission to export case data within Go.Data. By default, cases will be returned for the user's active outbreak. If the user wishes to query a different outbreak, the Go.Data outbreak ID for the outbreak of interest should be supplied. To obtain the IDs of non-active outbreaks, use godataR::get_all_outbreaks() before running this function.

Value

Returns data.frame of lab results, including Go.Data lab record IDs

Author(s)

Amy Mikhail, [e-mail]

Examples

## Not run: 
# Get lab results for samples collected within the last 30 days:
labres <- get_labresults_epiwindow(url = url,
                                   username = username,
                                   password = password,
                                   cols2return = "all",
                                   datequery = "epiwindow",
                                   epiwindow = 30)

# Create vector of sample dates to search on:
mysampledates <- c("2022-07-14", "2022-08-16", "2022-08-17")

# Get lab records matching the vector of sample dates:
labres <- get_labresults_epiwindow(url = url,
                                   username = username,
                                   password = password,
                                   cols2return = "identifiers",
                                   datequery = "sample dates",
                                   daterangeformat = "ymd",
                                   sampledates = mysampledates)

# View the result:
labres

## End(Not run)

WorldHealthOrganization/godataR documentation built on May 21, 2023, 11:30 a.m.