OuhscBbmc / REDCapR

@@ -152,7 +152,7 @@
Loading
152 152
      silent = TRUE
153 153
    )
154 154
155 -
    if (exists("ds") & inherits(ds, "data.frame")) {
155 +
    if (exists("ds") && inherits(ds, "data.frame")) {
156 156
      outcome_message <- sprintf(
157 157
        "%s rows were read from REDCap in %0.1f seconds.  The http status code was %i.",
158 158
        format(  nrow(ds), big.mark = ",", scientific = FALSE, trim = TRUE),

@@ -10,6 +10,7 @@
Loading
10 10
# This function isn't used during testing itself.  Just to create the expected file.
11 11
save_expected <- function(o, path) {
12 12
  # nocov start
13 +
  attr(returned_object$data, which = "problems") <- NULL
13 14
  path <- file.path("inst", path)
14 15
  if (!dir.exists(dirname(path))) dir.create(dirname(path), recursive = FALSE)
15 16

@@ -14,7 +14,7 @@
Loading
14 14
#' 32-character hexadecimal value.  The pattern that validates their tokens
15 15
#' can be specified with the system environmental variable
16 16
#' `REDCAP_TOKEN_PATTERN` using
17 -
#' [`base::Sys.setenv()`](base::Sys.setenv).
17 +
#' [base::Sys.setenv].
18 18
#'
19 19
#' For example, the following regex pattern captures a
20 20
#' [base64 encoded value]() with 40 characters:

@@ -0,0 +1,259 @@
Loading
1 +
#' @title Export project information.
2 +
#'
3 +
#' @description This function exports some of the basic attributes of a given
4 +
#' REDCap project, such as the project's title, if it is longitudinal,
5 +
#' if surveys are enabled, the time the project was created and moved to
6 +
#' production.  Returns a [tibble::tibble()].
7 +
#'
8 +
#' @param redcap_uri The
9 +
#' [uri](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier)/url
10 +
#' of the REDCap server
11 +
#' typically formatted as "https://server.org/apps/redcap/api/".
12 +
#' Required.
13 +
#' @param token The user-specific string that serves as the password for a
14 +
#' project.  Required.
15 +
#' @param http_response_encoding  The encoding value passed to
16 +
#' [httr::content()].  Defaults to 'UTF-8'.
17 +
#' @param locale a [readr::locale()] object to specify preferences like
18 +
#' number, date, and time formats.  This object is passed to
19 +
#' [`readr::read_csv()`].  Defaults to [readr::default_locale()].
20 +
#' @param verbose A boolean value indicating if `message`s should be printed
21 +
#' to the R console during the operation.  The verbose output might contain
22 +
#' sensitive information (*e.g.* PHI), so turn this off if the output might
23 +
#' be visible somewhere public. Optional.
24 +
#' @param config_options  A list of options to pass to `POST` method in the
25 +
#' `httr` package.
26 +
#'
27 +
#' @return Currently, a list is returned with the following elements:
28 +
#' * `data`: An R [tibble::tibble()] of all data access groups of the project.
29 +
#' * `success`: A boolean value indicating if the operation was apparently
30 +
#' successful.
31 +
#' * `status_codes`: A collection of
32 +
#' [http status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes),
33 +
#' separated by semicolons.  There is one code for each batch attempted.
34 +
#' * `outcome_messages`: A collection of human readable strings indicating the
35 +
#' operations' semicolons.  There is one code for each batch attempted.  In an
36 +
#' unsuccessful operation, it should contain diagnostic information.
37 +
#' * `elapsed_seconds`: The duration of the function.
38 +
#'
39 +
#' @details
40 +
#'
41 +
#' **Timezones**
42 +
#'
43 +
#' Several datetime variables are returned, such as the project's
44 +
#' `creation_time`.  For the time to be meaningful, you'll need to set
45 +
#' the time zone because this function uses [readr::read_csv()],
46 +
#' which assigns
47 +
#' [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time)
48 +
#' if no timezone is specified.  Find your server's location listed in
49 +
#' [base::OlsonNames()], and pass it to readr's [readr::locale()] function,
50 +
#' and then pass that to `redcap_project_info_read()`.  See the examples below
51 +
#'
52 +
#' For more timezone details see the
53 +
#' [Timezones](https://readr.tidyverse.org/articles/locales.html#timezones)
54 +
#' section of readr's
55 +
#' [locales](https://readr.tidyverse.org/articles/locales.html) vignette.
56 +
#'
57 +
#' **Columns not yet added**
58 +
#' This function casts columns into data types that we think are most natural to
59 +
#' use.  For example, `in_production` is cast from a 0/1 to a
60 +
#' boolean TRUE/FALSE.  All columns not (yet) recognized by REDCapR will be
61 +
#' still be returned to the client, but cast as a character.
62 +
#' If the REDCap API adds a new column in the future,
63 +
#' please alert us in a
64 +
#' [REDCapR issue](https://github.com/OuhscBbmc/REDCapR/issues) and we'll
65 +
#' expand the casting specifications.
66 +
#'
67 +
#' **External Modules**
68 +
#'
69 +
#' A project's `external_modules` cell contains all its approved EMs,
70 +
#' separated by a column.  Consider using a function like
71 +
#' [tidyr::separate_rows()] to create a long data structure.
72 +
#'
73 +
#' @author Will Beasley, Stephan Kadauke
74 +
#' @references The official documentation can be found on the 'API Help Page'
75 +
#' and 'API Examples' pages on the REDCap wiki (*i.e.*,
76 +
#' https://community.projectredcap.org/articles/456/api-documentation.html
77 +
#' and
78 +
#' https://community.projectredcap.org/articles/462/api-examples.html).
79 +
#' If you do not have an account for the wiki, please ask your campus REDCap
80 +
#' administrator to send you the static material.
81 +
#'
82 +
#' @examples
83 +
#' \dontrun{
84 +
#' # Specify your project uri and token(s).
85 +
#' uri                  <- "https://bbmc.ouhsc.edu/redcap/api/"
86 +
#' token_simple         <- "9A81268476645C4E5F03428B8AC3AA7B"
87 +
#' token_longitudinal   <- "0434F0E9CF53ED0587847AB6E51DE762"
88 +
#'
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)
95 +
#'
96 +
#' # ---- Specify timezone
97 +
#' # Specify the server's timezone, for example, US Central
98 +
#' server_locale <- readr::locale(tz = "America/Chicago")
99 +
#' d3 <-
100 +
#'   REDCapR::redcap_project_info_read(
101 +
#'     uri,
102 +
#'     token_simple,
103 +
#'     locale     = server_locale
104 +
#'   )$data
105 +
#' d3$creation_time
106 +
#'
107 +
#' # Alternatively, set timezone to the client's location.
108 +
#' client_locale <- readr::locale(tz = Sys.timezone())
109 +
#'
110 +
#' # ---- Inspect multiple projects in the same tibble
111 +
#' # Stack all the projects on top of each other in a (nested) tibble,
112 +
#' #   starting from a csv of REDCapR test projects.
113 +
#' # The native pipes in this snippet require R 4.1+.
114 +
#' d_all <-
115 +
#'   system.file("misc/example.credentials", package = "REDCapR") |>
116 +
#'   readr::read_csv(
117 +
#'     comment     = "#",
118 +
#'     col_select  = c(redcap_uri, token),
119 +
#'     col_types   = readr::cols(.default = readr::col_character())
120 +
#'   ) |>
121 +
#'   dplyr::filter(32L == nchar(token)) |>
122 +
#'   purrr::pmap_dfr(REDCapR::redcap_project_info_read, locale = server_locale)
123 +
#'
124 +
#' # Inspect values stored on the server.
125 +
#' View(d_all$data)
126 +
#'
127 +
#' # Inspect everything returned, including values like the http status code.
128 +
#' View(d_all)
129 +
#' }
130 +
131 +
#' @export
132 +
redcap_project_info_read <- function(
133 +
  redcap_uri,
134 +
  token,
135 +
  http_response_encoding        = "UTF-8",
136 +
  locale                        = readr::default_locale(),
137 +
  verbose                       = TRUE,
138 +
  config_options                = NULL
139 +
) {
140 +
  checkmate::assert_character(redcap_uri                , any.missing = FALSE, len = 1, pattern = "^.{1,}$")
141 +
  checkmate::assert_character(token                     , any.missing = FALSE, len = 1, pattern = "^.{1,}$")
142 +
143 +
  checkmate::assert_character(http_response_encoding    , any.missing=FALSE,   len = 1)
144 +
  checkmate::assert_class(    locale, classes = "locale", null.ok = FALSE)
145 +
  checkmate::assert_logical(  verbose                   , any.missing=FALSE,   len = 1, null.ok = TRUE)
146 +
  checkmate::assert_list(     config_options            , any.missing=TRUE ,            null.ok = TRUE)
147 +
148 +
  token               <- sanitize_token(token)
149 +
  verbose             <- verbose_prepare(verbose)
150 +
151 +
  post_body <- list(
152 +
    token                   = token,
153 +
    content                 = "project",
154 +
    format                  = "csv"
155 +
  )
156 +
157 +
  # This is the important line that communicates with the REDCap server.
158 +
  kernel <- kernel_api(
159 +
    redcap_uri      = redcap_uri,
160 +
    post_body       = post_body,
161 +
    config_options  = config_options,
162 +
    encoding        = http_response_encoding
163 +
  )
164 +
165 +
  col_types <- readr::cols(
166 +
    project_id                              = readr::col_integer(),
167 +
    project_title                           = readr::col_character(),
168 +
    creation_time                           = readr::col_datetime(format = ""),
169 +
    production_time                         = readr::col_datetime(format = ""),
170 +
    in_production                           = readr::col_logical(),
171 +
    project_language                        = readr::col_character(),
172 +
    purpose                                 = readr::col_integer(),
173 +
    purpose_other                           = readr::col_character(),
174 +
    project_notes                           = readr::col_character(),
175 +
    custom_record_label                     = readr::col_character(),
176 +
    secondary_unique_field                  = readr::col_character(),
177 +
    is_longitudinal                         = readr::col_logical(),
178 +
    has_repeating_instruments_or_events     = readr::col_logical(),
179 +
    surveys_enabled                         = readr::col_logical(),
180 +
    scheduling_enabled                      = readr::col_logical(),
181 +
    record_autonumbering_enabled            = readr::col_logical(),
182 +
    randomization_enabled                   = readr::col_logical(),
183 +
    ddp_enabled                             = readr::col_logical(),
184 +
    project_irb_number                      = readr::col_character(),
185 +
    project_grant_number                    = readr::col_character(),
186 +
    project_pi_firstname                    = readr::col_character(),
187 +
    project_pi_lastname                     = readr::col_character(),
188 +
    display_today_now_button                = readr::col_logical(),
189 +
    missing_data_codes                      = readr::col_character(),
190 +
    external_modules                        = readr::col_character(),
191 +
    bypass_branching_erase_field_prompt     = readr::col_character(),
192 +
    .default                                = readr::col_character()
193 +
  )
194 +
195 +
  if (kernel$success) {
196 +
    try(
197 +
      # Convert the raw text to a dataset.
198 +
      ds <-
199 +
        readr::read_csv(
200 +
          file            = I(kernel$raw_text),
201 +
          locale          = locale,
202 +
          col_types       = col_types,
203 +
          show_col_types  = FALSE
204 +
        ),
205 +
206 +
      # Don't print the warning in the try block.  Print it below,
207 +
      #   where it's under the control of the caller.
208 +
      silent = TRUE
209 +
    )
210 +
211 +
    if (exists("ds") && inherits(ds, "data.frame")) {
212 +
      outcome_message <- sprintf(
213 +
        "%s rows were read from REDCap in %0.1f seconds.  The http status code was %i.",
214 +
        format(  nrow(ds), big.mark = ",", scientific = FALSE, trim = TRUE),
215 +
        kernel$elapsed_seconds,
216 +
        kernel$status_code
217 +
      )
218 +
219 +
      # If an operation is successful, the `raw_text` is no longer returned to
220 +
      #   save RAM.  The content is not really necessary with httr's status
221 +
      #   message exposed.
222 +
      kernel$raw_text   <- ""
223 +
    } else { # ds doesn't exist as a tibble.
224 +
      # nocov start
225 +
      # Override the 'success' determination from the http status code.
226 +
      #   and return an empty tibble
227 +
      kernel$success   <- FALSE
228 +
      ds               <- tibble::tibble()
229 +
      outcome_message  <- sprintf(
230 +
        "The REDCap log export failed.  The http status code was %i.  The 'raw_text' returned was '%s'.",
231 +
        kernel$status_code,
232 +
        kernel$raw_text
233 +
      )
234 +
      # nocov end
235 +
    }
236 +
  } else { # kernel fails
237 +
    ds              <- tibble::tibble() #Return an empty tibble
238 +
    outcome_message <- if (any(grepl(kernel$regex_empty, kernel$raw_text))) {
239 +
      "The REDCapR log export operation was not successful.  The returned dataset was empty."  # nocov
240 +
    } else {
241 +
      sprintf(
242 +
        "The REDCapR log export operation was not successful.  The error message was:\n%s",
243 +
        kernel$raw_text
244 +
      )
245 +
    }
246 +
  }
247 +
248 +
  if (verbose)
249 +
    message(outcome_message)
250 +
251 +
  list(
252 +
    data               = ds,
253 +
    success            = kernel$success,
254 +
    status_code        = kernel$status_code,
255 +
    outcome_message    = outcome_message,
256 +
    elapsed_seconds    = kernel$elapsed_seconds,
257 +
    raw_text           = kernel$raw_text
258 +
  )
259 +
}
Files Coverage
R 95.67%
Project Totals (39 files) 95.67%
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