Title: | R Utilities For REDCap |
---|---|
Description: | R utilities for interacting with the REDCap API. |
Authors: | Patrick Barks [aut, cre] |
Maintainer: | Patrick Barks <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.2.0 |
Built: | 2024-10-28 11:20:28 UTC |
Source: | https://github.com/epicentre-msf/redcap |
Delete records from a REDCap project
delete_records(conn, records)
delete_records(conn, records)
conn |
A REDCap API connection object (created with |
records |
Character vector of record IDs to delete |
An integer, the number of records successfully deleted
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) # delete all records associated with IDs "P004" and "P007" delete_records(conn, records = c("P004", "P007")) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) # delete all records associated with IDs "P004" and "P007" delete_records(conn, records = c("P004", "P007")) ## End(Not run)
Wrapper to fetch_records
that's vectorized over forms (i.e. instruments).
Returns a list whose elements are tibble
-style data
frames corresponding to each requested form.
fetch_database( conn, forms = NULL, names_fn = function(x) x, records = NULL, records_omit = NULL, id_field = TRUE, rm_empty = TRUE, value_labs = TRUE, value_labs_fetch_raw = FALSE, header_labs = FALSE, checkbox_labs = FALSE, use_factors = FALSE, times_chron = TRUE, date_range_begin = NULL, date_range_end = NULL, fn_dates = parse_date, fn_dates_args = list(orders = c("Ymd", "dmY")), fn_datetimes = lubridate::parse_date_time, fn_datetimes_args = list(orders = c("Ymd HMS", "Ymd HM")), na = c("", "NA"), dag = TRUE, batch_size = 100L, batch_delay = 0.5, form_delay = 0.5, double_resolve = FALSE, double_remove = FALSE, double_sep = "--", fns = NULL )
fetch_database( conn, forms = NULL, names_fn = function(x) x, records = NULL, records_omit = NULL, id_field = TRUE, rm_empty = TRUE, value_labs = TRUE, value_labs_fetch_raw = FALSE, header_labs = FALSE, checkbox_labs = FALSE, use_factors = FALSE, times_chron = TRUE, date_range_begin = NULL, date_range_end = NULL, fn_dates = parse_date, fn_dates_args = list(orders = c("Ymd", "dmY")), fn_datetimes = lubridate::parse_date_time, fn_datetimes_args = list(orders = c("Ymd HMS", "Ymd HM")), na = c("", "NA"), dag = TRUE, batch_size = 100L, batch_delay = 0.5, form_delay = 0.5, double_resolve = FALSE, double_remove = FALSE, double_sep = "--", fns = NULL )
conn |
A REDCap API connection object (created with |
forms |
Character vector of forms (i.e. instruments) to fetch data for.
Set to |
names_fn |
Function for creating custom list element names given a vector of form names. Defaults to an identity function in which case element names will correspond exactly to form names. |
records |
Character vector of record IDs to fetch. Set to |
records_omit |
Character vector of record IDs to ignore. Set to |
id_field |
Logical indicating whether to always include the 'record ID'
field (defined in REDCap to be the first variable in the project codebook)
in the API request, even if it's not specified in argument The record ID field is defined within the first form of a REDCap project,
and so API requests for other forms will not include the record ID field by
default (unless it's explicitly requested with argument |
rm_empty |
Logical indicating whether to remove rows for which all
fields from the relevant form(s) are missing. See section Removing empty
rows. Defaults to |
value_labs |
Logical indicating whether to return value labels ( |
value_labs_fetch_raw |
Logical indicating whether to request raw values
for categorical REDCap variables (radio, dropdown, yesno, checkbox), which
are then transformed to labels in a separate step when |
header_labs |
Logical indicating whether to export column names as
labels ( |
checkbox_labs |
Logical indicating whether to export checkbox labels
( |
use_factors |
Logical indicating whether categorical REDCap variables
(radio, dropdown, yesno, checkbox) should be returned as factors. Factor
levels can either be raw values (e.g. "0"/"1") or labels (e.g. "No"/"Yes")
depending on arguments |
times_chron |
Logical indicating whether to reclass time variables using
chron::times ( |
date_range_begin |
Fetch only records created or modified after a given date-time. Use format "YYYY-MM-DD HH:MM:SS" (e.g., "2017-01-01 00:00:00" for January 1, 2017 at midnight server time). Defaults to NULL to omit a lower time limit. |
date_range_end |
Fetch only records created or modified before a given date-time. Use format "YYYY-MM-DD HH:MM:SS" (e.g., "2017-01-01 00:00:00" for January 1, 2017 at midnight server time). Defaults to NULL to omit a lower time limit. |
fn_dates |
Function to parse REDCap date variables. Defaults to
|
fn_dates_args |
List of arguments to pass to |
fn_datetimes |
Function to parse REDCap datetime variables. Defaults to
|
fn_datetimes_args |
List of arguments to pass to |
na |
Character vector of strings to interpret as missing values. Passed
to readr::read_csv. Defaults to |
dag |
Logical indicating whether to export the
|
batch_size |
Number of records to fetch per batch. Defaults to |
batch_delay |
Delay in seconds between fetching successive batches, to
give the REDCap server time to respond to other requests. Defaults to
|
form_delay |
Delay in seconds between fetching successive forms, to
give the REDCap server time to respond to other requests. Defaults to
|
double_resolve |
Logical indicating whether to resolve double-entries (i.e. records entered in duplicate using REDCap's Double Data Entry module), by filtering to the lowest entry number associated with each unique record. If a project uses double-entry, the record IDs returned by an "Export
Records" API request will be a concatenation of the normal record ID and
the entry number (1 or 2), normally separated by "–" (e.g. "P0285–1"). To
resolve double entries we move the entry number portion of the ID to its
own column ( Unique records are identified using the record ID column (after separating
the entry number portion), and any of the following columns when present
(accounting for argument |
double_remove |
Logical indicating whether to remove double-entries
(i.e. records entered in duplicate using REDCap's Double Data Entry
module), by filtering out records where the record ID field contains
pattern |
double_sep |
If |
fns |
Optional list of one or more functions to apply to each list
element (i.e. each form). Could be used e.g. to filter out record IDs from
test entries, create derived variables, etc. Each function should take a
data frame returned by |
A list of tibble
-style data frames corresponding to each
of the requested forms.
Depending on the database design, an "Export Records" API request can sometimes return empty rows, representing forms for which no data has been collected. For example, if forms F1 and F2 are part of the same event, and participant "P001" has form data for F2 but not F1, an API request for F1 will include a row for participant "P001" where all F1-specific fields are empty.
If argument rm_empty
is TRUE
(the default), fetch_records()
will filter
out such rows. The check for empty rows is based only on fields that are
specific to the form(s) specified in argument forms
— i.e. it excludes the
record ID field, and generic fields like redcap_event_name
,
redcap_data_access_group
, etc. The check for empty rows also accounts for
checkbox fields, which, if argument checkbox_labs
is FALSE
, will be set
to "Unchecked" in an empty form (rather than missing per se).
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) fetch_database( conn, forms = c("my_form1", "my_form2", "my_form3") ) # use a custom fn to format the 'participant_id' column of each form # the function must take a data frame as its first argument format_ids <- function(x) { x$participant_id <- toupper(x$participant_id) x$participant_id <- gsub("[^[:alnum:]]+", "_", x$participant_id) x } fetch_database( conn, forms = c("my_form1", "my_form2", "my_form3"), fns = list(format_ids) ) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) fetch_database( conn, forms = c("my_form1", "my_form2", "my_form3") ) # use a custom fn to format the 'participant_id' column of each form # the function must take a data frame as its first argument format_ids <- function(x) { x$participant_id <- toupper(x$participant_id) x$participant_id <- gsub("[^[:alnum:]]+", "_", x$participant_id) x } fetch_database( conn, forms = c("my_form1", "my_form2", "my_form3"), fns = list(format_ids) ) ## End(Not run)
Execute an "Export Records" API request to fetch a
tibble
-style data frame containing records for one or
more REDCap instruments.
fetch_records( conn, forms = NULL, events = NULL, records = NULL, records_omit = NULL, fields = NULL, id_field = TRUE, rm_empty = TRUE, value_labs = TRUE, value_labs_fetch_raw = FALSE, header_labs = FALSE, checkbox_labs = FALSE, use_factors = FALSE, times_chron = TRUE, date_range_begin = NULL, date_range_end = NULL, fn_dates = parse_date, fn_dates_args = list(orders = c("Ymd", "dmY")), fn_datetimes = lubridate::parse_date_time, fn_datetimes_args = list(orders = c("Ymd HMS", "Ymd HM")), na = c("", "NA"), dag = TRUE, batch_size = 100L, batch_delay = 0.5, double_resolve = FALSE, double_remove = FALSE, double_sep = "--" )
fetch_records( conn, forms = NULL, events = NULL, records = NULL, records_omit = NULL, fields = NULL, id_field = TRUE, rm_empty = TRUE, value_labs = TRUE, value_labs_fetch_raw = FALSE, header_labs = FALSE, checkbox_labs = FALSE, use_factors = FALSE, times_chron = TRUE, date_range_begin = NULL, date_range_end = NULL, fn_dates = parse_date, fn_dates_args = list(orders = c("Ymd", "dmY")), fn_datetimes = lubridate::parse_date_time, fn_datetimes_args = list(orders = c("Ymd HMS", "Ymd HM")), na = c("", "NA"), dag = TRUE, batch_size = 100L, batch_delay = 0.5, double_resolve = FALSE, double_remove = FALSE, double_sep = "--" )
conn |
A REDCap API connection object (created with |
forms |
Character vector of forms (i.e. instruments) to fetch data for.
Set to |
events |
Character vector of events to fetch. Must correspond to the
selected |
records |
Character vector of record IDs to fetch. Set to |
records_omit |
Character vector of record IDs to ignore. Set to |
fields |
Character vector of fields (i.e. variables) to fetch. Set to
|
id_field |
Logical indicating whether to always include the 'record ID'
field (defined in REDCap to be the first variable in the project codebook)
in the API request, even if it's not specified in argument The record ID field is defined within the first form of a REDCap project,
and so API requests for other forms will not include the record ID field by
default (unless it's explicitly requested with argument |
rm_empty |
Logical indicating whether to remove rows for which all
fields from the relevant form(s) are missing. See section Removing empty
rows. Defaults to |
value_labs |
Logical indicating whether to return value labels ( |
value_labs_fetch_raw |
Logical indicating whether to request raw values
for categorical REDCap variables (radio, dropdown, yesno, checkbox), which
are then transformed to labels in a separate step when |
header_labs |
Logical indicating whether to export column names as
labels ( |
checkbox_labs |
Logical indicating whether to export checkbox labels
( |
use_factors |
Logical indicating whether categorical REDCap variables
(radio, dropdown, yesno, checkbox) should be returned as factors. Factor
levels can either be raw values (e.g. "0"/"1") or labels (e.g. "No"/"Yes")
depending on arguments |
times_chron |
Logical indicating whether to reclass time variables using
chron::times ( |
date_range_begin |
Fetch only records created or modified after a given date-time. Use format "YYYY-MM-DD HH:MM:SS" (e.g., "2017-01-01 00:00:00" for January 1, 2017 at midnight server time). Defaults to NULL to omit a lower time limit. |
date_range_end |
Fetch only records created or modified before a given date-time. Use format "YYYY-MM-DD HH:MM:SS" (e.g., "2017-01-01 00:00:00" for January 1, 2017 at midnight server time). Defaults to NULL to omit a lower time limit. |
fn_dates |
Function to parse REDCap date variables. Defaults to
|
fn_dates_args |
List of arguments to pass to |
fn_datetimes |
Function to parse REDCap datetime variables. Defaults to
|
fn_datetimes_args |
List of arguments to pass to |
na |
Character vector of strings to interpret as missing values. Passed
to readr::read_csv. Defaults to |
dag |
Logical indicating whether to export the
|
batch_size |
Number of records to fetch per batch. Defaults to |
batch_delay |
Delay in seconds between fetching successive batches, to
give the REDCap server time to respond to other requests. Defaults to
|
double_resolve |
Logical indicating whether to resolve double-entries (i.e. records entered in duplicate using REDCap's Double Data Entry module), by filtering to the lowest entry number associated with each unique record. If a project uses double-entry, the record IDs returned by an "Export
Records" API request will be a concatenation of the normal record ID and
the entry number (1 or 2), normally separated by "–" (e.g. "P0285–1"). To
resolve double entries we move the entry number portion of the ID to its
own column ( Unique records are identified using the record ID column (after separating
the entry number portion), and any of the following columns when present
(accounting for argument |
double_remove |
Logical indicating whether to remove double-entries
(i.e. records entered in duplicate using REDCap's Double Data Entry
module), by filtering out records where the record ID field contains
pattern |
double_sep |
If |
A tibble
-style data frame containing the requested
records
Depending on the database design, an "Export Records" API request can sometimes return empty rows, representing forms for which no data has been collected. For example, if forms F1 and F2 are part of the same event, and participant "P001" has form data for F2 but not F1, an API request for F1 will include a row for participant "P001" where all F1-specific fields are empty.
If argument rm_empty
is TRUE
(the default), fetch_records()
will filter
out such rows. The check for empty rows is based only on fields that are
specific to the form(s) specified in argument forms
— i.e. it excludes the
record ID field, and generic fields like redcap_event_name
,
redcap_data_access_group
, etc. The check for empty rows also accounts for
checkbox fields, which, if argument checkbox_labs
is FALSE
, will be set
to "Unchecked" in an empty form (rather than missing per se).
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) fetch_records(conn, forms = "my_form") ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) fetch_records(conn, forms = "my_form") ## End(Not run)
Generates two types of data validation queries using the project codebook
(see meta_dictionary
) and translate_logic
:
Field missing: Branching logic evaluates to TRUE
(if specified), but
field is missing. By default only applies to required fields (required_field == "y"
) (can modify with argument non_required
).
Field not missing: Branching logic evaluates to FALSE
but field is
not missing. Applies to any field with branching logic.
generate_queries( conn, forms = NULL, dict = meta_dictionary(conn, forms = forms, expand_checkbox = FALSE), lang = "en", query_types = "both", non_required = FALSE, drop_redundant = FALSE, field_nchar_max = 80L, on_error = "warn" )
generate_queries( conn, forms = NULL, dict = meta_dictionary(conn, forms = forms, expand_checkbox = FALSE), lang = "en", query_types = "both", non_required = FALSE, drop_redundant = FALSE, field_nchar_max = 80L, on_error = "warn" )
conn |
A REDCap API connection object (created with |
forms |
Character vector of forms (i.e. instruments) to include. Set to
|
dict |
Metadata dictionary. By default is fetched automatically with
|
lang |
Query language, either English ("en") or French ("fr"). Defaults to "en". |
query_types |
Which type of queries to generate (see Description above). Options are "missing", "not missing", or "both". Defaults to "both". |
non_required |
Logical indicating whether to include non-required fields
in queries of type "Field missing". Defaults to |
drop_redundant |
Logical indicating whether to simplify expressions by
removing redundant components from expressions that test both for equality
and inequality with the same variable. E.g.: |
field_nchar_max |
Integer indicating the maximum number of characters to allow in field name labels before they are truncated and appended with "...". Defaults to 80L. |
on_error |
What to do if one or more elements of statements can't be
translated into valid R expressions? Options are "ignore" (return |
A tibble
-style data frame specifying queries, with the
following 7 columns:
Unique query identifier based on form name and integer sequence
Field name (from REDCap dictionary, see meta_dictionary
)
Form name (from REDCap dictionary)
Is it a required field in REDCap dictionary ("y" or <NA>
) ?
Description of query (e.g. "Missing: [Signed consent forms?]")
Suggestion for query resolution. A human-readable translation of query expression (e.g. If [Is the participant 18 years or older?] is "Yes", item [Signed consent forms?] should not be missing)
Branching logic for given field (from REDCap dictionary)
R-style query expression (can be evaluated with queryr::query
)
Import records into a REDCap project
import_records( conn, data, type = c("flat", "eav"), overwrite = "normal", return = "count" )
import_records( conn, data, type = c("flat", "eav"), overwrite = "normal", return = "count" )
conn |
A REDCap API connection object (created with |
data |
A data.frame containing record data to import into REDCap |
type |
One of:
|
overwrite |
Overwrite behaviour. Either "normal" to prevent missing values from overwriting data, or "overwrite" to allow data to be overwritten with missing values. Defaults to "normal". |
return |
What to return. Use "count" to return a count of imported records, "ids" to return a vector of the IDs that were imported, or "nothing" to return nothing. Defaults to "count". |
Depends on argument return
. Either a count of imported records, a vector of
record IDs, or nothing.
Execute an "Export Arms" API request to fetch the "arms" (number and name) associated with a REDCap project.
meta_arms(conn)
meta_arms(conn)
conn |
A REDCap API connection object (created with |
A tibble
-style data frame with 2 columns:
arm_num
name
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_arms(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_arms(conn) ## End(Not run)
Execute an "Export Metadata (Data Dictionary)" API request to fetch a
tibble
-style data frame containing the project codebook
(field names, types, labels, choices, validation, etc.).
meta_dictionary( conn, forms = NULL, expand_checkbox = TRUE, add_complete = FALSE, cols_omit = c("section_header", "custom_alignment", "question_number", "matrix_group_name", "matrix_ranking") )
meta_dictionary( conn, forms = NULL, expand_checkbox = TRUE, add_complete = FALSE, cols_omit = c("section_header", "custom_alignment", "question_number", "matrix_group_name", "matrix_ranking") )
conn |
A REDCap API connection object (created with |
forms |
Character vector of forms (i.e. instruments) to include in the
return. Set to |
expand_checkbox |
Logical indicating whether to expand checkbox
variables. Defaults to Unlike an "Export Records" API request (see When |
add_complete |
Logical indicating whether to add "{form}_complete"
fields to the dictionary, one for each form included in the return. These
will be of field_type "radio" with possible choices "0, Incomplete | 1,
Unverified | 2, Complete". Defaults to |
cols_omit |
Character vector of dictionary columns to omit from the
return for brevity. Set to |
A tibble
-style data frame containing the project
dictionary. Note that some of the returned column names are shortened
versions of the original column names returned by the API:
Original | Returned |
select_choices_or_calculations |
choices |
text_validation_type_or_show_slider_number |
validation |
text_validation_min |
validation_min |
text_validation_max |
validation_max |
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_dictionary(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_dictionary(conn) ## End(Not run)
Execute an "Export Events" API request to fetch a
tibble
-style data frame containing event names and
labels. Note that this request type is not available for 'classic projects',
from which event details cannot be exported.
meta_events(conn, on_error = "fail")
meta_events(conn, on_error = "fail")
conn |
A REDCap API connection object (created with |
on_error |
How to handle errors returned by the API (e.g. events cannot
be exported for classic projects). Set to "fail" to halt execution and
return the API error message, or "null" to ignore the error and return
|
A tibble
-style data frame with 7 columns:
event_name
arm_num
day_offset
offset_min
offset_max
unique_event_name
custom_event_label
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_events(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_events(conn) ## End(Not run)
Converts field options and labels from the metadata dictionary (see
meta_dictionary
), which has 1 row per variable and field options in
compact string-form, to long form with 1 row per option. E.g.:
Dictionary version (1 row per variable):
field_name |
form_name |
field_type |
choices |
consented | enrollment | radio | 0, No | 1, Yes |
Long format (1 row per option):
field_name |
form_name |
field_type |
value |
label |
consented | enrollment | radio | 0 | No |
consented | enrollment | radio | 1 | Yes |
meta_factors( conn, forms = NULL, expand_checkbox = TRUE, add_complete = FALSE, types = c("radio", "yesno", "dropdown", "checkbox") )
meta_factors( conn, forms = NULL, expand_checkbox = TRUE, add_complete = FALSE, types = c("radio", "yesno", "dropdown", "checkbox") )
conn |
A REDCap API connection object (created with |
forms |
Character vector of forms (i.e. instruments) to include. Set to
|
expand_checkbox |
Logical indicating whether to expand checkbox
variables. Defaults to Unlike an "Export Records" API request (see When |
add_complete |
Logical indicating whether to add "{form}_complete"
fields to the dictionary, one for each form included in the return. These
will be of field_type "radio" with possible choices "0, Incomplete | 1,
Unverified | 2, Complete". Defaults to |
types |
Character vector of variable types to return field options for.
|
A tibble
-style data frame with 6 columns:
field_name
form_name
field_type
field_label
value
label
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_factors(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_factors(conn) ## End(Not run)
Execute an "Export List of Export Field Names" API request to fetch a
tibble
-style data frame containing field (i.e. variable)
names as listed in the project codebook (column original_field_name
) and
the corresponding exported variable name(s) (column export_field_name
).
Original and exported field names will be identical except in the case of
checkbox-type variables. A given checkbox variable (e.g. "patient_status")
will have a single entry in the codebook (i.e. field_name
=
"patient_status"), but will be exported as multiple variables — one for each
possible choice value.
original_field_name |
choice_value |
export_field_name |
patient_status | 1 | patient_status___1 |
patient_status | 2 | patient_status___2 |
patient_status | 3 | patient_status___3 |
patient_status | 88 | patient_status___88 |
meta_fields(conn)
meta_fields(conn)
conn |
A REDCap API connection object (created with |
A tibble
-style data frame with 3 columns:
original_field_name
choice_value
export_field_name
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_fields(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_fields(conn) ## End(Not run)
Execute an "Export Instrument (Data Entry Forms)" API request to fetch a
tibble
-style data frame containing instrument names and
labels.
meta_forms(conn)
meta_forms(conn)
conn |
A REDCap API connection object (created with |
A tibble
-style data frame with 2 columns:
instrument_name
instrument_label
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_forms(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_forms(conn) ## End(Not run)
Execute an "Export Instrument-Event Mappings" API request to fetch a
tibble
-style data frame containing the mapping between
instruments and events. Note that this request type is not available for
'classic projects', from which event details cannot be exported.
meta_mapping(conn, on_error = "fail")
meta_mapping(conn, on_error = "fail")
conn |
A REDCap API connection object (created with |
on_error |
How to handle errors returned by the API (e.g. events cannot
be exported for classic projects). Set to "fail" to halt execution and
return the API error message, or "null" to ignore the error and return
|
A tibble
-style data frame with 3 columns:
arm_num
unique_event_name
form
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_mapping(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_mapping(conn) ## End(Not run)
Execute an "Export Repeating Instruments and Events" API request to fetch a
tibble
-style data frame containing repeating instrument
names and labels.
meta_repeating(conn, on_error = "fail")
meta_repeating(conn, on_error = "fail")
conn |
A REDCap API connection object (created with |
on_error |
How to handle errors returned by the API (e.g. events cannot
be exported for classic projects). Set to "fail" to halt execution and
return the API error message, or "null" to ignore the error and return
|
A tibble
-style data frame with 2 columns:
instrument_name
instrument_label
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_repeating(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) meta_repeating(conn) ## End(Not run)
REDCap project log files have a complicated format where multiple types of
information are contained in a single column. For example the column action
contains the relevant record ID, the type of action that was taken (e.g.
Updated / Created / Deleted), and sometimes further details about the source
of the action (e.g. API / Import / Automatic field calculation). The
details
column contains a string of variable/value combinations describing
any changes (e.g. "var1 = '0', var2 = '1', var3(1) = checked"), and may also
contain the relevant repeat instance number (e.g. "[instance = 3]").
The parse_logging() function tidies up the log file by splitting the record
ID, action, action type, and repeat instance into separate columns.
Optionally, the string of variable/value changes in the details
column may
be further transformed to long format to yield a single row for each
combination of variable and value.
Note that this function only deals with log entries of type Created / Deleted / Updated Record. All other log entries (e.g. Data Export, Manage/Design, Edited Role, User Assigned to Role) will be filtered out.
parse_logging(x, format_long = FALSE, dict = NULL)
parse_logging(x, format_long = FALSE, dict = NULL)
x |
REDCap project log file (data frame), e.g. returned by
|
format_long |
Logical indicating whether to transform the log file to
long format, with one row per variable-value combination. Defaults to
|
dict |
A REDCap metadata dictionary (data frame), e.g. returned by
|
A tibble
-style data frame with 8 columns:
rowid
Row number based on original log file. There may be gaps for rows that have been excluded from the output because they reflected an action type other than create / delete / update.
timestamp
unchanged from original log file
username
unchanged from original log file
action
One of "Created Record", "Deleted Record", or "Updated
Record", extracted from original details
column
action_type
Parenthetical details, if any, extracted from original
action
column (e.g. "(API)", "(import)", "(Auto calculation)")
record_id
Record ID, extracted from original action
column
redcap_repeat_instance
Instance number (integer), extracted from
original details
column. Note that 1st instances are not explicitly
specified in the log file and will appear as NA
details
String of variable value pairs (e.g. "var1 = '0', var2 = '1', var3(1) = checked"), reflecting the data that was modified
If argument format_long
is TRUE
the details
column will be replaced
with three other columns:
form_name
Form name, joined from metadata dictionary based on
variable field_name
. Will be <NA>
in cases where field name has been
changed or removed and therefore doesn't appear in the dictionary, or for
fields not associated with a specific form like
redcap_data_access_group
.
field_name
Field name, extracted from original details
column
value
Value, extracted from original details
column
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) parse_logging(project_logging(conn)) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) parse_logging(project_logging(conn)) ## End(Not run)
Extract records from a REDCap project XML file (e.g. returned by
project_xml
) and assemble into a tidy long-form data frame, with one row
for each combination of record x field x event x instance.
parse_xml(x)
parse_xml(x)
x |
A REDCap project XML obect of class
|
A tibble
-style data frame with 6 columns:
record_id
form
redcap_event
redcap_repeat_instance
field
value
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) parse_xml(project_xml(conn)) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) parse_xml(project_xml(conn)) ## End(Not run)
Execute an "Export Data Access Groups (DAGs)" API request to fetch the DAGs (labels and code names) associated with a REDCap project.
project_dags(conn)
project_dags(conn)
conn |
A REDCap API connection object (created with |
A tibble
-style data frame with 2 columns:
data_access_group_name
unique_group_name
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_dags(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_dags(conn) ## End(Not run)
Execute an "Export Project Info" API request to fetch project-related details (e.g. title, creation time, production status, language, etc.) corresponding to a REDCap project.
project_info(conn)
project_info(conn)
conn |
A REDCap API connection object (created with |
A tibble
-style data frame containing the columns returned
by an "Export Project Info" API request
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_info(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_info(conn) ## End(Not run)
Execute an "Export Logging" API request to export the logging (audit trail) of all changes made to the project, including data exports, data changes, project metadata changes, modification of user rights, etc.
project_logging( conn, type = NULL, user = NULL, record = NULL, time_start = NULL, time_end = NULL, timestamp_to_posix = TRUE )
project_logging( conn, type = NULL, user = NULL, record = NULL, time_start = NULL, time_end = NULL, timestamp_to_posix = TRUE )
conn |
A REDCap API connection object (created with |
type |
Type of logging to return. Defaults to NULL to return all types. Specific logging types include:
|
user |
REDCap username to fetch logs for. Defaults to NULL to fetch logs relating to all users. Note that, in the current API version (10.8.5), it's not possible to pass a character vector with multiple usernames (i.e. one user per request, or NULL for all). |
record |
Record ID to fetch logs for. Defaults to NULL to fetch logs relating to all record IDs. Note that, in the current API version (10.8.5), it's not possible to pass a character vector with multiple record IDs (i.e. one record per request, or NULL for all). |
time_start |
Fetch logs from after a given date-time. Use format "YYYY-MM-DD HH:MM". Defaults to NULL to omit a lower time limit. |
time_end |
Fetch logs from before a given date-time. Use format "YYYY-MM-DD HH:MM". Defaults to NULL to omit an upper time limit. |
timestamp_to_posix |
Logical indicating whether to convert the
|
A tibble
-style data frame with 4 columns:
timestamp
username
actions
details
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_logging(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_logging(conn) ## End(Not run)
Execute an "Export Users" API request to fetch user-related details (e.g. username, email, access permissions, etc.) corresponding to a REDCap project.
project_users(conn)
project_users(conn)
conn |
A REDCap API connection object (created with |
A tibble
-style data frame containing the columns returned
by an "Export Users" API request
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_users(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_users(conn) ## End(Not run)
Execute an "Export User-DAG Assignments" API request to fetch the mapping between users and Data Access Groups (DAGs) associated with a REDCap project.
project_users_dags(conn)
project_users_dags(conn)
conn |
A REDCap API connection object (created with |
A tibble
-style data frame with 2 columns:
username
redcap_data_access_group
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_users_dags(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_users_dags(conn) ## End(Not run)
Execute an "Export Entire Project as REDCap XML File" API request to fetch all metadata (and optionally also data records) corresponding to a REDCap project.
project_xml( conn, meta_only = FALSE, records = NULL, fields = NULL, events = NULL, filter_logic = NULL, export_dag = FALSE, export_survey = FALSE, export_files = FALSE )
project_xml( conn, meta_only = FALSE, records = NULL, fields = NULL, events = NULL, filter_logic = NULL, export_dag = FALSE, export_survey = FALSE, export_files = FALSE )
conn |
A REDCap API connection object (created with |
meta_only |
Logical indicating whether to fetch only the project
metadata (if |
records |
Optional character vector of specific record IDs to fetch
record data for. Only used when |
fields |
Optional character vector of specific fields to fetch record
data for. Only used when |
events |
Optional character vector of specific events to fetch record
data for. Only used when |
filter_logic |
Optional character string containing a REDCap-style expression used to filter records returned by the API (e.g. "[age] > 30") |
export_dag |
Logical indicating whether to export the
redcap_data_access_group field. Defaults to |
export_survey |
Logical indicating whether to export survey identifier
or timestamp fields, if surveys are used in the project. Defaults to
|
export_files |
Logical indicating whether to export uploaded files. Note
this may lead to large exports. Defaults to |
An object of class xml_document
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_xml(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) project_xml(conn) ## End(Not run)
Creates an object of class "rconn" containing the URL and token used to access a REDCap project API.
rconn(url, token, config = httr::config())
rconn(url, token, config = httr::config())
url |
URL for a REDCap database API |
token |
REDCap project API token (good practice to set using an
environmental variable, e.g. with |
config |
Optional configuration settings passed to |
An object of class "rconn", to be passed as the first argument to most other
redcap
functions.
conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") )
conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") )
Reclass columns of a data frame to match classes specified in a metadata dictionary
reclass( x, dict, use_factors = FALSE, value_labs = TRUE, header_labs = FALSE, times_chron = TRUE, fn_dates = parse_date, fn_dates_args = list(orders = c("Ymd", "dmY")), fn_datetimes = lubridate::parse_date_time, fn_datetimes_args = list(orders = c("Ymd HMS", "Ymd HM")) )
reclass( x, dict, use_factors = FALSE, value_labs = TRUE, header_labs = FALSE, times_chron = TRUE, fn_dates = parse_date, fn_dates_args = list(orders = c("Ymd", "dmY")), fn_datetimes = lubridate::parse_date_time, fn_datetimes_args = list(orders = c("Ymd HMS", "Ymd HM")) )
x |
A data frame representing a REDCap form |
dict |
A metadata dictionary |
use_factors |
Logical indicating whether categorical REDCap variables
(radio, dropdown, yesno, checkbox) should be returned as factors. Factor
levels can either be raw values (e.g. "0"/"1") or labels (e.g. "No"/"Yes")
depending on arguments |
value_labs |
Logical indicating whether to return value labels ( |
header_labs |
Logical indicating whether to export column names as
labels ( |
times_chron |
Logical indicating whether to reclass time variables using
chron::times ( |
fn_dates |
Function to parse REDCap date variables. Defaults to
|
fn_dates_args |
List of arguments to pass to |
fn_datetimes |
Function to parse REDCap datetime variables. Defaults to
|
fn_datetimes_args |
List of arguments to pass to |
Convert between values and labels for factor-type variables (e.g. yes/no, radio, dropdown, checkbox)
recode_labels( x, conn, dict = redcap::meta_dictionary(conn, add_complete = TRUE), convert_to = c("labels", "values"), types = c("radio", "yesno", "dropdown", "checkbox"), header_labs = FALSE )
recode_labels( x, conn, dict = redcap::meta_dictionary(conn, add_complete = TRUE), convert_to = c("labels", "values"), types = c("radio", "yesno", "dropdown", "checkbox"), header_labs = FALSE )
x |
Data frame representing a REDCap form (e.g. from a previous export
using |
conn |
A REDCap API connection object (created with |
dict |
REDCap metadata dictionary. Defaults to fetching the current
version with |
convert_to |
Convert values to labels ("labels") or labels to values ("values") |
types |
Types of REDCap variables to convert, based on column
"field_type" in the metadata dictionary. Defaults to |
header_labs |
Logical indicating whether column names of |
Execute an "Export REDCap version" API request
redcap_version(conn)
redcap_version(conn)
conn |
A REDCap API connection object (created with |
A character string
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) redcap_version(conn) ## End(Not run)
## Not run: conn <- rconn( url = "https://redcap.msf.fr/api/", token = Sys.getenv("MY_REDCAP_TOKEN") ) redcap_version(conn) ## End(Not run)
Translate REDCap branching logic into expressions evaluable in R. E.g.
Translation step | Example expression |
0. Initial REDCap logic | [over_18]='1' and [signed_consent]<>'' |
1. Translate to R | over_18 == '1' & signed_consent != '' |
2. (Optional) Swap values/labels | over_18 == 'Yes' & signed_consent != '' |
3. (Optional) Use is.na | over_18 == 'Yes' & !is.na(signed_consent) |
4. (Optional) Use %in% | over_18 %in% 'Yes' & !is.na(signed_consent) |
translate_logic( x, use_value_labs = TRUE, use_header_labs = FALSE, use_is_na = TRUE, use_in = TRUE, drop_redundant = FALSE, field_nchar_max = 80L, meta_factors = NULL, meta_dictionary = NULL, on_error = "warn" )
translate_logic( x, use_value_labs = TRUE, use_header_labs = FALSE, use_is_na = TRUE, use_in = TRUE, drop_redundant = FALSE, field_nchar_max = 80L, meta_factors = NULL, meta_dictionary = NULL, on_error = "warn" )
x |
A character vector of REDCap branching logic statements |
use_value_labs |
Logical indicating whether to replace factor option
values with labels (based on the mapping defined in |
use_header_labs |
Logical indicating whether to use labels instead of
variable names as column names (based on the mapping defined in
|
use_is_na |
Logical indicating whether to replace REDCap-style tests for
missingness with |
use_in |
Logical indicating whether to replace instances of |
drop_redundant |
Logical indicating whether to simplify expressions by
removing redundant components from expressions that test both for equality
and inequality with the same variable. E.g.: |
field_nchar_max |
Integer indicating the maximum number of characters to allow in field name labels before they are truncated and appended with "...". Defaults to 80L. |
meta_factors |
A data frame containing variable names (column
|
meta_dictionary |
A data frame containing variable names (column
|
on_error |
What to do if one or more elements of statements can't be
translated into valid R expressions? Options are "ignore" (return |
A character vector of R-style expressions
# normally would fetch factor metadata with redcap::meta_factors(), but here # we'll create a simple example by hand df_factors <- data.frame( field_name = c("head_household", "head_household"), value = c("0", "1"), label = c("No", "Yes"), stringsAsFactors = FALSE ) redcap_logic <- "head_household=1 and age<>\"\"" translate_logic(redcap_logic, meta_factors = df_factors)
# normally would fetch factor metadata with redcap::meta_factors(), but here # we'll create a simple example by hand df_factors <- data.frame( field_name = c("head_household", "head_household"), value = c("0", "1"), label = c("No", "Yes"), stringsAsFactors = FALSE ) redcap_logic <- "head_household=1 and age<>\"\"" translate_logic(redcap_logic, meta_factors = df_factors)