Merge pull request #9 from ucsf-bhhi/stata-helpers

Stata Helpers

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: statewide.survey.tools
 Title: Statewide Survey Tools
-Version: 0.3.3
+Version: 0.3.4
 Authors@R: 
     person("Eve", "Perry", , "[email protected]", role = c("aut", "cre"))
 Description: Helper tools for the Statewide Survey.

R/fetch_redcap_data.R

@@ -6,6 +6,16 @@
 #' the RDS project token.
 #'
 #' @param ... Options passed to [REDCapR::redcap_read()].
+#' @param export_survey_fields A boolean that specifies whether to export the
+#'   survey identifier field (e.g., 'redcap_survey_identifier') or survey
+#'   timestamp fields (e.g., instrument+'_timestamp'). The timestamp outputs
+#'   reflect the survey's completion time (according to the time and timezone of
+#'   the REDCap server.)
+#' @param for_stata Should the data be prepared for use in Stata? This sets
+#'   col_types to be compatible with what Stata expects and makes sure variable
+#'   names are legal Stata variable names.
+#' @param col_types Override default col_types for Stata by providing a
+#'   [readr::cols()] specification.
 #' @param redcap_uri REDCap API URL. Defaults to [redcap_api_url()].
 #' @param token REDCap API Token. Defaults to main project token. Use RDS
 #'   project token with `redcap_token("rds")`.
@@ -18,15 +28,60 @@
 #' @seealso [redcap_token()]
 fetch_redcap_data = function(
   ...,
+  export_survey_fields = TRUE,
+  for_stata = FALSE,
+  col_types = NULL,
   redcap_uri = redcap_api_url(),
   token = redcap_token(),
   verbose = FALSE
 ) {
-  REDCapR::redcap_read_oneshot(
+  if (for_stata & is.null(col_types)) {
+    col_types = readr::cols(
+      "age_self_report" = readr::col_double(),
+      "date" = readr::col_character(),
+      "episode_date" = readr::col_character(),
+      "stable_time_years" = readr::col_double(),
+      "yrs_ago" = readr::col_character()
+    )
+    if (export_survey_fields)
+      col_types$cols = append(col_types$cols, list(
+        "carceral_system_timestamp" = readr::col_character(),
+        "children_timestamp" = readr::col_character(),
+        "consent_timestamp" = readr::col_character(),
+        "demographics_timestamp" = readr::col_character(),
+        "discrimination_timestamp" = readr::col_character(),
+        "eligibility_timestamp" = readr::col_character(),
+        "end_survey_and_rds_timestamp" = readr::col_character(),
+        "healthcare_utilization_timestamp" = readr::col_character(),
+        "history_of_homelessness_timestamp" = readr::col_character(),
+        "housing_services_timestamp" = readr::col_character(),
+        "housing_trajectory_timestamp" = readr::col_character(),
+        "income_employment_and_benefits_timestamp" = readr::col_character(),
+        "ipv_2_timestamp" = readr::col_character(),
+        "living_situation_timestamp" = readr::col_character(),
+        "lumpsumsubsidy_prevention_timestamp" = readr::col_character(),
+        "mental_health_3_timestamp" = readr::col_character(),
+        "physical_health_timestamp" = readr::col_character(),
+        "precipitants_to_homelessness_timestamp" = readr::col_character(),
+        "pregnancy_timestamp" = readr::col_character(),
+        "prescreen_timestamp" = readr::col_character(),
+        "rehousing_timestamp" = readr::col_character(),
+        "stable_housing_supplement_timestamp" = readr::col_character(),
+        "substance_use_2_timestamp" = readr::col_character()
+      ))
+  }
+
+  data = REDCapR::redcap_read_oneshot(
     ...,
+    export_survey_fields = export_survey_fields,
+    col_types = col_types,
     redcap_uri = redcap_uri,
     token = token,
     verbose = verbose
   )$data %>%
     dplyr::as_tibble()
+
+  if (for_stata) data = prepare_for_stata(data)
+
+  data
 }

R/prepare_for_stata.R

@@ -0,0 +1,24 @@
+prepare_for_stata = function(data) {
+  dplyr::rename_with(data, stata_safe_variable_names, everything())
+}
+
+stata_safe_variable_names = function(name) {
+  name %>%
+    # stata variables can't contain non-letters, numbers, or '_', so replace them with a '_'
+    strip_stata_illegal_char() %>%
+    strip_leading_digit() %>%
+    stata_name_truncate()
+}
+
+strip_stata_illegal_char = function(name) {
+  gsub("[^a-zA-Z0-9_]", "_", name)
+}
+
+strip_leading_digit = function(name) {
+  dplyr::if_else(grepl("^[0-9]", name), paste0("_", name), name)
+}
+
+stata_name_truncate = function(name) {
+  substr(name, 1, 32)
+}
+