recordsMethods: Export Records and Reports

Description

These methods enable the user to export records and reports from a project.

Usage

exportRecords(
  rcon,
  factors = TRUE,
  fields = NULL,
  forms = NULL,
  records = NULL,
  events = NULL,
  labels = TRUE,
  dates = TRUE,
  drop = NULL,
  survey = TRUE,
  dag = TRUE,
  checkboxLabels = FALSE,
  colClasses = character(0),
  ...
)
exportRecords_offline(
  dataFile,
  metaDataFile,
  factors = TRUE,
  fields = NULL,
  forms = NULL,
  labels = TRUE,
  dates = TRUE,
  checkboxLabels = FALSE,
  colClasses = NA,
  ...,
  meta_data
)
exportReports(
  rcon,
  report_id,
  factors = TRUE,
  labels = TRUE,
  dates = TRUE,
  drop = NULL,
  checkboxLabels = FALSE,
  ...
)
# S3 method for redcapApiConnection
exportRecords(
  rcon,
  factors = TRUE,
  fields = NULL,
  forms = NULL,
  records = NULL,
  events = NULL,
  labels = TRUE,
  dates = TRUE,
  drop = NULL,
  survey = TRUE,
  dag = TRUE,
  checkboxLabels = FALSE,
  colClasses = character(0),
  ...,
  batch.size = -1,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list(),
  form_complete_auto = TRUE
)
# S3 method for redcapApiConnection
exportReports(
  rcon,
  report_id,
  factors = TRUE,
  labels = TRUE,
  dates = TRUE,
  drop = NULL,
  checkboxLabels = FALSE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

Value

exportRecords returns a data frame with the project data. The data will be formatted consistent with the meta data and the arguments provided by the user.

exportReports returns a data frame with the data from the requested report. The data will be formatted consisted with the meta data and the arguments provided by the user.

Arguments

rcon: A redcapConnection object.
report_id: integerish(1). Gives the report id of the desired report. This is located on the Report Builder page of the user interface.
factors: logical(1). When TRUE, multiple choice fields will be returned as factors. Otherwise, they are returned as character values. See 'Exporting Records' for more on how this interacts with the checkboxLabels argument.
fields: character. Fields to be returned. When NULL, all fields are returned.
forms: character. Forms to be returned. When NULL, all forms are returned.
records: character or integerish. Record ID's to be returned. When NULL, all records are returned.
events: character. Events to be returned from a longitudinal database. When NULL, all events are returned.
labels: logical(1). When TRUE, field labels are attached to each column as an attribute.
dates: logical(1). When TRUE, date variables are converted to POSIXct objects.
drop: character. An optional vector of REDCap field names to remove from the dataset. Ignored when NULL. Any fields in this argument that do not exist in the project will be ignored.
survey: logical(1). specifies whether or not to export the survey identifier field (redcap_survey_identifier) or survey timestamp fields ([form_name]_timestamp) when surveys are utilized in the project.
dag: logical(1). When TRUE, the system field redcap_data_access_group is included in the export. This option 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 FALSE.
checkboxLabels: logical(1). When FALSE labels are applied as "Unchecked"/"Checked". When TRUE, they are applied as ""/[field_label] where [field_label] is the label assigned to the level in the data dictionary.
form_complete_auto: logical(1). When TRUE (default), the [form]_complete fields for any form from which at least one variable is requested will automatically be retrieved. When FALSE, these fields must be explicitly requested.
colClasses: Named character vector. Column classes passed to utils::read.csv() calls. Useful to force the interpretation of a column in a specific type and avoid an unexpected recast.
batch.size: integerish(1). Specifies the number of subjects to be included in each batch of a batched export or import. Non-positive numbers export/import the entire operation in a single batch. Batching may be beneficial to prevent tying up smaller servers. See Details.
dataFile: character(1). Gives the location of the dataset downloaded from REDCap. This should be the raw (unlabeled) data set.
metaDataFile: character(1). Gives the location of the data dictionary downloaded from REDCap.
...: Arguments to pass to other methods
error_handling: character(1). One of c("error", "null"). An option for how to handle errors returned by the API. see redcapError().
config: A named list. Additional configuration parameters to pass to httr::POST(). These are appended to any parameters in rcon$config.
api_param: A named list. Additional API parameters to pass into the body of the API call. This provides users to execute calls with options that may not otherwise be supported by redcapAPI.
meta_data: Deprecated version of metaDataFile.

Functions

exportRecords(): Export records from a project.
exportRecords_offline(): Format records from REDCap data file exports.
exportReports(): Export data via a report.

Details

It is unnecessary to include `"redcap_event_name"`` in the fields argument. This field is automatically exported for any longitudinal database. If the user does include it in the fields argument, it is removed quietly in the parameter checks.

There are four ways the data from checkbox variables may be represented depending on the values of factors and checkboxLabels. The most common are the first and third rows of the table below. When checkboxLabels = TRUE, either the coded value or the labeled value is returned if the box is checked, or an empty string if it is not.

`factors`	`checkboxLabels`	`Output`
`FALSE`	`FALSE`	0 / 1
`FALSE`	`TRUE`	"" / code
`TRUE`	`FALSE`	Unchecked / Checked
`TRUE`	`TRUE`	"" / label

The 'offline' version of exportReports operates on the raw (unlabeled) data file downloaded from REDCap along with the data dictionary. This is made available for instances where the API cannot be accessed for some reason (such as waiting for API approval from the REDCap administrator).

A 'batched' export (or import) 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 record 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 ten and there are four records per patient, each batch will consist of 40 records. Thus, if the user is concerned about tying up the server with a large, longitudinal project, it would be prudent to use a smaller batch size.

Examples

Run this code

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Export records
exportRecords(rcon)

# Export records in batches of one hundred IDs
exportRecords(rcon, 
              batch.size = 100)
              
# Export records without factors
exportRecords(rcon, 
              factors = FALSE)
              

# Export a report
exportReports(rcon, 
              report_id = 12345)

}

Run the code above in your browser using DataLab