These features are not yet on CRAN. Install with
These changes could possibly break existing code –but it’s very unlikely. We feel they will (directly and indirectly) improve the package considerably.
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
For more information, read the short chapter in R for Data Science.
*_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
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:
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_namewill be returned for longitudinal projects
redcap_repeat_instancewill be returned for projects with repeating instruments
This will help extract forms from longitudinal & repeating projects.
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_metadata_coltypes()function. Inspects the fields types and validation text of each field to generate a suggested
readr::col_typesobject that reflects the project’s current data dictionary. The object then can be passed to the
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_statusin the functions
redcap_read_oneshot_eav(). (@greg-botwin, #386, #389)
httr::handlevalue 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)
guess_maxnow allows floating point values to support
readr::read_csv()ability to accept a Inf value. (Suggested by @eveyp, #392)
data_access_group_idfield (introduced maybe in 13.1.0) (#459)
mycap_participantsfield (introduced maybe in 13.0.0) (#459)
bypass_branching_erase_field_prompt(@the-mad-statter, #465, #466)
redcap_meta_coltypes()correctly determines data type for autonumber
record_idfields. 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_oneshot()now remove “pseudofields” (e.g.,
redcap_repeat_instance) from the
fieldsparameter. 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, such as
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_oneshot()accept a new
localeparameter that specifies date, time, and number formats, like using a comma as the decimal separator. It is a
readr::localeobject. (#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
usernameto identify the desired credential row (#364)
http_response_encodingparameter 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_exportvariable and added the
redcap_read_oneshot_eav(): if the project isn’t longitudinal, a dummy value for
event_idis 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_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_oneshot()can toggle the ability to overwrite with blank/NA cells (suggested by @auricap, #315)
redcap_read_oneshot_eav()now support the parameters
datetime_range_end. The are passed to the REDCap parameters
dateRangeEnd, which restricts records returned, based on their last modified date in the server. (Thanks @pbchase, #321 & #323.)
export_survey_fieldsparameter in the functions
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_optionelement. (Proposed by @BastienRance, #307)
successvalue returned by
redcap_write()when the parameter
continue_on_erroris true. (Bug found by @llrs, #317)
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
readr::cols object) that is passed to
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://bbmc.ouhsc.edu/redcap/surveys/?s=8KuzSLMHf6”) (#293)
convert_logical_to_integer is a new parameter for
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)
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_oneshot()allow the user to specify if all variables should be returned with the
characterdata 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_oneshot_eav()always return Linux-style line endings (ie
\n) instead of Windows style line endings (ie,
\r\n) on all OSes. (#198)
charactervectors for all variables. With readr 1.2.0, some column were returned differently than before. (#193)
redcap_users_export()now included (#163)
redcap_read_oneshot_eav()(#206). It was already implemented for
constants()) easily exposes REDCap-specific constants. (#217)
id_positionallows 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_oneshot()are more consistent with the order in raw REDCap API. (#204)
verboseparameter is NULL, then the value from getOption(“verbose”) is used. (#215)
guess_maxparameter 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
odbcpackage 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.
base:stop()) (#190 & #208).
collapse_vector()is refactored and tested (#209)
retrieve_credential_mssql()is more general and more useful.
redcap_read_oneshot_eav(), which can be accessed with a triple colon (ie,
config_optionsin 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_oneshot()are now tested and public.
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_collapseddefault empty value is now an empty string (i.e.,
"") instead of
NULL. This applies when
records_collapsedis either a parameter, or a returned value.
redcap_download_file_oneshot()documentation, thanks to Andrew Peters (@ARPeters #45).
httrpackage, 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.
outcome_message. This is because the message associated with http code returned is conventionally called the ‘status messages’ (eg, OK, Forbidden, Not Found).
raw_textvalue (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 characters
redcap_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(). These changes reflect our suggestion that reads should typically be batched.
redcap_write_oneshot()(which is an internal function).
redcap_read()takes parameter for
raw_or_label(Thanks Rollie Parrish #3)
redcap_read()takes parameter for
export_data_access_groupsthanks to Rollie Parrish (@rparrish #4)
GitHub Commits and Releases