get_contacts_epiwindow: Import contacts from Go.Data notified within a specific date...

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

Import contacts from Go.Data notified within a specific date range

Description

This function imports contacts to R from Go.Data with contact report 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. "epibuffer": adds the epiwindow to the minimum and maximum date

The date that is queried is the date that cases were notified on (a mandatory field in all contact investigation forms in Go.Data called dateOfReporting)

Users can also specify whether to return "all" available columns in the case data export API, or only "identifiers" (a subset of columns comprising only case identifying data such as first names, last names and dates of birth). Selecting "identifiers" is recommended for record linkage with another data set (such as linking lab results to Go.Data contact IDs) as this smaller subset of 9 columns will be returned much faster and use less memory in R for date ranges that include a lot of contacts.

Usage

get_contacts_epiwindow(
  url,
  username,
  password,
  outbreak = "active",
  cols2return = c("identifiers", "all"),
  datequery = c("date range", "epiwindow", "epibuffer"),
  daterangeformat = c("ymd", "dmy", "mdy"),
  epiwindow,
  mindate = NULL,
  maxdate = 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" or "epibuffer"
daterangeformat	Min & max date element order; "ymd", "dmy" or "mdy"
epiwindow	User-defined illness episode window in days (integer)
mindate	Minimum contact reporting date for date range
maxdate	Maximum contact reporting date for date range

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 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, contacts 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 case data, including Go.Data case ID

Author(s)

Amy Mikhail, [e-mail]

Examples

## Not run: 
# Get contacts from the active outbreak notified within the last 30 days:
contacts <- get_contacts_epiwindow(url = url,
                                   username = username,
                                   password = password,
                                   cols2return = "all",
                                   datequery = "epiwindow",
                                   epiwindow = 30)

# Get contacts from 01 August to 25 September 2022 with a 30-day buffer:
contacts <- get_contacts_epiwindow(url = url,
                                   username = username,
                                   password = password,
                                   cols2return = "identifiers",
                                   datequery = "epibuffer",
                                   epiwindow = 30,
                                   daterangeformat = "dmy",
                                   mindate = "01/08/2022",
                                   maxdate = "25/09/2022")

# View the result:
contacts

## End(Not run)

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