R/exportBundle.R

Defines functions exportBundle exportBundle.redcapDbConnection exportBundle.redcapApiConnection

Documented in exportBundle exportBundle.redcapApiConnection exportBundle.redcapDbConnection

#' @name exportBundle
#' @title Perform a bundle of API calls.
#'  
#' @description Several of the API calls return objects that can be used to perform
#'   various validations in \code{exportRecords}, \code{exportReports}, and other
#'   methods.  Using an export bundle allows you 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 you are uploading several files to the API, without an 
#'   export bundle, \code{importFiles} will utilize the \code{exportMetaData}
#'   on each call in order to perform validations.  Using a bundle allows you 
#'   to download the meta data once and refer to it on every subsequent call 
#'   that requires the data dictionary.
#'   
#' @param rcon A REDCap connection object as generated by \code{redcapConnection}
#' @param date Logical. If \code{TRUE}, user expiration dates are converted to 
#'   \code{POSIXct} objects.
#' @param label Logical.  If \code{TRUE}, the user form permissions are 
#'   converted to labelled factors.
#' @param meta_data Logical.  Indicates if the meta data (data dictionary) 
#'   should be exported.
#' @param users Logical. Indicates if the users table should be exported.
#' @param instruments Logical. Indicates if the instruments table should be exported.
#' @param events Logical. Indicates if the event names should be exported.
#' @param arms Logical. Indicates if the arms table should be exported.
#' @param mappings Logical. Indicates if the form-event mappings should 
#'   be exported.
#' @param version Indicates if the REDCap version number should be exported.  
#'   Only applicable in REDCap 6.0.0 and higher.
#' @param ... Arguments to be passed to other methods
#' @param return_object Logical.  When \code{TRUE}, the \code{exportBundle} object
#' is returned to the workspace.
#' 
#' @details The project information is stored in the option 
#'   \code{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.
#'   
#' @author Benjamin Nutter
#' 
#' @export

exportBundle <- function(rcon, date=TRUE, label=TRUE, 
                              meta_data=TRUE, users=TRUE, instruments=TRUE,
                              events=TRUE, arms=TRUE, mappings=TRUE,
                              version=TRUE, ...) 
  UseMethod("exportBundle")

#' @rdname exportBundle
#' @export

exportBundle.redcapDbConnection <- function(rcon, date=TRUE, label=TRUE, 
                                                 meta_data=TRUE, users=TRUE, instruments=TRUE,
                                                 events=TRUE, arms=TRUE, mappings=TRUE,
                                                 version=TRUE, ...){
  message("Please accept my apologies.  The redcapProjectInfo method for redcapDbConnection objects\n",
          "has not yet been written.  Please consider using the API.")
}

#' @rdname exportBundle
#' @export

exportBundle.redcapApiConnection <- function(rcon, date=TRUE, label=TRUE, 
                                             meta_data=TRUE, users=TRUE, instruments=TRUE,
                                             events=TRUE, arms=TRUE, mappings=TRUE,
                                             version=TRUE, ..., 
                                             return_object = TRUE){
  
  coll <- checkmate::makeAssertCollection()
  
  checkmate::assert_class(x = rcon,
                          classes = "redcapApiConnection",
                          add = coll)
  
  massert(~ date + label + meta_data + users + instruments + 
            events + arms + mappings + version + return_object,
          fun = checkmate::assert_logical,
          fixed = list(len = 1,
                       add = coll))
  
  checkmate::reportAssertions(coll)
  
  if (return_object)
    message("It appears you are saving your export bundle to an object.\n  ",
            "This is only necessary when working with multiple projects in the same session.\n  ",
            "'return_object = FALSE' will become the default behavior in a future version of redcapAPI.")
  
  
  if (!is.na(match("v.number", names(list(...)))))
    message("In redcapAPI 2.0, the 'v.number' argument is obsolete and deprecated. ",
            "Please discontinue its use")
  
  bundle <- 
    structure(
      list(
        version = if (version) exportVersion(rcon) else NULL,
        meta_data = if (meta_data) exportMetaData(rcon) else NULL,
        users = if (users) exportUsers(rcon, date, label, 
                                       bundle = NULL) else NULL,
        instruments = if (instruments) exportInstruments(rcon) else NULL,
        events = if (events) exportEvents(rcon) else NULL,
        arms = if (arms) exportArms(rcon) else NULL,
        mappings = if (mappings) exportMappings(rcon) else NULL
      ),
      class = c("redcapBundle", "redcapProject", "list")
    )
  
  options(redcap_bundle = bundle)
  if (return_object) return(bundle)
}

Try the redcapAPI package in your browser

Any scripts or data that you put into this service are public.

redcapAPI documentation built on Feb. 18, 2020, 1:09 a.m.