% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mvnma.R
\name{mvnma}
\alias{mvnma}
\alias{print.mvnma}
\title{Perform a Bayesian multivariate network meta-analysis using a
single-correlation coefficient model}
\usage{
mvnma(
  ...,
  reference.group = NULL,
  outclab = NULL,
  n.domain = NULL,
  n.chains = 4,
  n.iter = 10000,
  n.burnin = 2000,
  n.thin = max(1, floor((n.iter - n.burnin)/1000)),
  level = gs("level.ma"),
  scale.psi,
  lower.rho,
  upper.rho,
  method = "standard",
  quiet = FALSE
)

\method{print}{mvnma}(
  x,
  digits = gs("digits"),
  digits.sd = gs("digits.sd"),
  print.sd = FALSE,
  ...
)
}
\arguments{
\item{\dots}{Additional arguments (ignored)}

\item{reference.group}{A common reference treatment across all outcomes.}

\item{outclab}{An optional argument with labels for each outcome. If NULL,
the each outcome is labelled as 'outcome_1', 'outcome_2' etc.}

\item{n.domain}{Integer indicating the position of the last outcome in the 
first outcome domain (based on the order of the supplied pairwise objects). 
Used with `method = "DM"` to restrict information sharing within outcome 
domains. Ignored when `method = "standard"`. Default is `NULL`.}

\item{n.chains}{Number of Markov chains (default=4).}

\item{n.iter}{Number of iterations (default: 10000).}

\item{n.burnin}{Number of iterations for burn-in (default: 2000).}

\item{n.thin}{Thinning rate. Default is equal to
\code{max(1, floor((n.iter - n.burnin) / 1000))}.}

\item{level}{The level used to calculate confidence intervals
for network estimates.}

\item{scale.psi}{Values for the scale parameter(s) of the Half-Normal prior
used for the heterogeneity parameters within each outcome. If NULL, all
values are set to 1. If specified, it should have a length equal to the
number of outcomes.}

\item{lower.rho}{Lower bounds for the Uniform prior(s) used for the
correlation coefficient. If NULL all bounds are set to -1.}

\item{upper.rho}{Upper bounds for the Uniform prior(s) used for the
correlation coefficient. If NULL all bounds are set to 1.}

\item{method}{A character string specifying the method to be used for model
fitting. This can be either "standard" (default), referring to the
standard bivariate model, or "DM", referring to the bivariate model based
on the DuMouchel method. The argument can be abbreviated.}

\item{quiet}{A logical indicating whether to print information on the
progress of the JAGS model fitting.}

\item{x}{An object of class \code{\link{mvnma}}.}

\item{digits}{Minimal number of significant digits, see
\code{print.default}.}

\item{digits.sd}{Minimal number of significant digits for standard
deviations}

\item{print.sd}{A logical specifying whether standard deviations should be
printed.}
}
\value{
The function returns an 'mvnma' object. This consists of the results for each
outcome and the correlation coefficient estimates between the combined
outcomes. The outcome-specific estimates are expressed in the format of a
list (one for each outcome) which contains:
\itemize{
\item The basic estimates (i.e. treatment vs. reference.group) for each
  outcome.
\item The heterogeneity estimates for each outcome 
\item The posterior samples corresponding to the basic estimates.
}
}
\description{
This function fits a Bayesian multivariate network meta-analysis model.
Currently, the function can simultaneously pool up to five outcomes.
Additionally, the studies to be included should be of maximum three arms.
}
\details{
The multivariate network meta-analysis (mvNMA) model supported by this
package refers to the single correlation coefficient model, interpreted as
an amalgam of within- and across-outcome correlations
(Efthimiou et al., 2015) which is a generalisation of Riley et al. (2008).

The function \code{\link{mvnma}} expects two to five outcomes /
\code{\link[meta]{pairwise}} objects. A common reference treatment across
all outcomes is required to only show comparisons with the reference in
forest plots.

The Bayesian multivariate network meta-analysis model fitted in the
\bold{mvnma} package assumes uniform priors for the between-outcome
correlation coefficients. The lower and upper bounds of these priors can be
defined using the arguments `lower.rho` and `upper.rho`. If not set, the
model will assume a `Unif (-1, 1)` prior for all correlation coefficients.
For two outcomes, a single value can be provided for `lower.rho` and
`upper.rho`. For example, `lower.rho` = 0.5 and `upper.rho` = 1 for
rho12 ~ Unif (0.5, 1)).
For more than two outcomes, the order in which the bounds are provided
matters. For example, when pooling four outcomes, the lower and
upper bounds correspond to the following order of correlation coefficients:
(rho12, rho13, rho14, rho23, rho24, rho34).

Two types of priors for the treatment effect parameters are supported via 
the argument `method`. Setting `method = "standard"` fits an mvNMA model 
using non-informative normal priors (e.g., `N(0, 10^3)`).

Alternatively, `method = "DM"` specifies the DuMouchel prior, which assumes 
constant relative treatment effects across outcomes and enables information 
sharing (DuMouchel & Harris, 1983). This may improve precision but can
introduce bias when outcomes from different domains (e.g., efficacy and
safety) are analyzed jointly.

