eefAnalytics"

Travis build status

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

DESCRIPTION

Package: eefAnalytics
Version: 1.0.11
Date: 2021-02-11
Title: Robust Analytical Methods for Evaluating Educational
        Interventions using Randomised Controlled Trials Designs
Description: Analysing data from evaluations of educational interventions using a randomised controlled trial design. Various analytical tools to perform sensitivity analysis using different methods are supported (e.g. frequentist models with bootstrapping and permutations options, Bayesian models). The included commands can be used for simple randomised trials, cluster randomised trials and multisite trials. The methods can also be used more widely beyond education trials. This package can be used to evaluate other intervention designs using Frequentist and Bayesian multilevel models.
Author: Germaine Uwimpuhwe, Akansha Singh, Steve Higgins, ZhiMin Xiao, Ewoud De Troyer and Adetayo Kasim
Maintainer: Germaine Uwimpuhwe <germaine.uwimpuhwe@durham.ac.uk>
Imports: lme4, mvtnorm, graphics, stats, rstanarm, ggplot2, methods
License: GPL-3
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.1.1
Suggests: knitr, rmarkdown, testthat
VignetteBuilder: knitr
URL: https://github.com/germaine86/eefAnalytics
BugReports: https://github.com/germaine86/eefAnalytics/issues

ComparePlot: A plot function to compare different eefAnalytics S3 objects from the eefAnalytics package.

Description

It generates bar plot that compares the effect size from eefAnalytics' methods.

Usage

ComparePlot(
  eefAnalyticsList,
  group,
  Conditional = TRUE,
  ES_Total = TRUE,
  modelNames
)

Arguments

Argument |Description ------------- |---------------- eefAnalyticsList | A list of eefAnalytics S3 objects from eefAnalytics package. group | a string/scalar value indicating which intervention to plot. This must be one of the values of intervention variable excluding the control group. For a two arm trial, the maximum number of values to consider is 1 and 2 for three arm trial. Conditional | a logical value to indicate whether to plot conditional effect size. The default is Conditional=TRUE, otherwise Conditional=FALSE should be specified for plot based on unconditional effect size. Conditional variance is total or residual variance a multilevel model with fixed effects, whilst unconditional variance is total variance or residual variance from a multilevel model with only intercept as fixed effect. ES_Total | A logical value indicating whether to plot the effect size based on total variance or within school variance. The default is ES_Total=TRUE, to plot effect size using total variance. ES_Total=FALSE should be specified for effect size based on within school or residuals variance. modelNames | a string factor containing the names of model to compare. See examples below.

Details

ComparePlot produces a bar plot which compares the effect sizes and the associated confidence intervals from the different models. For a multilevel model, it shows the effect size based on residual variance and total variance.

Value

Returns a bar plot to compare the different methods. The returned figure can be further modified as any ggplot

Examples

 data(mstData)
 ###############
 ##### SRT #####
 ###############

 outputSRT <- srtFREQ(Posttest~ Intervention + Prettest,
 intervention = "Intervention", data = mstData)

 outputSRTBoot <- srtFREQ(Posttest~ Intervention + Prettest,
 intervention = "Intervention",nBoot=1000, data = mstData)

 ###############
 ##### MST #####
 ###############

 outputMST <- mstFREQ(Posttest~ Intervention + Prettest,
 random = "School", intervention = "Intervention", data = mstData)

 outputMSTBoot <- mstFREQ(Posttest~ Intervention + Prettest,
 random = "School", intervention = "Intervention",
 nBoot = 1000, data = mstData)

 ##################
 ##### Bayesian #####
 ##################

 outputSRTbayes <- srtBayes(Posttest~ Intervention + Prettest,
 intervention = "Intervention",
 nSim = 2000, data = mstData)

 ## comparing different results

 ComparePlot(list(outputSRT,outputSRTBoot,outputMST,outputMSTBoot,outputSRTbayes),
 modelNames =c("ols", "olsBoot","MLM","MLMBoot","OLSBayes"),group=1)



 ``` 

# `crtBayes`: Bayesian analysis of cluster randomised education trials using Vague Priors.

## Description


 `crtBayes` performs analysis of cluster randomised education trials using a multilevel model under a Bayesian setting,
 assuming vague priors.


## Usage

```r
crtBayes(
  formula,
  random,
  intervention,
  baseln,
  adaptD,
  nsim = 2000,
  data,
  threshold = 1:10/10,
  ...
)

