PKNCA provides functions to complete noncompartmental analysis (NCA) for pharmacokinetic (PK) data. Its intent is to provide a complete R-based solution enabling data provenance for NCA including tracking data cleaning, enabling calculations, exporting results, and reporting. The library is designed to give a reasonable answer without user intervention (load, calculate, and summarize), but it allows the user to override the automatic selections at any point.
The library design is modular to allow expansion based on needs unforseen by the authors including new NCA parameters, novel data cleaning methods, and modular summarization decisions. Expanding the library will be discussed in a separate vignette.
The simplest analysis requires concentration and dosing data, then five function calls can provide summarized results.
library(PKNCA)
## Load the PK concentration data
d.conc <- read.csv("concentration.csv", stringsAsFactors=FALSE)
## Load the dosing data
d.dose <- read.csv("dose.csv", stringsAsFactors=FALSE)
## Create a concentration object specifying the concentration, time,
## study, and subject columns. (Note that any number of grouping
## levels is supporting; you are not restricted to this list.)
my.conc <- PKNCAconc(d.conc,
concentration~time|study+subject)
## Create a dosing object specifying the dose, time, study, and
## subject columns. (Note that the grouping factors should be a
## subset of the grouping factors for concentration, and the columns
## must have the same names between concentration and dose objects.)
my.dose <- PKNCAdose(d.dose,
dose~time|study+subject)
## Combine the concentration and dosing information both to
## automatically define the intervals for NCA calculation and provide
## doses for calculations requiring dose.
my.data <- PKNCAdata(my.conc, my.dose)
## Calculate the NCA parameters
my.results <- pk.nca(my.data)
## Summarize the results
summary(my.results)After loading data, it must be in the right form. The minimum requirements are that concentration, dose, and time must all be numeric (and not factors). Grouping variables have no specific requirements; they can be any mode.
Values below the limit of quantificaiton are coded as zeros ({r eval=FALSE}0), and missing values are coded as {r eval=FALSE}NA.
Different organizations have different requirements for computation and summarization of NCA. Options for how to perform calculations and summaries are handled by the {r eval=FALSE}PKNCA.options command.
Default options have been set to commonly-used standard parameters. The current value for options can be found by running the command with no arguments:
PKNCA.options()## $adj.r.squared.factor
## [1] 1e-04
##
## $max.missing
## [1] 0.5
##
## $auc.method
## [1] "lin up/log down"
##
## $conc.na
## [1] "drop"
##
## $conc.blq
## $conc.blq$first
## [1] "keep"
##
## $conc.blq$middle
## [1] "drop"
##
## $conc.blq$last
## [1] "keep"
##
##
## $first.tmax
## [1] TRUE
##
## $allow.tmax.in.half.life
## [1] FALSE
##
## $min.hl.points
## [1] 3
##
## $min.span.ratio
## [1] 2
##
## $max.aucinf.pext
## [1] 20
##
## $min.hl.r.squared
## [1] 0.9
##
## $tau.choices
## [1] NA
##
## $single.dose.aucs
## start end auclast aucall aumclast aumcall cmax cmin tmax tlast tfirst
## 1 0 24 TRUE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
## 2 0 Inf FALSE FALSE FALSE FALSE TRUE FALSE TRUE FALSE FALSE
## clast.obs f cav ctrough ptr tlag half.life r.squared
## 1 FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
## 2 FALSE FALSE FALSE FALSE FALSE FALSE TRUE FALSE
## adj.r.squared lambda.z lambda.z.time.first lambda.z.n.points clast.pred
## 1 FALSE FALSE FALSE FALSE FALSE
## 2 FALSE FALSE FALSE FALSE FALSE
## span.ratio aucinf aumcinf aucpext cl mrt vss vd thalf.eff
## 1 FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
## 2 FALSE TRUE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
## kel vz
## 1 FALSE FALSE
## 2 FALSE FALSEAnd, to reset the current values to the library defaults, run the function with the default argument set to TRUE.
PKNCA.options(default=TRUE)Each of the options is documented where it is used; for example, the first.tmax option is documented in the {r eval=FALSE}pk.calc.tmax function.
On top of methods of calculation, summarization method preferences differ. Typical summarization preferences include selection of the measurement of central tendency and dispersion, handling of missing values, handling of values below the limit of quantification, and more. Beyond the method for summarization, presentation is managed through user preferences. Presentation is typically controlled by rounding to either a defined number of decimal places or significant figures.
An example is that Cmax may be summarized by the geometric mean with the geometric CV using three significant figures, and having a summary result requires that at least half of the available values are present (not missing). The code below will set this example.
PKNCA.set.summary(name="cmax",
point=business.geomean,
spread=business.geocv,
rounding=list(signif=3))Another example is that Tmax is usually summarized by the median and range, and as measurements are often taken with minute resolution and recorded in hours, reporting is usually to the second decimal place.
PKNCA.set.summary(name="tmax",
point=business.median,
spread=business.range,
rounding=list(round=2))If the functions or default rounding options provided in the library do not meet the summarization needs, a user-supplied function can be used for rounding.
As described in the quick start, concentration and dose data are generally grouped to identify how to separate the data. Typical groups for concentration data include study, treatment, subject, and analyte. Typical groups for dose data include study, treatment, and subject. By default, summaries are produced based on the concentration groups dropping the subject (so that averages are taken across subjects within the other parameters).
The quick start example can be extended to include multiple analytes as follows. The only difference is the {r eval=FALSE}/analyte formula element in the concentration data. The reason for the slash instead of the plus is that the last element before a slash is assumed to be the subject, and as noted before, the subject is (by default) excluded from the summary grouping (so that summaries are grouped by study, treatment, etc., but not by subject).
## Create a concentration object specifying the concentration, time,
## study, and subject columns. (Note that any number of grouping
## levels is supporting; you are not restricted to this list.)
my.conc <- PKNCAconc(d.conc,
concentration~time|study+subject/analyte)
## Create a dosing object specifying the dose, time, study, and
## subject columns. (Note that the grouping factors should be a
## subset of the grouping factors for concentration, and the columns
## must have the same names between concentration and dose objects.)
my.dose <- PKNCAdose(d.dose,
dose~time|study+subject)All NCA calculations require the inverval over which they are calculated. When the concentration and dosing information are combined to the PKNCAdata object, intervals are automatically determined. The exception to this automatic determination is if the user provides intervals.
When selected either automatically or manually, intervals define at minimum a start time, an end time, and the parameters to be calculated. The parameter list is available from the {r eval=FALSE}get.interval.cols function. The parameters requested are specified by setting the entry in a data.frame as requested.
intervals <-
data.frame(start=0, end=c(24, Inf),
cmax=c(FALSE, TRUE),
tmax=c(FALSE, TRUE),
auclast=TRUE,
aucinf=c(FALSE, TRUE))Intervals like the above is sufficient for designs with a single type of treatment– like single doses. For more complex treatments in a single analysis, like the combination of single and multiple doses, include a treatment column matching the treatment column name from the concentration data set. See the Manual Interval Specification section below for more details.
If intervals are not specified when combining the concentration and dosing data, they will automatically be found from the concentration and dosing data.
Single dose data has a simple interval selection: the option single.dose.aucs is used from the PKNCA.options.
| start | end | auclast | aucall | aumclast | aumcall | cmax | cmin | tmax | tlast | tfirst | clast.obs | f | cav | ctrough | ptr | tlag | half.life | r.squared | adj.r.squared | lambda.z | lambda.z.time.first | lambda.z.n.points | clast.pred | span.ratio | aucinf | aumcinf | aucpext | cl | mrt | vss | vd | thalf.eff | kel | vz |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 24 | TRUE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE |
| 0 | Inf | FALSE | FALSE | FALSE | FALSE | TRUE | FALSE | TRUE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | TRUE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | TRUE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE | FALSE |
For multiple-dose studies, PKNCA selects one group at a time and compares the concentration and dosing times. When there is a concentation measurement between doses, an interval row is added. The dosing interval (\(\tau\)) is determined by looking for pattern repeats within the dosing data using the find.tau function.
## find.tau can work when all doses have the same interval...
dose.times <- seq(0, 168, by=24)
print(dose.times)## [1] 0 24 48 72 96 120 144 168PKNCA::find.tau(dose.times)## [1] 24## or when the doses have mixed intervals (10 and 24 hours).
dose.times <- sort(c(seq(0, 168, by=24),
seq(10, 178, by=24)))
print(dose.times)## [1] 0 10 24 34 48 58 72 82 96 106 120 130 144 154 168 178PKNCA::find.tau(dose.times)## [1] 24After finding \(\tau\), PKNCA will also look after the last dose (or the beginning of the last dosing interval), and two additional intervals may be added:
One consequence of automatic interval selection is that many rows are generated for intervals; one row is generated per interval per subject. The benefit of the method producing a large number of rows is that it is fully flexible to the actual study results. If a subject has a different schedule than the others for the same treatment (e.g. measurements that were nominally scheduled for day 14 occurred on day 13), those differences will be found.
Intervals can also be specified manually. Two use cases are common for manual specification: fully manual (never requesting the automatic intervals) and updating the automatic intervals.
Fully manual intervals can be specified by providing it to the PKNCAdata call.
my.intervals <-
data.frame(start=0, end=c(24, Inf),
cmax=c(FALSE, TRUE),
tmax=c(FALSE, TRUE),
auclast=TRUE,
aucinf=c(FALSE, TRUE))
my.data <- PKNCAdata(my.conc, my.dose,
intervals=my.intervals)To update the automatically-selected intervals, extract the intervals, modify them, and put them back.
my.data <- PKNCAdata(my.conc, my.dose)
my.intervals <- my.data$intervals
my.intervals$aucinf[1] <- TRUE
mydata$intervals <- my.intervals