Quick links:
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
returnedredcap_event_name will be returned for longitudinal
projectsredcap_repeat_instrument and
redcap_repeat_instance will be returned for projects with
repeating instrumentsThis 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)
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)redcap_log_read() function. Exports a project’s
log. (Thanks @joundso, #383, #320)redcap_project_info_read() function. Exports a
project’s information, such as its language and production status.
(Suggested by @skadauke, @timothytsai, @pbchase, #236, #410)blank_for_gray_form_status in the
functions redcap_read(),
redcap_read_oneshot(), and
redcap_read_oneshot_eav(). (@greg-botwin, #386, #389)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)redcap_event_read() function. Exports metadata
associated with a project’s longitudinal events (@ezraporter, #457 & #460)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)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)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)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)redcap_delete() function. It deletes a vector of
records. (Thanks @joundso, #372, #373)redcap_arm_export() function. It retrieves a list
of REDCap project arms. (#375)redcap_read() and redcap_read_oneshot()
accept a new locale parameter that specifies date, time,
and number formats, like using a comma as the decimal separator. It is a
readr::locale
object. (#377, suggested by @joundso)redcap_instruments() function exports a list of the
data collection instruments for a project. (#381, @vcastro)redcap_event_instruments() function exports the
instrument-event mappings for a project (i.e., how the data collection
instruments are designated for certain events in a longitudinal
project). (#381, @vcastro)redcap_dag_read() function returns the Data Access
Groups for a project (#382, @joundso)sanitize_token() now allows lowercase characters –in
addition to uppercase characters & digits. (#347, @jmbarbone)redcap_metadata_read() now uses json (instead of csv)
to transfer the dictionary between server & client. This
accommodates super-wide dictionaries with 35k+ variables. The user
shouldn’t notice a difference, and still will receive a data.frame.
(#335, @januz &
@datalorax)testthat::skip_on_cran() calls to
comply with CRAN’s “fail
gracefully” policy. Similarly, skip remaining examples that depend
on external resources. (#352)retrieve_credential_local() can now user
username to identify the desired credential row (#364)redcap_read() and redcap_read_oneshot()
gain the http_response_encoding parameter that’s passed to
httr::content().
The default value remains “UTF-8”. (#354, @lrasmus)redcap_users_export() (which calls REDCap’s user
export). The API dropped the data_export variable and added
the forms_export variable. (#396)redcap_read_oneshot_eav(): if the project isn’t
longitudinal, a dummy value for event_id is used internally
(#396)httr::user_agent, following the advice of httr’s
vignette (#397)The package has been stable for years and should be reflected in the major version number.
redcap_write() and redcap_write_oneshot() have
a new parameter that converts R’s logical/boolean columns
to integers. This meshes well with T/F and Y/N items that are coded as
1/0 underneath. The default will be FALSE (ie, the integers are not
converted by default), so it doesn’t break existing code. (#305)redcap_write() and redcap_write_oneshot() can
toggle the ability to overwrite with blank/NA cells (suggested by @auricap, #315)redcap_read_oneshot(),
redcap_read(), & redcap_read_oneshot_eav()
now support the parameters datetime_range_begin and
datetime_range_end. The are passed to the REDCap parameters
dateRangeBegin and dateRangeEnd, which
restricts records returned, based on their last modified date in the
server. (Thanks @pbchase, #321 & #323.)export_survey_fields
parameter in the functions redcap_read() &
redcap_read_oneshot(). (Thanks @isaactpetersen, #333)redcap_report()
export records that populate a REDCap report. (#326.)create_credential_local()
starts a well-formed csv file that can contain tokens. (#340, after
conversations with @higgi13425 & @kamclean.)config_option element. (Proposed
by @BastienRance, #307)success value returned by
redcap_read() and redcap_write() when the
parameter continue_on_error is true. (Bug found by @llrs, #317)redcap_survey_link_export_oneshot()
documentation corrected & improved (@jrob95, #526)kernel_api()
defaults to “text/csv” and UTF-8 encoding. Formerly, the function would
decide on the content-type and encoding. More details are below in the
‘Stability Features’ subsection.
constant()
no longer accepts simplify as an options. An integer vector
is always returned. (#280)
It’s now possible to specify the exact col_types (a
readr::cols
object) that is passed to readr::read_csv() inside redcap_read_oneshot().
(#258)
reader::type_convert()
is used after all the batches are stacked on top of each other.
This way, batches cannot have incompatible data types as they’re
combined. (#257; thanks @isaactpetersen #245) Consequently,
the guess_max parameter in redcap_read() no
longer serves a purpose, and has been soft-deprecated. (#267)
redcap_metadata_write()
writes to the project’s metadata. (#274, @felixetorres)
redcap_survey_link_export_oneshot()
retrieves the URL to a specific record’s survey (e.g.,
“https://redcap-dev-2.ouhsc.edu/redcap/surveys/?s=8KuzSLMHf6”)
(#293)
convert_logical_to_integer is a new parameter for redcap_write()
and redcap_write_oneshot().
If TRUE, all [base::logical] columns in ds are
cast to an integer before uploading to REDCap. Boolean values are
typically represented as 0/1 in REDCap radio buttons. Defaults to
FALSE to maintain backwards compatibility. (#305)
httr::content() (which is inside
kernel_api()) now processes the returned value as
“text/csv”, by default. This should prevent strange characters from
tricking the process as the internal variable raw_text is
being formed. See the
[httr::content()](https://httr.r-lib.org/reference/content.html) documentation for a list of possible values for thecontent_type`
parameter. (Thanks to great debugging by @vortexing #269, @sybandrew #272, & @begavett, #290)
Similarly, kernel_api() now has an
encoding parameter, which defaults to “UTF-8”.
(#270)
‘checkmate’ package is now imported, not suggested (Thanks @dtenenba, #255).
Allow more than one httr::config() parameter to be
passed (Thanks @BastienRance, #307).
redcap_next_free_record_name(): API call for ‘Generate
Next Record Name’, which returns the next available record ID (Issue
#237)redcap_read() and redcap_read_oneshot()
allow the user to specify if all variables should be returned with the
character data type. The default is to allow
readr::read_csv() to guess the data type. (#194)redcap_read_oneshot() allows use to specify how many
rows should be considered when readr::read_csv() guesses
the data type. (#194)redcap_read(), redcap_read_oneshot(), and
redcap_read_oneshot_eav() always return Linux-style line
endings (ie \n) instead of Windows style line endings (ie,
\r\n) on all OSes. (#198)read_metadata() always returns character
vectors for all variables. With readr 1.2.0, some column were returned
differently than before. (#193)redcap_users_export() now included (#163)redcap_read(),
redcap_read_oneshot(), &
redcap_read_oneshot_eav()(#206). It was already implemented
for redcap_metadata_read().constants()) easily exposes
REDCap-specific constants. (#217)id_position allows user to specify if the record_id
isn’t in the first position (#207). However, we recommend that all
REDCap projects keep this important variable first in the data
dictionary.redcap_read() and
redcap_read_oneshot() are more consistent with the order in
raw REDCap API. (#204)verbose parameter is NULL, then the value from
getOption(“verbose”) is used. (#215)guess_max parameter provided in
redcap_read() (no longer just
redcap_read_oneshot()). Suggested by @isaactpetersen in #245.redcap_variables() now throws an error when passed a
bad URI (commit e542155639bbb7).kernal_api() function, which uses the ‘httr’ and ‘curl’
packages underneath. Until now, each function called those packages
directly. (#213)readr::read_csv() is used instead of
utils::read.csv() (Issue #127).odbc package to retrieve credentials from the
token server. Remove RODBC and RODBCext (#188). Thanks to @krlmlr for error checking
advice in https://stackoverflow.com/a/50419403/1082435.data.table::rbindlist() replaced by
dplyr::bind_rows()testit::assert() and base:stop() ) (#190
& #208).collapse_vector() is refactored and tested (#209)pkgload package (#218)retrieve_token_mssql(), because
retrieve_credential_mssql() is more general and more
useful.redcap_variables().redcap_read_oneshot_eav(),
which can be accessed with a triple colon (ie,
REDCapR::redcap_read_oneshot_eav()).redcap_read() and
redcap_read_oneshot() (PR #126)retrieve_credential_mssql() and
retrieve_credential_local(). These transition from storing
& retrieving just the token (ie,
retrieve_token_mssql()) to storing & retrieving more
information. retrieve_credential_local() facilitates a
standard way of storing tokens locally, which should make it easier to
follow practices of keeping it off the repository.data.table::rbindlist() is used. This should prevent errors
with the first batch’s data type (for a column) isn’t compatible with a
later batch. For instance, this occurs when the first batch has only
integers for record_id, but a subsequent batch has values
like aa-test-aa. The variable for the combined dataset
should be a character. (Issue #128 & https://stackoverflow.com/questions/39377370/bind-rows-of-different-data-types;
Thanks @arunsrinivasan)dplyr package instead of plyr.
This shouldn’t affect callers, because immediately before returning the
data, REDCapR::redcap_read() coerces the
tibble::tibble (which was formerly called
dplyr::tbl_df) back to a vanilla data.frame
with as.data.frame().retrieve-token() tests now account for the (OS X)
builds where the RODBC package isn’t available.curl package, instead of RCurl).requireNamespace() instead of
require().readcap_read() is being
used without ‘Full Data Set’ export privileges. The problem involves the
record IDs are hashed.id_position in the
first stage of batching. The metadata needed to be read before that,
after the updates for REDCap Version 6.0.x.retrieve_token_mssql() uses regexes to validate
parametersconfig_options in the httr package are exposed to
the REDCapR user. See issues #55 & #58; thanks to @rparrish and @nutterb for their
contributions (https://github.com/OuhscBbmc/REDCapR/issues/55 & https://github.com/OuhscBbmc/REDCapR/issues/58).redcap_metadata_read() are tested and public.testthat::skip_on_cran() before any
call involving OUHSC’s REDCap server.redcap_write() and redcap_write_oneshot()
are now tested and public.redcap_write() and redcap_write_oneshot()
are now tested and public.redcap_download_file_oneshot() function contributed by
John Aponte (@johnaponte; Pull request #35)redcap_upload_file_oneshot() function contributed by
@johnaponte (Pull
request #34)verbose==TRUE. Follows advice of @johnaponte, Benjamin Nutter (@nutterb), and Rollie
Parrish (@rparrish).
Closes #43.records_collapsed default empty value is now an
empty string (i.e., "") instead of
NULL. This applies when records_collapsed is
either a parameter, or a returned value.redcap_download_file_oneshot()
documentation, thanks to Andrew Peters (@ARPeters #45).httr package, which provides benefits
like the status code message can be captured (eg, 200-OK, 403-Forbidden,
404-NotFound). See https://cran.r-project.org/package=httr.status_message to
outcome_message. This is because the message associated
with http code returned is conventionally called the ‘status messages’
(eg, OK, Forbidden, Not Found).raw_text value
(which was formerly called raw_csv) is returned as an empty
string to save RAM. It’s not really necessary with httr’s status message
exposed.redcap_column_sanitize() function to address
non-ASCII charactersredcap_write() (as an internal function).redcap_project() object reduces repeatedly passing
parameters like the server URL, the user token, and the SSL cert
location.redcap_read_batch() to
redcap_read(). These changes reflect our suggestion that
reads should typically be batched.redcap_read() to
redcap_read_oneshot()redcap_write() to
redcap_write_oneshot() (which is an internal
function).redcap_read() and
redcap_read_batch() with documentationredcap_read() takes parameter for
raw_or_label (Thanks Rollie Parrish #3)redcap_read() takes parameter for
export_data_access_groups thanks to Rollie Parrish (@rparrish #4)GitHub Commits and Releases