Get Started

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Get Started

Very Quick Guide

Getting started is as simple as 1.) setting your token, 2.) setting up a project, and 3.) running project$sync().

# 1.) setting your token -------------------------------------------------------
Sys.setenv(REDCAPSYNC_FIRST_PROJECT = "YoUrNevErShaReToken")    # in console
# or WAY BETTER put this in your .Renviron file...
# REDCAPSYNC_FIRST_PROJECT = 'YoUrNevErShaReToken
# Then save file, restart R session (`.rs.restartR()`) and library(REDCapSync)

# 2.) setting up a project -----------------------------------------------------
project <- setup_project(
  project_name = "FIRST_PROJECT",                       
  redcap_uri = "https://redcap.fake.edu/api/",             # same as REDCapR
  dir_path = getwd(),                            # choose appropriate folder
  sync_frequency = "daily",                          # only checks max daily 
  get_entire_log = TRUE                       # for small or medium projects
)

# install.packages("keyring") 
project$test_token()                    # will launch keyring if token fails

# 3.) running project$sync() ---------------------------------------------------
project$sync() 

project$generate_dataset("custom", envir = globalenv())

Setup tokens

You can set your REDCap token in three ways! If you need more help setting your tokens, see the Tokens vignette.

#1. set in your Renviron file
usethis::edit_r_environ()                                 #finds your file
# another way to find same file
rstudioapi::navigateToFile(file.path(Sys.getenv("HOME")), ".Renviron"))
# Then you add --> `REDCAPSYNC_FIRST_PROJECT = 'YoUrNevErShaReToken'`
# then save file and restart R session (`.rs.restartR()`) and reload package

#2. set to your token with keyring package! (make sure is installed)
keyring::key_set(service = config$keyring.service(), # for keyring
                 username = "FIRST_PROJECT", # is project_name
                 keyring = config$keyring()) # now enter token in pop-up
# ... or if have project object already
project$set_keyring_token() # now enter token in pop-up

#3. set each time in your console or script (not recommended!) RISKY
Sys.setenv(REDCAPSYNC_FIRST_PROJECT = "YoUrNevErShaReToken")

# Confirm
# If it worked you will see your token when you run...
Sys.getenv("REDCAPSYNC_FIRST_PROJECT") # for R eviron
# or...
keyring::key_get(service = config$keyring.service(), # for keyring
                 username = "FIRST_PROJECT", # is project_name
                 keyring = config$keyring())

Explore Outputs!

# raw REDCap -------------------------------------------------------------------
forms <- project$metadata$forms 
fields <- project$metadata$fields 
choices <- project$metadata$choices 
log <- project$redcap$log
users <- project$redcap$users
form1 <- project$data$form1
form2 <- project$data$form2
# project$data |> list2env(globalenv()) # all forms to global

# summarized REDCap ------------------------------------------------------------
# has added columns using log to annotate metadata and users etc. customizable
# help(dataset)
# dataset <- project$load_dataset("REDCapSync") # de-identified and no free text
dataset <- project$generate_dataset("custom") # identified (see parameters)
annotated_forms <- dataset$metadata$forms 
annotated_fields <- dataset$metadata$fields 
annotated_choices <- dataset$metadata$choices 
annotated_users <- dataset$users
merged <- dataset$data$merged
# dataset$data |> list2env(globalenv()) # all forms to global
# dataset$to_envir(globalenv()) # send to R global env
# can modify if you want before save (the actual dataset object not global)
# dataset$save() # will save to output folder by default

Take note you are assigning variables above. So if you have a redcap form called “project”, “fields”, “choices”, etc. you will have to adjust what you choose to call them in your script to avoid any conflicts.

Go Further by Generating Datasets!

This is the intended way to extract data from the project object. It has parameters that control what is exported. It is unique from simply exporting the raw data because it can summarize data from the log, change the columns to R variable types, add variables, etc. It can also be used for visualization functions from RosyREDCap.

The following default merges all non-repeating forms and adds them to the right of any repeating forms. It also uses the REDCap log and REDCap data to add key information to metadata, users, and records. By default it is deidentified based on REDCap settings and excludes free text (but not dates).

project$load_dataset(summary_name = "REDCapSync", envir = globalenv())

This can be customized with add_dataset for refreshing datasets or generate_dataset for R-only use. This can give you filtered data (and corresponding annotations to metadata, etc), deidentified data, and more!

project$generate_dataset(
  dataset_name = "custom_name"
  filter_field = "has_something"  # Raw REDCap variable name
  filter_choices = "Yes"          # REDCap labelled choice
  exclude_identifiers = TRUE,
  exclude_free_text = TRUE,
  include_metadata = TRUE,
  envir = globalenv()
)

See the Datasets vignette.

Framework

For an in-depth demonstration of both REDCapSync and RosyREDCap, see thecodingdocs.github.io/RMed26-Demo.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.