R: Creating predictive centiles values

centiles.pred {gamlss} | R Documentation

## Creating predictive centiles values

### Description

This function creates predictive centiles curves for new x-values given a GAMLSS fitted model. The function has three options: i) for given new x-values and given percentage centiles calculates a matrix containing the centiles values for y, ii) for given new x-values and standard normalized centile values calculates a matrix containing the centiles values for y, iii) for given new x-values and new y-values calculates the z-scores. A restriction of the function is that it applies to models with only one explanatory variable.

### Usage

    centiles.pred(obj, type = c("centiles", "z-scores", "standard-centiles"),
                 xname = NULL, xvalues = NULL, power = NULL, yval = NULL,
                 cent = c(0.4, 2, 10, 25, 50, 75, 90, 98, 99.6),
                 dev = c(-4, -3, -2, -1, 0, 1, 2, 3, 4),
                 plot = FALSE, legend = TRUE,
                 ...)

### Arguments

`obj` | a fitted gamlss object from fitting a gamlss continuous distribution
`type` | the default, "centiles", gets the centiles values given in the option `cent`. `type="standard-centiles"` gets the standard centiles given in the `dev`. `type="z-scores"` gets the z-scores for given y and x new values
`xname` | the name of the unique explanatory variable (it has to be the same as in the original fitted model)
`xvalues` | the new values for the explanatory variable where the prediction will take place
`power` | if power transformation is needed (but read the note below)
`yval` | the response values for a given x required for the calculation of "z-scores"
`cent` | a vector with elements the % centile values for which the centile curves have to be evaluated
`dev` | a vector with elements the standard normalized values for which the centile curves have to be evaluated in the option `type="standard-centiles"`
`plot` | whether to plot the "centiles" or the "standard-centiles", the default is `plot=FALSE`
`legend` | whether a legend is required in the plot or not, the default is `legent=TRUE`
`...` | for extra arguments

### Value

a vector (for option `type="z-scores"`) or a matrix for options `type="centiles"` or `type="standard-centiles"` containing the appropriate values

### Warning

See example below of how to use the function when power transofrmation is used for the x-variables

### Note

The power option should be only used if the model

### Author(s)

Mikis Stasinopoulos , mikis.stasinopoulos@gamlss.org, based on ideas of Elaine Borghie from the World Health Organization

### 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.

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, http://www.jstatsoft.org/v23/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.

(see also http://www.gamlss.org/).

### See Also

`gamlss`, `centiles`, `centiles.split`

### Examples

    ## bring the data and fit the model
    data(abdom)
    a<-gamlss(y~pb(x),sigma.fo=~pb(x), data=abdom, family=BCT)
    ## plot the centiles
    centiles(a,xvar=abdom$x)
    ##-----------------------------------------------------------------------------
    ## first use of  centiles.pred()
    ## to calculate the centiles at new x values
    ##-----------------------------------------------------------------------------
    newx<-seq(12,40,2)
    mat <- centiles.pred(a, xname="x", xvalues=newx )
    mat
    ## now plot the centile curves
     mat <- centiles.pred(a, xname="x",xvalues=newx, plot=TRUE )
    ##-----------------------------------------------------------------------------
    ## second use of centiles.pred()
    ## to calculate (nornalised) standard-centiles for new x
    ## values using the fitted model
    ##-----------------------------------------------------------------------------
    newx <- seq(12,40,2)
    mat <- centiles.pred(a, xname="x",xvalues=newx, type="standard-centiles" )
    mat
    ## now plot the standard centiles
    mat <- centiles.pred(a, xname="x",xvalues=newx, type="standard-centiles",
           plot = TRUE )
    ##-----------------------------------------------------------------------------
    ## third use of centiles.pred()
    ##  if we have new x and y values what are their z-scores?
    ##-----------------------------------------------------------------------------
    # create new y and x values and plot them in the previous plot
    newx <- c(20,21.2,23,20.9,24.2,24.1,25)
    newy <- c(130,121,123,125,140,145,150)
    for(i in 1:7) points(newx[i],newy[i],col="blue")
    ## now calculate their z-scores
    znewx <- centiles.pred(a, xname="x",xvalues=newx,yval=newy, type="z-scores" )
    znewx
    ## Not run:
    ##-----------------------------------------------------------------------------
    ## What we do if the x variables is transformed?
    ##----------------------------------------------------------------------------
    ##  case 1 : transformed x-variable within the formula
    ##----------------------------------------------------------------------------
    ## fit model
    aa <- gamlss(y~pb(x^0.5),sigma.fo=~pb(x^0.5), data=abdom, family=BCT)
    ## centiles works
    centiles(aa,xvar=abdom$x, legend = FALSE)
    newx<-seq(12,40,2)
    mat <- centiles.pred(aa, xname="x",xvalues=newx, plot=TRUE )

    mat <- centiles.pred(aa, xname="x",xvalues=c(20, 2 )
    mat
    xx <- rep(mat[,1],9)
    yy<-mat[,2:10]
    points(xx,yy,col="red")
    ## case 2 : x-variable previously transformed
    nx<-abdom$x^0.5
    aa<-gamlss(y~pb(nx),sigma.fo=~pb(nx), data=abdom, family=BCT)
    centiles(aa, xvar=abdom$x)
    newd<-data.frame( abdom, nx=abdom$x^0.5)
    mat <-  centiles.pred(aa, xname="nx", xvalues=c(30), power=0.5, data=newd)
    xxx<-rep(mat[,1],9)
    yyy<-mat[,2:10]
    points(xxx,yyy,col="red")
    ## End(Not run)

[Package gamlss version 5.0-2 Index]