
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

                        Computer code corresponding to:

     Second term improvement to generalised linear mixed model asymptotics

                  by L. Maestrini, A. Bhaskaran and M.P. Wand

                          Last changed: 31 OCT 2023

""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

The R language script

   MBWinferenceExample.R

illustrates statistical inference, via approximate confidence intervals, for 
generalised linear mixed models based on the two-term asymptotic covariance 
results of Maestrini, Bhaskaran & Wand. The script is supported by files 
containing R functions and the R package "stipkg", which contains C++ code via 
the R packages "Rcpp" and "RcppArmadillo". Several other R packages are used by
MBWinferenceExample.R.

   The full instructions for running the illustrative script are:

   1. In an R session issue the command:

      install.packages(c("cubature","devtools","doParallel","glmmTMB","MASS",
                       "matrixcalc","parallel","Rcpp","RcppArmadillo"))

   2. Set the working directory of the R session to be the directory immediately 
      above the directory "stipkg". For example, if the full path name of the 
      "stipkg" directory is "/abc/def/stipkg" then the R working directory 
      should be set to "/abc/def".

   3. Issue the R commands:

      system("R CMD build stipkg")
      system("R CMD INSTALL stipkg_1.0.tar.gz")

   4. Issue the R command: source("MBWinferenceExample.R")

   The R language script

   powSSexamp.R

provides an example of a power sample size computation involving a 
Poisson-response mixed model.

   The following table summarises all files of the computer code bundle:

--------------------------------------------------------------------------------
   file name                            description 
--------------------------------------------------------------------------------

covParmsCIs1TermLogis.r              R function for obtaining natural 1-term 
                                     confidence intervals for the standard 
                                     deviation and correlation parameters of the 
                                     random effects for binary-logistic 
                                     generalised linear mixed models with 
                                     bivariate random effects.

covParmsCIs2TermLogis.r              R function for obtaining natural 2-term 
                                     confidence intervals for the standard 
                                     deviation and correlation parameters of the 
                                     random effects for binary-logistic 
                                     generalised linear mixed models with 
                                     bivariate random effects.

generExampData.r                     R function for generation of example 
                                     generalized linear mixed model data.

graphicCompareCIs.r                  R function for plotting confidence 
                                     intervals of fixed effects parameters and 
                                     standard deviation and correlation 
                                     components from the random effects 
                                     covariance matrix. The confidence intervals 
                                     obtained via the Maestrini, Bhaskaran & 
                                     Wand theory are compared with those 
                                     obtained using Theorem 1 of Jiang, Wand & 
                                     Bhaskaran (2022, JRSSB) and the 'glmmTMB' 
                                     package.

MBWinferenceExample.R                R script for computing confidence intervals 
                                     for fixed effects parameters and standard
                                     deviation and correlation parameters from 
                                     the random effects covariance matrix in 
                                     logistic generalized linear mixed models 
                                     with bivariate random effects. Confidence 
                                     intervals based on the theory of Maestrini, 
                                     Bhaskaran & Wand are obtained through the 
                                     function TwoTermAsyCov() and compared with 
                                     those from Jiang, Wand & Bhaskaran (2022, 
                                     JRSSB) produced using OneTermAsyCov() and 
                                     those from the 'glmmTMB' package. Graphical 
                                     comparison of the confidence intervals is 
                                     performed via the function 
                                     graphicCompareCIs().

OneTermAsyCov.r                      R function for estimating the one-term 
                                     asymptotic covariance of the beta parameter 
                                     vector and Sigma covariance matrix for 
                                     logistic generalized linear mixed models,
                                     based on the asymptotic normality theorem 
                                     of Jiang, Wand & Bhaskaran (2022, JRSSB).

stipkg (directory)                   R package containing C++ functions to 
                                     obtain the threee-dimensional arrays
                                     Omega_{AAA}' and Omega_{AAB}', and to 
                                     compute the star product between a 
                                     three-dimensional array and a matrix,
                                     as defined in Maestrini, Bhaskaran & Wand. 

powSSexamp.R                         R script for doing an example of a power 
                                     sample sizecomputation involving a 
                                     Poisson-response mixed model with a random 
                                     intercept and a random slope where dR=dF.

TwoTermAsyCov.r                      R function for estimating the two-term 
                                     asymptotic covariance of the beta_A and 
                                     beta_B parameter vectors and Sigma matrix 
                                     for logistic generalized linear mixed 
                                     models based on the results of Maestrini, 
                                     Bhaskaran & Wand.

vechInverse.r                        R function for obtaining the inverse 
                                     vecorisation-half of a vector.

vecInverse.r                         R function for obtaining the inverse 
                                     vectorisation of a matrix.

--------------------------------------------------------------------------------


                                ---o---O---o---
                                    