Overview

Setup

CAD Authentication

To interact with an Integral repository from R, you will need to supply your CAD authentication credentials, which are store in the form of an API key. This key is unique to you and is the equivalent of your login information, so make sure to not save it anywhere that other people may have access to (like inside an R script). To keep this key secure, we will save it in your .Renviron so that the IntegralR functions can supply the credentials directly to the Integral repository.

First, log in in to your Certara.net account and navigate to your profile page.

From there, scroll to the bottom left of your profile. Generate an API key and copy it to your clipboard.

Back in your R console, open your .Renviron to add your API key.

# Open .Renviron to add API key
if (!requireNamespace("usethis", quietly = TRUE)) {
  install.packages("usethis")
}

usethis::edit_r_environ()

You will need to add the following line, making sure to replace the API key below with the one copied from your clipboard.

CAD_API_KEY="RF9UFz4B7ET3WfQLLWYmOhujJfMXQeahQzgkIaTJETzb0gEUywtym3hhta4nyeiWnl8gQLMYP9wpZ5us4Zkf4T0M7JwuvjMq34LM"

Save your .Renviron file and restart R/RStudio to finish the setup.

Repository Configuration

While all IntegralR functions accept the URL of the Integral repository as an argument, it is typically easier to configure this option globally in your .Rprofile. This will eliminate the need to supply the URL every time you use an IntegralR function.

# Open .Rprofile for editing
usethis::edit_r_profile()

Next, add the following line to your .Rprofile file. Note that the value assigned to integral_url should correspond to the URL that you are using in the web application.

See example:

options("integral_url" = "https://certara.integral.qa.certara.net")

You will also need to save and restart R/RStudio to save any changes you make to .Rprofile.

Usage

Create Folders

To create new root folders in the Integral repository, you can use the create_root_folder() function, making sure to supply a folder type. For a list of types available in your repository, use get_folder_types().

get_folder_types()

create_root_folder(
  name = "Root Folder",
  type = "Study"
)

## Integral Folder Types 
## 
##  Integral URL: https://certara.integral.qa.certara.net 
## 
##  Types:  
## 
##      Study
##      Library
##      Data
##      Documents
##      Model Type
##      Model File Type
##      Folder
##      Analyses
##      Analysis
##      Legacy Study
##      Scenarios
##      Scenario
##      Study Objects
##      Study Views
##      Study View
##      Legacy Library
##      CUSTOM
##      FileUploadEnabled
##      FileUploadDisabled
##      TEST
##      Project
##      SYSTEM
##      NONE

## Successfully created root folder 'Root Folder'

You can also add a sub folder by using create_subfolder(). If you encounter errors in creating a sub folder, be sure to check the permissible folder type structure from within the Administration tab of your Integral repository.

create_subfolder(
  path = "Root folder/Data", 
  name = "sub_folder"
)

## Successfully created subfolder 'sub_folder'

Adding Additional Fields

Information for all the other fields that are seen when creating folders from within the Integral web application can be added as well. To see the available fields and accepted values, use get_folder_type_attributes() and get_folder_type_values(). These values can be passed as additional arguments when creating the folder.

# Check which fields are required
get_folder_type_attributes(type = "Study")

# Check what values are allowed within each field
get_folder_type_values(type = "Study")

# Create folders
create_root_folder(
  name      = "Root Folder",
  type      = "Study",
  attribute = "value"
)

create_subfolder(
  path      = "Root folder/Data", 
  name      = "sub_folder",
  attribute = "value"
)

## Integral Folder Type Attributes 
## 
##  Integral URL: https://certara.integral.qa.certara.net 
## 
##  Folder Type: Study 
## 
##  Attributes:  
## 
##              Name Required
##            Client    FALSE
##          Compound    FALSE
##        Indication    FALSE
##         Portfolio    FALSE
##        Study Type    FALSE
##      Study Design    FALSE
##  Therapeutic Area    FALSE
##             Group    FALSE
##           Program    FALSE
##             Phase    FALSE
##            Reason    FALSE
##            custom    FALSE
##           Project    FALSE
##        Start Date    FALSE
##       Description    FALSE

## Integral Folder Type Values 
## 
##  Integral URL: https://certara.integral.qa.certara.net 
## 
##  Folder Type: Study 
## 
##  Values:  
## 
##      Client:           Any
##      Compound:         Any
##      Indication:       Any
##      Portfolio:        Any
##      Study Type:       "ADME" | "Clinical" | "Pre-Clinical"
##      Study Design:     "Crossover" | "Dose Response" | "Parallel" | "Randomized"
##      Therapeutic Area: Any
##      Group:            Any
##      Program:          Any
##      Phase:            "Phase I" | "Phase II" | "Phase III" | "Phase IV" | "Pre-Clinical"
##      Reason:           Any
##      custom:           "FALSE" | "TRUE"
##      Project:          Any
##      Start Date:       Any
##      Description:      Any

## Successfully created root folder 'Root Folder'

## Successfully created subfolder 'sub_folder'

Check Repository Contents

If you need to find a root folder that already exists in an Integral repository, you can use get_root_folders(). This will return a list of all the root folders in the repository, along with some information about the folder properties.

# Get list of root folders in Integral repository
roots <- get_root_folders()

# Print the first 5 entries
print(roots, n = 5)

