MBNMAtime (version 0.2.6)

mb.run: Run MBNMA time-course models

Description

Fits a Bayesian time-course model for model-based network meta-analysis (MBNMA) that can account for repeated measures over time within studies by applying a desired time-course function. Follows the methods of pedder2019;textualMBNMAtime.

Usage

mb.run(
  network,
  fun = tpoly(degree = 1),
  positive.scale = FALSE,
  intercept = NULL,
  link = "identity",
  sdscale = FALSE,
  parameters.to.save = NULL,
  rho = 0,
  covar = "varadj",
  corparam = FALSE,
  class.effect = list(),
  UME = FALSE,
  parallel = FALSE,
  priors = NULL,
  n.iter = 20000,
  n.chains = 3,
  n.burnin = floor(n.iter/2),
  n.thin = max(1, floor((n.iter - n.burnin)/1000)),
  pD = TRUE,
  model.file = NULL,
  jagsdata = NULL,
  ...
)

Value

An object of S3 class c("mbnma", "rjags")`` containing parameter results from the model. Can be summarized by print()and can check traceplots usingR2jags::traceplot()or various functions from the packagemcmcplots`.#'

If there are errors in the JAGS model code then the object will be a list consisting of two elements - an error message from JAGS that can help with debugging and model.arg, a list of arguments provided to mb.run()

which includes jagscode, the JAGS code for the model that can help users identify the source of the error.

Arguments

network

An object of class "mb.network".

fun

An object of class "timefun" generated (see Details) using any of tloglin(), tpoly(), titp(), temax(), tfpoly(), tspline() or tuser()

positive.scale

A boolean object that indicates whether all continuous mean responses (y) are positive and therefore whether the baseline response should be given a prior that constrains it to be positive (e.g. for scales that cannot be <0).

intercept

A boolean object that indicates whether an intercept (written as alpha in the model) is to be included. If left as NULL (the default), an intercept will be included only for studies reporting absolute means, and will be excluded for studies reporting change from baseline (as indicated in network$cfb).

link

Can take either "identity" (the default), "log" (for modelling Ratios of Means friedrich2011MBNMAtime) or "smd" (for modelling Standardised Mean Differences - although this also corresponds to an identity link function).

sdscale

Logical object to indicate whether to write a model that specifies a reference SD for standardising when modelling using Standardised Mean Differences. Specifying sdscale=TRUE will therefore only modify the model if link function is set to SMD (link="smd").

parameters.to.save

A character vector containing names of parameters to monitor in JAGS

rho

The correlation coefficient when modelling within-study correlation between time points. The default is a string representing a prior distribution in JAGS, indicating that it be estimated from the data (e.g. rho="dunif(0,1)"). rho also be assigned a numeric value (e.g. rho=0.7), which fixes rho in the model to this value (e.g. for use in a deterministic sensitivity analysis). If set to rho=0 (the default) then this implies modelling no correlation between time points.

covar

A character specifying the covariance structure to use for modelling within-study correlation between time-points. This can be done by specifying one of the following:

• "varadj" - a univariate likelihood with a variance adjustment to assume a constant correlation between subsequent time points jansen2015MBNMAtime. This is the default.

• "CS" - a multivariate normal likelihood with a compound symmetry structure

• "AR1" - a multivariate normal likelihood with an autoregressive AR1 structure

corparam

A boolean object that indicates whether correlation should be modeled between relative effect time-course parameters. Default is FALSE and this is automatically set to FALSE if class effects are modeled. Setting it to TRUE models correlation between time-course parameters. This can help identify parameters that are estimated poorly for some treatments by allowing sharing of information between parameters for different treatments in the network, but may also cause some shrinkage.

class.effect

A list of named strings that determines which time-course parameters to model with a class effect and what that effect should be ("common" or "random"). For example: list(emax="common", et50="random").

UME

Can take either TRUE or FALSE (for an unrelated mean effects model on all or no time-course parameters respectively) or can be a vector of parameter name strings to model as UME. For example: c("beta.1", "beta.2").

parallel

A boolean value that indicates whether JAGS should be run in parallel (TRUE) or not (FALSE). If TRUE then the number of cores to use is automatically calculated. Functions that involve updating the model (e.g. devplot(), fitplot()) cannot be used with models implemented in parallel.

priors

A named list of parameter values (without indices) and replacement prior distribution values given as strings using distributions as specified in JAGS syntax (see jagsmanual;textualMBNMAtime).

n.iter

number of total iterations per chain (including burn in; default: 20000)

n.chains

number of Markov chains (default: 3)

n.burnin

length of burn in, i.e. number of iterations to discard at the beginning. Default is n.iter/2``, that is, discarding the first half of the simulations. If n.burnin` is 0, jags() will run 100 iterations for adaption.

n.thin

thinning rate. Must be a positive integer. Set n.thin > 1`` to save memory and computation time if n.iteris large. Default ismax(1, floor(n.chains * (n.iter-n.burnin) / 1000))`` which will only thin if there are at least 2000 simulations.

pD

logical; if TRUE (the default) then adds the computation of pD, using the method of plummer2008MBNMAtime. If FALSE then uses the approximation of pD=var(deviance) / 2 (often referred to as pV).

model.file

The file path to a JAGS model (.jags file) that can be used to overwrite the JAGS model that is automatically written based on the specified options in MBNMAtime. Useful for adding further model flexibility.

jagsdata

