The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.
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
These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.