Writing PKNCA Parameter Functions

Bill Denney

Writing PKNCA Parameter Functions

The PKNCA package is designed to be comprehensive in its coverage of the needs of an noncompartmental analysis (NCA) specialist. While it has many NCA parameters specified, it may not have all parameters defined, and its design is modular to accept new parameter definitions. From its inception, PKNCA is built in modules to allow addition of new components (or removal of unnecessary ones). Defining new NCA parameters is straight-forward, and this guide will describe how it is done. The three parts to writing a new NCA parameter in PKNCA are described below.

Writing the Parameter Function

Requirements

The starting point to writing a new NCA parameter is writing the function that calculates the parameter value. The function can be passed any of the following arguments. The arguments must be named as described below:

The function should return either a scalar which is the value for the parameter (usually the case) or a data.frame with parameters named for each parameter calculated. For an example of returning a data.frame, see the half.life function.

The return value may have an attribute of exclude (set by attr(return_value, "exclude") <- "reason"). If the exclude attribute is set to a character string, then that string will be included in the exclude column for results. If any of the input parameters have an exclude attribute set, then those are also added to the exclude column. The exception to the setting of the exclude column is if the exclude attribute is "DO NOT EXCLUDE", then the exclude column is set to NA_character_.

Best Practices

Tell PKNCA about the Parameter

Just writing a function doesn’t connect it to the rest of PKNCA. You have to tell PKNCA that the function exists and a few more details about it. To do this, you need to use the add.interval.col function. The function takes up to seven arguments:

Tell PKNCA How to Summarize the Parameter

For any parameter, PKNCA needs to know how to summarize it for the summary function of the PKNCAresults class. To tell PKNCA how to summarize a parameter, use the PKNCA.set.summary function. It takes at least these four arguments:

Putting It Together

One of the most common examples is the function to calculate Cmax:

#' Determine maximum observed PK concentration
#'
#' @inheritParams assert_conc_time
#' @param check Run \code{\link{assert_conc_time}}?
#' @return a number for the maximum concentration or NA if all
#' concentrations are missing
#' @export
pk.calc.cmax <- function(conc, check=TRUE) {
  if (check)
    assert_conc_time(conc=conc)
  if (length(conc) == 0 | all(is.na(conc))) {
    NA
  } else {
    max(conc, na.rm=TRUE)
  }
}
## Add the column to the interval specification
add.interval.col("cmax",
                 FUN="pk.calc.cmax",
                 values=c(FALSE, TRUE),
                 unit_type="conc",
                 pretty_name="Cmax",
                 desc="Maximum observed concentration",
                 depends=c())
PKNCA.set.summary("cmax", "geometric mean and geometric coefficient of variation", business.geomean, business.geocv)