centiles.boot {gamlss.foreach}

Bootstrapping centiles curves estimated using GAMLSS

Description

This is a function designed for non-parametric bootstrapping centile curves (growth curves) when the fitted model is fitted using GAMLSS with a single explanatory variable (usually age). Non parametric bootstrapping resample the data with replacement. The model is refitted for each bootstraps sample. Notes that if smoothing is used in the model, it is advisable (but not necessary) that the smoothing degree of freedom are fixed throughout.

Usage

centiles.boot(obj, data = NULL, xname = NULL, xvalues = NULL, 
  power = NULL, cent = c(2.5, 50, 97.5), B = 100, calibration = FALSE,
  ...)
             
## S3 method for class 'centiles.boot'
print(x, ...) 
## S3 method for class 'centiles.boot'
summary(object, fun = "mean", ...)              
## S3 method for class 'centiles.boot'
plot(x, quantiles = c(0.025, 0.975), 
       ylab = NULL, xlab = NULL, location = "median", original = FALSE, 
       scheme = c("shaded", "lines"), col.cent = "darkred", 
       col.se = "orange", col.shaded = "gray", lwd.center = 1.5, ...)  
             

Arguments

obj

a fitted gamlss object for the function centiles.boot()

data

a data frame containing the variables occurring in the formula. If it is missing, then it will try to get the data frame from the GAMLSS object

xname

the name (as character) of the unique explanatory variable (it has to be the same as in the original fitted model)

xvalues

a vector containing the new x-variable values for which bootstrap simulation predictions will be made

power

if power transformation is needed (but see example below)

cent

a vector of centile values for which the predicted centiles have to be evaluated, by default is: 2.5, 50 and 97.5

B

the number of bootstraps

calibration

whether to calibrate the centiles, default is FALSE

...

for extra arguments, for the centiles.pred() function

x

an a centiles.boot object

object

an a centiles.boot object

fun

for the summary() function this is a summary statistics function. The "mean" is the default

quantiles

specify which quantiles (in the plot() function) of the bootstrap distribution to plot

location

which location parameter to plot, with default the mean

original

logical if TRUE the original predicted centile values at the given xvalues are plotted (the default is FALSE)

ylab

y label for the plot

xlab

x label for the plot

scheme

which scheme of plotting to use "shaded" or "lines"

col.cent

the colour of the centile in the "shaded" scheme, with "darkred" as default

col.se

the colour of the standard errors for the "lines" scheme with default "orange"

col.shaded

the colour of the standard errors for the "shaded" scheme with default "gray"

lwd.center

the width of the central line

Details

This function is designed for bootstrapping centiles curves. It can be used to provide bootstrap means, standard deviations and quantiles, so the variability of the centile curves can be accessed (eg. by deriving confidence bands for centile curves).

Value

The function returns an object centile.boot which has its own print(), summary(), and plot() functions. The object centile.boot is a list with elements:

boot0

Containing centile predictions from the fitted model to the original data using the centile.pred() function on the new xvalues. This can be compared with the mean of the object to assess the bias

boot

A list of length trueB, each containing a matrix of dimension length(xvalues) by (length(cent)+1)

B

The number of bootstrap samples requested

trueB

The number of actual bootstrapping simulations performed. It is equal to B-number of failed simulations

xvalues

The new x-variable values for which the bootstrap simulation has taken place

cent

The centile values requested

original.call

The call of the original gamlss fitted model

yname

The name of the response variable, used in the plot() function

xname

The name of the x-variable, used in the plot() function

failed

A vector containing values identifying which of the bootstrap simulations had failed to converge and therefore have not included in the list boot

Note

See example below of how to use the function when a power transformation is used for the x-variable

Do not forget to use registerDoParallel(cores = NUMBER) or cl <- makeCluster(NUMBER) and registerDoParallel(cl) before calling the function centiles.boot(). Use closeAllConnections() after the fits to close the connections. Where NUMBER depends on the machine used.

Author(s)

Mikis Stasinopoulos, [e-mail], Bob Rigby [e-mail] and Calliope Akantziliotou

References

Rigby, R. A. and Stasinopoulos D. M. (2005). Generalized additive models for location, scale and shape, (with discussion), Appl. Statist., 54, part 3, pp 507-554.

Rigby, R. A., Stasinopoulos, D. M., Heller, G. Z., and De Bastiani, F. (2019) Distributions for modeling location, scale, and shape: Using GAMLSS in R, Chapman and Hall/CRC, doi:10.1201/9780429298547. An older version can be found in https://www.gamlss.com/.

Stasinopoulos D. M. Rigby R.A. (2007) Generalized additive models for location scale and shape (GAMLSS) in R. Journal of Statistical Software, Vol. 23, Issue 7, Dec 2007, doi:10.18637/jss.v023.i07.

Stasinopoulos D. M., Rigby R.A., Heller G., Voudouris V., and De Bastiani F., (2017) Flexible Regression and Smoothing: Using GAMLSS in R, Chapman and Hall/CRC. doi:10.1201/b21973

Stasinopoulos, M. D., Rigby, R. A., and De Bastiani F., (2018) GAMLSS: a distributional regression approach, Statistical Modelling, Vol. 18, pp, 248-273, SAGE Publications Sage India: New Delhi, India. doi:10.1177/1471082X18759144

(see also https://www.gamlss.com/).

See Also

gamlss,centiles,centiles.pred

Examples

# bring the data and fit the model
data(abdom) 
m1<-gamlss(y~poly(x,2), sigma.fo=~x, data=abdom, family=BCT)
# perform the bootstrap simulation 
# (only 10 bootstrap samples here)
registerDoParallel(cores = 2)
boC<-centiles.boot(m1,xname="x", xvalues=c(15,20,25,30,35,40,45), B=10)
stopImplicitCluster()
boC
# get summaries
summary(boC, fun="mean")
#summary(boC, "median")
#summary(boC, "quantile", 0.025)
plot(boC)

# with transformation in x within the formula
# unsuitable for large data set since it is slow
m2<-gamlss(y~cs(x^0.5),sigma.fo=~cs(x^0.5), data=abdom, family=BCT) 
boC<-centiles.boot(m2,xname="x", xvalues=c(15,20,25,30,35,40,45), B=10)
summary(boC)
plot(boC)
#
# now with x-variable previously transformed
# better for large data set as it is faster 
nx<-abdom$x^0.5
newd<-data.frame(abdom, nx=abdom$x^0.5)
m3<-gamlss(y~cs(nx),sigma.fo=~cs(nx), data=newd, family=BCT)
boC <- centiles.boot(m3, xname="nx", xvalues=c(15,20,25,30,35,40,45), data=newd, power=0.5, B=10)
summary(boC)
#plot(boC)
# the original variables can be added in
#points(y~x,data=abdom)