The GLMMGibbs Package

Transcription

1 The GLMMGibbs Package April 22, 2002 Version Author Jonathan Myles and David Clayton Maintainer Jonathan Myles Depends R (>= 1.0) Date 2001/22/01 Title Generalised Linear Mixed Models by Gibbs Sampling Generalised Linear Mixed Models are an extension of Generalised Linear Models to include non-independent responses. This package allows them to be fitted by including functions for declaring factors to be random effects, for fitting models and generic functions for examining the fits. License GPL version 2 or later R topics documented: Ra ordinal.end bugs.out coda.object epil.bugs glmm model.init add.block plot.glmmfit print.glmmfit rtparse sampled.values scottish.lip.cancer seeds Index 12 1

2 2 Ra Ra Create Random Factor Create a random factor to be used in the glmm function for fitting generalised linear mixed models by Gibbs sampling Ra(data, shape=0.001, scale=0.001, type="identity", contrast="identity", map="none", zlevel=1, of.interest=false) data shape scale type type map of.interest The values of the factor which is to be declared random. The shape parameter of the gamma prior distribution to be placed on the hyperparameter. The scale parameter of the gamma prior distribution to be placed on the hyperparameter. The type of random effect. Current possible options are "identity" which creates an exchangeable random effect, "adj.map" which creates a spatially smoothed effect, assuming the levels to represent the values of the effect. The default value is "identity". A character string representing the way in which the factor is to be encoded in the model matrix. The possible values are "identity", which causes a dummy coding to be used, "treatment" which causes a coding which sets the first level of the factor to zero, sum which forces the effects to sum to zero, and helmert the S-plus default coding mechanism. If the factor is defined to be of type adj.map, the full path name to a file containing information about which levels of the factor represent adjacent regions, in a format described below. if TRUE, all values of each level of the effect are output during the keep phase of sampling (see the instructions for glmm below). If FALSE, only the sampled values of the hyperparameter are kept. Ra returns an a factor, which when included in the model passed to the glmm function, is treated as a random effect. The effect values have a multivariate normal prior with mean zero and a covariance matrix which depends on the type of random effect and the parameterisation being used. Its inverse is the product of a fixed matrix and a random scalar hyperparameter, which has a gamma prior distribution with given shape and scale parameters. Value Full details are given in the document GLMMGibbs: An R Package for Estimating Bayesian Generalised Linear Mixed Models by Gibbs Sampling, supplied with this package. A value of class factor, but with additional attributes.

3 ordinal.end 3 Note if the factor is set to be of type adj.map, the argument mapfile must be set to the name of a file which describes which areas are adjacent to which. The format of the file is as follows: each area should be assigned a number, and the file should then have successive lines representing the consecutive areas, each consisting of the number of neighbours of the area, followed by a colon, followed by the numbers of the neighbouring areas, followed by a Thus, for example, if area 1 has three neighbours, numbered 7, 11, and 12, the first line of the file should be: 3:7,11,12 Compare the file scotland.adj with the data given in the document GLMMGibbs: An R Package for Estimating Bayesian Generalised Linear Mixed Models by Gibbs Sampling, supplied with this package, for a further example. Author(s) Jonathan Myles, Imperial Cancer Research Fund, and David Clayton, Wellcome Trust mylesj@icrf.icnet.uk References Clayton, D.G. (1996) Generalized Linear Mixed Models in PhMarkov chain Monte Carlo in Practice, ed. Gilks, W. R. and Richardson, S. and and Spiegelhalter, D. J., Chapman & Hall. glmm ordinal.end The ordinal end of an expression An internal function of the GLMMGibbs package bugs.out Write Glmm Fit To Bugs Output Files bugs.out writes out the returned value from a call to the glmm function to two files, with extensions.ind and.out, in BUGS output format. bugs.out(g,file)

4 4 coda.object g file The result of a call to the glmm function, an object of class glmmfit. The primary filename of the files to which the the object is to be written. The sampled values and parameter names of the fitted model object are written to two files, "filemame.ind" and "filename.out", where "filename" is the value of the character object argument file. The format of these files is described in the section Using CODA and BOA with the output of glmm of the document GLMMGibbs: An R Package for Estimating Bayesian Generalised Linear Mixed Models by Gibbs Sampling, supplied with this package. Author(s) Jonathan Myles, Imperial Cancer Research Fund, and David Clayton, Wellcome Trust mylesj@icrf.icnet.uk glmm, plot.glmm, print.glmm coda.object Convert Glmm Output For Use With CODA Convert the result of a glmm fit for use with the CODA package rcoda.object(g) g The returned value from a call to the glmm function, an object of class glmmfit. Value CODA is a package which can be used to check the convergence of output produced by the BUGS program. The rcoda.object function converts an object returned by a call to the glmm into an object which can be used with the CODA package. The glmm function yielding g must have been called with the argument store.results set to TRUE. an object of class mcmc, which can be passed to functions in the CODA library Author(s) Jonathan Myles, Imperial Cancer Research Fund, and David Clayton, Wellcome Trust mylesj@icrf.icnet.uk