A named list of the data objects to be used in the JAGS model. Only required if users are defining their own JAGS model using model.file. Format should match that of standard models fitted in MBNMAtime (see mbnma$model.arg$jagsdata)

...

Arguments to be sent to R2jags.

Time-course parameters

Nodes that are automatically monitored (if present in the model) have the same name as in the time-course function for named time-course parameters (e.g. emax). However, for named only as beta.1, beta.2, beta.3 or beta.4 parameters may have an alternative interpretation.

Details of the interpretation and model specification of different parameters can be shown by using the summary() method on an "mbnma" object generated by mb.run().

Parameters modelled using relative effects

• If pooling is relative (e.g. pool.1="rel") for a given parameter then the named parameter (e.g. emax) or a numbered d parameter (e.g. d.1) corresponds to the pooled relative effect for a given treatment compared to the network reference treatment for this time-course parameter.

• sd. followed by a named (e.g. emax, beta.1) is the between-study SD (heterogeneity) for relative effects, reported if pooling for a time-course parameter is relative (e.g. pool.1="rel") and the method for synthesis is random (e.g. method.1="random).

• If class effects are modelled, parameters for classes are represented by the upper case name of the time-course parameter they correspond to. For example if class.effect=list(emax="random"), relative class effects will be represented by EMAX. The SD of the class effect (e.g. sd.EMAX, sd.BETA.1) is the SD of treatments within a class for the time-course parameter they correspond to.

Parameters modelled using absolute effects

• If pooling is absolute (e.g. pool.1="abs") for a given parameter then the named parameter (e.g. emax) or a numbered beta parameter (e.g. beta.1) corresponds to the estimated absolute effect for this time-course parameter.

• For an absolute time-course parameter if the corresponding method is common (e.g. method.1="common") the parameter corresponds to a single common parameter estimated across all studies and treatments. If the corresponding method is random (e.g. method.1="random") then parameter is a mean effect around which the study-level absolute effects vary with SD corresponding to sd. followed by the named parameter (e.g. sd.emax, sd.beta.1) .

Other model parameters

• rho The correlation coefficient for correlation between time-points. Its interpretation will differ depending on the covariance structure specified in covar

• totresdev The residual deviance of the model

• deviance The deviance of the model

Time-course function

Several general time-course functions with up to 4 time-course parameters are provided, but a user-defined time-course relationship can instead be used. Details can be found in the respective help files for each function.

Available time-course functions are:

• Log-linear: tloglin()

• Polynomial: tpoly()

• Integrated Two-Component Prediction (ITP): titp()

• Emax: temax()

• Fractional polynomial: tfpoly()

• Splines (various spline types can be used): tspline()

• User-defined: tuser()

Correlation between observations

When modelling correlation between observations using rho, values for rho must imply a positive semidefinite covariance matrix.

Advanced options

model.file and jagsdata can be used to run an edited JAGS model and dataset. This allows users considerably more modelling flexibility than is possible using the basic MBNMAtime syntax, though requires strong understanding of JAGS and the MBNMA modelling framework. Treatment-specific priors, meta-regression and bias-adjustment are all possible in this way, and it allows users to make use of the subsequent functions in MBNMAtime (plotting, prediction, ranking) whilst fitting these more complex models.

References

Examples

# \donttest{
# Create mb.network object
network <- mb.network(osteopain)

# Fit a linear time-course MBNMA with:
# random relative treatment effects on the slope
mb.run(network, fun=tpoly(degree=1, pool.1="rel", method.1="random"))

# Fit an emax time-course MBNMA with:
# fixed relative treatment effects on emax
# a common parameter estimated independently of treatment
# a common Hill parameter estimated independently of treatment
# a prior for the Hill parameter (normal with mean 0 and precision 0.1)
# data reported as change from baseline
result <- mb.run(network, fun=temax(pool.emax="rel", method.emax="common",
                                    pool.et50="abs", method.et50="common",
                                    pool.hill="abs", method.hill="common"),
                 priors=list(hill="dunif(0.5, 2)"),
                 intercept=TRUE)


#### commented out to prevent errors from JAGS version in github actions build ####
# Fit a log-linear MBNMA with:
# random relative treatment effects on the rate
# an autoregressive AR1 covariance structure
# modelled as standardised mean differences
# copdnet <- mb.network(copd)
# result <- mb.run(copdnet, fun=tloglin(pool.rate="rel", method.rate="random"),
#                covar="AR1", rho="dunif(0,1)", link="smd")



####### Examine MCMC diagnostics (using mcmcplots package) #######

# Traceplots
# mcmcplots::traplot(result)

# Plots for assessing convergence
# mcmcplots::mcmcplot(result, c("rate", "sd.rate", "rho"))

########## Output ###########

# Print R2jags output and summary
print(result)
summary(result)

# Plot forest plot of results
plot(result)


###### Additional model arguments ######

# Use gout dataset
goutnet <- mb.network(goutSUA_CFBcomb)

# Define a user-defined time-course relationship for use in mb.run
timecourse <- ~ exp(beta.1 * time) + (time^beta.2)

# Run model with:
# user-defined time-course function
# random relative effects on beta.1
# default common effects on beta.2
# default relative pooling on beta.1 and beta.2
# common class effect on beta.2
mb.run(goutnet, fun=tuser(fun=timecourse, method.1="random"),
       class.effect=list(beta.1="common"))

# Fit a log-linear MBNMA
# with variance adjustment for correlation between time-points
result <- mb.run(network, fun=tloglin(),
                 rho="dunif(0,1)", covar="varadj")
# }