preserveProject() R function from [redcapAPI]

Preserve Project Data Locally

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.


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.

Returns

`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.

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.

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)

preserveProject function