prctilemlx.R

---

Overview

Description

Compute and display percentiles of the empiricial distribution of longitudinal data.

Usage

prctilemlx(r,col=NULL, number=8, level=80, plot=TRUE, color="#9a35ff", group=NULL, facet=TRUE, labels=NULL, band=NULL)

Arguments

r

a data frame with a column id, a column time and a column with values. The times should be the same for each individual.

col

a vector with the three column indexes for id, time and y. Default = c(1, 2, 3).

number

the number of intervals (i.e. the number of percentiles minus 1).

level

the largest interval (i.e. the difference between the lowest and the highest percentile).

plot

if TRUE the empirical distribution is displayed, if FALSE values are returned in a data frame.

color

a color to be used for the plots (default=“#9a35ff”).

col

variable to be used for defining groups (by default, group is used when it exists).

facet

makes subplots for different groups if TRUE.

labels

vector of strings.

band

deprecated (use number and level instead) ; a list with fields number and level.

Value

If plot=TRUE: a ggplot object

If plot=FALSE: a list with fields

proba

a vector of probabilities of length band$number+1,

color

a vector of colors used for the plot of length band$number,

y

a data frame with the values of the empirical percentiles computed at each time point.

Examples

Some basic examples

We simulate longitudinal data for \(N=2000\) individuals using simulx

myModel <- inlineModel("
[LONGITUDINAL]
input = {ka, V, Cl}
EQUATION:
C = pkmodel(ka,V,Cl)

[INDIVIDUAL]
input = {ka_pop, V_pop, Cl_pop, omega_ka, omega_V, omega_Cl}
DEFINITION:
ka = {distribution=lognormal, reference=ka_pop, sd=omega_ka}
V  = {distribution=lognormal, reference=V_pop,  sd=omega_V }
Cl = {distribution=lognormal, reference=Cl_pop, sd=omega_Cl}
")

N=2000

pop.param   <- c(
  ka_pop  = 1,    omega_ka  = 0.5,
  V_pop   = 10,   omega_V   = 0.4,
  Cl_pop  = 1,    omega_Cl  = 0.3)
  
res <- simulx(model     = myModel,
              parameter = pop.param,
              treatment = list(time=0, amount=100),
              group     = list(size=N, level='individual'),
              output    = list(name='C', time=seq(0,24,by=0.5)))

## [INFO] The lixoftConnectors package has been successfully initialized:
## lixoftConnectors package version -> 2019.2
## Lixoft softwares suite version   -> 2019R2

res$C is a dataframe with \(2000 \times 241=482000\) rows and 3 columns

res$C[1:10,]

##    id time        C
## 1   1  0.0 0.000000
## 2   1  0.5 4.492849
## 3   1  1.0 6.635521
## 4   1  1.5 7.563427
## 5   1  2.0 7.867194
## 6   1  2.5 7.853903
## 7   1  3.0 7.683051
## 8   1  3.5 7.437336
## 9   1  4.0 7.159490
## 10  1  4.5 6.871459

we can compute and display the empirical percentiles of \(C\) using the default settings (i.e. percentiles of order 10%, 20%, … 90%)

p1   <- prctilemlx(res$C)
print(p1)

The 3 quartiles (i.e. percentiles of order 25%, 50% and 75%) are displayed by selecting a 50% interval splitted into 2 subintervals

p2 <- prctilemlx(res$C, number=2, level=50)
print(p2)

A one 90% interval can be displayed using only one interval

p3 <- prctilemlx(res$C, number=1, level=90)
print(p3)

or 75 subintervals in order to better represent the continuous distribution of the data within this interval

p4 <- prctilemlx(res$C, number=75, level=90)
print(p4)

A List of data frames is returned and the percentiles are not plotted by setting plot=FALSE

p5 <- prctilemlx(res$C, number=4, level=80, plot=FALSE)
print(names(p5))

## [1] "proba" "color" "y"

print(p5$proba)

## [1] 0.1 0.3 0.5 0.5 0.7 0.9

print(p5$color)

## [1] "#9A35FF33" "#9A35FF80" "#9A35FFFF" "#9A35FF80" "#9A35FF33"

print(p5$y[1:5,])

##   time      10%      30%      50%      50%      70%       90%
## 1  0.0 0.000000 0.000000 0.000000 0.000000 0.000000  0.000000
## 2  0.5 1.856938 2.864419 3.762692 3.762692 4.952836  7.288577
## 3  1.0 3.098585 4.496711 5.764983 5.764983 7.308034 10.269165
## 4  1.5 3.827213 5.444827 6.817854 6.817854 8.429400 11.225729
## 5  2.0 4.276883 5.905203 7.244816 7.244816 8.747637 11.347721

Using prctilemlx with groups

We now define 4 treatment groups:

Ng=400
g1 <- list(size=Ng, level='individual', treatment = list(time=0, amount=60))
g2 <- list(size=Ng, level='individual', treatment = list(time=0, amount=100))
g3 <- list(size=Ng, level='individual', treatment = list(time=3, amount=60))
g4 <- list(size=Ng, level='individual', treatment = list(time=3, amount=100))

t.out <- seq(0,24,by=0.5)
res <- simulx(model     = myModel,
              parameter = pop.param,
              group     = list(g1, g2, g3, g4),
              output    = list(name='C', time=t.out))

By default, column “group” is used - if it exists - to make subplots

labels <- c("60 mg - 0h ", "100 mg - 0h", "60 mg - 3h ", "100 mg - 3h")
resC <- res$C
prctilemlx(resC, label=labels) + theme(legend.position = "none")

facet_wrap is used by prctilemlx with the default settings to produce these subplots. These default settings can be modified using facet_wrap explicitely

prctilemlx(resC, label=labels) + theme(legend.position = "none")  + facet_wrap(~ group, nrow=1)

A single plot is produced with group=“none” as input argument

prctilemlx(resC, group="none") 

Covariates, such as the time of dose, or the dose amount can be added to the data frame resC and used as categorical covariates to define groups.

resC$doseTime <- 0
resC$doseTime[res$C$group %in% c(3,4)] <- 3
resC$doseAmount <- 60
resC$doseAmount[res$C$group %in% c(2,4)] <- 100

These covariates can now be used separately as factors to make subplots

prctilemlx(resC, group="doseAmount", labels=c("60 mg", "100 mg"))   + theme(legend.position = "none") 

prctilemlx(resC, group="doseTime", labels=c("0 h", "3 h"))  + 
  theme(legend.position = "none")