redcapAPI (version 2.8.0)

missingSummary: Report of Missing Values

Description

Returns a data frame of subject events with missing values.

Usage

missingSummary(
  rcon,
  excludeMissingForms = TRUE,
  ...,
  fixed_fields = REDCAP_SYSTEM_FIELDS
)
# S3 method for redcapApiConnection
missingSummary(
  rcon,
  excludeMissingForms = TRUE,
  ...,
  fixed_fields = REDCAP_SYSTEM_FIELDS,
  exportRecordsArgs = list(),
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)
missingSummary_offline(
  records,
  meta_data,
  excludeMissingForms = TRUE,
  fixed_fields = REDCAP_SYSTEM_FIELDS
)

Arguments

rcon

A redcapConnection object.

excludeMissingForms

logical(1) When TRUE, forms where all fields are missing are assumed to be deliberately missing data and are excluded from the count of missing values. An example when this is desirable is if a patient did not experience an adverse event; the adverse event form would contain no data and the empty fields should not be considered missing data.

...

Arguments to pass to other methods

fixed_fields

character A vector of field names that will be used as the identifying fields in the output summary. This always includes the record identifier (ie, the first field in the data dictionary). By default it also includes any fields identified in REDCAP_SYSTEM_FIELDS, which are fields that REDCap adds to exports to identify arms, events, etc..

exportRecordsArgs

named list. Arguments to pass to exportRecords. This allows for testing specific forms, events, and/or records. Internally, any setting passed for factors, labels, dates, survey, or dag arguments will be ignored.

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.

records

character(1) A filename pointing to the raw records download from REDCap.

meta_data

character(1) A filename pointing to the data dictionary download from REDCap.

Details

The intention of this function is to generate a list of subject events that are missing and could potentially be values that should have been entered.

The branching logic from the data dictionary is parsed and translated into and R expression. When a field with branching logic passes the logical statement, it is evaluated with is.na, otherwise, it is set to FALSE (non-missing, because there was never an opportunity to provide a value). The utility of this function is limited to simple logic where all of the data exist within the same row. Any complex statements using events will result in a failure.

Optionally, forms that are entirely missing can be determined to be non-missing. This is applicable when, for instance, a patient did not have an adverse event. In this case, a form dedicated to adverse events would contain meaningless missing values and could be excluded from the report.

Examples

if (FALSE) {
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Generate a summary of missing values for the entire project
missingSummary(rcon)

# Generate a summary of missing values for a single form
missingSummary(rcon, 
               exportRecordsArgs = list(forms = "target_form"))
}