OuhscBbmc / REDCapR

@@ -16,7 +16,7 @@
Loading
16 16
#'
17 17
#' @examples
18 18
#' uri     <- "https://bbmc.ouhsc.edu/redcap/api/"
19 -
#' token   <- "D70F9ACD1EDD6F151C6EA78683944E98"
19 +
#' token   <- "9A81268476645C4E5F03428B8AC3AA7B"
20 20
#' \dontrun{
21 21
#' project <- REDCapR::redcap_project$new(redcap_uri=uri, token=token)
22 22
#' ds_all  <- project$read()
@@ -31,6 +31,8 @@
Loading
31 31
#' ds_males        <- project$read(records=ids_of_males, batch_size=2)$data
32 32
#' ds_shorties     <- project$read(records=ids_of_shorties)$data
33 33
#'
34 +
#' }
35 +
#' if (FALSE) {
34 36
#' #Switch the Genders
35 37
#' sex_original   <- ds_skinny$sex
36 38
#' ds_skinny$sex  <- (1 - ds_skinny$sex)

@@ -59,7 +59,7 @@
Loading
59 59
#' administrator to send you the static material.
60 60
#'
61 61
#' @examples
62 -
#' \dontrun{
62 +
#' if (FALSE) {
63 63
#' #Define some constants
64 64
#' uri            <- "https://bbmc.ouhsc.edu/redcap/api/"
65 65
#' token          <- "D70F9ACD1EDD6F151C6EA78683944E98"

