Skip to contents

Fits a Gaussian contrast likelihood with separate sampling and heterogeneity covariance. Effects are treatment_2 minus treatment_1. Studies are independent. The default is common-effect GLS; common heterogeneity induces equal pairwise heterogeneity variances and coherent multi-arm random effects.

Usage

network_meta_coherent(
  data,
  study_id,
  treatment_1,
  treatment_2,
  effect,
  variance,
  reference = NULL,
  heterogeneity = c("none", "common", "unstructured"),
  sampling_covariance = NULL,
  observation_id = NULL,
  covariance_repair = c("error", "roundoff"),
  outcome = NULL,
  time = NULL,
  treatment_effects = c("common", "by_outcome", "by_time", "by_outcome_time"),
  moderators = NULL,
  random_levels = NULL,
  tau2 = NULL,
  estimation_method = "REML",
  inference = c("model", "CR1"),
  diagnostics = TRUE,
  ci_level = 0.95,
  control = list(),
  assume_independent = FALSE,
  adjust = c("none", "holm", "bonferroni")
)

# S3 method for class 'nma_coherent'
predict(
  object,
  newdata,
  se.fit = FALSE,
  interval = c("none", "confidence", "prediction"),
  level = 0.95,
  new_levels = c("study", object$random_levels),
  treatment_1 = "treatment_1",
  treatment_2 = "treatment_2",
  ...
)

Arguments

data

Contrast data, one row per observation.

study_id, treatment_1, treatment_2, effect, variance

Column names for study, treatments, effect (treatment_2 minus treatment_1), and sampling variance.

reference

Network reference treatment; defaults to first sorted label. It need not occur in every study. Supplied basic-effect covariance must use this reference's coordinates. Printed models and summaries show treatment minus reference contrasts by default. Use comparisons="all" in print() or summary() to display every pair; all contrasts remain in $effects.

heterogeneity

One of none, common, or unstructured.

sampling_covariance

Named full matrix or named study blocks. With NULL, sampling errors are independent. Covariance dimension names are observation IDs.

observation_id

Column of unique observation IDs. Defaults to row numbers.

covariance_repair

error or roundoff; the latter clips only tiny negative eigenvalues. Singular matrices are rejected without a supplied independent contrast basis.

outcome, time

Optional columns defining outcome and time strata.

treatment_effects

One of common, by_outcome, by_time, by_outcome_time. Each stratum has its own treatment network.

moderators

Numeric covariate column names; effects are treatment interactions.

random_levels

Optional grouping columns for additional signed treatment random effects within studies. Crossed groups are allowed. Each group adds one common contrast variance; IDs are interpreted within study.

tau2

Fixed nonnegative variance(s), or a named basic-effect covariance matrix in the requested reference/stratum coordinates. NULL estimates variance.

estimation_method

ML or REML; MLE is accepted as ML.

inference

model or study-cluster sandwich CR1. CR1 uses a K/(K-1) adjustment and t reference with K-1 degrees of freedom; it is not CR2.

diagnostics

Compute design-by-treatment Wald incoherence tests with heterogeneity refitted by REML under the augmented model.

ci_level

Confidence level.

control

List with maxit and boundary_tol for optimization diagnostics.

assume_independent

Explicitly assume independent sampling errors for multiple observations within a study when covariance is unavailable. FALSE requires sampling covariance for such studies.

adjust

none, holm, or bonferroni for all unique treatment pairs across reported outcome/time strata. Intervals remain pointwise.

object

A fitted joint network model.

newdata

Prediction treatment pairs, strata and covariates.

se.fit

Return standard errors.

interval

None, confidence, or prediction for a true treatment contrast. Prediction-interval data frames use the compact display documented in network_prediction_intervals(); detailed=TRUE at print time shows all fields.

level

Prediction/confidence coverage.

new_levels

Grouping levels contributing variance for new random units. Omitted levels are fixed at zero; this is not a conditional BLUP prediction.

...

Reserved prediction arguments.

Value

An nma_coherent object also inheriting from nma_mars, with aligned sampling covariance, fitted covariance, coefficients, contrasts, and diagnostics. $design_incoherence contains cached design-by-treatment tests when requested. $incoherence retains the same design-test list for compatibility; use network_incoherence() explicitly for independent direct/indirect splits.

Details

Printed results include network counts, model settings and sampling-only Q/I-squared summaries. See network_model_summary for count definitions, diagnostic interpretation and reference/all-pair display selection.

Computational safeguards. Observation IDs must be unique and match covariance dimension names. The supplied covariance diagonal must agree with the variance column; variances must be finite and positive. Covariance is checked for symmetry, positive semidefiniteness and absence of cross-study dependence. The likelihood also rejects singular or numerically near-singular sampling covariance: redundant contrasts require a justified independent basis, not artificial diagonal noise. covariance_repair="roundoff" clips only tiny negative eigenvalues; it does not permit materially invalid or singular input.

The treatment/moderator design must have full column rank. A failure can indicate disconnected treatments or nonestimable mean strata/interactions. Before estimating heterogeneity, the covariance-kernel derivatives must be linearly independent, and residual observations must remain after estimating the means. These checks establish numerical/structural estimability, not precision of covariance estimates.

Inspect convergence$code, convergence$message, and convergence$boundary. Boundary flags mean a variance or covariance eigenvalue is near zero; this may be a supported zero-variance solution or weak information, rather than an error. Optimization success and valid input covariance do not establish transitivity, coherence of evidence, or correct scientific dependence assumptions. Use network_transitivity(), network_incoherence(), network_nodesplit(), and network_covariance_sensitivity() for the complementary assessments.

References

Lu, G., and Ades, A. E. (2004). Combination of direct and indirect evidence in mixed treatment comparisons. Statistics in Medicine, 23(20), 3105–3124. doi:10.1002/sim.1875 .

Higgins, J. P. T., Jackson, D., Barrett, J. K., Lu, G., Ades, A. E., and White, I. R. (2012). Consistency and inconsistency in network meta-analysis: concepts and models for multi-arm studies. Research Synthesis Methods, 3, 98–110. doi:10.1002/jrsm.1044 .

White, I. R., Barrett, J. K., Jackson, D., and Higgins, J. P. T. (2012). Consistency and inconsistency in network meta-analysis: model estimation using multivariate meta-regression. Research Synthesis Methods, 3, 111–125. doi:10.1002/jrsm.1045 .

White, I. R. (2015). Network meta-analysis. The Stata Journal, 15(4), 951–985. doi:10.1177/1536867X1501500403 .

Examples

dat <- data.frame(study = 1:6, a = rep(c("A", "A", "B"), 2),
                  b = rep(c("B", "C", "C"), 2),
                  yi = c(.2, .5, .3, .3, .6, .4), vi = .04)
fit <- network_meta_coherent(dat, "study", "a", "b", "yi", "vi")
coef(fit)
#>       d_B       d_C 
#> 0.2333333 0.5666667