Coercion to data.frame

The object returned from export_content is a string in either csv or json format. To have that information as a data.frame call as.data.frame.

This method works for the metadata and records directly.

avs_metadata_DF <- as.data.frame(avs_raw_metadata)
avs_record_DF   <- as.data.frame(avs_raw_record)

For rcer_rccore objects returned by export_core all the elements can be coerced to data.frames via lapply

avs_core_DFs  <- lapply(avs_raw_core, as.data.frame)

The behavior of as.data.frame for these objects is to return a data.frame with all character columns.

avs_metadata_DF |> sapply(class) |> sapply(is.character) |> all()
## [1] TRUE
avs_record_DF   |> sapply(class) |> sapply(is.character) |> all()
## [1] TRUE

Obviously, this is not ideal for analysis. It does give the user a known starting point for formatting the records explicitly. However, REDCapExporter provides the format_record method to simplify this task by using the metadata from the REDCap project.

format_record

format_record uses the metadata to inform the storage mode of the elements of a data.frame. For example, after exporting the core of a REDCap project we can build a data.frame avsDF via

avsDF <- format_record(avs_raw_core)
str(avsDF, max.level = 0)
## Classes 'rcer_record' and 'data.frame':  32 obs. of  75 variables:

Note: the above uses the core export from REDCap. You can use just the record and metadata to get the same result:

identical(
  format_record(avs_raw_core),
  format_record(avs_raw_record, avs_raw_metadata)
)
## [1] TRUE

Let’s look at the avsDF object (presented as a nice human readable table)

Now, consider the classes of the columns. Start by looking at a few columns which look like they are numeric values, record_id, uniform_number, height, and points.

cols <- c("record_id", "uniform_number", "height", "points")
head(avsDF[, cols], n = 3)
##   record_id uniform_number height points
## 1         1              1     73      1
## 2         2             46     73      0
## 3         3             45     74      4
sapply(avsDF[, cols], class)
##      record_id uniform_number         height         points 
##    "character"    "character"      "integer"      "numeric"

Why are record_id and uniform_number, stored as characters whereas height and points (sum of goals scored and assists) integer and numeric values respectively? The answer is in the metadata.

avs_metadata_DF[avs_metadata_DF$field_name %in% cols, ]

Notice that for the record_id and uniform_number the field_type is “text” with no value for “select_choices_or_calculations” and no value for “text_validation_type_or_show_slider_number”. This is interpreted, then, as just a text field and should be character vector in the data.frame. Obviously the user could coerce to integer of numeric is desired and if appropriate.

For height, note that the field_type is “text” and the “text_validation_type_or_show_slider_number” is “integer”, hence the coercion from the raw data to integer when building the data.frame. Lastly, the points are a calculated field and set to numeric.

REDCapExporter attempts to make reasonable assumptions for the data types base on the metadata. For example, dates in REDCap can by entered and validated in Year-Month-Day, Month-Day-Year, and Day-Month-Year formats. The raw data is all in Year-Month-Day format.

The coercion that will be used when calling format_record is defined by an implicit call to col_type which uses the metadata, in raw or formatted form, to determine the coercion.

identical(col_type(avs_raw_metadata), col_type(avs_metadata_DF))
## [1] TRUE
ct <- col_type(avs_metadata_DF)

Each of the elements of ct are applied to the column of the data frame with the same name. Examples: The record_id is to be a character string by default.

ct[["record_id"]]
## as.character(record_id)

If the user would prefer the record_id to be an integer we can modify ct and apply it explicitly when calling format_record.

ct[["record_id"]] |> str()
##  language as.character(record_id)
ct[["record_id"]] <- expression(as.integer(record_id))
avsDF2 <- format_record(avs_raw_core, col_type = ct)
## Ignoring metadata, using col_type

Two notes to make here, first, we can see that the storage mode is different between avsDF$record_id and avsDF2$record_id.

class(avsDF$record_id)
## [1] "character"
class(avsDF2$record_id)
## [1] "integer"

Second, there is a message (not a warning), that the metadata that is part of the avs_raw_core object, is not being used to define the column types.

If you want to suppress that message you can use

suppressMessages(format_record(avs_raw_core, col_type = ct))

or use the records as the object passed to format_record

format_record(avs_record_DF, col_type = ct)

By default, variables recorded in REDCap via radio buttons or dropdown lists are formatted as factors. For example, the position of the player is a factor.

class(avsDF$position)
## [1] "factor"
summary(avsDF$position)
##       Goal  Left Wing Right Wing     Center    Defence 
##          2          6          5          8         11

If you’d prefer to have all these variables stored as characters instead of factors you can modify the call to col_type

ct <- col_type(avs_raw_metadata, factors = FALSE)
avsDF2 <- format_record(avs_raw_record, col_type = ct)
class(avsDF2$position)
## [1] "character"
summary(avsDF2$position)
##    Length     Class      Mode 
##        32 character character
table(avsDF2$position)
## 
##     Center    Defence       Goal  Left Wing Right Wing 
##          8         11          2          6          5

The default formatting is documented in the manual file The implemented code is within the S3 method:

?col_type