R/redcapDataStructure.R

In redcapAPI: Interface to 'REDCap'

#' @name redcapDataStructures
#' @title REDCap Data Structures
#'
#' @description Utilities for recognizing and validating data structures
#'   for use with the REDCap API
#'
#' @param data `data.frame` User provided data to be compared against
#'   the established REDCap data structure.
#' @param redcap_data `data.frame` A data set from the `redcapAPI`
#'   package to use a reference for comparing to expected data structure.

validateRedcapData <- function(data, redcap_data){
  if (is.null(data)) return(NULL)

  checkmate::assert_data_frame(x = data,
                               col.names = "named")

  in_data_and_not_structure <- setdiff(names(data),
                                       names(redcap_data))

  # names in data not in the redcap structure
  if (length(in_data_and_not_structure) > 0){
    logWarning("The following names in 'data' are not recognized in the REDCap data structure.\n",
            "Downstream functions may not operate as expected. {",
            paste0(in_data_and_not_structure, collapse = ", "), "}\n")
  }

  # names in the redcap structure not in the data

  in_structure_and_not_data <- setdiff(names(redcap_data),
                                       names(data))

  if (length(in_structure_and_not_data) > 0)
  {
    logWarning("The following names in the REDCap data structure are not in 'data'. \n",
            "Downstream functions may not operate as expected. {",
            paste0(in_structure_and_not_data, collapse = ", "), "}\n")
  }
  return(data)
}

#' @rdname redcapDataStructures
#' @export

# The field names listed here are those generated by REDCap records export.
# A listing of these fields was needed to support missingSummary.
# It would not hurt to contemplate how these could be obtained
# dynamically rather than relying up updating constants.

REDCAP_SYSTEM_FIELDS <- c("redcap_event_name",
                          "redcap_data_access_group",
                          "redcap_repeat_instrument",
                          "redcap_repeat_instance",
                          "redcap_survey_identifier")

#' @rdname redcapDataStructures
#' @export

# These are the purposes that can be used when using
# createRedcapProject

REDCAP_PROJECT_PURPOSE <- c("Practice/just for fun",
                            "Other",
                            "Research",
                            "Quality Improvement",
                            "Operational Support")

# Arms --------------------------------------------------------------
# Arms - Data Frame Structure

REDCAP_ARMS_STRUCTURE <-
  data.frame(arm_num = numeric(0),
             name = character(0),
             stringsAsFactors = FALSE)

# Data Access Groups ------------------------------------------------
# DAG Structure

REDCAP_DAG_STRUCTURE <-
  data.frame(data_access_group_name = character(0),
             unique_group_name = character(0),
             data_access_group_id = numeric(0),
             stringsAsFactors = FALSE)

# DAG Assignment Structure

REDCAP_DAG_ASSIGNMENT_STRUCTURE <-
  data.frame(username = character(0),
             redcap_data_access_group = character(0),
             stringsAsFactors = FALSE)

# Events ------------------------------------------------------------
# Event Structure

REDCAP_EVENT_STRUCTURE <-
  data.frame(event_name = character(0),
             arm_num = numeric(0),
             unique_event_name = character(0),
             custom_event_label = character(0),
             event_id = numeric(0),
             days_offset = numeric(0),
             offset_min = numeric(0),
             offset_max = numeric(0),
             stringsAsFactors = FALSE)

# Field Names -------------------------------------------------------
# Field Name Structure

REDCAP_FIELDNAME_STRUCTURE <-
  data.frame(original_field_name = character(0),
             choice_value = character(0),
             export_field_name = character(0),
             stringsAsFactors = FALSE)

# Instruments -------------------------------------------------------
# Instrument Structure

REDCAP_INSTRUMENT_STRUCTURE <-
  data.frame(instrument_name = character(0),
             instrument_label = character(0),
             stringsAsFactors = FALSE)

# Instrument Mapping Structure

REDCAP_INSTRUMENT_MAPPING_STRUCTURE <-
  data.frame(arm_num = numeric(0),
             unique_event_name = character(0),
             form = character(0),
             stringsAsFactors = FALSE)

# Logging -----------------------------------------------------------
# Logging Structure

REDCAP_LOGGING_STRUCTURE <-
  data.frame(timestamp = as.POSIXct(character(0)),
             username = character(0),
             action = character(0),
             details = character(0),
             record = character(0),
             stringsAsFactors = FALSE)

# Meta Data ---------------------------------------------------------
# Meta Data - Data Frame Structure

REDCAP_METADATA_STRUCTURE <-
  data.frame(field_name = character(0),
             form_name = character(0),
             section_header = character(0),
             field_type = character(0),
             field_label = character(0),
             select_choices_or_calculations = character(0),
             field_note = character(0),
             text_validation_type_or_show_slider_number = character(0),
             text_validation_min = character(0),
             text_validation_max = character(0),
             identifier = character(0),
             branching_logic = character(0),
             required_field = character(0),
             custom_alignment = character(0),
             question_number = character(0),
             matrix_group_name = character(0),
             matrix_ranking = character(0),
             field_annotation = character(0),
             stringsAsFactors = FALSE)

