Examples simplify understanding. Below is an example of how to use the theophylline dataset to generate NCA parameters.

Load the data

## It is always a good idea to look at the data
head(datasets::Theoph)
## Grouped Data: conc ~ Time | Subject
##   Subject   Wt Dose Time  conc
## 1       1 79.6 4.02 0.00  0.74
## 2       1 79.6 4.02 0.25  2.84
## 3       1 79.6 4.02 0.57  6.57
## 4       1 79.6 4.02 1.12 10.50
## 5       1 79.6 4.02 2.02  9.66
## 6       1 79.6 4.02 3.82  8.58

The columns that we will be interested in for our analysis are conc, Time, and Subject in the concentration data set and Dose, Time, and Subject for the dosing data set.

## By default it is groupedData; convert it to a data frame for use
my.conc <- PKNCAconc(as.data.frame(datasets::Theoph), conc~Time|Subject)

## Dosing data needs to only have one row per dose, so subset for
## that first.
d.dose <- unique(datasets::Theoph[datasets::Theoph$Time == 0,
                                  c("Dose", "Time", "Subject")])
d.dose
##     Dose Time Subject
## 1   4.02    0       1
## 12  4.40    0       2
## 23  4.53    0       3
## 34  4.40    0       4
## 45  5.86    0       5
## 56  4.00    0       6
## 67  4.95    0       7
## 78  4.53    0       8
## 89  3.10    0       9
## 100 5.50    0      10
## 111 4.92    0      11
## 122 5.30    0      12
my.dose <- PKNCAdose(d.dose, Dose~Time|Subject)

Merge the Concentration and Dose

After loading the data, they must be combined to prepare for parameter calculation. Intervals for calculation will automatically be selected based on the single.dose.aucs setting in PKNCA.options