The argument `n.domain` can be used to restrict information sharing to 
predefined outcome domains. It indicates the position (based on the order 
of the supplied pairwise objects) of the last outcome in the first domain. 
For example, with four outcomes, setting `n.domain = 2` assigns the first 
two outcomes to one domain and the remaining outcomes to a second domain. 
In this case, information is shared only within domains.

By default, `n.domain = NULL`, in which case information is shared across 
all outcomes when `method = "DM"`. This may be appropriate when all outcomes 
belong to the same domain or when cross-domain sharing is justified.

The argument `n.domain` is ignored when `method = "standard"`.
}
\examples{
# Use 'pairwise' to obtain contrast based data for the first two outcomes

# Early response
pw1 <- pairwise(treat = list(treatment1, treatment2, treatment3),
  event = list(resp1, resp2, resp3), n = list(n1, n2, n3),
  studlab = id, data = Linde2015, sm = "OR")

# Early remissions
pw2 <- pairwise(treat = list(treatment1, treatment2, treatment3),
  event = list(remi1, remi2, remi3), n = list(n1, n2, n3),
  studlab = id, data = Linde2015, sm = "OR")

# Define outcome labels
outcomes <- c("Early_Response", "Early_Remission",
  "Adverse_events", "Loss_to_follow_up", "Loss_to_follow_up_AE")

# Fit the model combining only the two efficacy outcomes
# (note, we are using only 10 iterations and 2 burnins to reduce the
#  runtime of the example; in real applications use larger numbers)
set.seed(1910)
mvnma(pw1, pw2,
  reference.group = "Placebo", outclab = outcomes[1:2],
  n.iter = 10, n.burnin = 2)

\donttest{
# Use 'pairwise' to obtain contrast based data for the third to fifth
# outcome

# Adverse events
pw3 <- pairwise(treat = list(treatment1, treatment2,treatment3),
  event = list(ae1, ae2, ae3),  n = list(n1, n2, n3),
  studlab = id, data = Linde2015, sm = "OR")

# Loss to follow-up
pw4 <- pairwise(treat = list(treatment1, treatment2, treatment3),
  event = list(loss1, loss2, loss3), n = list(n1, n2, n3),
  studlab = id, data = Linde2015, sm = "OR")

# Loss_to_follow_up_(AE)
pw5 <- pairwise(treat = list(treatment1, treatment2, treatment3),
  event = list(loss.ae1, loss.ae2, loss.ae3), n = list(n1, n2, n3),
  studlab = id, data = Linde2015, sm = "OR")

# Fit the model combining only the two efficacy outcomes
# (note, we are using only 100 iterations and 20 burnins to reduce the
#  runtime of the example; in real applications use larger numbers)
set.seed(1909)
mvnma12 <- mvnma(pw1, pw2,
  reference.group = "Placebo", outclab = outcomes[1:2],
  n.iter = 100, n.burnin = 20)
mvnma12

# Extract treatment effect estimates and heterogeneity for Early_Response 
mvnma12$Early_Response$basic_estimates
mvnma12$Early_Response$heterogeneity

# Extract outcome correlation
mvnma12$cor

# Plot the results for efficacy outcomes
forest(mvnma12)

# Print odds ratios for efficacy outcomes
outc <- names(mvnma12)[names(mvnma12) != "cor"]
#
for (i in outc) {
  cat(paste0("\nOutcome: ", i, "\n\n"))
  print(round(exp(mvnma12[[i]]$TE.random), 2))
}

# Fit the model combining all five outcomes
# (note, we are using only 100 iterations and 20 burnins to reduce the
#  runtime of the example; in real applications use larger numbers)
set.seed(1904)
mvnma_all <- mvnma(pw1, pw2, pw3, pw4, pw5,
  reference.group = "Placebo", outclab = outcomes,
  n.iter = 100, n.burnin = 20)

# Extract treatment effect estimates and heterogeneity for Early_Response 
mvnma_all$Early_Response$basic_estimates
mvnma_all$Early_Response$heterogeneity      

# Extract outcome correlation 
mvnma_all$cor

# Plot the results for all outcomes
forest(mvnma_all)

# Print odds ratios for all outcomes
outc <- names(mvnma_all)[names(mvnma_all) != "cor"]
#
for (i in outc) {
  cat(paste0("\nOutcome: ", i, "\n\n"))
  print(round(exp(mvnma_all[[i]]$TE.random), 2))
}
}

}
\references{
DuMouchel WH, Harris JE (1983):
Bayes methods for combining the results of cancer studies in humans and
other species.
\emph{Journal of the American Statistical Association},
\bold{78}, 293--308

Efthimiou O, Mavridis D, Riley RD, Cipriani A, Salanti G (2015):
Joint synthesis of multiple correlated outcomes in networks of interventions.
\emph{Biostatistics}, 
\bold{16}, 84--97

Riley RD, Thompson JR, Abrams KR (2008):
An alternative model for bivariate random-effects meta-analysis when the
within-study correlations are unknown.
\emph{Biostatistics},
\bold{9}, 172--86
}
\seealso{
\code{\link[meta]{pairwise}}
}
