redcapConnection: Connect to a REDCap Database

Description

These methods enable the user to create a connection object used to access the database.

Usage

redcapConnection(
  url = getOption("redcap_api_url"),
  token,
  config = NULL,
  retries = 5,
  retry_interval = 2^(seq_len(retries)),
  retry_quietly = TRUE
)
# S3 method for redcapApiConnection
print(x, ...)
offlineConnection(
  meta_data = NULL,
  arms = NULL,
  events = NULL,
  instruments = NULL,
  field_names = NULL,
  mapping = NULL,
  repeat_instrument = NULL,
  users = NULL,
  user_roles = NULL,
  user_role_assignment = NULL,
  dags = NULL,
  dag_assignment = NULL,
  project_info = NULL,
  version = "14.4.0",
  file_repo = NULL,
  records = NULL,
  url = NULL,
  external_coding = list()
)
# S3 method for redcapOfflineConnection
print(x, ...)

Arguments

url: character(1). URL for the user's REDCap database API.
token: character(1) REDCap API token
config: A list to be passed to curl::handle_setopt. This allows the user to set additional configurations for the API calls, such as certificates, SSL version, etc. For the majority of users, this does not need to be altered.
retries: integerish(1). Sets the number of attempts to make to the API if a timeout error is encountered. Must be a positive value.
retry_interval: numeric. Sets the intervals (in seconds) at which retries are attempted. By default, set at a 2^r where r is the rth retry (ie, 2, 4, 8, 16, ...). For fixed intervals, provide a single value. Values will be recycled to match the number of retries.
retry_quietly: logical(1). When FALSE, messages will be shown giving the status of the API calls. Defaults to TRUE.
x: redcapConnection object to be printed
...: arguments to pass to other methods
meta_data: Either a character giving the file from which the metadata can be read, or a data.frame.
arms: Either a character giving the file from which the arms can be read, or a data.frame.
events: Either a character giving the file from which the events can be read, or a data.frame.
instruments: Either a character giving the file from which the instruments can be read, or a data.frame.
field_names: Either a character giving the file from which the field names can be read, or a data.frame.
mapping: Either a character giving the file from which the Event Instrument mappings can be read, or a data.frame.
repeat_instrument: Either a character giving the file from which the Repeating Instruments and Events settings can be read, or a data.frame. Note: The REDCap GUI does not offer a download file of these settings (at the time of this writing).
users: Either a character giving the file from which the User settings can be read, or a data.frame.
user_roles: Either a character giving the file from which the User Roles can be read, or a data.frame.
user_role_assignment: Either a character giving the file from which the User-Role Assignments can be read, or a data.frame.
dags: Either a character giving the file from which the Data Access Groups can be read, or a data.frame.
dag_assignment: Either a character giving the file from which the Data Access Group Assignments can be read, or a data.frame.
project_info: Either a character giving the file from which the Project Information can be read, or a data.frame. See Details.
version: character(1) giving the instance's REDCap version number.
file_repo: Either a character giving the file from which the File Repository Listing can be read, or a data.frame.
records: Either a character giving the file from which the Records can be read, or a data.frame. This should be the raw data as downloaded from the API, for instance. Using labeled or formatted data is likely to result in errors when passed to other functions.
external_coding: Named list of named character vectors or a character giving the file from which the external coding may be read. The list is generally obtained from the API using exportExternalCoding(). The name of the list element should be a field name in the data that is of type bioportal or sql. The named vectors are code-label pairings where the value of the vector is the code and the name is the label. If passing a file name, it should be a file with the list saved via dput.

Details

redcapConnection objects will retrieve and cache various forms of project information. This can make metadata, arms, events, etc. available directly from the redcapConnection object. The retrieval of these objects uses the default values of the respective export functions (excepting the file repository, which uses recursive = TRUE).

For each of these objects, there are four methods that can be called from the redcapConnection object:

Function type	Purpose	Example
`[info_type]`	Returns the information from the connection object	`rcon$metadata()`
`has_[info_type]`	Returns a boolean indicating if the information is cached	`rcon$has_metadata()`
`flush_[info_type]`	Purges the information from the connection object	`rcon$flush_metadata()`
`refresh_[info_type]`	Replaces the information with a new call to the API	`rcon$refresh_metadata()`

Information is cached for

metadata
arms
events
instruments
fieldnames
mapping (field-event mappings)
repeatInstrumentEvent
users
user_roles
user_role_assignment
dags
dag_assignment
projectInformation
version
fileRepository
externalCoding

There is also a flush_all and refresh_all method that will purge the entire cache and refresh the entire cache, respectively.

The externalCoding elements relate to the code-label mappings of text fields with the external validation types (such as sql fields or text fields with BioPortal Ontology modules enabled).

Specific to API Connections

The redcapApiConnection object also stores the user preferences for handling repeated attempts to call the API. In the event of a timeout error or server unavailability, these settings allow a system pause before attempting another API call. In the event all of the retries fail, the error message of the last attempt will be returned. These settings may be altered at any time using the methods rcon$set_retries(r), rcon$set_retry_interval(ri), and rcon$set_retry_quietly(rq). The argument to these functions have the same requirements as the corresponding arguments to redcapConnection.

Tokens are specific to a project, and a token must be created for each project for which the user wishes to use the API.

Additional Curl option can be set in the config argument. See the documentation for curl::handle_setopt for more curl options.

Specific to Offline Connections

"Offline connections" are a tool designed to provide the users without API privileges with at least a subset of the functionality available to API users. The offline connections are typically constructed from the comma separated value (CSV) files downloaded from the REDCap user interface. Alternatively, data frames may be provided with the necessary data.

Not all of the components of an offline connection are needed for most operations. Rather, the object was built to accept the same components available to the redcapApiConnection in order to provide a consistent interface and simplify future development.

The meta data will be required for nearly all operations. For validating and casting data, the records data must be provided, and works best if the data are the raw, unlabeled data downloaded from the REDCap user interface.

Other components that may prove useful when casting records are the url, version, events (if the project is longitudinal), and a subset of the project information. The user is encouraged to review the vignette for working with offline connections for more details.