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.6.0 (2026-04-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] AplosNCA_1.0.1 rmarkdown_2.31
#> 
#> loaded via a namespace (and not attached):
#>  [1] cli_3.6.6        knitr_1.51       rlang_1.2.0      xfun_0.58       
#>  [5] stringi_1.8.7    otel_0.2.0       jsonlite_2.0.0   glue_1.8.1      
#>  [9] buildtools_1.0.0 htmltools_0.5.9  maketools_1.3.2  sys_3.4.3       
#> [13] sass_0.4.10      rappdirs_0.3.4   evaluate_1.0.5   jquerylib_0.1.4 
#> [17] fastmap_1.2.0    yaml_2.3.12      lifecycle_1.0.5  stringr_1.6.0   
#> [21] compiler_4.6.0   AzureAuth_1.3.4  digest_0.6.39    R6_2.6.1        
#> [25] magrittr_2.0.5   bslib_0.11.0     tools_4.6.0      cachem_1.1.0