• Coercion to data.frame
• format_record

library(REDCapExporter)avs_raw_core# object returned from export_core(format = "csv")avs_raw_metadata# object returned from export_content(content = "metadata", format = "csv")avs_raw_record# object returned from export_content(content = "record", format = "csv")

Coercion to data.frame

The object returned fromexport_content is a string ineither csv or json format. To have that information as a data.frame callas.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)

Forrcer_rccore objects returned byexport_core all the elements can be coerced to data.framesvialapply

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

The behavior ofas.data.frame for these objects is toreturn a data.frame with all character columns.

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

Obviously, this is not ideal for analysis. It does give the user aknown starting point for formatting the records explicitly. However,REDCapExporter provides theformat_record method tosimplify this task by using the metadata from the REDCap project.

format_record

format_record uses the metadata to inform the storagemode of the elements of a data.frame. For example, after exporting thecore of a REDCap project we can build a data.frameavsDFvia

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 justthe 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 theavsDF object (presented as a nicehuman readable table)

Now, consider the classes of the columns. Start by looking at a fewcolumns 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      4sapply(avsDF[, cols], class)##      record_id uniform_number         height         points##    "character"    "character"      "integer"      "numeric"

Why are record_id and uniform_number, stored as characters whereasheight and points (sum of goals scored and assists) integer and numericvalues 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 valuefor “text_validation_type_or_show_slider_number”. This is interpreted,then, as just a text field and should be character vector in thedata.frame. Obviously the user could coerce to integer of numeric isdesired and if appropriate.

For height, note that the field_type is “text” and the“text_validation_type_or_show_slider_number” is “integer”, hence thecoercion 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 datatypes base on the metadata. For example, dates in REDCap can by enteredand validated in Year-Month-Day, Month-Day-Year, and Day-Month-Yearformats. The raw data is all in Year-Month-Day format.

The coercion that will be used when callingformat_record is defined by an implicit call tocol_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] TRUEct<-col_type(avs_metadata_DF)

Each of the elements ofct are applied to the column ofthe data frame with the same name. Examples: The record_id is to be acharacter string by default.

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

If the user would prefer the record_id to be an integer we can modifyct and apply it explicitly when callingformat_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 isdifferent betweenavsDF$record_id andavsDF2$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 ispart of theavs_raw_core object, is not being used todefine 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 toformat_record

format_record(avs_record_DF,col_type = ct)

By default, variables recorded in REDCap via radio buttons ordropdown lists are formatted as factors. For example, the position ofthe 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 charactersinstead of factors you can modify the call tocol_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 charactertable(avsDF2$position)####     Center    Defence       Goal  Left Wing Right Wing##          8         11          2          6          5

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

?col_type