REDCAP_METADATA_API_UI_MAPPING <-
  c("Variable...Field.Name" = "field_name",
    "Form.Name" = "form_name",
    "Section.Header" = "section_header",
    "Field.Type" = "field_type",
    "Field.Label" = "field_label",
    "Choices..Calculations..OR.Slider.Labels" = "select_choices_or_calculations",
    "Field.Note" = "field_note",
    "Text.Validation.Type.OR.Show.Slider.Number" = "text_validation_type_or_show_slider_number",
    "Text.Validation.Min" = "text_validation_min",
    "Text.Validation.Max" = "text_validation_max",
    "Identifier." = "identifier",
    "Branching.Logic..Show.field.only.if...." = "branching_logic",
    "Required.Field." = "required_field",
    "Custom.Alignment" = "custom_alignment",
    "Question.Number..surveys.only." = "question_number",
    "Matrix.Group.Name" = "matrix_group_name",
    "Matrix.Ranking." = "matrix_ranking",
    "Field.Annotation" = "field_annotation")

# Meta Data - Known Field Types

#' @rdname redcapDataStructures
#' @export

REDCAP_METADATA_FIELDTYPE <- c("calc",
                               "checkbox",
                               "descriptive",
                               "dropdown",
                               "file",
                               "notes",
                               "radio",
                               "slider",
                               "text",
                               "truefalse",
                               "yesno")

# Meta Data - Known Validation Types

#' @rdname redcapDataStructures
#' @export
REDCAP_METADATA_VALIDATION_TYPE <- c(
  "alpha_only",
  "autocomplete",
  "date_dmy",
  "date_mdy",
  "date_ymd",
  "datetime_dmy",
  "datetime_mdy",
  "datetime_seconds_dmy",
  "datetime_seconds_mdy",
  "datetime_seconds_ymd",
  "datetime_ymd",
  "email",
  "integer",
  "number",
  "number_1dp",
  "number_1dp_comma_decimal",
  "number_2dp",
  "number_2dp_comma_decimal",
  "phone",
  "signature",
  "time",
  "time_hh_mm_ss",
  "time_mm_ss",
  "vmrn",
  "zipcode")

# Project Information -----------------------------------------------
# Project Information Structure

# REDCAP_PROJECT_INFORMATION_STRUCTURE <-
redcapProjectInformationStructure <-
function(version)
{
  data.frame(project_id = character(0),
             project_title = character(0),
             creation_time = character(0),
             production_time = character(0),
             in_production = character(0),
             project_language = character(0),
             purpose = character(0),
             purpose_other = character(0),
             project_notes = character(0),
             custom_record_label = character(0),
             secondary_unique_field = character(0),
             is_longitudinal = character(0),
             has_repeating_instruments_or_events = character(0),
             surveys_enabled = character(0),
             scheduling_enabled = character(0),
             record_autonumbering_enabled = character(0),
             randomization_enabled = character(0),
             ddp_enabled = character(0),
             project_irb_number = character(0),
             project_grant_number = character(0),
             project_pi_firstname = character(0),
             project_pi_lastname = character(0),
             project_pi_email = if(is.null(version) || utils::compareVersion(version, "15.8.2") < 0) NULL else character(0),
             display_today_now_button = character(0),
             missing_data_codes = character(0),
             external_modules = character(0),
             bypass_branching_erase_field_prompt = character(0),
             stringsAsFactors = FALSE)
}

# This is the list of fields recognized for updates in importProjectInformation

PROJECT_INFO_FIELDS_EDITABLE <-
  c("project_title",
    "project_language",
    "purpose",
    "purpose_other",
    "project_notes",
    "custom_record_label",
    "secondary_unique_field",
    "is_longitudinal",
    "surveys_enabled",
    "scheduling_enabled",
    "record_autonumbering_enabled",
    "randomization_enabled",
    "project_irb_number",
    "project_grant_number",
    "project_pi_firstname",
    "project_pi_lastname",
    "project_pi_email",
    "display_today_now_button",
    "bypass_branching_erase_field_prompt")

PROJECT_INFO_FIELDS_FIXED <- # These cannot be updated via the API
  c("project_id",
    "creation_time",
    "production_time",
    "in_production",
    "has_repeating_instruments_or_events",
    "ddp_enabled",
    "missing_data_codes",
    "external_modules")

# Repeating Instruments and Events ----------------------------------

#' @rdname redcapDataStructures
#' @export

REDCAP_REPEAT_INSTRUMENT_STRUCTURE <-
  data.frame(event_name = character(0),
             form_name = character(0),
             custom_form_label = character(0))

