Package 'redcapAPI'

Generate Allocation Tables for the Randomization Module

Description

These methods enable the user to generate allocation tables for the REDCap randomization module. Randomization may be stratified by other (categorical) variables in the data set as well as by Data Access Group. Additionally, randomization may be blocked to ensure balanced groups throughout the allocation

Usage

allocationTable(
  rcon,
  random,
  strata = NULL,
  group = NULL,
  dag.id = NULL,
  replicates,
  block.size,
  block.size.shift = 0,
  seed.dev = NULL,
  seed.prod = NULL,
  weights = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
allocationTable(
  rcon,
  random,
  strata = NULL,
  group = NULL,
  dag.id = NULL,
  replicates,
  block.size,
  block.size.shift = 0,
  seed.dev = NULL,
  seed.prod = NULL,
  weights = c(1, 1),
  ...
)

allocationTable_offline(
  meta_data,
  random,
  strata = NULL,
  group = NULL,
  dag.id = NULL,
  replicates,
  block.size,
  block.size.shift = 0,
  seed.dev = NULL,
  seed.prod = NULL,
  weights = c(1, 1),
  ...
)

Arguments

rcon	A redcapConnection object.
random	character(1). The field name to be randomized.
strata	character. Field names by which to stratify the randomization.
group	character(1). A field name giving a group by which randomization should be stratified. This could also be listed in strata, but the argument is provided to remain consistent with the REDCap user interface.
dag.id	integerish. Data Access Group IDs.
replicates	integerish(1). The number of randomizations to perform within each stratum
block.size	integerish. Block size for the randomization. Blocking is recommended to ensure balanced groups throughout the randomization. This may be a vector to indicate variable block sizes throughout the randomization.
block.size.shift	numeric on the interval ⁠[0, 1]⁠. A vector the same length as block.size where the first element is 0. This controls when the block size changes as a proportion of the total sample size. When block.size=c(8, 4, 2) and block.size.shift = c(0, .5, .9), the first half of the randomization is performed in blocks of 8, then the next 40 percent of the randomization is performed in blocks of 4, with the last ten percent performed in blocks of 2.
seed.dev	integerish. At least one value is required. If only one value is given, it will be converted to a vector with length equal to the number of strata. Values will be incremented by 100 to provide independent randomizations. This may also have length equal to the number of strata.
seed.prod	integerish. Same as seed.dev, but used to seed the production allocation. No pairwise elements of seed.dev and seed.prod may be equal. This guarantees that the two randomization schemes are unique.
weights	An optional vector giving the sampling weights for each of the randomization groups. There must be one number for each level of the randomization variable. If named, the names must match the group labels. If unnamed, the group labels will be assigned in the same order they appear in the data dictionary. The weights will be normalized, so they do not need to sum to 1.0. In other words, weights=c(3, 1) can indicate a 3:1 sampling ratio.
...	Arguments to pass to other methods
meta_data	character(1). For the offline method, a text string giving the location of the data dictionary downloaded from REDCap.

Details

Each element in block.size must be a multiple of the number of groups in the randomized variable.

The 'offline' version of the function operates on the data dictionary file downloaded from REDCap. This is made available for instances where the API cannot be accessed for some reason (such as waiting for API approval from the REDCap administrator).

The value of replicates controls how many allocations are generated. It is possible to get slightly more replicates than requested if your blocking design cannot exactly match replicates. For example, if the users asks for 30 replicates in blocks of 8, a warning will be printed and 32 replicates will be returned in the randomization table.

Value

Returns a list with the elements

dev_allocation	data.frame with the randomization allocations for the development environment.
prod_allocation	data.frame with the randomization allocations for the production environment.
dev_seed	The random seed values for the development environment.
prod_seed	The random seed values for the production environment.
blocks	Blocking scheme used to generate the randomization.
weights	Weighting scheme for the randomization.

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
allocationTable(rcon, 
                random = "treatment_assignment", 
                strata = c("demographic_group", "hospital_group"), 
                replicates = 12, 
                block.size = 4, 
                seed.dev = 12345, 
                seed.prod = 54321)

## End(Not run)

---

Export, Import, and Delete Arms from a Project

Description

These methods enable the user to export the current arms from a project, import new arms, and modify or delete existing arms.

Usage

exportArms(rcon, ...)

importArms(rcon, data, override = FALSE, ...)

deleteArms(rcon, arms, ...)

## S3 method for class 'redcapApiConnection'
exportArms(rcon, arms = character(0), ...)

## S3 method for class 'redcapApiConnection'
importArms(rcon, data, override = FALSE, ...)

## S3 method for class 'redcapApiConnection'
deleteArms(rcon, arms, ...)

Arguments

rcon	A redcapConnection object.
arms	character or integerish identifying the arm numbers to export or delete.
data	A data.frame with two columns. The first column (arm_num) is an integerish value . The second (name) is a character value. For backward compatibility, this may also be passed as arms_data.
override	logical(1). By default, data will add to or modify existing arms data. When TRUE, all the existing arms data is deleted and replaced with the contents of data.
...	Arguments to pass to other methods

Details

Exporting arms is not supported for classical REDCap projects. If the user attempts to export arms for a classical project, a data frame will be returned with zero rows.

When importing, arms are added when the value of arm_num does not already exist in the project.

Arm names may be modified by altering the name value associated with an existing arm_num value.

Deleting arms–whether by deleteArms or importArms with override = TRUE–is a destructive act that also deletes events and records associated with the arm. This is irreversible data loss. REDCap will only permit these actions to occur in projects in Development status.

Value

exportArms returns a data.frame with columns:

arm_num	The ID number for the arm in the project.
name	The display name of the arm.

importArms invisibly returns the number of arms imported.

deleteArms invisibly returns the number of arms deleted.

Functions

• exportArms(): Export the arms defined in a project.

• importArms(): Import and modify the arms definitions in a project.

• deleteArms(): Delete arms from a project.

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export all of the Arms
exportArms(rcon)

# Export only a subset of arms
exportArms(rcon, 
           arms = c(1, 3))


# Import a new arms
# Assume arms 1, 2, and 3 exist in the project already
NewData <- data.frame(arm_num = 4, 
                      name = "Arm Four Name")
importArms(rcon, 
           data = NewData)
           
# Change the name of an existing arm
NewData <- data.frame(arm_num = 1, 
                      name = "New Arm Name")
importArms(rcon, 
           data = NewData)
           
# Delete all arms and replace with a new specification
NewData <- data.frame(arm_num = c(1, 2), 
                      name = c("Treatment Arm", "Control Arm"))
importArms(rcon, 
           data = NewData, 
           override = TRUE)
           
# Delete an existing arm
deleteArms(rcon, 
           arms = 4)
         
# Delete multiple existing arm
deleteArms(rcon, 
           arms = c(2, 3))

## End(Not run)

---

S3 method to turn curl response into character

Description

Converts a raw curl response into a character string.

Usage

## S3 method for class 'response'
as.character(x, ...)

Arguments

x	response from curl to render to character
...	If type='text/csv' this is passed to read.csv. If type='application/json' this is sent to jsonlite::fromJSON

---

Assemble Codebook From the Data Dictionary

Description

This method enables the user to construct a code book similar in style to the REDCap project codebook. The codebook is similar in nature to the data dictionary, but multiple choice fields are represented with one line per coding.

Usage

assembleCodebook(
  rcon,
  fields = NULL,
  forms = NULL,
  drop_fields = NULL,
  field_types = NULL,
  include_form_complete = TRUE,
  expand_check = FALSE,
  ...
)

## S3 method for class 'redcapConnection'
assembleCodebook(
  rcon,
  fields = NULL,
  forms = NULL,
  drop_fields = NULL,
  field_types = NULL,
  include_form_complete = TRUE,
  expand_check = FALSE,
  ...
)

## S3 method for class 'redcapCodebook'
as.list(x, ...)

Arguments

rcon	A redcapConnection object.
fields	character or NULL. When character, the code book will be limited to the intersection of the fields designated by fields and forms. When NULL, all fields are included.
forms	character or NULL. When character, the code book will be limited to the intersection of the fields designated by fields and forms. When NULL, all forms are included.
drop_fields	character or NULL. When given, fields named will be removed from the code book.
field_types	character or NULL. When given, only the field types listed will be included in the code book. This will supercede the intersection of fields and forms. Matching of field types is performed against the values in the field_type column of the meta data.
include_form_complete	logical(1). When TRUE, the ⁠[form name]_complete⁠ fields will be included in the codebook.
expand_check	logical(1). When FALSE, the codebook for checkbox fields will be similar to the codebook for dropdown and radio fields, with one line per user-defined option. When TRUE, each checkbox option will be represented in two fields, one each for 0 (Unchecked) and 1 (Checked).
...	Arguments to pass to other methods
x	A redcapCodebook object as returned by assembleCodebook.

Value

Returns a redcapCodebook object. This inherits the data.frame class and has the columns

• field_name - The name of the field.

• form - The name of the form on which the field is located.

• field_type - The field type.

• code - For multiple choice fields, the coding for the option.

• label - For multiple choice fields, the label for the option.

• min - For date and numeric fields, the minimum value in the validation, if any.

• max - For date and numeric fields, the maximum value in the validation, if any.

• branching_logic - For fields with branching logic, the string denoting the logic applied.

• field_order - The numeric order of the field in the data dictionary.

• form_order - The numeric order of the form in the data dictionary.

See Also

exportMetaData()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# codebook for the entire project
assembleCodebook(rcon)

# codebook for multiple choice fields
assembleCodebook(rcon, 
                 field_types = c("dropdown", "radio", "checkbox", 
                                 "yesno", "truefalse"))

## End(Not run)

---

returns a list of record IDs changed (adds, updates, deletes)

Description

This is a convenience function that scans logs and returns record IDs of changed records.

Usage

changedRecords(rcon, ...)

Arguments

rcon	A redcapConnection object.
...	Arguments passed to exportLogging()

Details

Makes a call to exportLogging with passed arguments. Returns filtered list or records IDs with update, delete or create events.

Value

Returns a list with the elements

updated	character vector of updated record IDs
deleted	character vector of deleted record IDs
created	character vector of created record IDs

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Changes in last 24 hours     
changedRecords(rcon, beginTime=as.POSIXct(Sys.time()-86400))

## End(Not run)

---

Checkbox Suffixes

Description

Checkbox variables return one vector of data for each option defined in the variable. The variables are returned with the suffix ⁠___[option]⁠. exportRecords needs these suffixes in order to retrieve all of the variables and to apply the correct labels.

Usage

checkbox_suffixes(fields, meta_data)

Arguments

fields	The current field names of interest
meta_data	The metadata data frame.

---

Construct a Link to a REDCap Form

Description

Uses information from the project and a record to link to the form on which a data element is recorded. This is intended to be used within the report of invalid results when exporting or importing records. It should be noted that when importing records, the records may not yet exist and the links may not work.

Usage

constructLinkToRedcapForm(rcon, form_name, record_id, event_id = NULL, ...)

## S3 method for class 'redcapApiConnection'
constructLinkToRedcapForm(rcon, form_name, record_id, event_id = NULL, ...)

## S3 method for class 'redcapOfflineConnection'
constructLinkToRedcapForm(rcon, form_name, record_id, event_id = NULL, ...)

Arguments

rcon	A redcapConnection object.
form_name	character. The name of the form on which the field name exists.
record_id	character. The ID of the record being linked to. If passed as a numeric value, it will be coerced to character. Must have the same length as form_name.
event_id	character or NULL. For classical projects, use either NULL or NA (NA support is permitted to assist with vectorization). For longitudinal projects, the ID of the unique event. If passed as a numeric value, it will be coerced to character.
...	Arguments to pass to other methods

Details

Constructing a link to a REDCap form requires knowledge of the following:

• The REDCap instance url (usually 'redcap.institution.domain').

• The REDCap instance version number.

• The REDCap project ID number

• The record ID

• The form name

• The event ID number (if the project is longitudinal).

If any of these items in unknown, a missing value will be returned. For redcapOfflineConnections, the user will need to provide the version number, the project information, and the events (if the project is longitudinal) as part of the call to offlineConnection. Note that the REDCap User Interface does not include the event ID number with the file download for events.

Value

Returns a character vector the same length of form_name.

---

Create a Folder in the File Repository

Description

This method enables the user to create a folder in the file repository. The folder created may also be a subfolder of an existing folder.

Usage

createFileRepositoryFolder(
  rcon,
  name,
  folder_id = numeric(0),
  dag_id = numeric(0),
  role_id = numeric(0),
  ...
)

## S3 method for class 'redcapApiConnection'
createFileRepositoryFolder(
  rcon,
  name,
  folder_id = numeric(0),
  dag_id = numeric(0),
  role_id = numeric(0),
  ...
)

Arguments

rcon	A redcapConnection object.
name	character(1) The name of the folder. If a folder by this name already exists, no action will be taken.
folder_id	integerish(0/1). The ID of the parent folder. When length is 0, the new folder is placed in the top-level.
dag_id	integerish(0/1) The ID of a data access group. When provided, access to the folder will be restricted to the DAG.
role_id	integerish(0/1) The ID of a role. When provided, access to the folder will be restricted to users with that role.
...	Arguments to pass to other methods

Value

Returns a data frame with the columns

folder_id	The REDCap assigned ID value for the newly created folder.
name	The name assigned to the folder by the user.

See Also

exportFromFileRepository(),
importToFileRepository(),
deleteFromFileRepository(),
exportFileRepository(),
importFileRepository(),
deleteFileRepository(),
exportFileRepositoryListing()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Create a folder in the top-level directory
createFileRepositoryFolder(rcon, 
                           name = "New Folder Name")
                           
# Create a folder in a subfolder
createFileRepositoryFolder(rcon, 
                           name = "New Folder Name", 
                           folder_id = 12345)
                           
# Create a folder assigned to a Data Access Group
createFileRepositoryFolder(rcon, 
                           name = "New Folder Name", 
                           dag_id = 678)

## End(Not run)

---

Create REDCap Project

Description

These methods enable a user with a 64-character Super API token to create a new REDCap project.

Usage

createRedcapProject(
  rcon,
  project_title,
  purpose = REDCAP_PROJECT_PURPOSE,
  purpose_other = NULL,
  is_longitudinal = FALSE,
  surveys_enabled = FALSE,
  record_autonumbering_enabled = FALSE,
  xml = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
createRedcapProject(
  rcon,
  project_title,
  purpose = REDCAP_PROJECT_PURPOSE,
  purpose_other = NULL,
  is_longitudinal = FALSE,
  surveys_enabled = FALSE,
  record_autonumbering_enabled = FALSE,
  xml = NULL,
  ...
)

Arguments

rcon	A redcapConnection object.
project_title	character(1). Title for the new project.
purpose	character, one of c("Practice/just for fun", "Other", "Research", "Quality Improvement", "Operational Support")
purpose_other	character(1) or NULL. Ignored unless purpose = "Other", in which case this becomes a required argument.
is_longitudinal	logical(1). When TRUE the project will be set as a longitudinal project.
surveys_enabled	logical(1). When TRUE surveys are enabled for the project. (This will not add any survey instruments, only enable them).
record_autonumbering_enabled	logical(1). When TRUE if auto numbering will be enabled in the project.
xml	character(1) or NULL an XML string in CDISC ODM XML format that contains project metadata (fields, forms, events, arms) and might optionally contain data to be imported as well. When not NULL, all other arguments are ignored. See Details.
...	Arguments to pass to other methods

Details

The user creating the project will automatically be added to the project as a user with full user privileges and a project-level API token, which could then be used for subsequent project-level API requests.

When the project is created, it will automatically be given all the project-level defaults just as if it had been created via the web user interface, such as automatically creating a single data collection instrument seeded with a single Record ID field and Form Status field, as well as (for longitudinal projects) one arm with one event.

If the user intends to populate the project with arms and events immediately after creating the project, it is recommended that override = TRUE be used in importArms and importEvents so that the default arm and event are removed.

The xml argument must be in CDISC ODM XML format. It may come from a REDCap Project XML export file from REDCap itself (see exportProjectXml()), or may come from another system that is capable of exporting projects and data in CDISC ODM format. If the xml argument is used in the API request, it will use the XML to import its contents into the newly created project. This will not only create the project with the API request, but also to import all fields, forms, and project attributes (and events and arms, if longitudinal) as well as record data all at the same time.

Only users with a 64-character Super API Tokens can utilize this method (the standard API token is 32 characters). Users can only be granted a super token by a REDCap administrator (using the API Tokens page in the REDCap Control Center). Please be advised that users with a Super API Token can create new REDCap projects via the API without any approval needed by a REDCap administrator.

Value

Returns a character(1) the 32-character, project level API token assigned to the user that created the project. This token is intended to be used for further project configuration using the API.

See Also

exportProjectXml()

Examples

## Not run: 
# The token must be a 64-character token
super_token <- redcapConnection(url = "your_redcap_url", 
                                token = "[64-character-super-api-token]")
         
# Create a new project    
createRedcapProject(super_token, 
                    project_title = "New Project Name", 
                    purpose = "Quality Improvement", 
                    is_longitudinal = FALSE, 
                    surveys_enabled = TRUE)
                    
                    
                    
# Copy an existing project into a new project
unlockREDCap(connections = c(rcon = "token_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
xml_file <- tempfile(file.ext = ".xml")
exportProjectXml(rcon, 
                 file = xml_file)
 
xml_text <- paste0(readLines(xml_file), collapse = " ")
createRedcapProject(super_token, 
                    xml = xml_text)

## End(Not run)

---

Export and Import Users Assigned to Data Access Groups

Description

These methods enable the user to export existing assignments of users to Data Access Groups, or import new or updated assignments to the project.

Usage

exportUserDagAssignments(rcon, ...)

importUserDagAssignments(rcon, data, ...)

## S3 method for class 'redcapApiConnection'
exportUserDagAssignments(rcon, ...)

## S3 method for class 'redcapApiConnection'
importUserDagAssignments(rcon, data, ...)

Arguments

rcon	A redcapConnection object.
data	data.frame with the columns username and redcap_data_access_group. The should only be one row per user name.
...	Arguments to pass to other methods

Details

When modifying existing assignments using the import method, the user must provide the unique user name and the group name. If the redcap_data_access_group column is not provided, the REDCap user will not be assigned to any group.

Value

exportUserDagAssignments method returns a data frame with two columns:

username	The unique user name for each user in the project.
redcap_data_access_group	The unique Data Access Group name to which the user is assigned.

importUserDagAssignments invisibly returns the number of assignments imported.

Functions

• exportUserDagAssignments(): Export current User-DAG Assignments

• importUserDagAssignments(): Import new or modified User-DAG Assignments.

See Also

exportDags(),
importDags(),
deleteDags(),
switchDag()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export the current assignments
exportUserDagAssignments(rcon)

# Assign a user to a Data Access Group
ForImport <- data.frame(username = "user1", 
                        redcap_data_access_group = "facility_one")
importUserDagAssigments(rcon, 
                        data = ForImport)
                                          
# Assign a multiple users to a Data Access Group
ForImport <- data.frame(username = c("user1", "user2", "user3"), 
                        redcap_data_access_group = c("facility_one", 
                                                     "facility_one", 
                                                      "facility_two"))
importUserDagAssigments(rcon, 
                        data = ForImport)
                        
# Remove a user from all Data Access Groups
ForImport <- data.frame(username = "user1", 
                        redcap_data_access_group = NA_character_)
importUserDagAssigments(rcon, 
                        data = ForImport)

## End(Not run)

---

Export, Import, Delete Data Access Groups from a Project

Description

These methods enable the user to export existing Data Access Groups, import new Data Access Groups, or delete Data Access Groups from a project.

Usage

exportDags(rcon, ...)

importDags(rcon, data, ...)

deleteDags(rcon, dags, ...)

## S3 method for class 'redcapApiConnection'
exportDags(rcon, ...)

## S3 method for class 'redcapApiConnection'
importDags(rcon, data, ...)

## S3 method for class 'redcapApiConnection'
deleteDags(rcon, dags, ...)

Arguments

rcon	A redcapConnection object.
dags	character vector of names matching the unique_group_name.
data	A data.frame with two columns: data_access_group_name and unique_group_name.
...	Arguments to pass to other methods

Details

To import new data access groups, the user must provide a value for data_access_group_name with no value (NA) for unique_group_name.

To modify a group name, provide a new value for data_access_group_name with the associated unique_group_name. If unique_group_name is provided, it must match a value currently in the project.

Value

exportDags with the columns

data_access_group_name	The human readable name for the data access group.
unique_group_name	The internal unique group name.
data_access_group_id	The internal numeric identifier.

importDags invisibly returns the number of Data Access Groups imported.

deleteDags invisibly returns the number of Data Access Groups deleted.

Functions

• exportDags(): Export Data Access Groups from a REDCap Project

• importDags(): Import Data Access Groups to a project.

• deleteDags(): Delete Data Access Groups from a project.

See Also

switchDag(),
exportUserDagAssignments(),
importUserDagAssignments()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

exportDags(rcon)


# Import a new Data Access Group
NewData <- data.frame(data_access_group_name = "New DAG Name", 
                      unique_group_name = NA_character_)
importDags(rcon, 
           data = NewData)
           
# Modify an existing Data Access Group Name
# The user will need to match the unique_group_name to the existing DAGs
ChangeData <- data.frame(data_access_group_name = "Altered DAG Name", 
                         unique_group_name = "new_dag_name")
importDags(rcon, 
           data = ChangeData)
           
# Delete a Data Access Group
deleteDags(rcon, 
           dags = c("new_dag_name"))

## End(Not run)

---

Delete Records from a Project

Description

These methods enable the user to delete records from a project.

Usage

deleteRecords(
  rcon,
  records,
  arm = NULL,
  instrument = NULL,
  event = NULL,
  repeat_instance = NULL,
  delete_logging = FALSE,
  ...
)

## S3 method for class 'redcapApiConnection'
deleteRecords(
  rcon,
  records,
  arm = NULL,
  instrument = NULL,
  event = NULL,
  repeat_instance = NULL,
  delete_logging = FALSE,
  ...
)

Arguments

rcon	A redcapConnection object.
records	character or integerish. Record ID's to be returned.
arm	integerish. the arm number of the arm in which the record(s) should be deleted. This can only be used if the project is longitudinal with more than one arm. If the arm parameter is not provided, the specified records will be deleted from all arms in which they exist. Whereas, if arm is provided, they will only be deleted from the specified arm.
instrument	character(1) Optional instrument to delete records from.
event	character(1) Optional event to delete records from.
repeat_instance	numeric(1) optional repeat instance to delete records from.
delete_logging	logical. Should the logging for this record be delete as well. Default to FALSE.
...	Arguments to pass to other methods

Value

deleteRecords invisibly returns a character value giving the number of records deleted.

See Also

exportRecords(),
importRecords(),
exportRecordsTyped()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Delete records
deleteRecords(rcon, 
              records = c("1", "2"))


## End(Not run)

---

Deprecated Functions

Description

The redcapProjectInfo function has been deprecated to avoid confusion with the API method now executed by exportProjectInformation. The replacement function is exportBundle().

Usage

redcapProjectInfo(
  rcon,
  date = TRUE,
  label = TRUE,
  meta_data = TRUE,
  users = TRUE,
  instruments = TRUE,
  events = TRUE,
  arms = TRUE,
  mappings = TRUE,
  version = TRUE,
  ...
)

## S3 method for class 'redcapApiConnection'
redcapProjectInfo(
  rcon,
  date = TRUE,
  label = TRUE,
  meta_data = TRUE,
  users = TRUE,
  instruments = TRUE,
  events = TRUE,
  arms = TRUE,
  mappings = TRUE,
  version = TRUE,
  ...,
  v.number = ""
)

Arguments

rcon	A REDCap connection object as generated by redcapConnection
date	Logical. If TRUE, user expiration dates are converted to POSIXct objects.
label	Logical. If TRUE, the user form permissions are converted to labeled factors.
meta_data	Logical. Indicates if the meta data (data dictionary) should be exported.
users	Logical. Indicates if the users table should be exported.
instruments	Logical. Indicates if the instruments table should be exported.
events	Logical. Indicates if the event names should be exported.
arms	Logical. Indicates if the arms table should be exported.
mappings	Logical. Indicates if the form-event mappings should be exported.
version	Indicates if the REDCap version number should be exported. Only applicable in REDCap 6.0.0 and higher.
...	Arguments to be passed to other methods
v.number	A character string given the desired version number should the API method not be available.

---

Drop Row Where Repeat Instrument Is NA

Description

Drops rows where the repeat instrument is NA. Returns a data frame of records where repeat instruments have a value.

Usage

dropRepeatingNA(Records, rcon, quiet = FALSE)

Arguments

Records	A data.frame containing the records from exportRecordsTyped()
rcon	A redcapConnection object.
quiet	logical(1). When FALSE, a message is printed indicating how many rows were in Records at the start and completion of the subset.

See Also

exportRecordsTyped(),
exportReportsTyped()

---

Export, Import, and Delete Event Settings

Description

These methods enable the user to export event settings, import new events, update settings for existing events, or delete events.

Usage

exportEvents(rcon, ...)

importEvents(rcon, data, override = FALSE, ...)

deleteEvents(rcon, events = NULL, ...)

## S3 method for class 'redcapApiConnection'
exportEvents(rcon, arms = NULL, ...)

## S3 method for class 'redcapApiConnection'
importEvents(rcon, data, override = FALSE, ...)

## S3 method for class 'redcapApiConnection'
deleteEvents(rcon, events = NULL, ...)

Arguments

rcon	A redcapConnection object.
arms	character or integerish identifying the arm numbers for which event data will be exported.
events	character giving the unique event names of the events to be deleted.
data	data.frame. Must have columns event_name and arm_num. To modify existing events, it must also have a column unique_event_name. It may optionally have columns for days_offset, offset_min, offset_max. For backward compatibility, this argument may be passed as event_data.
override	logical(1). By default, data will add to or modify existing arms data. When TRUE, all the existing arms data is deleted and replaced with the contents of data.
...	Arguments to pass to other methods

Details

Exporting events is not supported for classical REDCap projects. If the user attempts to export arms for a classical project, a data frame will be returned with zero rows.

Additionally, in order for events to be exported, the project must be longitudinal, have at least one arm, and at least one event defined. When these conditions are not satifisfied, exportEvents will return a data frame with zero rows.

To import new events, the user must provide data with the unique_event_name set to NA (REDCap assigns the unique event name automatically from the user provided event_name).

To modify existing events, the user must provide the unique_event_name. The other fields in the data provided will overwrite the current values for the matching event.

Deleting events–whether by deleteEvents or importEvents with override = TRUE–is a destructive act that also deletes arms and records associated with the event. This is irreversible data loss. REDCap will only permit these actions to occur in projects in Development status.

Value

exportEvents returns a data frame with the columns:

event_name	The user provided name for the event.
arm_num	The arm number the event is associated with.
unique_event_name	The REDCap generated event name.
custom_event_label	An optional user provided label that may be used in place of the event name.
event_id	REDCap's internal event identifier.
days_offset	The number of days since time zero (start of the study or project period) an event is scheduled to occur. This field is only provided when the scheduling module is enabled.
offset_min	The number of days before the days_offset during which the event may occur. This field is only provided when the scheduling module is enabled.
offset_max	The number of days before the days_offset during which the event may occur. This field is only provided when the scheduling module is enabled.

importEvents invisibly returns the number of events added or modified.

deleteEvents invisibly returns the number of events deleted.

Functions

• exportEvents(): Export events from a REDCap project.

• importEvents(): Add events to a project or modify existing events.

• deleteEvents(): Delete events from a project.

See Also

exportMappings(),
importMappings()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export all events
exportEvents(rcon)

# Export events for a subset of arms
exportEvents(rcon, 
             arms = c(1, 3))
             
# Import new events
NewEvents <- data.frame(event_name = c("Event 1", 
                                       "Event 2"), 
                        arm_num = c(1, 1))
importEvents(rcon, 
             data = NewEvents)
             
# Modify existing events
UpdateEvents <- data.frame(event_name = "Event 2 New Name", 
                           arm_num = 1, 
                           unique_event_name = "event_2_arm_1", 
                           custom_event_label = "The second visit")
importEvents(rcon, 
             data = UpdateEvents)
             
# Replace all events with a new set
NewEvents <- data.frame(event_name = c("Event 1", 
                                       "Event 2", 
                                       "Event 1"), 
                        arm_num = c(1, 1, 2))
importEvents(rcon, 
             data = NewEvents, 
             override = TRUE)
             
# Delete events
deleteEvents(rcon, 
             events = c("event_1_arm_1", "event_1_arm_2"))

## End(Not run)

---

A helper function to export multiple records and forms using a single call.

Description

Exports records from multiple REDCap Databases using multiple calls to exportRecordsTyped()

Usage

exportBulkRecords(
  lcon,
  forms = NULL,
  envir = NULL,
  sep = "_",
  post = NULL,
  ...
)

Arguments

lcon	A named list of connections. The name is used as a prefix for data.frame names in the environment specified. It may also be used as a reference from the forms argument.
forms	A named list that is a subset of rcon's names. A specified rcon will provide a list of forms for repeated calls to exportRecordsType. If a connection reference is missing it will default to all forms. To override this default specify a connection's forms with NA to just get all data.
envir	A environment to write the resulting Records in as variables given by their name in rcon or if from a form their rcon named pasted to their form name joined by sep. If not specified the function will return a named list with the results. Will accept a number of the environment.
sep	A character string to use when joining the rcon name to the form name for storing variables.
post	A function that will run on all returned sets of Records.
...	Any additional variables to pass to exportRecordsTyped().

Value

Will return a named list of the resulting records if envir is NULL. Otherwise will assign them to the specified envir.

See Also

Other records exporting functions

exportRecordsTyped(),
exportRecords(),
exportReports()

Field validations and casting

fieldValidationAndCasting(),
reviewInvalidRecords()

Post-processing functionality

recastRecords(),
guessCast(),
guessDate(),
castForImport(),
mChoiceCast(),
splitForms(),
widerRepeated()

Vignettes

vignette("redcapAPI-offline-connection")
vignette("redcapAPI-casting-data")
vignette("redcapAPI-missing-data-detection")
⁠vignette("redcapAPI-data-validation)⁠
⁠vignette("redcapAPI-faq)⁠

Examples

## Not run: 
unlockREDCap(c(test_conn    = 'TestRedcapAPI',
               sandbox_conn = 'SandboxAPI'),
             keyring      = 'MyKeyring',
             envir        = globalenv(),
             url          = 'https://<REDCAP_URL>/api/') 

# After user interaction to unlock the local encrypted keyring
# the global environment will contain the REDCap connections
# `test_conn` and `sandbox_conn`
# 
# Next the user wants to bulk specify importing all the forms
# of interest and post process

exportBulkRecords(
 rcon  = list(test = test_conn,
              sand = sandbox_conn),
 forms = list(test = c('form1', 'form2'),
 envir = globalenv(),
 post  = function(Records, rcon)
         {
           Records              |>
           mChoiceCast(rcon)    |>
           guessDat(rcon)       |>
           widerRepeating(rcon)
         }
 )
 
# The environment now contains the data.frames: `test.form1`, `test.form2`, `sand`.
# Each of these were retrieved, possibly using the forms argument and all were
# post processed in the same manner as specified by `post`.

## End(Not run)

---

Perform a bundle of API calls.

Description

This function is deprecated and will be removed with the release of redcapAPI 3.0.0. It's functionality is built into caching of data onto the redcapConnection object.

Several of the API calls return objects that can be used to perform various validations in exportRecords, exportReports, and other methods. Using an export bundle allows the user to call these methods once and store the result instead of issuing an additional call to the API each time a method is invoked.

For example, if the user is uploading several files to the API, without an export bundle, importFiles will utilize the exportMetaData on each call in order to perform validations. Using a bundle allows the user to download the meta data once and refer to it on every subsequent call that requires the data dictionary.

Usage

exportBundle(
  rcon,
  date = TRUE,
  label = TRUE,
  meta_data = TRUE,
  users = TRUE,
  instruments = TRUE,
  events = TRUE,
  arms = TRUE,
  mappings = TRUE,
  version = TRUE,
  ...
)

## S3 method for class 'redcapApiConnection'
exportBundle(
  rcon,
  date = TRUE,
  label = TRUE,
  meta_data = TRUE,
  users = TRUE,
  instruments = TRUE,
  events = TRUE,
  arms = TRUE,
  mappings = TRUE,
  version = TRUE,
  ...,
  return_object = TRUE
)

Arguments

rcon	A REDCap connection object as generated by redcapConnection
date	Logical. If TRUE, user expiration dates are converted to POSIXct objects.
label	Logical. If TRUE, the user form permissions are converted to labeled factors.
meta_data	Logical. Indicates if the meta data (data dictionary) should be exported.
users	Logical. Indicates if the users table should be exported.
instruments	Logical. Indicates if the instruments table should be exported.
events	Logical. Indicates if the event names should be exported.
arms	Logical. Indicates if the arms table should be exported.
mappings	Logical. Indicates if the form-event mappings should be exported.
version	Indicates if the REDCap version number should be exported. Only applicable in REDCap 6.0.0 and higher.
...	Arguments to be passed to other methods
return_object	Logical. When TRUE, the exportBundle object is returned to the workspace.

Details

The project information is stored in the option redcap_project_info. If the project is not longitudinal, the events, arms, and event-form mappings elements will be assigned character vectors instead of data frames.

---

A helper function to export data queries from the Data Quality REDCap module.

Description

Exports Data Quality queries by record. The Data Quality module must be enabled on the Control Center of REDCap to use this function. Additionally, this module must be enabled on each project before it can be used.

Usage

exportDataQuality(rcon, prefix, ...)

Arguments

rcon	A REDCap connection object as generated by redcapConnection.
prefix	A string from your REDCap institutions Data Quality module url. The module prefix can be found by exporting module settings under External Modules in REDCap. At VUMC the prefix is 'vanderbilt_dataQuality'.
...	additional arguments that are ignored.

---

Export Codebook Mappings for Fields with External Dependencies

Description

These methods enable redcapAPI to obtain a mapping of codes and associated labels for fields that have external dependencies. The fields include SQL fields (dependent on another project) or fields that utilize the BioPortal Ontology modules.

Usage

exportExternalCoding(rcon, fields, ...)

## S3 method for class 'redcapApiConnection'
exportExternalCoding(rcon, fields = NULL, ..., batch_size = 1000)

Arguments

rcon	A redcapConnection object.
fields	character or NULL. Vector of fields to be returned. If NULL, all fields are returned (unless forms is specified).
...	Arguments to pass to other methods
batch_size	integerish(1) or NULL. When NULL, all records are pulled. Otherwise, the records all pulled in batches of this size.

Details

These methods operate by executing two API calls to export first the coded values and then the labeled values of fields with external dependencies. The two exports are then used to generate the code-label mappings for use in casting data.

Fields of type sql are dropdown fields that are populated by a SQL query to another project.

Fields of type bioportal are text fields that have the BioPortal Ontology module enabled as the validation method.

Value

Returns a named list of named character vectors.

Each element is in the list is named for the field it maps.

The character vectors are name-value pairs where the name is the labeled data and the value is the coded data.

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
exportExternalCoding(rcon)

## End(Not run)

---

Export the Complete Field Names for a REDCap Project

Description

This method enables the user to access the complete field names utilized during export and import methods. These are expecially relevant when working with checkbox fields.

Usage

exportFieldNames(rcon, ...)

## S3 method for class 'redcapApiConnection'
exportFieldNames(rcon, fields = character(0), ...)

Arguments

rcon	A redcapConnection object.
fields	NULL or character(1). Field name to be returned. By default, all fields are returned.
...	Arguments to pass to other methods

Details

exportFieldNames returns a data frame of the field names the user may use when performing export and import functions. This is most useful when working with checkbox fields, which have a different field name than the one used in the Meta Data. The exported/imported field names for checkbox fields have the pattern ⁠[field_name]___[coded_checkbox_value]⁠ (there are exactly three underscores separating the field name and the coded value).

Fields of types "calc", "file", and "descriptive" are not included in the export. (Signature fields also have the "file" type and are not included)

Value

exportFieldNames returns a data frame with the columns:

original_field_name	The field name as recorded in the data dictionary
choice_value	represents the raw coded value for a checkbox choice. For non-checkbox fields, this will always be NA.
export_field_name	The field name specific to the field. For non-checkbox fields, this is the same as original_field_name. For checkbox fields, it is the field name appended with ⁠___[choice_value]⁠.

See Also

exportMetaData(),
importMetaData(),
exportInstruments(),
exportMappings(),
importMappings(),
exportPdf()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export all of the field names
exportFieldNames(rcon)

# Export MetaData for a specific field
exportFieldNames(rcon, 
                 fields = "checkbox_test")

## End(Not run)

---

Export a Listing of Folders and Files in the File Repository

Description

This method enables the user to export a list of folders and files saved to the File Repository. The listing may optionally include contents of subfolders.

Usage

exportFileRepositoryListing(
  rcon,
  folder_id = numeric(0),
  recursive = FALSE,
  ...
)

## S3 method for class 'redcapApiConnection'
exportFileRepositoryListing(
  rcon,
  folder_id = numeric(0),
  recursive = FALSE,
  ...
)

Arguments

rcon	A redcapConnection object.
folder_id	integerish(0/1). The folder ID of a specific folder in the File Repository for which a list of files and subfolders will be exported. By default, the top-level directory of the File Repository will be used.
recursive	logical(1). When TRUE, content of subfolders will be retrieved until a full listing is produced. If FALSE, only the contents of the requested folder will be returned.
...	Arguments to pass to other methods

Value

Returns a data frame with the columns

folder_id	The REDCap assigned ID value for the folder. Will be NA if the item is a file.
doc_id	The REDCap assigned ID value for the file. Will be NA if the item is a folder.
name	The name of the folder of file.
parent_folder	The ID of the parent folder of the item. The top-level folder is represented as 0.

See Also

exportFromFileRepository(),
importToFileRepository(),
deleteFromFileRepository(),
exportFileRepository(),
importFileRepository(),
deleteFileRepository(),
createFileRepositoryFolder()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Export the top-level listing of the File Repository
exportFileRepositoryListing(rcon)

# Export the complete listing of the File Repository
exportFileRepositoryListing(rcon, 
                            recursive = TRUE)
                            
# Export the listing of a subfolder in the File Repository
exportFileRepositoryListing(rcon, 
                            folder_id = 12345)

## End(Not run)

---

Export Multiple Files From a Project

Description

This method enables the user to export multiple files from a REDCap project with a single call. The REDCap API only allows for one file to be exported per call, and the exportFiles() methods are written to mirror that limitation. This extension allows the user to pass vectors of arguments for records, fields, events, or repeat instances. Files that can be matched to any combination of these values will be exported.

Usage

exportFilesMultiple(
  rcon,
  record,
  field,
  event = NULL,
  dir,
  file_prefix = TRUE,
  ...
)

## S3 method for class 'redcapApiConnection'
exportFilesMultiple(
  rcon,
  record,
  field,
  event = NULL,
  dir,
  file_prefix = TRUE,
  repeat_instance = NULL,
  ...,
  quiet = TRUE
)

Arguments

rcon	A redcapConnection object.
record	character or integerish. The record ID in which the desired file is stored.
field	character. The field name in which the file is stored.
event	character or NULL. The event name for the file. This applies only to longitudinal projects. If the event is not supplied for a longitudinal project, the API will return an error message
dir	character(1). A directory/folder to which the file will be saved. By default, the working directory is used.
file_prefix	logical(1). Determines if a prefix is appended to the file name. The prefix takes the form ⁠[record_id]-[event_name]-[file_name]⁠. The file name is always the same name of the file as it exists in REDCap.
...	Arguments to pass to other methods
repeat_instance	integerish or NULL. The repeat instance number of the repeating event or the repeating instrument. When available in your instance of REDCap, and passed as NULL, the API will assume a value of 1.
quiet	logical(1). When TRUE, any errors encountered while exporting files will be converted to messages.

Details

exportFilesMultiple will construct all combinations of the record, field, event, and repeat_instance arguments and attempt to export the file associated with each combination. Should any of these combinations produce an error (for example, if a record does not have a third repeat instance), the error is captured and returned with the output.

Value

Invisibly returns a data.frame with the following columns:

Column	Description
record	The record ID
field	The name of the field in which the file is stored.
event	The name of the event associated with the file.
repeat_instance	For repeat instances, the instance associated with the file.
is_exported	logical indicating if the file was successfully exported.
saved_to	The file path to which the file was saved.
error	If an error was encountered, the text of the error.

See Also

exportFiles()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
save_to_dir <- tempdir() 

# Export files for multiple records
# Results are returned invisibly - saving to an object is
#   helpful to be able to view the results

Export <- 
  exportFilesMultiple(rcon, 
                      record = 1:4, 
                      field = "file_upload_field", 
                      event = "event_1_arm_1", 
                      dir = save_to_dir)
Export 
                    
# Export files for multiple instances

Export <- 
  exportFilesMultiple(rcon, 
                      record = 1, 
                      field = "file_upload_field", 
                      event = "event_1_arm_1", 
                      repeat_instance = 1:4, 
                      dir = save_to_dir)
Export
                    
# Export files for multiple records, fields, events, and instances

Export <- 
  exportFilesMultiple(rcon, 
                      record = 1:10, 
                      field = c("registration", "waiver"), 
                      events = c("event_1_arm_1", "event_2_arm_1"), 
                      repeat_instance = 1:3, 
                      dir = save_to_dir)
Export

## End(Not run)

---

Export Instruments Defined in a Project

Description

These methods enable the user to view the instruments defined in the project.

Usage

exportInstruments(rcon, ...)

## S3 method for class 'redcapApiConnection'
exportInstruments(rcon, ...)

Arguments

rcon	A redcapConnection object.
...	Arguments to pass to other methods

Value

Returns a data frame with the columns:

instrument_name	The REDCap generated instrument name.
instrument_label	The user provided instrument label.

See Also

exportMetaData(),
importMetaData(),
exportInstruments(),
exportMappings(),
importMappings(),
exportPdf()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
 
exportInstruments(rcon)

## End(Not run)

---

Export Logging Records

Description

These methods enable to user to export the logging (audit trail) of all changes made to a project, including data exports, data changes, project metadata changes, modification of user rights, etc.

Usage

exportLogging(
  rcon,
  logtype = character(0),
  user = character(0),
  record = character(0),
  dag = character(0),
  beginTime = as.POSIXct(character(0)),
  endTime = as.POSIXct(character(0)),
  batchInterval = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
exportLogging(
  rcon,
  logtype = character(0),
  user = character(0),
  record = character(0),
  dag = character(0),
  beginTime = as.POSIXct(character(0)),
  endTime = as.POSIXct(character(0)),
  batchInterval = NULL,
  ...
)

Arguments

rcon	A redcapConnection object.
logtype	character(0/1). The log event types to export. When the length is zero, all event types are exported. Otherwise, it must be one of c("export", "manage", "user", "record", "record_add", "record_edit", "record_delete", "lock_record", "page_view")
user	character(0/1). Users for whom to return logs. By default logs for all users are returned.
record	character(0/1). Record ID for which logs are to be returned. By default, logs are returned for all records.
dag	character(0/1). Data access group ID for which to return logs. By default, logs are returned for all data access groups.
beginTime	POSIXct(0/1). When given, only logs recorded on or after this time will be returned. The time specified is rounded to minutes and ignores the timezone. This can cause issues if the caller and server computers are configured in different timezones. Least surprising behavior is making sure the date specified is encoded in the timezone of the REDCap server.
endTime	POSIXct(0/1). When given, only logs recorded on or before this time will be returned. If using batchInterval it will only be before this time. See beginTime for details on time encoding.
batchInterval	integerish(1). When provided will batch log pulls to intervals of this many days. Requires that beginTime is specified.
...	Arguments to pass to other methods

Value

Returns a data frame with columns

timestamp	The date/time of the logging record.
username	The user name of the user that performed the action being logged.
action	The classification of action being logged.
details	Details of the action being logged.
record	The record ID associated with the action being logged. When not related to a record, this will be NA

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
                    
# Export all of the logging events       
exportLogging(rcon)
  
# Export all of the events for record '2'
exportLogging(rcon, 
              record = "2")
                
# Export all of the events where a record was deleted
exportLoging(rcon, 
             logtype = "record_delete")

## End(Not run)

---

Export PDF file of Data Collection Instruments

Description

These methods allow the user to download PDF files of data collection instruments. The download may be with or without collected data; and may return a single record, multiple records, or all records.

Usage

exportPdf(
  rcon,
  dir,
  filename = "redcap_forms_download",
  record = NULL,
  events = NULL,
  instruments = NULL,
  all_records = FALSE,
  ...
)

## S3 method for class 'redcapApiConnection'
exportPdf(
  rcon,
  dir,
  filename = "redcap_forms_download",
  record = NULL,
  events = NULL,
  instruments = NULL,
  all_records = FALSE,
  ...
)

Arguments

rcon	A redcapConnection object.
dir	character(1). The directory into which the file should be saved.
filename	character(1). The base of the file name. When record = NULL, it will be appended with "_blank.pdf". When record has a value, it will be appended with "_record_[record id].pdf"
record	character(1), integerish(1), or NULL. The record id for which forms should be downloaded.
events	character. The events for which forms should be downloaded
instruments	character. The instruments for which forms should be downloaded
all_records	logical(1). When TRUE forms for all records are downloaded. When TRUE, this overrides the records argument.
...	Arguments to pass to other methods

Details

These methods mimics the behavior of "Download PDF of Instruments" button on the REDCap user interface. They permit the user to export a PDF file for:

1. A single collection instrument (blank)c

2. All instruments (blank)

3. A single instrument (with data from a single record)c

4. All instruments (with data from a single record)

5. All instruments (with data from all records)

Value

exportPdf invisibly returns the location on the local system to whihc the files is saved.

See Also

exportMetaData(),
importMetaData(),
exportFieldNames(),
exportInstruments(),
exportMappings(),
importMappings()

---

Export Entire Project as REDCap XML File

Description

These methods enable the user to export a project's settings as an XML file in CDISC ODM format. This file may be used to transfer the project to another project, REDCap instance, or any other CDISC ODM compliant database.

Usage

exportProjectXml(
  rcon,
  file,
  return_metadata_only = TRUE,
  records = NULL,
  fields = NULL,
  events = NULL,
  survey = FALSE,
  dag = FALSE,
  export_files = FALSE,
  ...
)

## S3 method for class 'redcapApiConnection'
exportProjectXml(
  rcon,
  file,
  return_metadata_only = TRUE,
  records = NULL,
  fields = NULL,
  events = NULL,
  survey = FALSE,
  dag = FALSE,
  export_files = FALSE,
  ...
)

Arguments

rcon	A redcapConnection object.
file	character(1) The file to which the XML export will be saved.
return_metadata_only	logical(1). When TRUE (default) only meta data values are returned. When FALSE, project records data are also exported.
records	character or integerish. A vector of study id's to be returned. When NULL, all subjects are returned.
fields	character. Vector of fields to be returned. When NULL, all fields are returned (unless forms is specified).
events	A character. Vector of events to be returned from a longitudinal database. When NULL, all events are returned.
survey	logical(1). When TRUE the survey identifier fields (e.g., redcap_survey_identifier) or survey timestamp fields (e.g., ⁠[form_name]_timestamp⁠) will be included in the export when surveys are utilized in the project.
dag	logical(1). When TRUE the redcap_data_access_group field is exported when data access groups are utilized in the project.
export_files	logical(1). When TRUE will cause the XML returned to include all files uploaded for File Upload and Signature fields for all records in the project. Setting this option to TRUE can make the export very large and may prevent it from completing if the project contains many files or very large files.
...	Arguments to pass to other methods

Details

The entire project (all records, events, arms, instruments, fields, and project attributes) can be downloaded as a single XML file, which is in CDISC ODM format (ODM version 1.3.1). This XML file can be used to create a clone of the project (including its data, optionally) on this REDCap server or on another REDCap server (it can be uploaded on the Create New Project page). Because it is in CDISC ODM format, it can also be used to import the project into another ODM-compatible system.

When the return_metadata_only parameter is set to FALSE, the Data Export user rights will be applied to any data returned. For example, if the user has 'De-Identified' or 'Remove All Identifier Fields' data export rights, then some data fields might be removed and filtered out of the data set. To make sure that no data is unnecessarily filtered out of the API request, the user should have 'Full Data Set' export rights in the project.

See Also

createRedcapProject()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "token_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
xml_file <- tempfile(file.ext = ".xml")
exportProjectXml(rcon, 
                 file = xml_file)

## End(Not run)

---

Export the REDCap Version Number

Description

These methods enable the user to export the REDCap instance version number.

Usage

exportVersion(rcon, ...)

## S3 method for class 'redcapApiConnection'
exportVersion(rcon, ...)

Arguments

rcon	A redcapConnection object.
...	Arguments to pass to other methods

Value

Returns a character value giving the version number.

IF this function is used in a version of REDCap that does not support the method (prior to version 6.0.0), the value "5.12.2" will be returned. This is done solely for the convenience of always returning a value that can be compared against other versions.

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Export the version number
exportVersion(rcon)

## End(Not run)

---

Extraction and Assignment for redcapFactors

Description

Extract elements and make assignments to redcapFactors

Usage

## S3 method for class 'redcapFactor'
x[..., drop = FALSE]

## S3 method for class 'redcapFactor'
print(x, ...)

Arguments

x	an object of class redcapFactor
...	additional arguments to pass to other methods
drop	logical. If TRUE, unused levels are dropped.

---

Functions for Casting Fields After Export (Post Processing)

Description

The functions provided here allow for recasting fields after records have been exported. They generally have a similar interface to the casting strategy of exportRecordsTyped(), though they may not each offer all the same options.

Usage

recastRecords(
  data,
  rcon,
  fields,
  cast = list(),
  suffix = "",
  warn_zero_coded = TRUE
)

castForImport(
  data,
  rcon,
  fields = NULL,
  na = list(),
  validation = list(),
  cast = list(),
  warn_zero_coded = TRUE
)

guessCast(
  data,
  rcon,
  na = isNAorBlank,
  validation,
  cast,
  quiet = FALSE,
  threshold = 0.8
)

guessDate(
  data,
  rcon,
  na = isNAorBlank,
  validation = valRx("^[0-9]{1,4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01])$"),
  cast = function(x, ...) as.POSIXct(x, format = "%Y-%m-%d"),
  quiet = FALSE,
  threshold = 0.8
)

mChoiceCast(data, rcon, style = "labelled", drop_fields = TRUE)

Arguments

data	data.frame with the data fields to be recoded.
rcon	A redcapConnection object.
fields	character/logical/integerish. A vector for identifying which fields to recode. When logical, the length must match the number of columns in data (i.e., recycling not permitted). A message is printed if any of the indicated fields are not a multiple choice field; no action will be taken on such fields. For this function, yes/no and true/false fields are considered multiple choice fields. Fields of class mChoice are quietly skipped.
cast	A named list of user specified class casting functions. The same named keys are supported as the na argument. The function will be provided the variables (x, field_name, coding). The function must return a vector of logical matching the input length. The cast should match the validation, if one is using raw_cast, then validation=skip_validation is likely the desired intent. See fieldValidationAndCasting()
suffix	character(1). An optional suffix to provide if the recoded variables should be returned as new columns. For example, if recoding a field forklift_brand and suffix = "_labeled", the result will have one column with the coded values (forklift_brand) and one column with the labeled values (forklift_brand_labeled).
warn_zero_coded	logical(1). Turn on or off warnings about zero coded fields. Default is TRUE.
na	A named list of user specified functions to determine if the data is NA. This is useful when data is loaded that has coding for NA, e.g. -5 is NA. Keys must correspond to a truncated REDCap field type, i.e. date_, datetime_, datetime_seconds_, time_mm_ss, time_hh_mm_ss, time, float, number, calc, int, integer, select, radio, dropdown, yesno, truefalse, checkbox, form_complete, sql, system. The function will be provided the variables (x, field_name, coding). The function must return a vector of logicals matching the input. It defaults to isNAorBlank() for all entries.
validation	A named list of user specified validation functions. The same named keys are supported as the na argument. The function will be provided the variables (x, field_name, coding). The function must return a vector of logical matching the input length. Helper functions to construct these are valRx() and valChoice(). Only fields that are not identified as NA will be passed to validation functions.
quiet	Print no messages if triggered, Default=FALSE.
threshold	numeric(1). The threshold of non-NA data to trigger casting.
style	character. One of "labelled" or "coded". Default is "labelled"
drop_fields	character or NULL. A vector of field names to remove from the data.

Details

recastRecords is a post-processing function motivated initially by the need to switch between codes and labels in multiple choice fields. Field types for which no casting function is specified will be returned with no changes. It will not attempt to validate the content of fields; fields that cannot be successfully cast will be quietly returned as missing values.

castForImport is written with defaults that will return data in a format ready to be imported to a project via importRecords. All fields are returned as character vectors. If any values fail to validation check, are report is returned as an attribute named invalid. This attribute may be retrieved using reviewInvalidRecords(). These are then set to NA, which will be imported as blanks through the API.

guessCast is a helper function to make a guess at casting uncast columns. It will do a type cast if a validation is met above a threshold ratio of non-NA records. It modifies the existing invalid attribute to reflect the cast. This attribute may be retrieved using reviewInvalidRecords(). guessDate is a special cast of guessCast that has defaults set for casting a date field.

mChoiceCast is a helper function that adds the Hmisc::mChoice multiple choice class. It adds a column for a multiple choice checkbox that is cast to the Hmisc::mChoice class. Requires Hmisc to be loaded.

Zero-Coded Check Fields

A zero-coded check field is a field of the REDCap type checkbox that has a coding definition of ⁠0, [label]⁠. When exported, the field names for these fields is ⁠[field_name]___0⁠. As in other checkbox fields, the raw data output returns binary values where 0 represent an unchecked box and 1 represents a checked box. For zero-coded checkboxes, then, a value of 1 indicates that 0 was selected.

This coding rarely presents a problem when casting from raw values (as is done in exportRecordsTyped). However, casting from coded or labeled values can be problematic. In this case, it becomes indeterminate from context if the intent of 0 is 'false' or the coded value '0' ('true') ...

The situations in which casting may fail to produce the desired results are

Code	Label	Result
0	anything other than "0"	Likely to fail when casting from coded values
0	0	Likely to fail when casting from coded or labeled values

Because of the potential for miscast data, casting functions will issue a warning anytime a zero-coded check field is encountered. A separate warning is issued when a field is cast from coded or labeled values.

When casting from coded or labeled values, it is strongly recommended that the function castCheckForImport() be used. This function permits the user to state explicitly which values should be recognized as checked, avoiding the ambiguity resulting from the coding.

See Also

Exporting records

exportRecordsTyped(),
exportReportsTyped(),
fieldValidationAndCasting(),
reviewInvalidRecords()

Other Post Processing Functions

splitForms(),
widerRepeated()

Vignettes

vignette("redcapAPI-offline-connection", package = "redcapAPI")
vignette("redcapAPI-casting-data")
vignette("redcapAPI-missing-data-detection")
⁠vignette("redcapAPI-data-validation)⁠

Examples

## Not run: 
# Using recastRecords after export
Recs <- 
  exportRecordsTyped(rcon) |>
  recastRecords(rcon, 
                fields = "dropdown_test",
                cast = list(dropdown = castCode))
                
                
# Using castForImport
castForImport(Records, 
              rcon)
              
              
# Using castForImport to recast zero-coded checkbox values
castForImport(Records, 
              rcon, 
              cast = list(checkbox = castCheckForImport(c("0", "Unchecked"))))


# Using guessCast
exportRecordsTyped(rcon,
                   validation=skip_validation,
                   cast = raw_cast) |> 
  guessCast(rcon, 
            validation=valRx("^[0-9]{1,4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01])$"), 
            cast=as.Date,
            threshold=0.6)
            
            
# Using mChoiceCast
exportRecordsTyped(rcon) |> 
  mChoiceCast(rcon)


## End(Not run)

---

Split a Field Choice Mapping Into a Two Column Matrix

Description

Uses the string from the select_choices_or_calculations for the meta data to create a matrix of codes and their mapped labels.

Usage

fieldChoiceMapping(object, field_name, ...)

## S3 method for class 'character'
fieldChoiceMapping(object, field_name, ...)

## S3 method for class 'redcapApiConnection'
fieldChoiceMapping(object, field_name, ...)

Arguments

object	redcapConnection or character(1). When character, is matches the format of the meta data field choices (i.e. rcon$meta_data()$select_choices_or_calculations).
field_name	character(1) gives the field name for which to make the choice mapping.
...	Arguments to pass to other methods

Value

Returns a matrix with two columns, choice_value and choice_label

---

Convert a REDCap Data Field to an R Vector

Description

Converts a field exported from REDCap into a valid R vector

Usage

fieldToVar(
  records,
  meta_data,
  factors = TRUE,
  dates = TRUE,
  checkboxLabels = FALSE,
  labels = TRUE,
  handlers = list(),
  mChoice = NULL,
  ...
)

Arguments

records	A data frame of records returned by exportRecords or exportReports
meta_data	A data frame giving the data dictionary, as returned by exportMetaData
factors	Logical, determines if checkbox, radio button, dropdown and yesno variables are converted to factors
dates	Logical, determines if date variables are converted to POSIXct format
checkboxLabels	Logical, determines if checkbox variables are labeled as "Checked" or using the checkbox label. Only applicable when factors = TRUE
labels	Logical. Determines if the variable labels are applied to the data frame.
handlers	List, Specify type conversion overrides for specific REDCap field types. E.g., handlers=list(date_ = as.Date). For datetime specifications the datetime ordering directive from the tail is dropped. The following field types are supported: date_, datetime_, datetime_seconds_, time_mm_ss, time, float, number, calc, int, integer, select, radio, dropdown, yesno, truefalse, checkbox, and form_complete.
mChoice	logical; defaults to TRUE. Convert checkboxes to mChoice if Hmisc is installed.
...	additional arguments that are ignored.

Details

This function is called internally by exportRecords and exportReports. it is not available to the user.

---

Helper functions for exportRecordsTyped Validation and Casting

Description

This set of functions assists in validating that the content of fields coming from REDCap match the MetaData, allowing for a validation report to provided. The cast helpers allow for transforming the REDCap data into R data types and allowing the user to customize the end product.

Usage

isNAorBlank(x, ...)

valRx(rx)

valChoice(x, field_name, coding)

valPhone(x, field_name, coding)

valSkip(x, field_name, coding)

na_values(FUN)

castLabel(x, field_name, coding)

castLabelCharacter(x, field_name, coding)

castCode(x, field_name, coding)

castCodeCharacter(x, field_name, coding)

castRaw(x, field_name, coding)

castChecked(x, field_name, coding)

castCheckedCharacter(x, field_name, coding)

castCheckLabel(x, field_name, coding)

castCheckLabelCharacter(x, field_name, coding)

castCheckCode(x, field_name, coding)

castCheckCodeCharacter(x, field_name, coding)

castCheckForImport(checked = c("Checked", "1"))

castDpNumeric(dec_symbol = ",")

castDpCharacter(n_dec, dec_symbol = ",")

castTimeHHMM(x, field_name, coding)

castTimeMMSS(x, field_name, coding)

castLogical(x, field_name, coding)

raw_cast

default_cast_no_factor

default_cast_character

skip_validation

Arguments

x	character. A vector to check.
...	Consumes anything else passed to function. I.e., field_name and coding.
rx	character. The regular expression pattern to check.
field_name	character(1). Name of the field(s)
coding	named character vector. The defined coding from the meta data.
FUN	function. A function that takes a character vector.
checked	character. Values to recognize as checked in a checkbox field.
dec_symbol	character(1). The symbol in the field used to denote a decimal.
n_dec	integerish(1). The number of decimal places permitted by the field validation.

Format

An object of class list of length 21.

An object of class list of length 25.

An object of class list of length 25.

An object of class list of length 21.

Details

Functions passed to the na, validation, and cast parameter of exportRecordsTyped() all take the form of ⁠function(x, coding, field_name)⁠. na and validation functions are expected to return a logical vector of the same length as the column processed. Helper routines are provided here for common cases to construct these functions.

Missing Data Detection

na_values is a helper function to create a list of functions to test for NA based on field type. Useful for bulk override of NA detection for a project. The output can be directly passed to the na parameter of exportRecordsTyped().

Missing data detection is performed ahead of validation. Data that are found to be missing are excluded from validation reports.

REDCap users may define project-level missing value codes. If such codes are defined, they can be seen in Project Setup > Additional Customizations > Missing Data Codes. They will also be displayed in the project's Codebook. Project-level missing data codes cannot be accessed via the API, meaning redcapAPI is unable to assist in determining if a project has any. The most likely symptom of project-level codes is a high frequency of values failing validation (See vignette("redcapAPI-missing-data-detection")).

Validation Functions

isNAorBlank returns TRUE/FALSE if field is NA or blank. Helper function for constructing na overrides in exportRecordsTyped().

valRx constructs a validation function from a regular expression pattern. The function returns a TRUE/FALSE if the value matches the pattern.

valChoice constructs a validation function from a set of choices defined in the MetaData. The functions returns a TRUE/FALSE if the value matches one of the choices.

valPhone constructs a validation function for (North American) phone numbers. It removes punctuation and spaces prior to validating with the regular expression.

valSkip is a function that supports skipping the validation for a field type. It returns a TRUE value for each record, regardless of its value. Validation skipping has occasional utility when importing certain field types (such as bioportal or sql) where not all of the eventual choices are available in the project yet.

skip_validation is a list of functions that just returns TRUE for all data passed in.

Casting Functions

castLabel constructs a casting function for multiple choice variables. The field will be cast to return the choice label (generally more human readable). castLabelCharacter is an equivalent casting function that returns a character vector instead of a factor.

castCode constructs a casting function for multiple choice variables. Similar to castLabel, but the choice value is returned instead. The values are typically more compact and their meaning may not be obvious. castCodeCharacter is an equivalent casting function that retuns a character vector instead of a factor.

castRaw constructs a casting function that returns the content from REDCap as it was received. It is functionally equivalent to identity. For multiple choice variables, the result will be coerced to numeric, if possible; otherwise, the result is character vector.

castChecked constructs a casting function for checkbox fields. It returns values in the form of Unchecked/Checked. castCheckedCharacter is an equivalent casting function that returns a character vector instead of a factor.

castCheckLabel and castCheckCode also construct casting functions for checkbox fields. For both, unchecked variables are cast to an empty string (""). Checked variables are cast to the option label and option code, respectively. castCheckLabelCharacter and castCheckCodeCharacter are equivalent casting functions that returns a character vector instead of a factor.

castCheckForImport is a special case function to allow the user to specify exactly which values are to be considered "Checked". Values that match are returned as 1 and all other values are returned as 0. This is motivated by the special case where the coding on a checkbox includes "0, Option". In the resulting field checkbox___0, a coded value of 0 actually implies the choice was selected. In order to perform an import on such data, it is necessary to cast it using castCheckForImport(c("0")).

castDpNumeric is a casting function for fields that use the number_ndp_comma field type (where n is the number of decimal places). This function will convert the values to numeric values for use in analysis. This is a function that returns the appropriate casting function, thus the appropriate usage when using the defaults is cast = list(number_1dp_comma = castDpNumeric()) (using the parentheses).

castDpCharacter is a casting function to return fields that use number_ndp_comma field types to character strings for import. This is a function that returns the appropriate casting function, thus the appropriate usage when casting for one decimal place is cast = list(number_1dp_comma = castDpCharacter(1)).

castTimeHHMM and castTimeMMSS are casting functions to facilitate importing data. They convert time data into a character format that will pass the API requirements.

castLogical is a casting function that returns a logical vector for common, binary-type responses. It is well suited to changing true/false, yes/no, and checkbox fields into logical vectors, as it returns TRUE if the value is one of c("1", "true", "yes") and returns FALSE otherwise.

Casting Lists

raw_cast overrides all casting if passed as the cast parameter. It is important the the validation specified matches the chosen cast. For fully raw it should be skip_validation.

default_cast_no_factor is a list of casting functions that matches all of the default casts but with the exception that any fields that would have been cast to factors will instead be cast to characters. It is provided for the user that prefers to work absent factors. The list default_cast_character is equivalent and is provided for those that prefer to describe their casting in terms of what the result is (and not what it is not).

Value

Validation and casting functions return the objects indicated in the following table:

Function Name	Object Type Returned
isNAOrBlank	logical
valRx	logical
valChoice	logical
valPhone	logical
valSkip	logical
castLabel	factor
castLabelCharacter	character
castCode	factor
castCodeCharacter	character
castRaw	character
castChecked	factor
castCheckedCharacter	character
castCheckLabel	factor
castCheckLabelCharacter	character
castCheckCode	factor
castCheckCodeCharacter	character
castCheckForImport	numeric
castDpNumeric	numeric
castDpCharacter	character
castTimeHHMM	character
castTimeMMSS	character
castLogical	logical

See Also

fieldCastingFunctions(),
exportRecordsTyped(),
exportReportsTyped()

Vignettes

vignette("redcapAPI-casting-data")
vignette("redcapAPI-missing-data-detection")
⁠vignette("redcapAPI-data-validation)⁠
⁠vignette("redcapAPI-faq)⁠

Examples

## Not run: 
# Make a custom function to give special treatment to a field.
# In this function, the field "field_name_to_skip" will 
# be cast using `castRaw`. All other fields will be cast 
# using `castCode`
customCastCode <- function(x, field_name, coding){
  if (field_name == "field_name_to_skip"){
    castRaw(x, field_name, coding)
  } else {
    castCode(x, field_name, coding)
  }
}

## End(Not run)

---

Export, Import, or Delete Files to a Field in a REDCap Project

Description

These methods enable to the user to export a file stored in a project field, import a file, or delete an existing file.

Usage

exportFiles(
  rcon,
  record,
  field,
  event = NULL,
  dir = getwd(),
  file_prefix = TRUE,
  ...
)

importFiles(
  rcon,
  file,
  record,
  field,
  event,
  overwrite = TRUE,
  repeat_instance = NULL,
  ...
)

deleteFiles(rcon, record, field, event, ...)

## S3 method for class 'redcapApiConnection'
exportFiles(
  rcon,
  record,
  field,
  event = NULL,
  dir = getwd(),
  file_prefix = TRUE,
  repeat_instance = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
importFiles(
  rcon,
  file,
  record,
  field,
  event = NULL,
  overwrite = TRUE,
  repeat_instance = NULL,
  ...
)

## S3 method for class 'redcapApiConnection'
deleteFiles(
  rcon,
  record = NULL,
  field = NULL,
  event = NULL,
  repeat_instance = NULL,
  ...
)

Arguments

rcon	A redcapConnection object.
record	character(1) or integerish(1). The record ID in which the desired file is stored.
field	character(1). The field name in which the file is stored.
event	character(1) or NULL. The event name for the file. This applies only to longitudinal projects. If the event is not supplied for a longitudinal project, the API will return an error message
repeat_instance	integerish(1) or NULL. The repeat instance number of the repeating event or the repeating instrument. When available in your instance of REDCap, and passed as NULL, the API will assume a value of 1.
file	character(1). The file path to the file to be imported.
overwrite	logical(1). When FALSE, the function checks if a file already exists for that record. If a file exists, the function terminates to prevent overwriting. When TRUE, no additional check is performed.
dir	character(1). A directory/folder to which the file will be saved. By default, the working directory is used.
file_prefix	logical(1). Determines if a prefix is appended to the file name. The prefix takes the form ⁠[record_id]-[event_name]-[file_name]⁠. The file name is always the same name of the file as it exists in REDCap.
...	Arguments to pass to other methods

Details

These functions only export, import, or delete a single file.

When exporting, the file name cannot be changed; whatever name exists in REDCap is the name that will be used. The record ID and event name may be appended as a prefix.

Value

exportFiles invisibly returns the file path to which the exported file was saved.

importFiles invisibly returns TRUE when successful, or throws an error if the import failed.

deleteFiles invisible returns TRUE when successful, or throws an error if the deletion failed.

Functions

• exportFiles(): Export a file from a REDCap project.

• importFiles(): Import a file to a REDCap project.

• deleteFiles(): Delete a file from a REDCap project.

See Also

exportFilesMultiple(),
importFileToRecord() (can create a record to receive the file if it does yet exist)

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

save_to_dir <- tempdir()              

# Export a file
exportFiles(rcon, 
            record = 1, 
            field = "file_upload_test", 
            dir = save_to_dir)
            
# Export a file for a specific event
exportFiles(rcon, 
            record = 1, 
            field = "file_upload_test",
            event = "event_1_arm_1", 
            dir = save_to_dir)

# Import a file 
importFiles(rcon,
            file = "file_to_upload.txt" 
            record = 1, 
            field = "file_upload_test")
           
# Delete a file
deleteFiles(rcon, 
            record = 1, 
            field = "file_upload_test")

## End(Not run)

---

Export, Import, or Delete Multiple Files from the File Repository

Description

These methods enable the user to export, import, or delete entire folders of files from the file repository. These actions may be done recursively to include subfolders as well.

Usage

exportFileRepository(
  rcon,
  folder_id,
  dir = getwd(),
  dir_create = FALSE,
  recursive = FALSE,
  ...
)

importFileRepository(rcon, dir, folder_id = numeric(0), ...)

deleteFileRepository(rcon, folder_id, recursive = FALSE, ...)

## S3 method for class 'redcapApiConnection'
exportFileRepository(
  rcon,
  folder_id = numeric(0),
  dir = getwd(),
  dir_create = FALSE,
  recursive = FALSE,
  ...
)

## S3 method for class 'redcapApiConnection'
importFileRepository(
  rcon,
  dir,
  folder_id = numeric(0),
  dag_id = numeric(0),
  role_id = numeric(0),
  recursive = FALSE,
  ...
)

## S3 method for class 'redcapApiConnection'
deleteFileRepository(
  rcon,
  folder_id,
  recursive = FALSE,
  ...,
  confirm = c("ask", "no", "yes")
)

Arguments

rcon	A redcapConnection object.
folder_id	integerish(0/1) The folder ID with the files to download. If length 0, defaults to the top-level directory.
dir	character(1). A directory on the local system to which the files are to be saved. Defaults to the working directory.
dir_create	logical(1). When TRUE create the directory dir if it does not already exist. Defaults to FALSE. If dir does not exist and dir_create = FALSE, an error is thrown.
dag_id	integerish(0/1) The ID of a data access group. When provided, access to the folder will be restricted to the DAG.
role_id	integerish(0/1) The ID of a role. When provided, access to the folder will be restricted to users with that role.
recursive	logical(1). When TRUE, export all subfolders and their files as well.
confirm	character. One of c("ask", "no", "yes"). When "ask", user will be prompted to confirm the deletion. When "no", the function will terminate with no action. When "yes", the function will proceed without confirmation (useful for automated processes).
...	Arguments to pass to other methods

Details

deleteFileRepository will only delete files and cannot delete folders.

Deleted files will remain in the recycling bin for up to 30 days.

Value

exportFileRepository returns a data frame with the locations to which the files were saved on the local system. It has the columns:

directory	The directory in which the file is saved.
filename	The name of the saved file.

importFileRepository returns a data frame with the locations to which the files were saved on the local system. It has the columns:

directory	The directory in which the file is saved.
filename	The name of the saved file.

deleteFileRepository returns a data frame listing the files that were deleted from the file repository. It has the columns:

folder_id	The REDCap assigned ID number for the folder. This will be NA for files.
doc_id	The REDCap assigned ID number for the file.
name	The filename of the deleted files.
parent_folder	The folder ID of parent folder.

Functions

• exportFileRepository(): Export multiple files from the File Repository.

• importFileRepository(): Import multiple files to the File Repository.

• deleteFileRepository(): Delete multiple files from the File Repository.

See Also

exportFromFileRepository(),
importToFileRepository(),
deleteFromFileRepository(),
exportFileRepositoryListing(),
createFileRepositoryFolder()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
save_location <- tempdir()

# Export the top-level file repository folder
exportFileRepository(rcon, 
                     folder_id = numeric(0), 
                     dir = save_location)
                     
# Export the entire repository 
exportFileRepository(rcon, 
                     folder_id = numeric(0), 
                     dir = save_location, 
                     recursive = TRUE)
                     
# Export a file repository folder below the top-level
exportFileRepository(rcon, 
                     folder_id = 12345, 
                     dir = save_location)
                     
# Import the files from a folder to the top-level file repository
importFileRepository(rcon, 
                     dir = "path/to/folder")
                     
# Import the files from a folder to sub folder of the file repository
importFileRepository(rcon, 
                     dir = "path/to/folder", 
                     folder_id = 12345) 
                     
# Import the files from a folder and assign to a specific 
# Data Access Group
importFileRepository(rcon, 
                     dir = "path/to/folder", 
                     dag_id = 789)  
                     
# Delete files from the top-level folder of the file repository
deleteFileRepository(rcon, 
                     folder_id = numeric(0))
                     
# Delete all the file sfrom the file repository
deleteFileRepository(rcon, 
                     folder_id = numeric(0), 
                     recursive = TRUE)                   

## End(Not run)

---

Reconstruct the file repository path

Description

Reconstruct the file repository path

Usage

fileRepositoryPath(doc_id = numeric(0), folder_id = numeric(0), fileRepo)

Arguments

doc_id	integerish(0/1). The document ID for which the file path should be returned. Only one of doc_id or folder_id should be specified.
folder_id	integerish(0/1). The folder ID for which the file path should be returned. Only one of doc_id or folder_id should be specified.
fileRepo	data.frame with the file repository listing. Typically provided by rcon$fileRepository()

---

Remove Rows Containing Only Missing Values

Description

Evaluates each row of a data frame for missingness. If all fields (excluding the identifying fields) are missing, the row is removed from the data. For the purpose of this function, redcap_data_access_group is considered an identifying field.

Usage

filterEmptyRow(data, rcon)

Arguments

data	A data.frame to be filtered.
rcon	A redcapConnection object.

See Also

exportRecordsTyped(),
exportReportsTyped()

---

Export, Import, and Delete Individual Files from the File Repository

Description

These methods enable the user to export, import, or delete individual files from a REDCap project's file repository.

Usage

exportFromFileRepository(rcon, doc_id, dir = getwd(), dir_create = FALSE, ...)

importToFileRepository(rcon, file, folder_id = numeric(0), ...)

deleteFromFileRepository(rcon, doc_id, ...)

## S3 method for class 'redcapApiConnection'
exportFromFileRepository(rcon, doc_id, dir = getwd(), dir_create = FALSE, ...)

## S3 method for class 'redcapApiConnection'
importToFileRepository(rcon, file, folder_id = numeric(0), ...)

## S3 method for class 'redcapApiConnection'
deleteFromFileRepository(rcon, doc_id, ...)

Arguments

rcon	A redcapConnection object.
doc_id	integerish(1). The document ID to be downloaded.
folder_id	integerish(0/1). The ID of the folder into which the file is to be imported. If length is zero, it is imported to the top-level folder.
file	character(1). A file on the local system to be imported to the File Repository.
dir	character(1). A directory on the local system to which the file is to be saved. Defaults to the working directory.
dir_create	logical(1). Create the directory dir if it does not already exist. Defaults to FALSE. If dir does not exist and create = FALSE, an error is thrown.
...	Arguments to pass to other methods

Details

When a file is deleted, the file will remain in the Recycle Bin folder for up to 30 days.

Value

exportFromFileRepository, importToFileRepository, and deleteFromFileRepository each return a data frame with the columns:

directory	The directory in which the file is saved.
filename	The name of the saved file.

Functions

• exportFromFileRepository(): Export a file from the file repository.

• importToFileRepository(): Import a file to the file repository.

• deleteFromFileRepository(): Delete a file from the file repository.

See Also

exportFileRepository(),
importFileRepository(),
deleteFileRepository(),
exportFileRepositoryListing(),
createFileRepositoryFolder()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
 
write_to_path <- tempdir()            
             
# Export a file from the repository
exportFromFileRepository(rcon, 
                         doc_id = 12345, 
                         dir = write_to_path)
                         
# Export a file and create the target directory if it does not exist
exportFromFileRepository(rcon, 
                         doc_id = 12345, 
                         dir = write_to_path, 
                         dir_create = TRUE)
                         
# Import a file to the top-level directory of the file repository
importFileToRepository(rcon, 
                       file = "file_to_import.txt")
                       
# Import a file to a specific directory of the file repository
importFileToRepository(rcon, 
                       file = "file_to_import.txt", 
                       folder_id = 678)
                       
# Delete a file from the file repository
deleteFileFromRepository(rcon, 
                         doc_id = 12345)

## End(Not run)

---

Return a vector of the Project ID Fields

Description

Returns a character vector listing the project ID fields. This will be at most a vector of length two. The first element will be the first field in the meta data. The second, if provided, will be the name of the secondary unique field specified in the project.

Usage

getProjectIdFields(rcon)

Arguments

rcon	A redcapConnection object.

Value

Returns a character vector with the field names that uniquely identify an experimental unit.

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
getProjectIdFields(rcon)

## End(Not run)

---

Import a File With Option to Create A Record to Receive the File

Description

There are times when the user may desire to create a record and import a file as part of a single action. For example, a study consent form may have been collected and needs to be stored with the data of the new study participant. importFileToRecord extends importFiles to allow the concurrent creation of the record in which the file will be stored.

Usage

importFileToRecord(
  rcon,
  file,
  record = NULL,
  field,
  event,
  overwrite = TRUE,
  repeat_instance = NULL,
  ...
)

Arguments

rcon	A redcapConnection object.
file	character(1). The file path to the file to be imported.
record	character(1) or integerish(1) or NULL. The record ID in which the desired file is stored. When NULL, an attempt will be made to create a new record for the file. See 'Details'
field	character(1). The field name in which the file is stored.
event	character(1) or NULL. The event name for the file. This applies only to longitudinal projects. If the event is not supplied for a longitudinal project, the API will return an error message
overwrite	logical(1). When FALSE, the function checks if a file already exists for that record. If a file exists, the function terminates to prevent overwriting. When TRUE, no additional check is performed.
repeat_instance	integerish(1) or NULL. The repeat instance number of the repeating event or the repeating instrument. When available in your instance of REDCap, and passed as NULL, the API will assume a value of 1.
...	Arguments to pass to other methods

Details

The behavior of importFileToRecord depends on

1. whether record auto numbering has been enabled in the project,

2. if the record is specified by the user

3. if the record specified by the user exists.

The following table details the actions taken based on these conditions. (force_auto_number is an argument to importRecords()).

Autonumbering enabled	record	Record Exists	Action
Yes	NULL	No	Create a new record (using force_auto_number = TRUE) and import the file to the new record
Yes	Specified	Yes	Import the file to the existing record
Yes	Specified	No	Create a new record (using force_auto_number = TRUE)and import the file to the new record
No	NULL	No	Error: record must be provided when auto numbering is not enabled
No	Specified	Yes	Import the file to the existing record
No	Specified	No	Create the record (using force_auto_number = FALSE) and import the file to the new record.

See Also

importFiles(),
importRecords()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

importFileToRecord(rcon,
                   file = "file_to_upload.txt" 
                   record = NULL, 
                   field = "file_upload_test")

## End(Not run)

---

Import Records to a Project

Description

These methods enable the user to import new records or update existing records to a project.

Usage

importRecords(
  rcon,
  data,
  overwriteBehavior = c("normal", "overwrite"),
  returnContent = c("count", "ids", "nothing", "auto_ids"),
  returnData = FALSE,
  logfile = "",
  ...
)

## S3 method for class 'redcapApiConnection'
importRecords(
  rcon,
  data,
  overwriteBehavior = c("normal", "overwrite"),
  returnContent = c("count", "ids", "nothing", "auto_ids"),
  returnData = FALSE,
  logfile = "",
  force_auto_number = FALSE,
  ...,
  batch.size = -1
)

Arguments

rcon	A redcapConnection object.
data	A data.frame to be imported to the project.
overwriteBehavior	character(1). One of c("normal", "overwrite"). "normal" prevents blank fields from overwriting populated fields. "overwrite" causes blanks to overwrite data in the database.
returnContent	character(1). One of c("count", "ids", "nothing", "auto_ids"). 'count' returns the number of records imported; 'ids' returns the record ids that are imported; 'nothing' returns no message; 'auto_ids' returns a list of pairs of all record IDs that were imported. If used when force_auto_number = FALSE, the value will be changed to 'ids'.
returnData	logical(1). When TRUE, prevents the REDCap import and instead returns the data frame that would have been given for import. This is sometimes helpful if the API import fails without providing an informative message. The data frame can be written to a csv and uploaded using the interactive tools to troubleshoot the problem.
logfile	character(1). An optional filepath (preferably .txt) in which to print the log of errors and warnings about the data. When "", the log is printed to the console.
...	Arguments to pass to other methods
force_auto_number	logical(1). If record auto-numbering has been enabled in the project, it may be desirable to import records where each record's record name is automatically determined by REDCap (just as it does in the user interface). When TRUE, the record names provided in the request will not be used (although they are still required in order to associate multiple rows of data to an individual record in the request); instead those records in the request will receive new record names during the import process. It is recommended that the user use returnContent = "auto_ids" when force_auto_number = TRUE
batch.size	integerish(1). Specifies the number of subjects to be included in each batch of a batched export or import. Non-positive numbers export/import the entire operation in a single batch. Batching may be beneficial to prevent tying up smaller servers. See Details.

Details

importRecords prevents the most common import errors by testing the data before attempting the import. Namely

1. Check that all variables in data exist in the REDCap data dictionary.

2. Check that the record id variable exists

3. Force the record id variable to the first position in the data frame (with a warning)

4. Remove calculated fields (with a warning)

5. Verify that REDCap date fields are represented in the data frame as either character, POSIXct, or Date class objects.

6. Determine if values are within their specified validation limits.

See the documentation for validateImport() for detailed explanations of the validation.

A 'batched' import is one where the export is performed over a series of API calls rather than one large call. For large projects on small servers, this may prevent a single user from tying up the server and forcing others to wait on a larger job.

BioPortal Fields

Text fields that are validation enabled using the BioPortal Ontology service may be imported by providing the coded value. Importing the coded value does not, however, guarantee that the labeled value will be immediately available. Labels for BioPortal values are cached on the REDCap server in a process that occurs when viewing data in the user interface. Thus, if the label has not be previously cached on the server, the code will be used to represent both the code and the label.

Value

importRecords, when returnData = FALSE, returns the content from the API response designated by the returnContent argument.

importRecords, when returnData = TRUE, returns the data frame that was internally prepared for import. This data frame has values transformed from R objects to character values the API will accept.

See Also

exportRecords(),
deleteRecords(),
exportRecordsTyped()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Import records
NewData <- data.frame(record_id = c(1, 2, 3), 
                      age = c(27, 43, 32), 
                      date_of_visit = rep(Sys.Date(), 3))
importRecords(rcon, 
              data = NewData)
              
              
# Import records and save validation info to a file
NewData <- data.frame(record_id = c(1, 2, 3), 
                      age = c(27, 43, 32), 
                      date_of_visit = rep(Sys.Date(), 3))
importRecords(rcon, 
              data = NewData, 
              logfile = "import-validation-notes.txt")      


## End(Not run)

---

Helper functions for formatting validation failure report

Description

exportRecordsTyped() may have an invalid attribute if validations fail. This data has some routines which help locate the failing records.

Usage

## S3 method for class 'invalid'
format(x, ...)

## S3 method for class 'invalid'
print(x, ...)

## S3 method for class 'invalid'
summary(object, ...)

Arguments

x	The invalid class object.
...	additional arguments to print
object	The invalid class object.

Examples

## Not run: 
rcon <- redcapConnection(url=[YOUR_REDCAP_URL], token=[API_TOKEN])

rec <- exportRecordsTyped(rcon)

attr(rec, "invalid")

## End(Not run)

---

Identify Check Fields with a Zero Coded Option

Description

Check fields that have 0 as a coding option can confuse certain data processing steps because it can be difficult to differentiate if a 0 value represents an unchecked or checked option. Identifying these fields is important to handling them correctly.

Usage

isZeroCodedCheckField(field_name)

warnOfZeroCodedCheckCasting(field_name, x)

warnZeroCodedFieldPresent(field_names, warn_zero_coded)

Arguments

field_name	character(1) The name of a field to be tested.
x	atomic object.
field_names	character vector of field names.
warn_zero_coded	logical(1). Turn on or off warnings about zero coded fields. Defaults to TRUE.

Value

isZeroCodedCheckField returns a logical(1)

warnOfZeroCodedCheckCasting has no return and issues a warning if the field name appears to be zero-coded.

warnZeroCodedFieldPresent has no return and issues a warning if any of the fields passed appear to be zero-coded.

Zero-Coded Check Fields

A zero-coded check field is a field of the REDCap type checkbox that has a coding definition of ⁠0, [label]⁠. When exported, the field names for these fields is ⁠[field_name]___0⁠. As in other checkbox fields, the raw data output returns binary values where 0 represent an unchecked box and 1 represents a checked box. For zero-coded checkboxes, then, a value of 1 indicates that 0 was selected.

This coding rarely presents a problem when casting from raw values (as is done in exportRecordsTyped). However, casting from coded or labeled values can be problematic. In this case, it becomes indeterminate from context if the intent of 0 is 'false' or the coded value '0' ('true') ...

The situations in which casting may fail to produce the desired results are

Code	Label	Result
0	anything other than "0"	Likely to fail when casting from coded values
0	0	Likely to fail when casting from coded or labeled values

Because of the potential for miscast data, casting functions will issue a warning anytime a zero-coded check field is encountered. A separate warning is issued when a field is cast from coded or labeled values.

When casting from coded or labeled values, it is strongly recommended that the function castCheckForImport() be used. This function permits the user to state explicitly which values should be recognized as checked, avoiding the ambiguity resulting from the coding.

Examples

## Not run: 
isZeroCodedCheckField("check_field___x")

isZeroCodedCheckField("check_field___0")


x <- factor(c(1, 0, 1, 0, 0), 
            levels = 0:1)
warnOfZeroCodedCheckCasting(field_name = "check_field___0", 
                            x = x)
                       
 
warnZeroCodedFieldPresent(c("check_field___x", "check_field___0"), TRUE)

## End(Not run)

---

Make REDCap API Calls

Description

Constructs and executes API calls to the REDCap API. These are left deliberately abstract in order to be flexible enough to support the redcapAPI functions, but also allow users to execute calls for new REDCap features that are not yet implemented.

Usage

makeApiCall(rcon, body = list(), url = NULL, success_status_codes = 200L, ...)

Arguments

rcon	A redcapConnection object.
body	list List of parameters to be passed to curl::curl's body argument
url	character(1) A url string to hit. Defaults to rcon$url.
success_status_codes	integerish A vector of success codes to ignore for error handling. Defaults to c(200L).
...	This will capture api_param (if specified) which will modify the body of the the specified body of the request. It also captures config which will get passed to curl::handle_setopt.

Details

The intent of this function is to provide an approach to execute calls to the REDCap API that is both consistent and flexible. Importantly, this provides a framework for making calls to the API using features that the R package does not yet support (redcapAPI will always lag behind when REDCap adds new features).

The API call consists of two components: the "body" and the "config." The body of the call contains all of the arguments being passed to the API. When building body components, be sure to review the documentation. options to the API that require an array need to be built using vectorToApiBodyList; options that are not an array can be entered directly (see examples).

The config list is a list of parameter overrides that reflect the curl request object. The most commonly used elements of this list is options or maybe headers.

Using the settings stored in the redcapConnection object, a response code of 408 (Request Timeout), 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), or 504 (Gateway Timeout) will prompt reattempts at calling the API. See redcapConnection() for details. If the API reaches its attempt limit without resolving to any other code, the last response is returned. If any other response code is returned at any point in the retry loop, the loop breaks and returns that response.

Examples

## Not run: 
  url <- "Enter your API URL here"
  token <- "Enter your API token here"
  
  rcon <- redcapConnection(url = url, 
                           token = token)
                           
  MetaData <- 
    makeApiCall(rcon = rcon,
               body = list(content = "metadata",
                           format = "csv",
                           returnFormat = "csv"))
  MetaData <- utils::read.csv(text = as.character(MetaData),
                              stringsAsFactors = FALSE,
                              na.strings = "")



  # Call to export Meta Data (Data Dictionary) for specific fields

  fields <- vectorToApiBodyList(vector = c("row_purpose", 
                                           "prereq_radio"),
                                parameter_name = "fields")
  MetaData <-
    makeApiCall(rcon = rcon,
                body = c(list(content = "metadata",
                              format = "csv",
                              returnFormat = "csv"),
                         fields))
  MetaData <- read.csv(text = as.character(MetaData),
                       stringsAsFactors = FALSE,
                       na.strings = "")



  # Basic call to export records

  Records <- makeApiCall(rcon = rcon,
                         body = list(content = "record",
                                     format = "csv",
                                     returnFormat = "csv",
                                     type = "flat"))

  Records <- read.csv(text = as.character(Records),
                      stringsAsFactors = FALSE,
                      na.strings = "")


  # Call to export records for a single form.
  # Note that even though we are interested in a single form, the
  # API requires an array, so we use vectorToApiBodyList

  export_form <- vectorToApiBodyList("branching_logic",
                                     parameter_name = "forms")
  Records <- makeApiCall(rcon = rcon,
                         body = c(list(content = "record",
                                       format = "csv",
                                       returnFormat = "csv",
                                       type = "flat"),
                                  export_form))
  Records <- read.csv(text = as.character(Records),
                      stringsAsFactors = FALSE,
                      na.strings = "")


  # Call to export records with a pipe delimiter.

  Records <- makeApiCall(rcon = rcon,
                         body = list(content = "record",
                                     format = "csv",
                                     returnFormat = "csv",
                                     type = "flat",
                                     csvDelimiter = "|"))
  Records <- read.csv(text = as.character(Records),
                      stringsAsFactors = FALSE,
                      na.strings = "",
                      sep = "|")


  # Call to export records created/modified after 25 Dec 2022 14:00.

  Records <- makeApiCall(rcon = rcon,
                         body = list(content = "record",
                                     format = "csv",
                                     returnFormat = "csv",
                                     type = "flat",
                                     dateRangeBegin = "2022-12-25 14:00:00"))

  Records <- read.csv(text = as.character(Records),
                      stringsAsFactors = FALSE,
                      na.strings = "")
                      
 

## End(Not run)

---

Export and Import Instrument-Event Mappings

Description

These methods enable the user to export and add/modify the mappings between instruments and events. The information provided with the methods corresponds to what is provided in the 'Designate Instruments for My Events' page in the user interface.

Usage

exportMappings(rcon, arms, ...)

importMappings(rcon, data, ...)

## S3 method for class 'redcapApiConnection'
exportMappings(rcon, arms = NULL, ...)

## S3 method for class 'redcapApiConnection'
importMappings(rcon, data, ...)

Arguments

rcon	A redcapConnection object.
arms	integerish or character. A vector of arm numbers. When given, mappings are only exported for the given arms.
data	data.frame with columns arm_num, unique_event_name, and form. See Details
...	Arguments to pass to other methods

Details

These methods are only applicable to longitudinal projects. If the project information reports that the project is not longitudinal, a data frame with 0 rows is returned without calling the API.

Value

exportMappings returns a data frame with the columns:

arm_num	The arm number for the unique event mapped to the instrument.
unique_event_name	The unique event name to which the instrument is assigned.
form	The REDCap assigned instrument name mapped to the event.

importMappings invisible returns the number of mappings added or edited.

Functions

• exportMappings(): Export instrument-event mappings.

• importMappings(): Import instrument-event mappings to the project.

See Also

exportFieldNames(),
exportInstruments(),
exportMetaData(),
importMetaData(),
exportPdf()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export all mappings
exportMappings(rcon)

# Export mappings for a specific arm
exportMappings(rcon, 
               arms = 1)
               
# Import mappings
NewMapping <- 
  data.frame(arm_num = c(1, 1, 2), 
             unique_event_name = c("event_1_arm_1", 
                                   "event_2_arm_1", 
                                   "event_1_arm_2"), 
             form = c("registration", 
                      "follow_up", 
                      "registration"))

importMapping(rcon, 
              data = NewMapping)

## End(Not run)

---

Export and Import the Project Meta Data (Data Dictionary)

Description

These methods provide the user access to a REDCap project's data dictionary. The data dictionary may be exported or altered via the import.

Usage

exportMetaData(rcon, ...)

importMetaData(rcon, data, ...)

## S3 method for class 'redcapApiConnection'
exportMetaData(rcon, fields = character(0), forms = character(0), ...)

## S3 method for class 'redcapApiConnection'
importMetaData(
  rcon,
  data,
  ...,
  field_types = REDCAP_METADATA_FIELDTYPE,
  validation_types = REDCAP_METADATA_VALIDATION_TYPE
)

Arguments

rcon	A redcapConnection object.
fields	character vector of field names for which the metadata is to be retrieved.
forms	character vector of forms for which the metadata is to be retrieved. If a form name is given, all of the fields on that form will be returned, regardless of whether it is included in fields or not. Form names should match those in the second column of the data dictionary, and not the display names shown on the web interface.
data	data.frame with the Meta Data to import.
...	Arguments to pass to other methods
field_types	character giving the acceptable field types when validating the field_type column. This
validation_types	character giving the acceptable values for the text_validation_or_show_slider_number column.

Details

When importing meta data, the following conditions apply:

Field names may start with a letter, have any number of letters, numbers, or underscores, and end in either a letter or a number. All letters must be lowercase (the function will coerce them to lower before checking for duplicate field names).

Form names may start with a letter, have any number of letters, numbers, or underscores, and end in either a letter or a number. All letters must be lowercase (the function will coerce them to lower before checking for duplicate field names).

Field types may be one of REDCAP_METADATA_FIELDTYPE. In the event that a new field type is added to REDCap and redcapAPI is not yet updated, the user may add additional values via c(REDCAP_METADATA_FIELDTYPE, "new_type").

Validation types may be one of REDCAP_METADATA_VALIDATION_TYPE or NA. As with field types, additional values can be appended if necessary. Only fields that have a field type of "text" or "slider" should have a validation type. "slider" fields should be either NA (do not display the selected number) or "number".

For multiple choice fields, the selection choices take the format of "code1, label1 | ... | coden, labeln". For slider fields, the format is "left_value | mid_value | right_value". Any of those values may be an empty character, but the two pipes are required, nonetheless.

For calculated fields, the values in "select_choices_or_calculations" are currently unvalidated.

All of the values between brackets in the branching logic must be either a field name or an existing unique event name (such as "event_1_arm_1")

Value

exportMetaData returns a data frame. Not all 18 (or more) columns are documented here, but the most commonly used within redcapAPI are (these may appear in a different order in the data frame):

field_name	The name of a field in the project.
filed_label	The human-readable form of the field name.
form_name	The name of the form on which the field is found.
field_type	One of two fields used to determine how a field is transformed into an R object.
select_choices_or_calculations	The second field used to determine how a field is translated into an R object.
text_validation_type_or_show_slider_number	Describes how fields are validated. For slider fields, it gives the limits and center point to display.
field_annotation	Contains annotations such as units of measures. Also contains action tags.

importMetaData invisibly returns the number of fields that were imported.

Functions

• exportMetaData(): Export the Meta Data (Data Dictionary) of a REDCap Project

• importMetaData(): Import New Meta Data (Data Dictionary) Definitions

See Also

exportFieldNames(),
exportInstruments(),
exportMappings(),
importMappings(),
exportPdf()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export the MetaData from REDCap
exportMetaData(rcon)

# Export MetaData for select fields only (returns two rows)
exportMetaData(rcon, 
               fields = c("dropdown_test", "radio_test"))

# Export MetaData for select forms
exportMetaData(rcon, 
               forms = c("first_form", "second_form"))
               
# MetaData my be exported for a combination of fields and forms
exportMetaData(rcon, 
               fields = c("dropdown_test", "radio_test"), 
               forms = c("first_form", "second_form"))
               
# Alter and import new MetaData (change the record ID label)
Meta <- exportMetaData(rcon)

Meta$field_label[1] <- "A better description of the Record ID"
importMetaData(rcon, 
               data = Meta)

## End(Not run)

---

Report of Missing Values

Description

Returns a data frame of subject events with missing values.

Usage

missingSummary(rcon, excludeMissingForms = TRUE, ...)

## S3 method for class 'redcapApiConnection'
missingSummary(rcon, excludeMissingForms = TRUE, ...)

missingSummary_offline(records, meta_data, excludeMissingForms = TRUE)

Arguments

rcon	A redcapConnection object.
excludeMissingForms	logical(1) When TRUE, forms where all fields are missing are assumed to be deliberately missing data and are excluded from the count of missing values. An example when this is desirable is if a patient did not experience an adverse event; the adverse event form would contain no data and the empty fields should not be considered missing data.
...	additional arguments passed to inner call of exportRecordsTyped.
records	character(1) A filename pointing to the raw records download from REDCap.
meta_data	character(1) A filename pointing to the data dictionary download from REDCap.

Details

The intention of this function is to generate a list of subject events that are missing and could potentially be values that should have been entered.

The branching logic from the data dictionary is parsed and translated into and R expression. When a field with branching logic passes the logical statement, it is evaluated with is.na, otherwise, it is set to FALSE (non-missing, because there was never an opportunity to provide a value). The utility of this function is limited to simple logic where all of the data exist within the same row. Any complex statements using events will result in a failure.

Optionally, forms that are entirely missing can be determined to be non-missing. This is applicable when, for instance, a patient did not have an adverse event. In this case, a form dedicated to adverse events would contain meaningless missing values and could be excluded from the report.

See Also

vignette("redcapAPI-offline-connection", package = "redcapAPI")

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Generate a summary of missing values for the entire project
missingSummary(rcon)

# Generate a summary of missing values for a single form
missingSummary(rcon, 
               exportRecordsArgs = list(forms = "target_form"))

## End(Not run)

---

Parse Branching Logic

Description

Branching logic from the REDCap Data Dictionary is parsed into R Code and returned as expressions. These can be evaluated if desired and allow the user to determine if missing values are truly missing or not required because the branching logic prevented the variable from being presented.

Usage

parseBranchingLogic(l)

Arguments

l	A vector of REDCap branching logic statements. These are usually passed as the vector meta_data$branching_logic.

Details

For a study, I was asked to identify which subjects had missing values so that remaining data could be collected. The initial pass of is.na produced a lot of subjects missing values where there was no need to collect data because they did not qualify for some variables in the branching logic. Parsing the logic allowed me to determine which values we expected to be missing and narrow the search to just those subjects with legitimately missing values.

The utility of this function is limited to simple logic where all of the data exist within the same row. Any complex statements using events will result in a failure.

Value

Returns a list of unevaluated expressions.

See Also

missingSummary()

Examples

## Not run: 
parseBranchingLogic("[age] > 30")
parseBranchingLogic("[dropdown_test] = 'd'")
parseBranchingLogic(c("[age] > 30", 
                      "[dropdown_test] = 'd'"))

## End(Not run)

---

Prepare User Data for Import

Description

Prepares a data frame for import via the API. Allows for data to be passed in either the raw format or the labeled data received from exportUsers.

Usage

prepUserImportData(data, rcon, consolidate = TRUE, user_role = FALSE)

Arguments

data	data.frame with the structure of redcapAPI:::REDCAP_USER_STRUCTURE. It may also have additional columns for the form and export access of each of the instruments.
rcon	A redcapConnection object.
consolidate	logical(1) If TRUE, the form and data export access values will be read from the expanded columns. Otherwise, the consolidated values (as provided by the API export) are utilized.
user_role	logical(1) If TRUE, the code will treat the data as if it is being prepared for importing User Roles.

Value

Returns a data.frame with user settings that will be accepted by the API for import.

See Also

importUsers(),
importUserRoles()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())


# Prep user data
NewData <- data.frame(username = "target_user", 
                      design = 1, 
                      api_export = "Access", 
                      api_import = "No Access", 
                      surveys_enabled = 0)
prepUserImportData(data = NewData, 
                   rcon = rcon)
                   
# Prep user role data
NewData <- data.frame(unique_role_name = "target_user", 
                      design = 1, 
                      api_export = "Access", 
                      api_import = "No Access", 
                      surveys_enabled = 0)
prepUserImportData(data = NewData, 
                   rcon = rcon)

## End(Not run)

---

Preserve Project Data Locally

Description

The methods enable the user to export a project data and meta data into local memory. For convenience, options are provided to save the objects to files on the local machine. Files may be saved as either .Rdata files or .csv files.

Usage

preserveProject(rcon, ..., save_as = NULL, dir, dir_create = TRUE)

## S3 method for class 'redcapApiConnection'
preserveProject(rcon, ..., save_as = NULL, dir, dir_create = TRUE)

readPreservedProject(x, ...)

## S3 method for class 'list'
readPreservedProject(x, ..., version = NULL, url = NULL)

## S3 method for class 'character'
readPreservedProject(x, ..., version = NULL, url = NULL)

Arguments

rcon	A redcapConnection object.
...	arguments to pass to other methods
save_as	character(1) or NULL. When "Rdata", the data objects will be saved to an .Rdata file. When "csv", the data objects will be written to files at dir. Any other character value will prompt an error.
dir	character(1). The path to a directory in which the data objects (or files) will be saved. Must be provided if save_as is not NULL.
dir_create	logical(1). When TRUE, an attempt will be made to create the directory at dir if it does not already exist. When FALSE, and the directory does not exist, an error is returned.
x	list or character. If a list, the list returned (or saved) by preserveProject. If character, the directory to which the CSV files are saved by preserveProject.
version	character(1) giving the instance's REDCap version number.
url	character(1). URL for the user's REDCap database API.

Details

The options to save files to local files provide the user a convenient tool set for providing other users with the ability to work with data offline. See the examples for suggestions on how to read data into an offlineConnection.

When saving to an .Rdata file, the data are saved in a list named RedcapList. The list has the same elements in the list returned when save_as = NULL and is suitable for creating an offlineConnection. The file name it is saved to follows the pattern "project-[project_id]-RedcapList.Rdata".

When saving to a .csv file, each element of the data is saved to a file with the pattern "project-[project_id]-[data type].csv".

readPreservedProject is a function of convenience for users who need to work using offline connections. If given a list, it must be in the format returned by preserveProject. If given a character, it must be the directory in which the CSV files were saved by preserveProject. If any of the file names have been changed, readPreservedProject will fail to execute. Refer to vignette("redcapAPI-offline-connection", package = "redcapAPI") for more details.

Value

'preserveProject

Whensave_as = NULL', returns a list is returned with the elements

• project_information

• arms

• events

• meta_data

• mappings

• repeating_instruments

• users

• user_roles

• user_role_assignments

• dags

• dag_assignments

• records

When save_as is not NULL, the logical TRUE is invisibly returned to provide an indication that the save operation(s) are complete.

readPreservedProject

Returns a redcapOfflineConnection object.

See Also

vignette("redcapAPI-offline-connection", package = "redcapAPI"),
offlineConnection()

purgeProject(),
restoreProject()

Examples

## Not run: 
unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())
             
# Save a project to the current session

projectData <- preserveProject(rcon)


# Save a project to an Rdata file

save_to_dir <- tempdir()
preserveProject(rcon, 
                save_as = "Rdata", 
                dir = save_to_dir)

# Create an offline connection from the Rdata file
load(file.path(save_to_dir, 
               "project-[project_id]-RedcapList.Rdata"))

off_conn <- readPreservedProject(RedcapList, 
                                 version = "[redcap_api_version]", 
                                 url = "[redcap_api_url]")
                  
                  
# Save a project to CSV files

save_to_dir <- tempdir()
preserveProject(rcon, 
                save_as = "csv", 
                dir = save_to_dir)
                
# Create an offline connection from the CSV files

off_con <- 
 readPreservedProject(save_to_dir, 
                      version = "[redcap_api_version]", 
                      url = "[redcap_api_url]")

## End(Not run)

---