@@ -1,6 +1,8 @@
Loading
1 -
#' @title Read/Export records from a REDCap project
1 +
#' @title Suggests a col_type for each field in a REDCap project
2 2
#'
3 -
#' @description This function uses REDCap's API to select and return data.
3 +
#' @description This function inspects a REDCap project to
4 +
#' determine a [readr::cols()] object that is compatible with the
5 +
#' the project's current definition.
4 6
#'
5 7
#' @param redcap_uri The
6 8
#' [uri](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)/url
@@ -21,26 +23,90 @@
Loading
21 23
#' @param config_options  A list of options to pass to `POST` method in the
22 24
#' `httr` package.  See the details below. Optional.
23 25
#'
24 -
#' @return Currently, a list is returned with the following elements:
25 -
#' * `data`: A [tibble::tibble()] of the desired records and columns.
26 -
#' * `success`: A boolean value indicating if the operation was apparently
27 -
#' successful.
28 -
#' * `status_code`: The
29 -
#' [http status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
30 -
#' of the operation.
31 -
#' * `outcome_message`: A human readable string indicating the operation's
32 -
#' outcome.
33 -
#' * `elapsed_seconds`: The duration of the function.
34 -
#' * `raw_text`: If an operation is NOT successful, the text returned by
35 -
#' REDCap.  If an operation is successful, the `raw_text` is returned as an
36 -
#' empty string to save RAM.
26 +
#' @return A [readr::cols()] object is returned, which can be
27 +
#' passed to [redcap_read()] or [redcap_read_oneshot()].
28 +
#'
29 +
#' Additionally objected is printed to the console, see the Details below.
37 30
#'
38 31
#' @details
32 +
#' `redcap_metadata_coltypes()` returns a [readr::cols()] object in two ways.
33 +
#' First, a literal object is returned that can be passed to
34 +
#' [redcap_read()] or [redcap_read_oneshot()].
35 +
#'
36 +
#' Second, the function acts as a code generator.
37 +
#' It prints text to the console so that it can be copied
38 +
#' and pasted into an R file.  This is useful to (a) document what
39 +
#' fields and data types are expected, and (b) adjust those fields and
40 +
#' data types if the defaults can be customized for your needs.
41 +
#' For instance, you may choose to exclude some variables or tweak a
42 +
#' data type (*e.g.*, changing a patient's height from an integer to
43 +
#' a double).
44 +
#'
45 +
#' When printing to the console, each data type decision is accompanied
46 +
#' by an explanation on the far right.  See the output from the
47 +
#' examples below.  Please file an
48 +
#' [issue](https://github.com/OuhscBbmc/REDCapR/issues) if you think
49 +
#' something is too restrictive or can be improved.
50 +
#'
51 +
#' The overall heuristic is assign a data type down a waterfall of decisions:
52 +
#'
53 +
#' 1. Is the field built into REDCap? This includes
54 +
#' an autonumber `record_id`,
55 +
#' `redcap_event_name`, `redcap_repeat_instrument`, `redcap_repeat_instance`,
56 +
#' and an instrument's completion status.
57 +
#'
58 +
#' 2. What is the field's type?  For example, sliders should be an
59 +
#' [integer](https://stat.ethz.ch/R-manual/R-devel/library/base/html/integer.html),
60 +
#' while check marks should be
61 +
#' [logical](https://stat.ethz.ch/R-manual/R-devel/library/base/html/logical.html.
62 +
#'
63 +
#' 3. If the field type is "text", what is the validation type?
64 +
#' For instance, a postal code should be a
65 +
#' [character](https://stat.ethz.ch/R-manual/R-devel/library/base/html/character.html)
66 +
#' (even though it looks like a number),
67 +
#' a "mdy" should be cast to a
68 +
#' [date](https://stat.ethz.ch/R-manual/R-devel/library/base/html/date.html),
69 +
#' and a "number_2dp" should be cast to a
70 +
#' [floating point](https://stat.ethz.ch/R-manual/R-devel/library/base/html/double.html)
71 +
#'
72 +
#' 4. If the field type or validation type is not recognized,
73 +
#' the field will be cast to
74 +
#' [character](https://stat.ethz.ch/R-manual/R-devel/library/base/html/character.html).
75 +
#' This will happen when REDCap develops & releases a new type.
76 +
#' If you see something like, "# validation doesn't have an associated col_type.
77 +
#' Tell us in a new REDCapR issue", please make sure REDCapR is running the newest
78 +
#' [GitHub release](https://ouhscbbmc.github.io/REDCapR/index.html#installation-and-documentation)
79 +
#' and file a new [issue](https://github.com/OuhscBbmc/REDCapR/issues) if it's still not
80 +
#' recognized.
81 +
#'
82 +
#' For details of the current implementation,
83 +
#' the decision logic starts about half-way down in the
84 +
#' [function's source code](https://github.com/OuhscBbmc/REDCapR/blob/HEAD/R/redcap-metadata-coltypes.R)
85 +
#'
86 +
#' **Validation does NOT Guarantee Conformity*
87 +
#'
88 +
#' If you're coming to REDCap from a database world, this will be unexpected.
89 +
#' A validation type does NOT guarantee that all retrieved values will conform to
90 +
#' complementary the data type.
91 +
#' The validation setting affects only the values entered
92 +
#' *after* the validation was set.
93 +
#'
94 +
#' For example, if values like "abcd" where entered in a field for a few months, then
95 +
#' the project manager selected the "integer" validation option, all those
96 +
#' "abcd" values remain untouched.
97 +
#'
98 +
#' This is one reason `redcap_metadata_coltypes` prints it suggestions to the console.
99 +
#' It allows the developer to adjust the specifications to match the values
100 +
#' returned by the API.  The the "abcd" scenario, consider (a) changing the type
101 +
#' from `col_integer` to `col_character`, (b) excluding the trash values,
102 +
#' then (c) in a [dplyr::mutate()] statement,
103 +
#' use [readr::parse_integer()] to cast it to the desired type.
104 +
#'
39 105
#' The full list of configuration options accepted by the `httr` package is
40 106
#' viewable by executing [httr::httr_options()].  The `httr` package and
41 107
#' documentation is available at https://cran.r-project.org/package=httr.
42 108
#'
43 -
#' @author Will Beasley
109 +
#' @author Will Beasley, Philip Chase
44 110
#'
45 111
#' @references The official documentation can be found on the 'API Help Page'
46 112
#' and 'API Examples' pages on the REDCap wiki (*i.e.*,
@@ -53,15 +119,27 @@
Loading
53 119
#' \dontrun{
54 120
#' uri      <- "https://bbmc.ouhsc.edu/redcap/api/"
55 121
#'
56 -
#' # A simple project with a variety of types
57 -
#' token    <- "9A81268476645C4E5F03428B8AC3AA7B" # 153 - Simple
58 -
#' redcap_metadata_coltypes(uri, token)
122 +
#' # A simple project
123 +
#' token      <- "9A81268476645C4E5F03428B8AC3AA7B" # 153
124 +
#' col_types  <- redcap_metadata_coltypes(uri, token)
125 +
#' redcap_read_oneshot(uri, token, col_types = col_types)$data
126 +
#'
127 +
#' # A longitudinal project
128 +
#' token      <- "0434F0E9CF53ED0587847AB6E51DE762" # 212
129 +
#' col_types  <- redcap_metadata_coltypes(uri, token)
130 +
#' redcap_read_oneshot(uri, token, col_types = col_types)$data
131 +
#'
132 +
#' # A repeating instruments project
133 +
#' token      <- "56F43A10D01D6578A46393394D76D88F" # 2603
134 +
#' col_types  <- redcap_metadata_coltypes(uri, token)
135 +
#' redcap_read_oneshot(uri, token, col_types = col_types)$data
59 136
#'
60 -
#' # This project includes every field type and validation type.
61 -
#' #   It throws a warning that some fields use a comma for a decimal,
137 +
#' # A project with every field type and validation type.
138 +
#' #   Notice It throws a warning that some fields use a comma for a decimal,
62 139
#' #   while other fields use a period/dot as a decimal
63 -
#' token    <- "8F5313CAA266789F560D79EFCEE2E2F1" # 2634 - Validation Types
64 -
#' redcap_metadata_coltypes(uri, token)
140 +
#' token      <- "8F5313CAA266789F560D79EFCEE2E2F1" # 2634 - Validation Types
141 +
#' col_types  <- redcap_metadata_coltypes(uri, token)
142 +
#' redcap_read_oneshot(uri, token, col_types = col_types)$data
65 143
#' }
66 144
67 145
#' @importFrom magrittr %>%
@@ -183,6 +261,7 @@
Loading
183 261
          field_type == "event_name"                          ~ paste0("col_character()"                      , "~~longitudinal event_name"),
