Possibly Breaking Change

These changes could possibly break existing code --but it's very unlikely. We feel they will (directly and indirectly) improve the package considerably.

• redcap_read(), redcap_read_oneshot(), redcap_dag_read(), redcap_log_read(), and redcap_report() return a tibble instead of a data.frame. (#415)

  This should affect client code only if you expect a call like ds[, 3] to return a vector instead of a single-column data.frame/tibble. One solution is to upcast the tibble to a data.frame (with something like as.data.frame()). We recommend using an approach that works for both data.frames and tibbles, such as ds[[3]] or dplyr::pull(ds, "gender").

  For more information, read the short chapter in R for Data Science.

• The *_collapsed parameters are deprecated. When your want to limit on records/fields/forms/events, pass the vector of characters, not the scalar character separated by commas (which I think everyone does already). In other words use c("demographics", "blood_pressure") instead of "demographics,blood_pressure".

  Here are the relationships between the four pairs of variables:

  records_collapsed   <- collapse_vector(records  , records_collapsed)
  fields_collapsed    <- collapse_vector(fields   , fields_collapsed)
  forms_collapsed     <- collapse_vector(forms    , forms_collapsed)
  events_collapsed    <- collapse_vector(events   , events_collapsed)

  If someone is using the *_collapsed parameter, they can programmatically convert it to a vector like:

  field_names <- trimws(unlist(strsplit(field_names_collapsed, ",")))

• redcap_read() will automatically include the "plumbing" variables, even if they're not included the list of requested fields & forms. (#442). Specifically:

  • record_id (or it's customized name) will always be returned
  • redcap_event_name will be returned for longitudinal projects
  • redcap_repeat_instrument and redcap_repeat_instance will be returned for projects with repeating instruments

This will help extract forms from longitudinal & repeating projects.

• redcap_read() and redcap_read_oneshot() now return an empty dataset if no records are retrieved (such as no records meet the filter criteria). Currently a 0x0 tibble is returned, but that may change in the future. Until now an error was deliberately thrown. (#452)

• redcap_event_instruments() now by default returns mappings for all arms. The previous default was to return the mappings for only the first arm. To recreate the previous behavior use a call like REDCapR::redcap_event_instruments(uri, token_2, arms = "1"). (Suggested by @januz, #482)

• redcap_users_export() used to return a boolean for user_rights, but now it can be 0, 1, or 2. (#523)

New Features

• New redcap_metadata_coltypes() function. Inspects the fields types and validation text of each field to generate a suggested readr::col_types object that reflects the project's current data dictionary. The object then can be passed to the col_types parameter of redcap_read() or redcap_read_oneshot(). (Suggested and discussed with @pbchase, @nutterb, @skadauke, & others, #405 & #294)
• New redcap_log_read() function. Exports a project's log. (Thanks @joundso, #383, #320)
• New redcap_project_info_read() function. Exports a project's information, such as its language and production status. (Suggested by @skadauke, @timothytsai, @pbchase, #236, #410)
• New parameter blank_for_gray_form_status in the functions redcap_read(), redcap_read_oneshot(), and redcap_read_oneshot_eav(). (@greg-botwin, #386, #389)
• A httr::handle value is accepted by functions that contact the server. This will accommodate some institutions with unconventional environments. (Suggested by @brandonpotvin, #429)
• sanitized_token() now accepts an alternative regex pattern. (Suggested by @maeon & @michalkouril, #370)
• redcap_read_eav_oneshot() is an UNexported function that returns data in an EAV format (#437)
• redcap_metadata_read() now correctly subsets the forms (identified & corrected by @ezraporter, #431 & #445)
• New redcap_event_read() function. Exports metadata associated with a project's longitudinal events (@ezraporter, #457 & #460)

Minor Enhancements

• Better documentation for the server url (suggested by @sutzig #395)

• read_read_oneshot()'s parameter guess_max now allows floating point values to support readr::read_csv() ability to accept a Inf value. (Suggested by @eveyp, #392)

• pkgdown pages run & display the examples, but CRAN still doesn't run them. It's illegal to call external resources/APIs from CRAN computers --mostly because they are occasionally unavailable, so the code breaks. (#419)

• Renamed some functions to follow a consistent pattern. Old names will be soft-deprecated for a while before being removed. (#416)

  • redcap_download_file_oneshot() to redcap_file_download_oneshot()
  • redcap_file_upload_oneshot() to redcap_file_upload_oneshot()
  • redcap_download_instrument() to redcap_instrument_download()

• redcap_dag_read() has new data_access_group_id field (introduced maybe in 13.1.0) (#459)

• redcap_users_export() has new mycap_participants field (introduced maybe in 13.0.0) (#459)

• Accommodate older versions of REDCap that don't return project-level variable, like has_repeating_instruments_or_events, missing_data_codes, external_modules, bypass_branching_erase_field_prompt (@the-mad-statter, #465, #466)

• redcap_meta_coltypes() correctly determines data type for autonumber record_id fields. It suggests a character if the project has DAGs, and an integer if not. (@pwildenhain, #472)

• redcap_log_read() now returns a new column reflecting the affected record id value (ref #478)

• redcap_read() and redcap_read_oneshot() now remove "pseudofields" (e.g., redcap_event_name, redcap_repeat_instrument, & redcap_repeat_instance) from the fields parameter. Starting with REDCap v13.4.10, an error is thrown by the server. REDCap will return a message if a common pseudofield is requested explicitly by the user. (#477)

• redcap_event_instruments() now can return mappings for all arms, instead of one arm per call.(Suggested by @januz, #482)

• validate_for_write() contains a few more checks. (#485) The complete list is now:

  • validate_data_frame_inherits()
  • validate_field_names()
  • validate_record_id_name()
  • validate_uniqueness()
  • validate_repeat_instance()
  • validate_no_logical()

• redcap_read() checks the event parameter and throws an error if a value is not recognized, or the project is not longitudinal (#493)

• The regex in regex_named_captures() is forgiving if there's an unnecessary leading space (@BlairCooper, #495, #501)

• redcap_log_read() assumes all columns are character, except for timestamp (#525)

• redcap_file_download_oneshot() no longer asks for the unnecessary parameter for repeating_instrument (that the REDCap server ignores). (@BlairCooper, #506, #530)

• redcap_read() and redcap_read_oneshot() accommodate readr::read_csv()'s parameter of na. (Suggested by @rmtrane in #529)