--- title: "Post-Processing" author: "Bill Denney" output: rmarkdown::html_vignette: toc: yes toc_depth: 6 vignette: > %\VignetteIndexEntry{Post-Processing} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, echo=FALSE, include=FALSE} library(PKNCA) library(dplyr) ``` # Introduction Once a calculation is complete, the steps to extract the desired results from the results object are described below. # Setup To extract results, first results must be available. The example below comes from the Introduction and Usage vignette and is reproduced here simply to have results available. See that vignette for more details about running PKNCA. ```{r setup-example} library(PKNCA) suppressPackageStartupMessages(library(dplyr)) d_conc <- as.data.frame(datasets::Theoph) %>% mutate(Subject=as.numeric(as.character(Subject))) ## Generate the dosing data d_dose <- d_conc[d_conc$Time == 0,] d_dose$Time <- 0 conc_obj <- PKNCAconc( d_conc, conc~Time|Subject ) dose_obj <- PKNCAdose( d_dose, Dose~Time|Subject ) data_obj <- PKNCAdata(conc_obj, dose_obj) results_obj <- pk.nca(data_obj) ``` # Modifying Results ## Exclusion of Select Results In many scenarios, individual results may need to be excluded from summaries. To exclude results, use the `exclude()` function. ### Exclusion Functions Several exclusion functions are built into PKNCA. The built-in functions will exclude all results that either apply to the current value or are dependencies of the current value. For example, $AUC_\infty$ depends on $\lambda_z$, and excluding based on span ratio will exclude all parameters that depend on $\lambda_z$, including $AUC_\infty$. To see the built-in functions, type `?exclude_nca` at the R command line and review that help page. To use them, provide the function to the `FUN` argument of `exclude()` as illustrated below. ```{r exclude-function} results_excl_span <- exclude(results_obj, FUN=exclude_nca_span.ratio()) # Without any exclusions applied, the 'exclude' column is all NA. as.data.frame(results_obj) %>% filter(Subject == 1) # With exclusions applied, the 'exclude' column has the reason for exclusion. as.data.frame(results_excl_span) %>% filter(Subject == 1) ``` You may also write your own exclusion function. The exclusion functions built-into PKNCA are a bit more complex than required because they handle options and manage general functionality that may not apply to a user-specific need. To write your own exclusion function, it should follow the description of how to write your own exclusion function as described in the details section of `?exclude`. ### Excluding Specific Results Excluding specific results has the benefit that full control is provided. But, excluding specific points allows for errors to also enter the analysis because parameters that depend on the excluded parameter will not be excluded. ```{r exclude-specific} mask_exclude_cmax <- results_obj %>% as.data.frame() %>% dplyr::mutate( mask_exclude=Subject == 1 & PPTESTCD == "cmax" ) %>% "[["("mask_exclude") results_excl_specific <- exclude( results_obj, mask=mask_exclude_cmax, reason="Cmax was actually above the ULOQ" ) # Without any exclusions applied, the 'exclude' column is all NA. results_obj %>% as.data.frame() %>% filter(Subject == 1) # With exclusions applied, the 'exclude' column has the reason for exclusion. results_excl_specific %>% as.data.frame() %>% filter(Subject == 1) ``` ### Multiple Exclusions More than one exclusion can be applied sequentially to results as in the example below. ```{r exclude-multi} mask_exclude_lz <- results_obj %>% as.data.frame() %>% dplyr::mutate( mask_exclude=Subject == 1 & PPTESTCD == "lambda.z" ) %>% "[["("mask_exclude") # Starting from the exclusion example above where short span ratios were # excluded, exclude Cmax for Subject 1, too. results_excl_multi <- exclude( results_excl_span, mask=mask_exclude_cmax, reason="Cmax was actually above the ULOQ" ) results_excl_multi <- exclude( results_excl_multi, mask=mask_exclude_lz, reason="Issue with lambda.z fit" ) # With exclusions applied, the 'exclude' column has the reason for exclusion. # More than one reason may appear if more than one exclusion is applied. results_excl_multi %>% as.data.frame() %>% filter(Subject == 1) ``` # Normalizing Results PKNCA provides functions to normalize calculated parameters by columns in your data or by using normalization tables. ## Example: Normalize by a column in the concentration data The function `normalize_by_col()` allows you to normalize parameters by any column present in the concentration data of your PKNCAresults object. You can also specify the unit as another column in the concentration data or as a constant value. Suppose your concentration data includes a column for body weight, and you want to normalize Cmax by each subject's weight: ```{r normalize-by-col} # Add a weight column to the concentration data d_conc2 <- d_conc d_conc2$weight <- unname(setNames(60:71, 1:12)[d_conc2$Subject]) d_conc2$weight_unit <- "kg" # Recreate the PKNCA objects with the new column conc_obj2 <- PKNCAconc( d_conc2, conc~Time|Subject ) dose_obj2 <- PKNCAdose( d_dose, Dose~Time|Subject ) data_obj2 <- PKNCAdata(conc_obj2, dose_obj2) results_obj2 <- pk.nca(data_obj2) # Normalize Cmax by the 'weight' column results_norm_by_col <- normalize_by_col( results_obj2, col = "weight", unit = "weight_unit", parameters = "cmax", suffix = ".wn" ) # Show the normalized results appended as.data.frame(results_norm_by_col) %>% filter(PPTESTCD == "cmax.wn") ``` ## Doing custom normalizations If your data does not have the normalization column explicitly, you can perform the same normalization using the `normalize()` function by providing a normalization table. Below, we use the same subject weights as above to normalize Cmax, but without adding the weight column to the concentration data: ```{r normalize-custom} # Use the same subject_weights as above norm_table <- data.frame(Subject = unique(d_conc$Subject), normalization = 60:71, unit = "kg") results_norm_custom <- normalize( results_obj, norm_table = norm_table, parameters = "cmax", suffix = ".wn" ) as.data.frame(results_norm_custom) %>% filter(PPTESTCD == "cmax.wn") ``` # Extracting Results ## Summary Results Summary results are obtained using the aptly named `summary()` function. It will output a `summary_PKNCAresults` object that is simply a data.frame with an attribute of `caption`. The summary is generated by evaluating summary statistics on each requested parameter. Which summary statistics are calculated for each parameter are set with `PKNCA.set.summary()`, and they are described in the caption. When a parameter is not requested for a given interval, it is illustrated with a period (`.`), by default (customizable with the `not.requested.string` argument to `summary()`). When a parameter is required to calculate another parameter, but it is not specifically requested, it will not be shown in the summary. The summary will have one column for each grouping variable other than the subject grouping variable; one column each for the start and end time; and one column per parameter calculated. ```{r summary} summary(results_obj) ``` When values are excluded as described above, the excluded values are not included in the summary (note that half.life and aucinf.obs differ). ```{r summary-exclusion} summary(results_excl_span) ``` ## Listing of Results A listing of all calculated values is available using `as.data.frame()`. ```{r listing} as.data.frame(results_obj) %>% head(20) ``` Excluded values remain in the listing. ```{r listing-exclusion} as.data.frame(results_excl_span) %>% head(20) ```