5 glmm 5 References glmm epil.bugs Results of a Clinical trial of Progadine The dataset describes the results of the pre-crossover phase of a crossover trial of the effects of progadine, an anti-epileptic drug. Patients were assigned blindly and at random to receive either the drug or a placebo in addition to standard chemotherapy. Each patient visited the trial centre on four subsequent occasions, on each of which the number of seizures in the previous two weeks was recorded. Also recorded was the patient s age, whether they were on treatment or placebo and the number of seizures suffered in the two-week period before the trial (known as the baseline seizures). The data is stored in the same format as in the BUGS example book data(epil.bugs) Format [,1] y numeric(236) number of seizures (one observation per visit) [,2] Trt numeric(59) whether the patient received Progadine (=1) or placebo (=0) (one observation per [,3] Base numeric(59) number of baseline seizures (one observation per patient) [,4] Age numeric(59) Age (one observation per patient) Source Thall, P. F. and Vail, S. C. 1990, Some covariance models for longitudinal count data with overdispersion Biometrics, pages , volume 46. glmm GLMMs By Gibbs Sampling glmm estimates the posterior distribution of the fixed effects of a Generalised Linear Mixed Model. It also estimates the hyperparameter related to each random effect, and the effect values of each random effect declared to be of interest by function Ra.

6 6 glmm glmm(formula, family, data, weights, offset, icm = 50, burnin = 1000, keep = 1000, model.show = FALSE, progress.info = 0, store.results = FALSE, thin = 1, bugsfile, seed1 = 6762, seed2 = 92928, seed3 = 19729) formula family data weights icm burnin keep thin model.show progress.info The model formula for the model to be fitted. A description of the error distribution and link function to be used. At present the available options are "binomial" and "poisson". The canonical link must always be used, so there is no link argument. The name of a data frame in which the data is stored. (at present, the function can only be used with the data in a data frame) A vector of weights. The number of steps of deterministic maximisation of the posterior distribution by the Iterative Conditional Mode algorithm before sampling begins. All hyperparameters are fixed to 1.0. The number of steps of Gibbs sampling taken before storage of the parameter values begins. The number of steps of Gibbs sampling taken once storage of the parameter values has begun. An integer t specifying that one storage of the parameter values has begun every (t) th iteration is saved A debugging argument used by he developers which will be deleted at the final release. If an integer, n say, the functions reports when every n iterations have been carried out bugsfile A character string. If not missing, the function creates two files, with this string their primary filenames and.ind and.out their secondary filenames (extensions).these contain the output in BUGS format. store.results seed1 seed2 seed3 Value if TRUE, returns the sampled values of the parameters (see Value below) The first of three seeds supplied to the Random Number Generator used by the underlying C code The second seed. The third seed. Generalised Linear Mixed Models (GLMMs) are an extension of GLMs with the addition of random effects given whose values the response values are conditionally independent. The function glmm fits these models in a Bayesian paradigm by Gibbs sampling. Full details are given in the document GLMMGibbs: An R Package for Estimating Bayesian Generalised Linear Mixed Models by Gibbs Sampling, supplied with this package. an object of class glmmfit, which contains the sample statistics of the sampled values and, if the store.results argument is set to TRUE, the sampled values themselves.

7 model.init 7 Note GLMMgibbs (the package from which glmm comes) is a beta release and we strongly recommend the use of save.image() before glmm() is used Author(s) Jonathan Myles, Imperial Cancer Research Fund, and David Clayton, Wellcome Trust mylesj@icrf.icnet.uk References Clayton, D.G. (1996) Generalized Linear Mixed Models in Markov chain Monte Carlo in Practice, ed. Gilks, W. R. and Richardson, S. and Spiegelhalter, D. J., Chapman & Hall. Ra, plot.glmm, print.glmm model.init Initialise a GLMM An internal function of the GLMMGibbs package add.block Add a block to a C Structure GLMM An internal function of the GLMMGibbs package plot.glmmfit Plot Result Of Glmm Fit Plot either the trace plots, the histograms, or both, of the sampled values for parameters of interest in a model fitted by glmm plot.glmmfit(g, parameters, type = "b", hscale = "b", plots.per.page = 4, postscript)

8 8 print.glmmfit g parameters type The result of a call to the glmm function, an object of class glmmfit. A vector of character strings giving names parameters in the model. If not missing, only sampled values for these parameters are plotted. If missing, sampled values for all parameters of interest are plotted. A character, determining which type of plot is given. If "t", "T", trace or Trace a trace plot is made. If "h", "H", "hist" or "Hist" a histogram is plotted. If "b", "B", "both" or "Both" both plots are made, side by side, with the trace plot on the left and the histogrm on the right. Default is "b". hscale A character, determining the scale on which scale sampled values of hyperparameter values are plotted. If "t", "T", "tau" or "Tau" sampled values are plotted on the tau scale. If "s", "S" "sigma" or "Sigma" values are plotted on the sigma scale. If "b", "B", "both" or "Both", sampled values are plotted on both scales. Default is "b". plots.per.page The number of variables plotted per page of output. Default is 4. postscript A character string. If it is not missing and takes the value "file", say, the output is written to files "file_page1.ps", "file_page2.ps", etc. The sampled values of some or all of the parameters of interest in a model fitted by the glmm function are plotted out. The parameters for which values are plotted, whether trace plots, histograms, or both are plotted, the scale on which hyperparameter values are plotted, the number of variables plotted per page and whether the plots are made to the screen or to postscript files are all decided by the arguments to the function Author(s) Jonathan Myles, Imperial Cancer Research Fund, and David Clayton, Wellcome Trust mylesj@icrf.icnet.uk glmm print.glmmfit Print Result Of Glmm Fit Print out information about a glmm fit. print.glmm(g) g The result of a call to the glmm function, an object of class glmmfit.

9 rtparse 9 The call made, the number of steps, and the sample statistics (mean, standard deviation, and 2.5, 25, 50, 75 and 97.5) of all the parameters of interest in the model are printed out. Sample statistics for hyperparameters are plotted on both the tau and sigma scales. Author(s) Jonathan Myles, Imperial Cancer Research Fund, and David Clayton, Wellcome Trust mylesj@icrf.icnet.uk glmm rtparse Parse a terms expression into blocks An internal function of the GLMMGibbs package sampled.values Sampled Values from a glmm fit Returns a vector consisting of the sampled values from an object returned from a call to the glmm function sampled.values(g,parameter.name) gthe result of a call to the glmm function, an object of class glmmfit. parameter.name The name of a parameter in the model The function takes and object g, the returned value of a call to the glmm function, and the name of a parameter in the model fitted, and returns a vector of the sampled values. The glmm function yielding g must have been called with the argument store.results set to TRUE. glmm

10 10 seeds scottish.lip.cancer Cases of Lip Cancer in Scottish Counties The number of cases of lip cancer registered in each of the 56 (pre-reoreganisation) counties of Scotland, together with the expected number of cases given the age-sex structure of the population and the percentege of workers employed in the agriculture, forestry and fishing industries. data(scottish.lip.cancer) Format [,1] observed numeric Number of oases [,2] expected numeric expected number of cases [,3] AFF numeric percentage of workers employed in AFF Source Breslow, N.E. and Clayton, D.G,. (1993) Approximate inference in generalized linear mixed models J. Amer. Statistical Association pages 9-25, volume 88 seeds Seeds germinating in a factorial experiment This data set gives the number of seeds germinating in different plates of a factorial experiment, together with the total number of seeds in each plate, the seed variety and the root type data(seeds) Format [,1] r numeric Number of seeds germinating [,2] n numeric Total number of seeds on plate [,3] x1 numeric seed variety, (0 = O. aegyptiaco 75, 1 = O. aegyptiaco 73) [,4] x2 numeric Root type (0 = bean, 1 = cucumber)

11 seeds 11 Source Crowder, M.J. (1978) Beta-Binomial ANOVA for Proportions Applied Statistics-J. Royal Statistical Soc. Series C page 34-37, volume 27

12 Index Topic datasets scottish.lip.cancer, 10 seeds, 10 Topic models add.block, 7 bugs.out, 3 coda.object, 4 glmm, 5 model.init, 7 ordinal.end, 3 plot.glmmfit, 7 print.glmmfit, 8 Ra, 1 rtparse, 9 sampled.values, 9 add.block, 7 bugs.out, 3 coda.object, 4 epil.bugs, 5 glmm, 3, 4, 5, 8, 9 model.init, 7 ordinal.end, 3 plot.glmm, 4, 7 plot.glmmfit, 7 print.glmm, 4, 7 print.glmmfit, 8 Ra, 1, 7 rtparse, 9 sampled.values, 9 scottish.lip.cancer, 10 seeds, 10 12