184 262
          field_type == "repeat_instrument"                   ~ paste0("col_character()"                      , "~~repeat_instrument"),
185 263
          field_type == "repeat_instance"                     ~ paste0("col_integer()"                        , "~~repeat_instance"),
264 +
          field_type == "complete"                            ~ paste0("col_integer()"                        , "~~completion status of form/instrument"),
186 265
          field_type == "truefalse"                           ~ paste0("col_logical()"                        , "~~field_type is truefalse"),
187 266
          field_type == "yesno"                               ~ paste0("col_logical()"                        , "~~field_type is yesno"),
188 267
          field_type == "checkbox"                            ~ paste0("col_logical()"                        , "~~field_type is checkbox"),
@@ -196,7 +275,6 @@
Loading
196 275
          field_type == "sql"                                 ~ paste0("col_character()"                      , "~~field_type is sql"),
197 276
          field_type == "text" & is.na(vt)                    ~ paste0("col_character()"                      , "~~field_type is text and validation isn't set"),
198 277
          field_type == "text" & vt == ""                     ~ paste0("col_character()"                      , "~~field_type is text and validation isn't set"),
199 -
          is.na(field_type) & vt == "complete"                ~ paste0("col_integer()"                        , "~~indicates completion status of form/instrument"),
200 278
          vt == "alpha_only"                                  ~ paste0("col_character()"                      , "~~validation is 'alpha_only'"),
201 279
          vt == "date_dmy"                                    ~ paste0("col_date()"                           , "~~validation is 'date_dmy'"),
202 280
          vt == "date_mdy"                                    ~ paste0("col_date()"                           , "~~validation is 'date_mdy'"),

@@ -72,7 +72,7 @@
Loading
72 72
#' administrator to send you the static material.
73 73
#'
74 74
#' @examples
75 -
#' \dontrun{
75 +
#' if (FALSE) {
76 76
#' #Define some constants
77 77
#' uri           <- "https://bbmc.ouhsc.edu/redcap/api/"
78 78
#' token         <- "D70F9ACD1EDD6F151C6EA78683944E98"

@@ -87,11 +87,8 @@
Loading
87 87
#' token_longitudinal   <- "0434F0E9CF53ED0587847AB6E51DE762"
88 88
#'
89 89
#' # ---- Simple examples
90 -
#' d1 <- REDCapR::redcap_project_info_read(uri, token_simple      )$data
91 -
#' View(d1)
92 -
#'
93 -
#' d2 <- REDCapR::redcap_project_info_read(uri, token_longitudinal)$data
94 -
#' View(d2)
90 +
#' REDCapR::redcap_project_info_read(uri, token_simple      )$data
91 +
#' REDCapR::redcap_project_info_read(uri, token_longitudinal)$data
95 92
#'
96 93
#' # ---- Specify timezone
97 94
#' # Specify the server's timezone, for example, US Central
@@ -122,10 +119,11 @@
Loading
122 119
#'   purrr::pmap_dfr(REDCapR::redcap_project_info_read, locale = server_locale)
123 120
#'
124 121
#' # Inspect values stored on the server.
125 -
#' View(d_all$data)
122 +
#' d_all$data
123 +
#' # or: View(d_all$data)
126 124
#'
127 125
#' # Inspect everything returned, including values like the http status code.
128 -
#' View(d_all)
126 +
#' d_all
129 127
#' }
130 128
131 129
#' @export

@@ -56,7 +56,7 @@
Loading
56 56
#' administrator to send you the static material.
57 57
#'
58 58
#' @examples
59 -
#' \dontrun{
59 +
#' if (FALSE) {
60 60
#' records_to_delete <- c(102, 103, 105, 120)
61 61
#'
62 62
#' # Deleting from a non-longitudinal project with no defined arms:
Files Coverage
R 95.99%
Project Totals (40 files) 95.99%
1
comment: false
2

3
coverage:
4
  status:
5
    project:
6
      default:
7
        target: auto
8
        threshold: 3%
9
    patch:
10
      default:
11
        target: auto
12
        threshold: 3%
Sunburst
The inner-most circle is the entire project, moving away from the center are folders then, finally, a single file. The size and color of each slice is representing the number of statements and the coverage, respectively.
Icicle
The top section represents the entire project. Proceeding with folders and finally individual files. The size and color of each slice is representing the number of statements and the coverage, respectively.
Grid
Each block represents a single file in the project. The size and color of each block is represented by the number of statements and the coverage, respectively.
Loading