Using the Castor API R package for data analysis

You can use the Castor API R package to access study data in Castor via R.  Please note that the 'castoRedc' project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms. For a simple data export and/or study and report data  merge, see: How can I export and merge data in R?

To get started with R, RStudio and RShiny, see also: Introduction to R, RStudio and RShiny - Create your own dashboards 

Package Structure

There are three ways to access data through the API:

1. Access to individual items (getStudyDataPoint, getStudy, getRecord, etc.)
2. Access to pages of items in a list (getStudies, getRecords, etc.)
3. Processed into a data frame for straightforward analysis (getStudyData)

Installation

# install.packages("remotes")
remotes::install_github("castoredc/castoRedc")

Usage

1. Generate your Castor credentials, see: Application Programming Interface (API). Please note that the Client ID and Secret grant the same access to your data as your own username and password. Please treat them as such and do not hand them out to others (including us at Castor). We recommend reading about securely managing your credentials.
2. Authenticate using your Castor credentials. In the code below we store the credentials in environment variables. If you share your code with collaborators, you won't have to worry about removing your credentials before sharing the code. Check here how you can use environment variables.
   

   library(castoRedc)
   
   castor_api <- CastorData$new(key = Sys.getenv("CASTOR_KEY"), 
                                secret = Sys.getenv("CASTOR_SECRET"), 
                                base_url = "https://data.castoredc.com")

   If you're not planning to share your code, you could simply use:
   

   library(castoRedc)
   
   castor_api <- CastorData$new(key = "YOUR_CLIENTID_HERE", 
                                secret = "YOUR_SECRET_HERE", 
                                base_url = "https://data.castoredc.com")

   Please bear in mind that this code will contain your client ID and secret, so do not share them with anyone. Anyone that has your client ID and secret will be able to access your data via your account!
3. Get a list of the studies you have access to with:               

   studies <- castor_api$getStudies()

4. Subsequently, get a study ID, for example:
   

   (example_study_id <- studies[["study_id"]][1])
   #> [1] "012A3A45-6ABB-7890-1234-567A8AB90A12"

5. You can use the study ID to get the study's records, data, fields, steps, and phases, etc.              
   1. Get a list of records with:
      

      records <- castor_api$getRecords("YOUR_STUDY_ID")

   2. Get the study data with:
      

      studydata <- castor_api$getStudyData("YOUR_STUDY_ID")

   3. Get the report data with:
      

      reportdata <- castor_api$getReportInstancesBulk("YOUR_STUDY_ID")

   4. Get the fields with:
      

      fields <- castor_api$getFields("YOUR_STUDY_ID")

   5. Get the steps with:
      

      steps <- castor_api$getSteps("YOUR_STUDY_ID")

   6. Get the phases with:
      

      phases <- castor_api$getPhases("YOUR_STUDY_ID")

Troubleshooting

I cannot authenticate

Upon authenticating you might have received the error:

Error in oauth2.0_access_token(endpoint, app, code = code, user_params = user_params, :
Bad Request (HTTP 400). Failed to get an access token

The error indicates that the authentication did not go well. Please check your user credentials - make sure that you use the most recent secret. You can check if your credentials are alright with:

castor_api <- CastorData$new(key = "YOUR_KEY_HERE", 
secret = "YOUR_SECRET_HERE", 
base_url = "https://data.castoredc.com")

In our R package documentation, we generally recommend to use system variables to store your credentials. This is safer than the example above, because the credentials are not directly pasted in the code. If you share your code with collaborators, you won't have to worry about removing your credentials before sharing the code. Please also view this article (bullet point 5) to learn more about what a system environment is.