Castor R-Package

Castor R-Package

Prerequisites

DRE:
  1. Owner access to workspace, to install R / RStudio / Rtools in a virtual machine
  2. External access to CRAN in the workspace where you want to export the data to (open up port rule)
  3. External access to Castor in the workspace where you want to export the data to (open up port rule)
Castor:
  1. View and Export rights in the study you want to export with R

Installing CastoRedc package

If you already have R, RStudio and RTools installed, you can skip steps 1 and 3. Note that the Install DRE Applications program contains older versions of R, RStudio and RTools. It is advised to follow the steps below to obtain the newest versions.
R Local Repositories (available in Install DRE Applications) contains the wrong version of devtools. Make sure to run the options line from step 4 to install packages directly from cran.r-project.org.
Step 1: Download R/RStudio/RTools installation files
To use the Castor R package, you need R, RStudio and Rtools installed on at least 1 VM in your workspace. Use the following links to download the installation files on your own computer, then transfer these files to your workspace via the Files tab in the DRE portal (https://mydre.org).
  1. R: https://cran.r-project.org/bin/windows/base/
  2. RStudio (for the user interface): https://rstudio.com/products/rstudio/download/#download
  3. Rtools (to install packages): https://cran.r-project.org/bin/windows/Rtools/ (choose the 64-bit version)
Step 2: Get CastoRedc package
Download the CastoRedc package to your own computer from the Castor github page by clicking on Code and then Download ZIP (see screenshot below). Transfer the .zip file to your workspace as well.


Step 3: Install R/RStudio/RTools
Log into the VM you want to use to connect to Castor using R. In the VM, find the R, RStudio and RTools installation files on the data (Z:/) drive and move them to the desktop. Next, run the installation files one by one as administrator (right-click -> run as administrator). Wait for each installation to finish before running the next one.

Step 4: Set package location
Put RTools on the PATH (see R project website for instructions). Run RStudio as administrator (Start -> RStudio [right-click] -> More -> run as administrator) and run the following line of code:
  1. options(download.file.method = "libcurl", repos = c("CRAN" = "https://cran.r-project.org/"))
N.B.: Each time you start R and want to install a package, you need to run this line of code.

Step 5: Install the devtools and generics package
Run the following lines of code or install these packages via Tools -> Install packages:
  1. install.packages("devtools")
  2. install.packages("generics")
N.B.: You may need to install the curl package (part of devtools) separately, if it receives a non-zero exit status during installation of devtools.

Step 6: Install CastoRedc package
Use the install_local function from the devtools package to install the castoRedc package from the downloaded .zip file (replace the path with the actual location of the .zip file):
  1. devtools::install_local("Z:\\path_to_zip\\castoRedc-master.zip")
Now you can load the package:
  1. library(castoRedc)

Authentication

Step 1: Retrieve Castor client ID and secret
On your own computer, follow the steps on the Castor site below to retrieve your client ID and secret (needed to connect to Castor and retrieve data):

Step 2: Set up Windows credentials
In your VM, go to the Start Menu and search for 'windows credentials'. Click on 'Manage Windows Credentials', then select 'Windows Credentials' and click on 'Add a generic credential'. Fill in the required information (also see screenshot below):
  1. Internet or network address: The name of the credential, between : symbol (we use :castor_client_id: in the example script)
  2. User name: Fill in a symbol, for example -
  3. Password: The client id you retrieved in step 1
  

Step 3: Install Keyring package
To safely store your client ID and secret, you can use the keyring R-package (see below for use): 
  1. install.packages("keyring")

Use CastoR package

Example R code, with functions in CastoR package

  1. library(castoRedc)

  3. castor_api <- CastorData$new(key = keyring::key_get("castor_client_id"),
  4.                              secret = keyring::key_get("castor_secret"),
  5.                              base_url = "https://data.castoredc.com/"

  7. studies <- castor_api$getStudies()
  8. records <- castor_api$getRecords("study_id_as_string")
  9. study_data <- castor_api$getStudyData("study_id_as_string")
  10. report_data <- castor_api$getReportInstancesBulk("study_id_as_string")
  11. fields <- castor_api$getFields("study_id_as_string")
  12. steps <- castor_api$getSteps("study_id_as_string")
  13. phases <- castor_api$getPhases("study_id_as_string")

Example R code, not (yet) in CastoR package (e.g. option groups)

  1. library(httr)
  2. library(jsonlite)

  4. base_url = "https://data.castoredc.com/"

  6. castorOAuth = function(key, secret, baseurl) {
  7.   castor_app = httr::oauth_app("CastorEDC", key = key, secret = secret)

  9.   castor_endpoint = httr::oauth_endpoint(
  10.     request = NULL,
  11.     base_url = paste0(baseurl, "oauth"),
  12.     access = "token",
  13.     "authorize"
  14.   )
  15.   castor_token = httr::oauth2.0_token(
  16.     castor_endpoint,
  17.     castor_app,
  18.     client_credentials = TRUE,
  19.     use_oob = FALSE,
  20.     cache = FALSE
  21.   )
  22.   castor_token
  23. }

  25. oauth_token <-
  26.   castorOAuth(
  27.     key = keyring::key_get("castor_client_id"),
  28.     baseurl = base_url,
  29.     secret = keyring::key_get("castor_secret")
  30.   )

  32. headers <- add_headers(Authorization = paste('Bearer',
  33.                                              oauth_token$credentials$access_token))

  35. request <-
  36.   GET(base_url, path = "api/study/study_id_as_string/export/optiongroups",
  37.       query = list(), headers)

  39. option_groups <- read.csv2(text = rawToChar(request$content))

More information (Castor site)

For further information on using the package, please visit the Castor website


    • Related Articles

    • Castor

      Setting up for Direct Access The method for accessing websites and internet-dependent services detailed on this page is outdated. We recommend to use domain-allowlisting, which is a self-service feature in the myDRE portal. Please see Domains to be ...

    • R/RStudio installation using domain allowlisting on Windows VMs

      First version: 2022-08-22 Last version: 2023-12-15 Last change: Added an alternative for installing packages from Github (installation from manually downloaded repository). This is a community effort. The article was created by the anDREa Support ...

    • Using Castor in Python

      Introduction anDREa would like to thank Reinier van Linschoten for bringing this package and description to our attention. This is a Python package for interacting with the API of Castor Electronic Data Capture (EDC). The package contains functions ...

    • R and RStudio using External Access rules

      This method of downloading R packages is outdated! This article will not be updated any longer. IP addresses are often subject to change. Therefore, the domain allowlisting feature has been introduced and it is self-service for Accountable and ...

    • Domains to be whitelisted/allowlisted for known applications

      First version: 2022-11-01 Last updated: 2024-11-22 Last change: Added details for cursor.com Introduction This is a community effort, if you experience issues, see mistakes/updates, or have other applications that you do know what to allowlist, ...