## Repository Root Folders 
## 
##  Integral URL: https://certara.integral.qa.certara.net 
## 
##     Name             Created            Modified Revision  Type Locked Blinded
##  _Revert 2025-04-10T14:21:55 2025-04-10T14:21:55        1 Study  FALSE   FALSE
##   001New 2025-03-10T18:59:26 2025-03-10T18:59:26        1 Study  FALSE   FALSE
##      002 2025-03-11T17:14:59 2025-03-11T17:14:59        1 Study  FALSE   FALSE
##      003 2025-03-12T12:31:33 2025-03-12T12:31:33        1 Study  FALSE   FALSE
##      004 2025-03-31T13:41:03 2025-03-31T13:41:03        1 Study  FALSE   FALSE

Similarly, you can explore the contents of a folder (or sub folder) by passing the folder name to get_children_of_folder(). This will return information on the children files and folders of the supplied parent folder.

get_children_of_folder(path = "Root Folder/Data")

## Folder Children 
## 
##  Integral URL: https://certara.integral.qa.certara.net 
## 
##  Parent Folder (UUID): Root Folder/Data (55717c19-8d36-40fd-b963-42ad7305480d)
## 
##            Name             Created            Modified Revision Object.Type Folder.Type Savepoint.Container Locked Blinded
##  airquality.csv 2025-03-28T19:35:21 2025-03-28T19:35:21        1        File                           FALSE   TRUE   FALSE
##        cars.csv 2025-03-28T19:34:49 2025-03-28T19:34:49        1        File                           FALSE   TRUE   FALSE
##          DM.xpt 2025-03-28T19:38:41 2025-03-28T19:38:41        1        File                           FALSE   TRUE   FALSE
##    finaldat.rds 2025-03-28T19:41:57 2025-03-28T19:41:57        1        File                           FALSE   TRUE   FALSE
##      mtcars.csv 2025-03-31T18:13:06 2025-03-31T18:13:06        1        File                           FALSE   TRUE   FALSE
##     my_data.csv 2025-03-28T19:31:46 2025-03-28T19:31:46        1        File                           FALSE   TRUE   FALSE
##      sub_folder 2025-03-28T19:30:46 2025-03-28T19:30:46        1      Folder      Folder               FALSE   TRUE   FALSE

Download File

Use the function integral_download() to download a file from Integral. The file argument corresponds to the file path in Integral, which can be copied to your clipboard directly from Integral. Use the path argument to specify the download location on your file system.

integral_download(
  file = "Root Folder/Data/my_data.csv",
  path = getwd()
)

If you’d like to save the file under a different name, you can specify the desired file name directly in the path argument, as shown below.

integral_download(
  file = "Root Folder/Data/my_data.csv",
  path = file.path(getwd(), "my_data_2.csv")
)

Multiple files can be downloaded by specifying a character vector of Integral file paths to the file argument.

files_to_download <- c("Root Folder/Data/airquality.csv", 
                       "Root Folder/Data/cars.csv")

integral_download(
  file = files_to_download,
  path = getwd()
)

Read Data

You can read data from a remote Integral repository directly into your R environment using the function integral_read. Use the FUN argument to specify the correct data import function given the type of file being imported, e.g., for a .csv file use read.csv, for an .xpt file use haven::read_xpt, etc.

Example importing a csv file using the read.csv function in base R.

my_data <- integral_read(FUN = read.csv,
                         file = "Root Folder/Data/my_data.csv")

Use the ... to add additional arguments corresponding to the function specified in FUN, e.g.,

my_data <- integral_read(
  FUN = read.csv,
  file = "Root Folder/Data/my_data.csv",
  col.names = c(
    "id",
    "nom_time",
    "act_time",
    "amount",
    "conc",
    "age",
    "bw",
    "sex"
  ),
  na.strings = ".",
  numerals = "no.loss"
)

Example importing a .xpt file using the read_xpt function from the haven package.

if (!requireNamespace("haven", quietly = TRUE)) {
  install.packages("haven")
}

DM <- integral_read(FUN = haven::read_xpt,
                    file = "Root Folder/Data/DM.xpt")

Example importing a .Rds file using the readRds function from base R.

rds_data <- integral_read(FUN = readRDS,
                          file = "Root Folder/Data/finaldat.RDS")

Upload File

Use the file argument to specify the path to the file in your file system. Use the path argument to specify the directory name or file path in the remote Integral repository.

Upload a single file.

write.csv(mtcars, "mtcars.csv")

integral_upload(file = "mtcars.csv",
                path = "Root Folder/Data/mtcars.csv")

Create plots and upload multiple files.

png(file = "mtcars_mpg_vs_wt.png", width = 800, height = 600)
plot(mtcars$wt, mtcars$mpg,
     xlab = "Weight (1000 lbs)",
     ylab = "Miles/(US) gallon",
     main = "Vars: MPG vs. Weight",
     pch = 19)
dev.off() 

png(file = "mtcars_mpg_vs_hp.png", width = 800, height = 600)
plot(mtcars$hp, mtcars$mpg,
     xlab = "Horsepower",
     ylab = "Miles/(US) gallon",
     main = "Vars: MPG vs. Horsepower",
     pch = 19)
dev.off() 

integral_upload(file = c("mtcars_mpg_vs_hp.png", "mtcars_mpg_vs_wt.png"),
                path = "Root Folder/Data")

Write Data

The integral_write function allows you to export objects e.g., data.frame written to a .csv file in Integral, directly from R. Use the x argument to specify an object available in your R environment. The FUN argument should specify the correct data writing function given the type of file being exported, e.g., for a .csv file use write.csv. Use the path argument to specify the file path in the remote Integral repository.

data <- mtcars

integral_write(x = data,
               FUN = write.csv,
               path = "Root Folder/Data/mtcars.csv",
               reason = "add more data")

Since Integral was designed to keep track of file revisions, writing and uploading of files more than once will return an error if the file has not changed. This prevents Integral from changing the revision count when the file in question was not actually revised.