Simulated percentiles, with confidence bands, from a solved rxode2 object

Summarizes a solved object into the percentiles of the simulated values at each time and, when the simulation can support it, a confidence band around each of those percentiles.

Usage

# S3 method for class 'rxSolve'
confint(object, parm = NULL, level = 0.95, ...)

Arguments

object

solved rxode2 object

parm

compartments or calculated (lhs) variables to summarize; when NULL everything rxStack() returns is summarized

level

width of the interval taken over the simulated individuals, that is, which percentiles are reported at each time

...

other options:

ci – width of the confidence band placed around each percentile, defaulting to level. ci = FALSE (or 0) returns the percentiles with no band.
mean – when TRUE report the mean and its interval with meanProbs() instead of the empirical quantiles; mean = "binom" uses binomProbs() for a 0/1 variable.
by – character vector of extra columns of object to stratify by.
useT, pred – passed to meanProbs(); n, m, M, tol, pred, ciMethod – passed to binomProbs().
doSim – passed to rxStack().

Value

A data.frame (a tibble when tibble is present) with one row per time, endpoint and requested percentile. Without a band it is class rxSolveConfint1 with the percentile in p1 and its value in eff; with a band it is class rxSolveConfint2 with the percentile in p1 and the band in the p<lower>, p50 and p<upper> columns. Both carry a Percentile label used by plot().

Details

The percentiles are always taken over the simulated individuals; how (and whether) the band around them is obtained depends on the simulation:

ci = FALSE – no band; the pooled percentiles are returned.
nStud > 1 – the percentiles are computed within each study and the band is the quantile of those study-level percentiles. This is the meaningful case, since the studies differ by the thetaMat/omega uncertainty draw.
a single study of at least 2500 individuals – the individuals are split into round(sqrt(n)) sub-samples, and the band is the quantile of the sub-sample percentiles, that is, the sampling variability of the percentile itself. It does not include parameter uncertainty.
anything smaller – no band, with a message saying so.

When the solve was given a thetaMat, confint() also says whether that thetaMat was actually drawn from – it is ignored unless the variability is being simulated (nStud > 1, or simVariability=TRUE) – so it is clear whether the summarized values carry parameter uncertainty. This describes the simulated values, not the band: a solve can carry parameter uncertainty and still have no study dimension left to place a band with (nSub = 1, or ci = FALSE).

Author

Matthew L. Fidler

Examples


# \donttest{

mod <- function() {
  ini({
    tka <- 0.45
    tcl <- 1
    tv <- 3.45
    eta.cl ~ 0.1
    add.sd <- 0.7
  })
  model({
    ka <- exp(tka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv)
    d/dt(depot) <- -ka * depot
    d/dt(center) <- ka * depot - cl / v * center
    cp <- center / v
    cp ~ add(add.sd)
  })
}

ev <- et(amt=100) |> et(seq(0, 24, length.out=25))

# 100 individuals in one study: percentiles only
s <- rxSolve(mod, ev, nSub=100)
#>  
#>  
#> ℹ parameter labels from comments are typically ignored in non-interactive mode
#> ℹ Need to run with the source intact to parse comments
#>  
#>  

confint(s, "cp", level=0.95, ci=FALSE)
#> summarizing data...
#> done
#> # A tibble: 75 × 5
#>     time trt       p1   eff Percentile
#>    <dbl> <fct>  <dbl> <dbl> <chr>     
#>  1     0 cp    0.0250  0    2.5%      
#>  2     0 cp    0.5     0    50%       
#>  3     0 cp    0.975   0    97.5%     
#>  4     1 cp    0.0250  2.31 2.5%      
#>  5     1 cp    0.5     2.39 50%       
#>  6     1 cp    0.975   2.45 97.5%     
#>  7     2 cp    0.0250  2.51 2.5%      
#>  8     2 cp    0.5     2.71 50%       
#>  9     2 cp    0.975   2.85 97.5%     
#> 10     3 cp    0.0250  2.29 2.5%      
#> # ℹ 65 more rows

# with 20 studies the percentiles get a confidence band, and the
# `thetaMat` is drawn from
s2 <- rxSolve(mod, ev, nSub=100, nStud=20, thetaMat=lotri(tka ~ 0.01))
#>  
#>  
#> ℹ parameter labels from comments are typically ignored in non-interactive mode
#> ℹ Need to run with the source intact to parse comments

confint(s2, "cp", level=0.95)
#> ℹ this simulation drew from 'thetaMat', so the simulated values include parameter uncertainty
#> summarizing data...
#> done
#> # A tibble: 75 × 7
#>        p1  time trt    p2.5   p50 p97.5 Percentile
#>     <dbl> <dbl> <fct> <dbl> <dbl> <dbl> <fct>     
#>  1 0.0250     0 cp     0     0     0    2.5%      
#>  2 0.5        0 cp     0     0     0    50%       
#>  3 0.975      0 cp     0     0     0    97.5%     
#>  4 0.0250     1 cp     2.09  2.27  2.38 2.5%      
#>  5 0.5        1 cp     2.17  2.37  2.51 50%       
#>  6 0.975      1 cp     2.22  2.43  2.58 97.5%     
#>  7 0.0250     2 cp     2.36  2.40  2.47 2.5%      
#>  8 0.5        2 cp     2.58  2.67  2.71 50%       
#>  9 0.975      2 cp     2.73  2.82  2.87 97.5%     
#> 10 0.0250     3 cp     2.07  2.15  2.25 2.5%      
#> # ℹ 65 more rows

# }