rc_export: Export Records from a REDCap Database

In chillywings/rctools: Tools for REDCap API and data manipulation

Export Records from a REDCap Database

Description

Exports records from a REDCap Database, allowing for subsets of subjects, fields, records, and events. By default, all records will be exported. If a report ID is supplied, only data from that report will be exported.

Usage

rc_export(
  report_id = NULL,
  url = getOption("redcap_bundle")$redcap_url,
  token = getOption("redcap_token"),
  data_dict = getOption("redcap_bundle")$data_dict,
  id_field = getOption("redcap_bundle")$id_field,
  records = NULL,
  fields = NULL,
  forms = NULL,
  events = NULL,
  survey = TRUE,
  dag = TRUE,
  form_complete_auto = FALSE,
  format = FALSE,
  filter_logic = "",
  strip = ifelse(is.null(report_id) & is.null(fields), T, F),
  batch_size = -1,
  ...
)

Arguments

report_id	Numeric. ID number for a report created in REDCap.
url	Character. A url address to connect to the REDCap API
token	Character. Path to a text file containing your REDCap API token
data_dict	Dataframe. REDCap project data data_dictionary. Required only if the format or form_complet_auto options are TRUE. By default, this will be fetched from the REDCap bundle option, as created by rc_bundle.
id_field	Character. The name of the record_id field for your REDCap project.
records	Character. A vector of study id's to be returned. If NULL, all subjects are returned.
fields	Character. A vector of fields to be returned. If NULL, all fields are returned.
forms	Character. A vector of forms to be returned. If NULL, all forms are returned.
events	Character. A vector of events to be returned from a longitudinal database. If NULL, all events are returned.
survey	Logical. Specifies whether or not to export the survey identifier field (e.g., "redcap_survey_identifier") or survey timestamp fields (e.g., form_name+"_timestamp") when surveys are utilized in the project. If you do not pass in this flag, it will default to "false". If set to "true", it will return the redcap_survey_identifier field and also the survey timestamp field for a particular survey when at least one field from that survey is being exported. NOTE: If the survey identifier field or survey timestamp fields are imported via API data import, they will simply be ignored since they are not real fields in the project but rather are pseudo-fields.
dag	Logical. Specifies whether or not to export the "redcap_data_access_group" field when data access groups are utilized in the project. If you do not pass in this flag, it will default to "false". NOTE: This flag is only viable if the user whose token is being used to make the API request is not in a data access group. If the user is in a group, then this flag will revert to its default value.
form_complete_auto	Logical. If fields are passed, REDCap does not return form complete fields unless specifically requested. However, if TRUE, the [form]_complete fields for any form from which at least one variable is requested will automatically be retrieved.
format	Logical. Determines whether the data will be formatted with rc_format using the default options (Default = FALSE)
filter_logic	Character. Optional logic filter for record exports. Use REDCap style syntax- ie. similar to branching logic, calculations, etc.
strip	Logical. If TRUE, empty rows and columns will be removed from record_data. See rc_strip for more information or call seperately for more options.
batch_size	Integer. Specifies the number of subjects to be included in each batch of a batched export. Non-positive numbers export the entire project in a single batch. Batching the export may be beneficial to prevent tying up smaller servers. See details for more explanation.
...	Additional arguments to be passed to rc_api_call. Any arguments accepted by the API may be passed, even if not pre-coded by this function.

Details

A record of exports through the API is recorded in the Logging section of the project.

It is unnecessary to include "redcap_event_name" or the "redcap_repeat" variables in the fields argument. These fields are automatically exported for any longitudinal database. If the user does include them in the fields argument, they are removed quietly in the parameter checks.

A 'batched' export is one where the export is performed over a series of API calls rather than one large call. For large projects on small servers, this may prevent a single user from tying up the server and forcing others to wait on a larger job. The batched export is performed by first calling the API to export the subject identifier field (the first field in the meta data). The unique ID's are then assigned a batch number with no more than batch_size ID's in any single batch. The batches are exported from the API and stacked together.

In longitudinal projects, batch_size may not necessarily be the number of records exported in each batch. If batch_size is 10 and there are four records per patient, each batch will consist of 40 records. Thus, if you are concerned about tying up the server with a large, longitudinal project, it would be prudent to use a smaller batch size.

Note about export rights (6.0.0+): Please be aware that Data Export user rights will be applied to this API request. For example, if you have "No Access" data export rights in the project, then the API data export will fail and return an error. And if you have "De-Identified" or "Remove all tagged Identifier fields" data export rights, then some data fields might be removed and filtered out of the data set returned from the API. To make sure that no data is unnecessarily filtered out of your API request, you should have "Full Data Set" export rights in the project.

REDCap Version:= 6.0.0

Deidentified Batched Calls: Batched calls to the API are not a feature of the REDCap API, but may be imposed by making multiple calls to the API. The process of batching the export requires that an initial call be made to the API to retrieve only the record IDs. The list of IDs is then broken into chunks, each about the size of batch_size. The batched calls then force the records argument in each call.

When a user's permissions require a de-identified data export, a batched call should be expected to fail. This is because, upon export, REDCap will hash the identifiers. When R attempts to pass the hashed identifiers back to REDCap, REDCap will try to match the hashed identifiers to the unhashed identifiers in the database. No matches will be found, and the export will fail.

Users who are exporting de-identified data will have to settle for using unbatched calls to the API (ie, batch_size = -1)

Author(s)

Jeffrey Horner

Marcus Lehr

References

Please refer to your institution's API documentation.

Additional details on API parameters are found on the package wiki at https://github.com/nutterb/redcapAPI/wiki/REDCap-API-Parameters

This functionality was originally developed by Jeffrey Horner in the redcap package. https://github.com/vubiostat/redcap

See also read_redcap_oneshot in the REDCapR package by Will Beasley. https://github.com/OuhscBbmc/REDCapR

Borrowed code from http://stackoverflow.com/a/8099431/1017276 to create a list of arbitrary length.

chillywings/rctools documentation built on Aug. 9, 2024, 11:52 p.m.