# Users -------------------------------------------------------------
# Users Structure

redcapUserStructure <- function(version)
{
  data.frame(username = character(0),
             email = character(0),
             firstname = character(0),
             lastname = character(0),
             expiration = as.POSIXct(character(0)),
             data_access_group = character(0),
             data_access_group_id = character(0),
             data_access_group_label = if(is.null(version) || utils::compareVersion(version, "16.0.0") < 0) NULL else character(0),
             design = character(0),
             alerts = character(0),
             user_rights = character(0),
             data_access_groups = character(0),
             reports = character(0),
             stats_and_charts = character(0),
             manage_survey_participants = character(0),
             calendar = character(0),
             data_import_tool = character(0),
             data_comparison_tool = character(0),
             logging = character(0),
             email_logging = if(is.null(version) || utils::compareVersion(version, "14.4.0") < 0) NULL else character(0),
             file_repository = character(0),
             data_quality_create = character(0),
             data_quality_execute = character(0),
             data_quality_resolution = character(0),
             api_export = character(0),
             api_import = character(0),
             api_modules=if(is.null(version) || utils::compareVersion(version, "14.0.3") < 0) NULL else character(0),
             mobile_app = character(0),
             mobile_app_download_data = character(0),
             record_create = character(0),
             record_rename = character(0),
             record_delete = character(0),
             lock_records_all_forms = character(0),
             lock_records = character(0),
             lock_records_customization = character(0),
             mycap_participants = character(0),
             random_setup = character(0),
             random_dashboard = character(0),
             random_perform = character(0),
             forms = character(0),
             forms_export = character(0),
             stringsAsFactors = FALSE)
}

# These are variables in the Users table coded as 0 = No Access, 1 = Access
REDCAP_USER_TABLE_ACCESS_VARIABLES <-
  c("design",
    "alerts",
    "user_rights",
    "data_access_group",
    "reports",
    "stats_and_charts",
    "manage_survey_participants",
    "calendar",
    "data_import_tool",
    "data_comparison_tool",
    "logging",
    "email_logging",
    "file_repository",
    "data_quality_create",
    "data_quality_execute",
    "api_export",
    "api_import",
    "api_modules",
    "mobile_app",
    "mobile_app_download_data",
    "record_create",
    "record_rename",
    "record_delete",
    "lock_records_all_forms",
    "lock_records",
    "lock_records_customization",
    "mycap_participants",
    "random_setup",
    "random_dashboard",
    "random_perform")

# User Roles --------------------------------------------------------
# User Role Structure

redcapUserRoleStructure <- function(version)
{
  data.frame(unique_role_name = character(0),
             role_label = character(0),
             design = character(0),
             user_rights = character(0),
             data_access_groups = character(0),
             # data_export = character(0),
             reports = character(0),
             stats_and_charts = character(0),
             manage_survey_participants = character(0),
             calendar = character(0),
             data_import_tool = character(0),
             data_comparison_tool = character(0),
             logging = character(0),
             email_logging = if(is.null(version) || utils::compareVersion(version, "14.4.0") < 0) NULL else character(0),
             file_repository = character(0),
             data_quality_create = character(0),
             data_quality_execute = character(0),
             api_export = character(0),
             api_import = character(0),
             mobile_app = character(0),
             mobile_app_download_data = character(0),
             record_create = character(0),
             record_rename = character(0),
             record_delete = character(0),
             lock_records_customization = character(0),
             lock_records = character(0),
             lock_records_all_forms = character(0),
             mycap_participants = character(0),
             forms = character(0),
             forms_export = character(0),
             random_setup = character(0),
             random_dashboard = character(0),
             random_perform = character(0),
             stringsAsFactors = FALSE)
}
# User Role Table Access Variables

REDCAP_USER_ROLE_TABLE_ACCESS_VARIABLES <-
  c("design",
    "alerts",
    "user_rights",
    "data_access_groups",
    # "data_export",
    "reports",
    "stats_and_charts",
    "manage_survey_participants",
    "calendar",
    "data_import_tool",
    "data_comparison_tool",
    "logging",
    "email_logging",
    "file_repository",
    "data_quality_create",
    "data_quality_execute",
    "api_export",
    "api_import",
    "mobile_app",
    "mobile_app_download_data",
    "record_create",
    "record_rename",
    "record_delete",
    "lock_records_customization",
    "lock_records",
    "lock_records_all_forms")

# User-Role Assignment Structure

# REDCAP_USER_ROLE_ASSIGNMENT_STRUCTURE <-
redcapUserRoleAssignmentStructure <- function(version)
{
  data.frame(username = character(0),
             unique_role_name = character(0),
             data_access_group = if(is.null(version) || utils::compareVersion(version, "15.8.2") < 0) NULL else character(0),
             stringsAsFactors = FALSE)
}