diff --git a/DESCRIPTION b/DESCRIPTION index 975c09e..6212594 100644 --- a/DESCRIPTION +++ b/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", , "eve.perry@ucsf.edu", role = c("aut", "cre")) Description: Helper tools for the Statewide Survey. diff --git a/R/fetch_redcap_data.R b/R/fetch_redcap_data.R index cd4ca4a..99232f5 100644 --- a/R/fetch_redcap_data.R +++ b/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 } diff --git a/R/prepare_for_stata.R b/R/prepare_for_stata.R new file mode 100644 index 0000000..a079946 --- /dev/null +++ b/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) +} + diff --git a/man/adjust_sheltered_unsheltered.Rd b/man/adjust_sheltered_unsheltered.Rd index b0c3198..483c1f5 100644 --- a/man/adjust_sheltered_unsheltered.Rd +++ b/man/adjust_sheltered_unsheltered.Rd @@ -56,7 +56,7 @@ unsheltered (or neither). Returns a character vector with either "Sheltered", "Unsheltered, or NA. \item \code{calculate_adjusters}: Calculate the adjustment factors for -the sheltered and unsheltered PEH estimates +the sheltered and unsheltered PEH estimates. \item \code{adjust_count}: Make Sheltered/Unsheltered Adjustment diff --git a/man/fetch_redcap_data.Rd b/man/fetch_redcap_data.Rd index 7a07edd..2187c94 100644 --- a/man/fetch_redcap_data.Rd +++ b/man/fetch_redcap_data.Rd @@ -6,6 +6,9 @@ \usage{ fetch_redcap_data( ..., + export_survey_fields = TRUE, + for_stata = FALSE, + col_types = NULL, redcap_uri = redcap_api_url(), token = redcap_token(), verbose = FALSE @@ -14,6 +17,19 @@ fetch_redcap_data( \arguments{ \item{...}{Options passed to \code{\link[REDCapR:redcap_read]{REDCapR::redcap_read()}}.} +\item{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.)} + +\item{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.} + +\item{col_types}{Override default col_types for Stata by providing a +\code{\link[readr:cols]{readr::cols()}} specification.} + \item{redcap_uri}{REDCap API URL. Defaults to \code{\link[=redcap_api_url]{redcap_api_url()}}.} \item{token}{REDCap API Token. Defaults to main project token. Use RDS