Simple PK Analysis with AplosNCA

Introduction

This vignette demonstrates a simple pharmacokinetic (PK) analysis using the Aplos NCA API via the AplosNCA package. It calculates PK parameters from concentration-time data.

We’ll use example data (ex1-data.csv) and configuration (ex1-analysis.json) included in the package. The example data included concentration-time data for 10 subjects following administration of an extravascular dose. In practice, replace these with your own files. Note that to use Aplos NCA, you must upload a file to the system, thus if you have a dataframe inside R with the concentration-time data, please write that to a CSV file which can then be uploaded to Aplos NCA.

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", "ex1-data.csv", package = "AplosNCA")

# Get upload URL
# Simulated - in real use, call aplos_get_upload_url("ex1-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("ex1-data.csv", upload_result, token)
print("File uploaded (simulated)")
#> [1] "File uploaded (simulated)"

Step 4: Load Configurations

Load the analysis configuration (for PK parameter calculation). In this example, we only provide analysis; adjust for your needs.

analysis_config_file <- system.file("extdata", "ex1-analysis.json", package = "AplosNCA")
analysis <- readChar(analysis_config_file, file.info(analysis_config_file)$size)

Step 5: Execute Analysis

Submit the analysis for processing.

# Simulated - in real use, call aplos_execute_analysis(upload_result, analysis = analysis,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 simple PK analysis! Explore the unzipped results for calculated parameters. For more advanced workflows, 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