- New
redcap_delete()function. It deletes a vector of records. (Thanks @joundso, #372, #373) - New
redcap_arm_export()function. It retrieves a list of REDCap project arms. (#375) redcap_read()andredcap_read_oneshot()accept a newlocaleparameter that specifies date, time, and number formats, like using a comma as the decimal separator. It is areadr::localeobject. (#377, suggested by @joundso)- New
redcap_instruments()function exports a list of the data collection instruments for a project. (#381, @vcastro) - New
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) - New
redcap_dag_read()function returns the Data Access Groups for a project (#382, @joundso) - New detection when REDCap has trouble with a large request and drops records. (#400 w/ @TimMonahan)
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)- Include a few more
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 userusernameto identify the desired credential row (#364)redcap_read()andredcap_read_oneshot()gain thehttp_response_encodingparameter that's passed tohttr::content(). The default value remains "UTF-8". (#354, @lrasmus)- Accommodate single-character REDCap variable names (#367 & #368, @daynefiler)
- Modify
redcap_users_export()(which calls REDCap's user export). The API dropped thedata_exportvariable and added theforms_exportvariable. (#396) - For
redcap_read_oneshot_eav(): if the project isn't longitudinal, a dummy value forevent_idis used internally (#396) - For the testing server & projects, the http errors are a little different, so the testing code was adjusted (#396)
- Set
httr::user_agent, following the advice of httr's vignette (#397)
- Added two more dictionaries that are super wide -5k & 35k variables (#335 & #360, @januz & @datalorax)
- Read, modify, & read projects with DAGs (#353, daniela.wolkersdorfer, #353)
The package has been stable for years and should be reflected in the major version number.
- When writing records to the server, the functions
redcap_write()andredcap_write_oneshot()have a new parameter that converts R'slogical/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) - When writing records to the server, the functions
redcap_write()andredcap_write_oneshot()can toggle the ability to overwrite with blank/NA cells (suggested by @auricap, #315) - The functions
redcap_read_oneshot(),redcap_read(), &redcap_read_oneshot_eav()now support the parametersdatetime_range_beginanddatetime_range_end. The are passed to the REDCap parametersdateRangeBeginanddateRangeEnd, which restricts records returned, based on their last modified date in the server. (Thanks @pbchase, #321 & #323.) - Better documentation about the
export_survey_fieldsparameter in the functionsredcap_read()&redcap_read_oneshot(). (Thanks @isaactpetersen, #333) - New function
redcap_report()export records that populate a REDCap report. (#326.) - New vignette Typical REDCap Workflow for a Data Analyst developed to support a workshop for the 2021 R/Medicine Conference (#332, with @higgi13425, @kamclean, & Amanda Miller)
- New function
create_credential_local()starts a well-formed csv file that can contain tokens. (#340, after conversations with @higgi13425 & @kamclean.)
- update for newer version of testthat -v3.0.0 (#312)
- update for newer version of readr 2.0.0 (#343)
- update for newer version of readr 1.4.0 (#313)
- update for newer version of REDCap on test server (#310)
- save expected datasets as files -instead of included in the actual test code (#308)
- Accepts more than one
config_optionelement. (Proposed by @BastienRance, #307) - Fixed calculation of
successvalue returned byredcap_read()andredcap_write()when the parametercontinue_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 acceptssimplifyas an options. An integer vector is always returned. (#280)
-
It's now possible to specify the exact
col_types(areadr::colsobject) that is passed toreadr::read_csv()insideredcap_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, theguess_maxparameter inredcap_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_integeris a new parameter forredcap_write()andredcap_write_oneshot(). IfTRUE, all [base::logical] columns indsare cast to an integer before uploading to REDCap. Boolean values are typically represented as 0/1 in REDCap radio buttons. Defaults toFALSEto maintain backwards compatibility. (#305)
-
httr::content()(which is insidekernel_api()) now processes the returned value as "text/csv", by default. This should prevent strange characters from tricking the process as the internal variableraw_textis 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 anencodingparameter, which defaults to "UTF-8". (#270)
- check for bad field names passed to the read records functions (#288)
-
'checkmate' package is now imported, not suggested (Thanks @dtenenba, #255).
-
Allow more than one
httr::config()parameter to be passed (Thanks @BastienRance, #307).
- export survey time-stamps optionally (Issue #159)
redcap_next_free_record_name(): API call for 'Generate Next Record Name', which returns the next available record ID (Issue #237)redcap_read()andredcap_read_oneshot()allow the user to specify if all variables should be returned with thecharacterdata type. The default is to allowreadr::read_csv()to guess the data type. (#194)redcap_read_oneshot()allows use to specify how many rows should be considered whenreadr::read_csv()guesses the data type. (#194)redcap_read(),redcap_read_oneshot(), andredcap_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 returnscharactervectors for all variables. With readr 1.2.0, some column were returned differently than before. (#193)- 'raw_or_label_headers' now supported (Thanks Hatem Hosny - hatemhosny, #183 & #203)
- 'export_checkbox_labels' now supported (#186)
redcap_users_export()now included (#163)- 'forms' now supported for
redcap_read(),redcap_read_oneshot(), &redcap_read_oneshot_eav()(#206). It was already implemented forredcap_metadata_read(). - If no records are affected, a zero-length character vector is returned (instead of sometimes a zero-length numeric vector) (#212)
- New function (called
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.- Link to new secure Zenodo DOI resolver (@katrinleinweber #191)
- parameters in
redcap_read()andredcap_read_oneshot()are more consistent with the order in raw REDCap API. (#204) - When the
verboseparameter is NULL, then the value from getOption("verbose") is used. (#215) guess_maxparameter provided inredcap_read()(no longer justredcap_read_oneshot()). Suggested by @isaactpetersen in #245.- Documentation website constructed with pkgdown (#224).
redcap_variables()now throws an error when passed a bad URI (commit e542155639bbb7).
- All interaction with the REDCap server goes through the new
kernal_api()function, which uses the 'httr' and 'curl' packages underneath. Until now, each function called those packages directly. (#213) - When converting REDCap's CSV to R's data.frame,
readr::read_csv()is used instead ofutils::read.csv()(Issue #127). - updated to readr 1.2.0 (#200). This changed how some data variables were assigned a data types.
- uses
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. data.table::rbindlist()replaced bydplyr::bind_rows()- the checkmate package inspects most function parameters now (instead of
testit::assert()andbase:stop()) (#190 & #208). collapse_vector()is refactored and tested (#209)- remove dependency on
pkgloadpackage (#218) - Update Markdown syntax to new formatting problems (#253)
retrieve_token_mssql(), becauseretrieve_credential_mssql()is more general and more useful.
- Enumerate the exported variables. with
redcap_variables(). - Experimental EAV export in
redcap_read_oneshot_eav(), which can be accessed with a triple colon (ie,REDCapR::redcap_read_oneshot_eav()).
- Adapted to new 2.4 version of curl (see #154)
- Support for filtering logic in
redcap_read()andredcap_read_oneshot()(PR #126) - New functions
retrieve_credential_mssql()andretrieve_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. - Using parameterized queries with the RODBCext package. (Thanks @nutterb in issues #115 & #116.)
- Remove line breaks from token (Thanks @haozhu233 in issues #103 & #104)
- When combining batches into a single data.frame,
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 forrecord_id, but a subsequent batch has values likeaa-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) - Uses the
dplyrpackage instead ofplyr. This shouldn't affect callers, because immediately before returning the data,REDCapR::redcap_read()coerces thetibble::tibble(which was formerly calleddplyr::tbl_df) back to a vanilladata.framewithas.data.frame(). - A few more instances of validating input parameters to read functions. (Issue #8).
- The
retrieve-token()tests now account for the (OS X) builds where the RODBC package isn't available.
- Adapted for version 1.0.0 of httr (which is now based on the
curlpackage, instead ofRCurl).
- Uses
requireNamespace()instead ofrequire(). - By default, uses the SSL cert files used by httr, which by default, uses those packaged with R.
- Added warning if it appears
readcap_read()is being used without 'Full Data Set' export privileges. The problem involves the record IDs are hashed. - Reconnected code that reads only the
id_positionin 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 parameters
- Updated for Version 6.0.x of REDCap (which introduced a lot of improvements to API behavior).
- The
config_optionsin the httr package are exposed to the REDCapR user. See issues #55 & #58; thanks to @rparrish and @nutterb for their contributions (OuhscBbmc#55 & OuhscBbmc#58).
redcap_metadata_read()are tested and public.
- Test suite now uses
testthat::skip_on_cran()before any call involving OUHSC's REDCap server. - Vignette example of subsetting, conditioned on a second variable's value.
redcap_write()andredcap_write_oneshot()are now tested and public.redcap_write()andredcap_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)- Users can specify if an operation should continue after an error occurs on a batch read or write. Regardless of their choice, more debugging output is written to the console if
verbose==TRUE. Follows advice of @johnaponte, Benjamin Nutter (@nutterb), and Rollie Parrish (@rparrish). Closes #43.
- The
records_collapseddefault empty value is now an empty string (i.e.,"") instead ofNULL. This applies whenrecords_collapsedis either a parameter, or a returned value.
- By default, the SSL certs come from the httr package. However, REDCapR will continue to maintain a copy in case httr's version on CRAN gets out of date.
- The tests are split into two collections: one that's run by the CRAN checks, and the other run manually. Thanks, Gabor Csardi. Any test with a dependency outside the package code (especially the REDCap test projects) is run manually so changes to the test databases won't affect the success of building the previous version on CRAN.
- Corrected typo in
redcap_download_file_oneshot()documentation, thanks to Andrew Peters (@ARPeters #45).
- Relies on the
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.
- Renamed the former
status_messagetooutcome_message. This is because the message associated with http code returned is conventionally called the 'status messages' (eg, OK, Forbidden, Not Found). - If an operation is successful, the
raw_textvalue (which was formerly calledraw_csv) is returned as an empty string to save RAM. It's not really necessary with httr's status message exposed.
- Correct batch reads with longitudinal schema #27
- Added
redcap_column_sanitize()function to address non-ASCII characters - Added
redcap_write()(as an internal function). - The
redcap_project()object reduces repeatedly passing parameters like the server URL, the user token, and the SSL cert location.
- New Mozilla SSL Certification Bundles released on cURL (released 2013-12-05)
- Renamed
redcap_read_batch()toredcap_read(). These changes reflect our suggestion that reads should typically be batched. - Renamed
redcap_read()toredcap_read_oneshot() - Renamed
redcap_write()toredcap_write_oneshot()(which is an internal function). - Small renames to parameters
- Introduces
redcap_read()andredcap_read_batch()with documentation - SSL verify peer by default, using cert file included in package
- Initial submission to GitHub
redcap_read()takes parameter forraw_or_label(Thanks Rollie Parrish #3)redcap_read()takes parameter forexport_data_access_groupsthanks to Rollie Parrish (@rparrish #4)
- For a detailed change log, please see https://github.com/OuhscBbmc/REDCapR/commits/master.
- For a list of the major releases, please see https://github.com/OuhscBbmc/REDCapR/releases.