Full PK Analysis with AplosNCA

Introduction

This vignette demonstrates a full pharmacokinetic (PK) analysis using the Aplos NCA API via the AplosNCA package. It uploads a raw data file, performs data cleaning, calculates PK parameters, performs a post-NCA calculation, and creates tables and plots.

We’ll use example data (ex2-data.csv) and 5 configuration files (ex2-data_cleaning.json, ex2-analysis.json, ex2-calcs.json, ex2-plots.json, ex2-tables.json) included in the package. The example data includes concentration-time data for 12 subjects following administration of an extravascular dose under fed and fasted conditions. The data cleaning step will add treatment information, add units, and perform BLQ handling. The analysis will calculate the PK parameters. The custom calculations will calculate the relative bioavailability for AUC and Cmax for the fed condition. Then tables and plots will be created.

Prerequisites: Set up your credentials in a local file (e.g., ~/.aplos_creds) as described in ?aplos_get_jwt. This vignette assumes the package functions are loaded.

library(AplosNCA)  # Load the package

Step 1: Load Credentials

Load your Aplos NCA credentials securely from a local file. Do not hardcode them!

# For vignette demonstration (offline), use fake credentials.
# In real use, source your .aplos_creds file.
creds <- list(
  COGNITO_CLIENT_KEY = "fake_key",
  COGNITO_USERNAME = "fake_user",
  COGNITO_PASSWORD = "fake_pass",
  COGNITO_REGION = "us-east-1",
  APLOS_API_URL = "https://api.app.aplos-nca.com"
)

Step 2: Authenticate

Obtain a JWT token for API access.

# Simulated for vignette - in real use, call aplos_get_jwt(creds$COGNITO_CLIENT_KEY, ...)
token <- "fake_token"
url <- creds$APLOS_API_URL
print("Authenticated (simulated)")
#> [1] "Authenticated (simulated)"

Step 3: Upload Input Data

Upload the example PK data file.

# Define your input file
input_file <- system.file("extdata", "ex2-data.csv", package = "AplosNCA")

# Get upload URL
# Simulated - in real use, call aplos_get_upload_url("ex2-data.csv", url, token)
upload_result <- list(data = list(fileId = "fake_file_id"))
print("Upload URL retrieved (simulated)")
#> [1] "Upload URL retrieved (simulated)"

# Upload file
# Simulated - in real use, call aplos_upload_file("ex2-data.csv", upload_result, token)
print("File uploaded (simulated)")
#> [1] "File uploaded (simulated)"

Step 4: Load Configurations

Load the configuration files for the analysis. Each file includes specific configuration for that step in the analysis.

# Data cleaning
data_cleaning_config_file <- system.file("extdata", "ex2-data_cleaning.json", package = "AplosNCA")
data_cleaning <- readChar(data_cleaning_config_file, file.info(data_cleaning_config_file)$size)
# PK analysis
analysis_config_file <- system.file("extdata", "ex2-analysis.json", package = "AplosNCA")
analysis <- readChar(analysis_config_file, file.info(analysis_config_file)$size)
# Custom calculations
calcs_config_file <- system.file("extdata", "ex2-calcs.json", package = "AplosNCA")
calcs <- readChar(calcs_config_file, file.info(calcs_config_file)$size)
# Custom tables
tables_config_file <- system.file("extdata", "ex2-tables.json", package = "AplosNCA")
tables <- readChar(tables_config_file, file.info(tables_config_file)$size)
# Custom plots
plots_config_file <- system.file("extdata", "ex2-plots.json", package = "AplosNCA")
plots <- readChar(plots_config_file, file.info(plots_config_file)$size)

Step 5: Execute Analysis

Submit the analysis for processing.

# Simulated - in real use, call aplos_execute_analysis(upload_result, data_cleaning = data_cleaning,
#                                 analysis = analysis, calcs = calcs, tables = tables,
#                                 plots = plots, url = api_url, token = token, name = "Simple PK Analysis Vignette")
exec_id <- "fake_exec_id"
print("Analysis executed (simulated)")
#> [1] "Analysis executed (simulated)"

Step 6: Check Status

Poll until the analysis is complete.

# Simulated polling - assume "succeeded" after delay - in real use, call exec_result <- aplos_execution_status(url = api_url, token = token, execution_id = exec_id, sleep=10)

exec_result <- list(data = list(status = "succeeded"))
print("Execution complete (simulated)")
#> [1] "Execution complete (simulated)"

Step 7: Download and Unzip Results

If succeeded, download and unzip the results.

if (exec_result$data$status == "succeeded") {
  # Simulated - in real use, call download_info <- aplos_download_results(url = api_url, token = token, execution_id = exec_id)
  # file_path <- aplos_fetch_results(download_info, dest_dir = "simple", unzip = TRUE)
} else {
  cat("Analysis failed; check status.\n")
}
#> NULL

Conclusion

You’ve now run a full PK analysis! Explore the unzipped results for calculated parameters. For more information, see other vignettes or the function documentation.

sessionInfo()
#> R version 4.4.3 (2025-02-28)
#> Platform: aarch64-apple-darwin20
#> Running under: macOS 26.3.1
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRblas.0.dylib 
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
#> 
#> locale:
#> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> time zone: America/Denver
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] AplosNCA_1.0.1
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.38     R6_2.6.1          fastmap_1.2.0     xfun_0.54        
#>  [5] AzureAuth_1.3.4   magrittr_2.0.4    rappdirs_0.3.4    glue_1.8.0       
#>  [9] cachem_1.1.0      stringr_1.6.0     knitr_1.50        htmltools_0.5.8.1
#> [13] rmarkdown_2.30    lifecycle_1.0.5   cli_3.6.5         sass_0.4.10      
#> [17] jquerylib_0.1.4   compiler_4.4.3    rstudioapi_0.17.1 tools_4.4.3      
#> [21] evaluate_1.0.5    bslib_0.9.0       yaml_2.3.10       rlang_1.1.7      
#> [25] jsonlite_2.0.0    stringi_1.8.7