my.data.automatic <- PKNCAdata(my.conc, my.dose)
PKNCA.options("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 FALSE
my.data.automatic$intervals
##    start end auclast aucall aumclast aumcall  cmax  cmin  tmax tlast
## 1      0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 2      0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 3      0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 4      0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 5      0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 6      0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 7      0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 8      0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 9      0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 10     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 11     0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 12     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 13     0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 14     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 15     0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 16     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 17     0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 18     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 19     0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 20     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 21     0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 22     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
## 23     0  24    TRUE  FALSE    FALSE   FALSE FALSE FALSE FALSE FALSE
## 24     0 Inf   FALSE  FALSE    FALSE   FALSE  TRUE FALSE  TRUE FALSE
##    tfirst clast.obs     f   cav ctrough   ptr  tlag half.life r.squared
## 1   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 2   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 3   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 4   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 5   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 6   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 7   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 8   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 9   FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 10  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 11  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 12  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 13  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 14  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 15  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 16  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 17  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 18  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 19  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 20  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 21  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 22  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE      TRUE     FALSE
## 23  FALSE     FALSE FALSE FALSE   FALSE FALSE FALSE     FALSE     FALSE
## 24  FALSE     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
## 3          FALSE    FALSE               FALSE             FALSE      FALSE
## 4          FALSE    FALSE               FALSE             FALSE      FALSE
## 5          FALSE    FALSE               FALSE             FALSE      FALSE
## 6          FALSE    FALSE               FALSE             FALSE      FALSE
## 7          FALSE    FALSE               FALSE             FALSE      FALSE
## 8          FALSE    FALSE               FALSE             FALSE      FALSE
## 9          FALSE    FALSE               FALSE             FALSE      FALSE
## 10         FALSE    FALSE               FALSE             FALSE      FALSE
## 11         FALSE    FALSE               FALSE             FALSE      FALSE
## 12         FALSE    FALSE               FALSE             FALSE      FALSE
## 13         FALSE    FALSE               FALSE             FALSE      FALSE
## 14         FALSE    FALSE               FALSE             FALSE      FALSE
## 15         FALSE    FALSE               FALSE             FALSE      FALSE
## 16         FALSE    FALSE               FALSE             FALSE      FALSE
## 17         FALSE    FALSE               FALSE             FALSE      FALSE
## 18         FALSE    FALSE               FALSE             FALSE      FALSE
## 19         FALSE    FALSE               FALSE             FALSE      FALSE
## 20         FALSE    FALSE               FALSE             FALSE      FALSE
## 21         FALSE    FALSE               FALSE             FALSE      FALSE
## 22         FALSE    FALSE               FALSE             FALSE      FALSE
## 23         FALSE    FALSE               FALSE             FALSE      FALSE
## 24         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
## 3       FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 4       FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 5       FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 6       FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 7       FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 8       FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 9       FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 10      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 11      FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 12      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 13      FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 14      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 15      FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 16      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 17      FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 18      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 19      FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 20      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 21      FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 22      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 23      FALSE  FALSE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
## 24      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
##      kel    vz Subject
## 1  FALSE FALSE       1
## 2  FALSE FALSE       1
## 3  FALSE FALSE       2
## 4  FALSE FALSE       2
## 5  FALSE FALSE       3
## 6  FALSE FALSE       3
## 7  FALSE FALSE       4
## 8  FALSE FALSE       4
## 9  FALSE FALSE       5
## 10 FALSE FALSE       5
## 11 FALSE FALSE       6
## 12 FALSE FALSE       6
## 13 FALSE FALSE       7
## 14 FALSE FALSE       7
## 15 FALSE FALSE       8
## 16 FALSE FALSE       8
## 17 FALSE FALSE       9
## 18 FALSE FALSE       9
## 19 FALSE FALSE      10
## 20 FALSE FALSE      10
## 21 FALSE FALSE      11
## 22 FALSE FALSE      11
## 23 FALSE FALSE      12
## 24 FALSE FALSE      12

Intervals for calculation can also be specified manually. Manual specification requires at least columns for start time, end time, and the parameters requested. The manual specification can also include any grouping factors from the concentration data set. Column order of the intervals is not important. When intervals are manually specified, they are expanded to the full interval set when added to a PKNCAdata object (in other words, a column is created for each parameter. Also, PKNCA automatically calculates parameters required for the NCA, so while lambda.z is required for calculating AUC0-\(\infinity\), you do not have to specify it in the parameters requested.

my.intervals <- data.frame(start=0,
                           end=Inf,
                           cmax=TRUE,
                           tmax=TRUE,
                           aucinf=TRUE,
                           auclast=TRUE)
my.data.manual <- PKNCAdata(my.conc, my.dose,
                            intervals=my.intervals)
my.data.manual$intervals
##   start end auclast aucall aumclast aumcall cmax  cmin tmax tlast tfirst
## 1     0 Inf    TRUE  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
##   adj.r.squared lambda.z lambda.z.time.first lambda.z.n.points clast.pred
## 1         FALSE    FALSE               FALSE             FALSE      FALSE
##   span.ratio aucinf aumcinf aucpext    cl   mrt   vss    vd thalf.eff
## 1      FALSE   TRUE   FALSE   FALSE FALSE FALSE FALSE FALSE     FALSE
##     kel    vz
## 1 FALSE FALSE

Compute the parameters

Parameter calculation will automatically split the data by the grouping factor(s), subset by the interval, calculate all required parameters, record all options used for the calculations, and include data provenance to show that the calculation was performed as described. For all this, just call the pk.nca function with your PKNCAdata object.

my.results.automatic <- pk.nca(my.data.automatic)
head(my.results.automatic$result)
##   start end Subject  PPTESTCD    PPORRES
## 1     0  24       1   auclast 92.3654416
## 2     0 Inf       1      cmax 10.5000000
## 3     0 Inf       1      tmax  1.1200000
## 4     0 Inf       1     tlast 24.3700000
## 5     0 Inf       1  lambda.z  0.0484570
## 6     0 Inf       1 r.squared  0.9999997
summary(my.results.automatic)
start end auclast cmax tmax half.life aucinf
0 24 74.6 [24.3] . . . .
0 Inf . 8.65 [17.0] 1.14 [0.630, 3.55] 8.18 [2.12] 115 [28.4]
my.results.manual <- pk.nca(my.data.manual)
head(my.results.manual$result)
##   start end Subject  PPTESTCD     PPORRES
## 1     0 Inf       1   auclast 147.2347485
## 2     0 Inf       1      cmax  10.5000000
## 3     0 Inf       1      tmax   1.1200000
## 4     0 Inf       1     tlast  24.3700000
## 5     0 Inf       1  lambda.z   0.0484570
## 6     0 Inf       1 r.squared   0.9999997
summary(my.results.manual)
start end auclast cmax tmax aucinf
0 Inf 98.7 [22.5] 8.65 [17.0] 1.14 [0.630, 3.55] 115 [28.4]