Quick links:
These features are not yet on CRAN. Install with remotes::install_github("OuhscBbmc/REDCapR")
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:
r
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:
r
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://bbmc.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 the
content_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
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.