preserveProject {redcapAPI}

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,
  error_handling = getOption("redcap_error_handling"),
  config = list()
)

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.

error_handling

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

config

A list to be passed to httr::POST(). This allows the user to set additional configurations for the API calls, such as certificates, SSL version, etc. For the majority of users, this does not need to be altered.

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)