redcapAPI (version 2.8.0)

armsMethods: 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 redcapApiConnection
exportArms(
  rcon,
  arms = character(0),
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)
# S3 method for redcapApiConnection
importArms(
  rcon,
  data,
  override = FALSE,
  refresh = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)
# S3 method for redcapApiConnection
deleteArms(
  rcon,
  arms,
  refresh = TRUE,
  ...,
  error_handling = getOption("redcap_error_handling"),
  config = list(),
  api_param = list()
)

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 has no return and prints a message indicating the number of arms imported.

deleteArms has no return and prints a message indicating the number of arms deleted.

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.

refresh

logical(1) If TRUE, the cached arms data will be refreshed after the API action is complete.

...

Arguments to pass to other methods

error_handling

character(1). One of c("error", "null"). An option for how to handle errors returned by the API. see redcapError().

config

A named list. Additional configuration parameters to pass to httr::POST(). These are appended to any parameters in rcon$config.

api_param

A named list. Additional API parameters to pass into the body of the API call. This provides users to execute calls with options that may not otherwise be supported by redcapAPI.

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.

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.

Examples

if (FALSE) {
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))
}