R: Run MBNMA time-course models

mb.run {MBNMAtime}

R Documentation

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 Pedder et al. (2019).

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",
  omega = NULL,
  corparam = FALSE,
  class.effect = list(),
  UME = FALSE,
  pd = "pv",
  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)),
  model.file = NULL,
  jagsdata = NULL,
  ...
)

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 (Friedrich et al. 2011)) 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 (Jansen et al. 2015). This is the default. `"CS"` - a multivariate normal likelihood with a compound symmetry structure `"AR1"` - a multivariate normal likelihood with an autoregressive AR1 structure
`omega`	DEPRECATED IN VERSION 0.2.3 ONWARDS (~uniform(-1,1) now used for correlation between parameters rather than a Wishart prior). A scale matrix for the inverse-Wishart prior for the covariance matrix used to model the correlation between time-course parameters (see Details for time-course functions). `omega` must be a symmetric positive definite matrix with dimensions equal to the number of time-course parameters modelled using relative effects (`pool="rel"`). If left as `NULL` (the default) a diagonal matrix with elements equal to 1 is used.
`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")`.
`pd`	Can take either: `pv` only pV will be reported (as automatically outputted by R2jags). `plugin` calculates pD by the plug-in method (Spiegelhalter et al. 2002). It is faster, but may output negative non-sensical values, due to skewed deviances that can arise with non-linear models. `pd.kl` (the default) calculates pD by the Kullback–Leibler divergence (Plummer 2008). This will require running the model for additional iterations but will always produce a sensical result. `popt` calculates pD using an optimism adjustment which allows for calculation of the penalized expected deviance (Plummer 2008)
`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 Plummer (2017)).
`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.iter`⁠is large. Default is⁠`max(1, floor(n.chains * (n.iter-n.burnin) / 1000))“ which will only thin if there are at least 2000 simulations.
`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.

Value

An object of S3 class ⁠c("mbnma", "rjags")`` containing parameter results from the model. Can be summarized by ⁠print()⁠and can check traceplots using⁠R2jags::traceplot()⁠or various functions from the package⁠mcmcplots‘.#’

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.

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

Friedrich JO, Adhikari NKJ, Beyene J (2011). “Ratio of means for analyzing continuous outcomes in meta-analysis performed as well as mean difference methods.” Journal of Clinical Epidemiology, 64(5), 556-564. doi:10.1016/j.jclinepi.2010.09.016.

Jansen JP, Vieira MC, Cope S (2015). “Network meta-analysis of longitudinal data using fractional polynomials.” Stat Med, 34(15), 2294-311. ISSN 1097-0258 (Electronic) 0277-6715 (Linking), doi:10.1002/sim.6492, https://pubmed.ncbi.nlm.nih.gov/25877808/.

Pedder H, Dias S, Bennetts M, Boucher M, Welton NJ (2019). “Modelling time-course relationships with multiple treatments: Model-Based Network Meta-Analysis for continuous summary outcomes.” Res Synth Methods, 10(2), 267-286.

Plummer M (2008). “Penalized loss functions for Bayesian model comparison.” Biostatistics, 9(3), 523-39. ISSN 1468-4357 (Electronic) 1465-4644 (Linking), https://pubmed.ncbi.nlm.nih.gov/18209015/.

Plummer M (2017). JAGS user manual. https://people.stat.sc.edu/hansont/stat740/jags_user_manual.pdf.

Spiegelhalter DJ, Best NG, Carlin BP, van der Linde A (2002). “Bayesian measures of model complexity and fit.” J R Statistic Soc B, 64(4), 583-639.

Examples


# 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")

[Package MBNMAtime version 0.2.4 Index]