Arguments

Argument |Description ------------- |---------------- formula | the model to be analysed is of the form y ~ x1+x2+.... Where y is the outcome variable and Xs are the independent variables. random | a string variable specifying the "clustering variable" as contained in the data. See example below. intervention | a string variable specifying the "intervention variable" as appearing in the formula and the data. See example below. baseln | A string variable allowing the user to specify the reference category for intervention variable. When not specified, the first level will be used as a reference. adaptD | As this function uses rstanarm, this term provides the target average proposal acceptance probability during Stan’s adaptation period. Default is NULL. nsim | number of MCMC iterations per chain. Default is 2000. data | data frame containing the data to be analysed. threshold | a scalar or vector of pre-specified threshold(s) for estimating Bayesian posterior probability such that the observed effect size is greater than or equal to the threshold(s). ... | additional arguments of stan_lmer to be passed to the function.

Value

S3 object; a list consisting of

Examples

 data(crtData)

 ########################################################
 ## Bayesian analysis of cluster randomised trials     ##
 ########################################################

 output <- crtBayes(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",nsim=2000,data=crtData)

 ### Fixed effects
 beta <- output$Beta
 beta

 ### Effect size
 ES1 <- output$ES
 ES1

 ## Covariance matrix
 covParm <- output$covParm
 covParm

 ### plot random effects for schools

 plot(output)

 ### plot posterior probability of an effect size to be bigger than a pre-specified threshold

 plot(output,group=1)

 ``` 

# `crtData`: Cluster Randomised Trial Data.

## Description


 A cluster randomised trial dataset containing 22 schools. The data contains a random sample of test data of pupils and not actual trial data.


## Format


 A data frame with 265 rows and 5 variables


## Details




*  Posttest: posttest scores  

*  Prettest: prettest scores  

*  Intervention: the indicator for intervention groups in a two arm trial, coded as 1 for intervention group and 0 for control group.  

*  Intervention2: a simulated indicator for intervention groups in a three arm trial.  

*  School: numeric school identifier 


# `crtFREQ`: Analysis of Cluster Randomised Education Trials using Multilevel Model under a Frequentist Setting.

## Description


 `crtFREQ` performs analysis of cluster randomised education trials using a multilevel model under a frequentist setting.


## Usage

```r
crtFREQ(formula, random, intervention, baseln, nPerm, nBoot, seed, data)

Arguments

Argument |Description ------------- |---------------- formula | the model to be analysed is of the form y ~ x1+x2+.... Where y is the outcome variable and Xs are the independent variables. random | a string variable specifying the "clustering variable" as contained in the data. See example below. intervention | a string variable specifying the "intervention variable" as appearing in the formula and the data. See example below. baseln | A string variable allowing the user to specify the reference category for intervention variable. When not specified, the first level will be used as a reference. nPerm | number of permutations required to generate a permutated p-value. nBoot | number of bootstraps required to generate bootstrap confidence intervals. seed | seed required for bootstrapping and permutation procedure, if not provided default seed will be used. data | data frame containing the data to be analysed.

Value

S3 object; a list consisting of

Examples

 data(crtData)

 ########################################################
 ## MLM analysis of cluster randomised trials + 1.96SE ##
 ########################################################

 output1 <- crtFREQ(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",data=crtData)


 ### Fixed effects
 beta <- output1$Beta
 beta

 ### Effect size
 ES1 <- output1$ES
 ES1

 ## Covariance matrix
 covParm <- output1$covParm
 covParm

 ### plot random effects for schools

 plot(output1)

 ###############################################
 ## MLM analysis of cluster randomised trials ##
 ## with bootstrap confidence intervals       ##
 ###############################################

 output2 <- crtFREQ(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",nBoot=1000,data=crtData)


 ### Effect size

 ES2 <- output2$ES
 ES2

 ### plot bootstrapped values

 plot(output2, group=1)

 #######################################################################
 ## MLM analysis of cluster randomised trials with permutation p-value##
 #######################################################################

 output3 <- crtFREQ(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",nPerm=1000,data=crtData)

 ### Effect size

 ES3 <- output3$ES
 ES3


 ### plot permutated values

 plot(output3, group=1)

 ``` 

# `eefAnalytics-defunct`: Defunct functions in eefAnalytics

## Description


 These functions are marked as defunct and have been removed from eefAnalytics.

 These functions are marked as defunct and have been removed from eefAnalytics.

 These functions are marked as defunct and have been removed from eefAnalytics.

 These functions are marked as defunct and have been removed from eefAnalytics.


## Usage

```r
mlmbayes(...)
caceMSTBoot(...)
caceCRTBoot(...)
caceSRTBoot(...)

mstBayes: Bayesian analysis of Multisite Randomised Education Trials using Vague Priors.

Description

mstBayes performs analysis of multisite randomised education trials using a multilevel model under a Bayesian setting assuming vague priors.

Usage

mstBayes(
  formula,
  random,
  intervention,
  baseln,
  adaptD,
  nsim = 2000,
  data,
  threshold = 1:10/10,
  ...
)

Arguments

Argument |Description ------------- |---------------- formula | the model to be analysed is of the form y ~ x1+x2+.... Where y is the outcome variable and Xs are the independent variables. random | a string variable specifying the "clustering variable" as contained in the data. See example below. intervention | a string variable specifying the "intervention variable" as appearing in the formula and the data. See example below. baseln | A string variable allowing the user to specify the reference category for intervention variable. When not specified, the first level will be used as a reference. adaptD | As this function uses rstanarm, this term provides the target average proposal acceptance probability during Stan’s adaptation period. Default is NULL. nsim | number of MCMC iterations per chain. Default is 2000. data | data frame containing the data to be analysed. threshold | a scalar or vector of pre-specified threshold(s) for estimating Bayesian posterior probability that the observed effect size is greater than or equal to the threshold(s). ... | additional arguments of stan_lmer to be passed to the function.

Value

S3 object; a list consisting of

Examples

 data(mstData)

 ########################################################
 ## Bayesian analysis of cluster randomised trials     ##
 ########################################################

 output <- mstBayes(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",nsim=2000,data=mstData)

 ### Fixed effects
 beta <- output$Beta
 beta

 ### Effect size
 ES1 <- output$ES
 ES1

 ## Covariance matrix
 covParm <- output$covParm
 covParm

 ### plot random effects for schools

 plot(output)

 ### plot posterior probability of an effect size to be bigger than a pre-specified threshold

 plot(output,group=1)

 ``` 

# `mstData`: Multisite Trial Data.

## Description


 A multisite trial dataset containing 54 schools. This data contains a random sample of test data of pupils and not actual trial data.


## Format


 A data frame with 210 rows and 5 variables


## Details




*  Posttest: posttest scores  

*  Prettest: prettest scores  

*  Intervention: the indicator for the intervention groups in a two arm trial, coded as 1 for intervention group and 0 for control group.  

*  Intervention2: a simulated indicator for intervention groups in a three arm trial.  

*  School: numeric school identifier 


# `mstFREQ`: Analysis of Multisite Randomised Education Trials using Multilevel Model under a Frequentist Setting.

## Description


 `mstFREQ` performs analysis of multisite randomised education trials using a multilevel model under a frequentist setting.


## Usage

```r
mstFREQ(formula, random, intervention, baseln, nPerm, data, seed, nBoot)

Arguments

Argument |Description ------------- |---------------- formula | the model to be analysed is of the form y ~ x1+x2+.... Where y is the outcome variable and Xs are the independent variables. random | a string variable specifying the "clustering variable" as contained in the data. See example below. intervention | a string variable specifying the "intervention variable" as appearing in the formula and the data. See example below. baseln | A string variable allowing the user to specify the reference category for intervention variable. When not specified, the first level will be used as a reference. nPerm | number of permutations required to generate permutated p-value. data | data frame containing the data to be analysed. seed | seed required for bootstrapping and permutation procedure, if not provided default seed will be used. nBoot | number of bootstraps required to generate bootstrap confidence intervals.

Value

S3 object; a list consisting of

Examples

 data(mstData)

 ########################################################
 ## MLM analysis of multisite trials + 1.96SE ##
 ########################################################

 output1 <- mstFREQ(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",data=mstData)


 ### Fixed effects
 beta <- output1$Beta
 beta

 ### Effect size
 ES1 <- output1$ES
 ES1

 ## Covariance matrix
 covParm <- output1$covParm
 covParm

 ### plot random effects for schools

 plot(output1)

 ###############################################
 ## MLM analysis of multisite trials          ##
 ## with bootstrap confidence intervals       ##
 ###############################################

 output2 <- mstFREQ(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",nBoot=1000,data=mstData)

 tp <- output2$Bootstrap
 ### Effect size

 ES2 <- output2$ES
 ES2

 ### plot bootstrapped values

 plot(output2, group=1)

 #######################################################################
 ## MLM analysis of mutltisite trials with permutation p-value##
 #######################################################################

 output3 <- mstFREQ(Posttest~ Intervention+Prettest,random="School",
 intervention="Intervention",nPerm=1000,data=mstData)

 ES3 <- output3$ES
 ES3

 #### plot permutated values

 plot(output3, group=1)

 ``` 

# `plot.eefAnalytics`: A plot method for an eefAnalytics S3 object obtained from the eefAnalytics package.

## Description


 Plots different figures based on output from eefAnalytics package.


## Usage

```r
list(list("plot"), list("eefAnalytics"))(x, group, Conditional = TRUE, ES_Total = TRUE, slope = FALSE, ...)

Arguments

Argument |Description ------------- |---------------- x | an output object from the eefAnalytics package. group | a string/scalar value indicating which intervention to plot. This must be one of the values of intervention variable excluding the control group. For a two arm trial, the maximum number of values to consider is 1 and 2 for three arm trial. Conditional | a logical value to indicate whether to plot the conditional effect size. The default is Conditional=TRUE, otherwise Conditional=FALSE should be specified for plot based on the unconditional effect size. Conditional variance is total or residual variance from a multilevel model with fixed effects, whilst unconditional variance is total variance or residual variance from a multilevel model with only intercept as fixed effect. ES_Total | A logical value indicating whether to plot the effect size based on total variance or within school variance. The default is ES_Total=TRUE, to plot the effect size using total variance. ES_Total=FALSE should be specified for the effect size based on within school or residuals variance. slope | A logical value indicating whether to return the plot of random intercept (default is slope=FALSE). return other school-by-intervention interaction random slope (s) is slope=TRUE. This argument is suitable only for mstBayes and mstFREQ functions. ... | arguments passed to plot.default

Details

Plot produces a graphical visualisation depending on which model is fitted:

Value

Returns relevant plots for each model.

Examples

 #### read data
 data(mstData)
 data(crtData)


 ###############
 ##### SRT #####
 ###############

 ##### Bootstrapped

 outputSRTBoot <- srtFREQ(Posttest~ Intervention + Prettest,
 intervention = "Intervention",nBoot=1000, data = mstData)
 plot(outputSRTBoot,group=1)

 ##### Permutation
 outputSRTPerm <- srtFREQ(Posttest~ Intervention + Prettest,
 intervention = "Intervention",nPerm=1000, data = mstData)

 plot(outputSRTPerm,group=1)


 ###############
 ##### MST #####
 ###############


 #### Random intercepts
 outputMST <- mstFREQ(Posttest~ Intervention + Prettest,
 random = "School", intervention = "Intervention", data = mstData)
 plot(outputMST)


 #### Bootstrapped
 outputMSTBoot <- mstFREQ(Posttest~ Intervention + Prettest,
 random = "School", intervention = "Intervention",
 nBoot = 1000, data = mstData)

 plot(outputMSTBoot)
 plot(outputMSTBoot,group=1)

 #### Permutation
 outputMSTPerm <- mstFREQ(Posttest~ Intervention + Prettest,
 random = "School", intervention = "Intervention",
 nPerm = 1000, data = mstData)
 plot(outputMSTPerm)
 plot(outputMSTPerm,group=1)



 ###############
 ##### CRT #####
 ###############

 #### Random intercepts
 outputCRT <- crtFREQ(Posttest~ Intervention + Prettest, random = "School",
 intervention = "Intervention", data = crtData)
 plot(outputCRT)


 ## Bootstrapped
 outputCRTBoot <- crtFREQ(Posttest~ Intervention + Prettest, random = "School",
 intervention = "Intervention", nBoot = 1000, data = crtData)

 plot(outputCRTBoot,group=1)


 ##Permutation
 outputCRTPerm <- crtFREQ(Posttest~ Intervention + Prettest, random = "School",
 intervention = "Intervention", nPerm = 1000, data = crtData)

 plot(outputCRTPerm,group=1)

 ``` 

# `print.eefAnalytics`: Print for a fitted model represented by an `eefAnalytics` object.

## Description


 Print for a fitted model represented by an `eefAnalytics` object.


## Usage

```r
list(list("print"), list("eefAnalytics"))(x, ...)

Arguments

Argument |Description ------------- |---------------- x | Object of class eefAnalytics ... | Additional arguments of print

Value

Print conditional and unconditional effect sizes.

srtBayes: Analysis of Simple Randomised Education Trials using Bayesian Linear Regression Model with Vague Priors.

Description

srtBayes performs analysis of educational trials under the assumption of independent errors among pupils using Bayesian framework with Stan. This can also be used with schools as fixed effects.

Usage

srtBayes(
  formula,
  intervention,
  baseln,
  adaptD,
  nsim = 2000,
  data,
  threshold = 1:10/10,
  ...
)

Arguments

Argument |Description ------------- |---------------- formula | The model to be analysed is of the form y~x1+x2+.... Where y is the outcome variable and Xs are the independent variables. intervention | A string variable specifying the "intervention variable" as appearing in the formula and the data. See example below. baseln | A string variable allowing the user to specify the reference category for intervention variable. When not specified, the first level will be used as a reference. adaptD | As this function uses rstanarm, this term provides the target average proposal acceptance probability during Stan’s adaptation period. Default is NULL. nsim | A number of MCMC iterations per chain. Default is 2000. data | Data frame containing the data to be analysed. threshold | a scalar or vector of pre-specified threshold(s) for estimating Bayesian posterior probability such that the observed effect size is greater than or equal to the threshold(s). ... | Additional arguments of stan_lmer to be passed to the function.

Value

S3 object; a list consisting of

Examples

 data(mstData)

 ########################################################
 ## Bayesian analysis of cluster randomised trials     ##
 ########################################################

 output <- srtBayes(Posttest~ Intervention+Prettest,
 intervention="Intervention",nsim=2000,data=mstData)

 ### Fixed effects
 beta <- output$Beta
 beta

 ### Effect size
 ES1 <- output$ES
 ES1

 ## Covariance matrix
 covParm <- output$covParm
 covParm

 ### plot random effects for schools

 plot(output)

 ### plot posterior probability of an effect size to be bigger than a pre-specified threshold

 plot(output,group=1)

 ``` 

# `srtFREQ`: Analysis of Simple Randomised Education Trial using Linear Regression Model.

## Description


 `srtFREQ` performs analysis of educational trials under the assumption of independent errors among pupils.
 This can also be used with schools as fixed effects.


## Usage

```r
srtFREQ(formula, intervention, baseln, nBoot, nPerm, seed, data)

Arguments

Argument |Description ------------- |---------------- formula | the model to be analysed is of the form y~x1+x2+.... Where y is the outcome variable and Xs are the independent variables. intervention | a string variable specifying the "intervention variable" as appearing in the formula and the data. See example below. baseln | A string variable allowing the user to specify the reference category for intervention variable. When not specified, the first level will be used as a reference. nBoot | number of bootstraps required to generate bootstrap confidence intervals. nPerm | number of permutations required to generate permutated p-value. seed | seed required for bootstrapping and permutation procedure, if not provided default seed will be used. data | data frame containing the data to be analysed.

Value

S3 object; a list consisting of

Examples

 data(mstData)

 ###################################################################
 ## Analysis of simple randomised trials using Hedges Effect Size ##
 ###################################################################

 output1 <- srtFREQ(Posttest~ Intervention+Prettest,
 intervention="Intervention",data=mstData )
 ES1 <- output1$ES
 ES1

 ###################################################################
 ## Analysis of simple randomised trials using Hedges Effect Size ##
 ## with Permutation p-value                                      ##
 ###################################################################

 output2 <- srtFREQ(Posttest~ Intervention+Prettest,
 intervention="Intervention",nPerm=1000,data=mstData )

 ES2 <- output2$ES
 ES2


 #### plot permutated values

 plot(output2, group=1)



 ###################################################################
 ## Analysis of simple randomised trials using Hedges Effect Size ##
 ## with non-parametric bootstrap confidence intervals            ##
 ###################################################################

 output3 <- srtFREQ(Posttest~ Intervention+Prettest,
 intervention="Intervention",nBoot=1000,data=mstData)

 ES3 <- output3$ES
 ES3

 ### plot bootstrapped values

 plot(output3, group=1)

 ####################################################################
 ## Analysis of simple randomised trials using Hedges' effect size  ##
 ##  with schools as fixed effects                                  ##
 ####################################################################

 output4 <- srtFREQ(Posttest~ Intervention+Prettest+as.factor(School),
 intervention="Intervention",data=mstData )

 ES4 <- output4$ES
 ES4

 ####################################################################
 ## Analysis of simple randomised trials using Hedges' effect size ##
 ## with schools as fixed effects and with permutation p-value     ##
 ####################################################################

 output5 <- srtFREQ(Posttest~ Intervention+Prettest+as.factor(School),
 intervention="Intervention",nPerm=1000,data=mstData )

 ES5 <- output5$ES
 ES5

 #### plot permutated values

 plot(output5, group=1)

 ####################################################################
 ## Analysis of simple randomised trials using Hedges' effect size ##
 ## with schools as fixed effects and with permutation p-value      ##
 ####################################################################

 output6 <- srtFREQ(Posttest~ Intervention+Prettest+as.factor(School),
 intervention="Intervention",nBoot=1000,data=mstData)

 ES6 <- output6$ES
 ES6

 ### plot bootstrapped values

 plot(output6, group=1)

 ``` 

# `summary.eefAnalytics`: Summary for a fitted model represented by an `eefAnalytics` object.

## Description


 Summary for a fitted model represented by an `eefAnalytics` object.


## Usage

```r
list(list("summary"), list("eefAnalytics"))(object, ...)

Arguments

Argument |Description ------------- |---------------- object | Object of class eefAnalytics ... | Additional arguments of summary

Value

Returns relevant summary including Rhat and effective sample sizes.



Try the eefAnalytics package in your browser

Any scripts or data that you put into this service are public.

eefAnalytics documentation built on March 16, 2021, 5:08 p.m.