Learn R Programming

redcapAPI (version 2.8.0)

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.

factorscheckboxLabelsOutput
FALSEFALSE0 / 1
FALSETRUE"" / code
TRUEFALSEUnchecked / Checked
TRUETRUE"" / 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.

See Also

exportRecordsTyped(),
exportReportsTyped(),
importRecords(),
deleteRecords(),
exportNextRecordName(),
renameRecord()

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