Skip to contents

Choosing the model

All three network_meta() interfaces fit basic treatment effects jointly under coherence: coherent for standard NMA, multivariate for a joint basic-effect covariance, and multilevel for signed treatment deviations at additional grouping levels. Sampling covariance is separate from heterogeneity. network_meta_coherent() exposes the common engine directly.

In the coherent model, heterogeneity="none" means zero between-study variation. "common" estimates one common pairwise contrast variance, not a common effect. "unstructured" estimates a basic-treatment covariance matrix when the observed covariance design identifies its parameters. A named matrix in tau2 fixes that matrix; it must use the chosen reference coordinates.

Each observation is an effect of treatment_2 minus treatment_1. Its unique ID matches the names in a supplied sampling covariance matrix. Studies are independent. Missing requested values produce an error: subset both data and covariance before fitting. A singular covariance requires a scientifically valid independent contrast basis; the software does not silently add diagonal noise or discard SMDs.

Common effects with supplied covariance

d <- data.frame(id=letters[1:6], study=rep(1:3,each=2),
                a="A", b=rep(c("B","C"),3),
                g=c(.2,.5,.4,.8,.3,.6),v=.04)
S <- diag(d$v)
dimnames(S) <- list(d$id,d$id)
for(i in c(1,3,5)) S[i,i+1] <- S[i+1,i] <- .015
fit <- network_meta_coherent(d,"study","a","b","g","v",
           observation_id="id",sampling_covariance=S)
fit$effects
#>   treatment_1 treatment_2     total  total_se  df total_ci_lower total_ci_upper
#> 1           A           B 0.3000000 0.1154701 Inf     0.07368285      0.5263171
#> 2           A           C 0.6333333 0.1154701 Inf     0.40701619      0.8596505
#> 3           B           C 0.3333333 0.1290994 Inf     0.08030307      0.5863636
#>   total_df    direct direct_se  indirect indirect_se direct_indirect_covariance
#> 1      Inf 0.3000000 0.1154701        NA          NA                         NA
#> 2      Inf 0.6333333 0.1154701        NA          NA                         NA
#> 3      Inf        NA        NA 0.3333333   0.1290994                         NA
#>   incoherence_factor if_se direct_n_effects direct_n_studies direct_ci_lower
#> 1                 NA    NA                3                3      0.07368285
#> 2                 NA    NA                3                3      0.40701619
#> 3                 NA    NA                0                0              NA
#>   direct_ci_upper indirect_ci_lower indirect_ci_upper total_p_value
#> 1       0.5263171                NA                NA  9.374768e-03
#> 2       0.8596505                NA                NA  4.138729e-08
#> 3              NA        0.08030307         0.5863636  9.823275e-03
#>   total_p_adjusted
#> 1     9.374768e-03
#> 2     4.138729e-08
#> 3     9.823275e-03

The diagonal entries are sampling variances, while the off-diagonals describe sampling dependence. Alternatively, pass a list of study matrices named by study ID. Row and column order is matched by observation ID. model_type="wls" with explicit covariance uses this same GLS engine, including its covariance-aware inference. Every interface uses the same sampling-covariance validation.

For study i, the likelihood is

g_i \sim N(X_i\beta,S_i+Z_iGZ_i^\top).

Here g_i is the vector of observed SMDs, X_i is the fixed-effect design, \beta contains average treatment coefficients, S_i is the sampling covariance, Z_i maps latent random effects to observations, and G is their covariance. Sampling errors are independent of random effects. With zero heterogeneity, G=0. The GLS coefficient covariance conditions on the supplied S_i.

Coherent heterogeneity

random_fit <- network_meta_coherent(d,"study","a","b","g","v",
           observation_id="id",sampling_covariance=S,heterogeneity="common")
random_fit$heterogeneity_summary
#> $tau2
#>       component tau2
#> study     study    0
#> 
#> $covariance
#> NULL
#> 
#> $boundary
#> [1] TRUE
network_prediction_intervals(random_fit)
#> Network prediction intervals (95%)
#> Question: What true treatment effect could occur in new random units?
#> Prediction intervals are descriptive; no additional null-hypothesis test.
#> Prediction target: New study
#> Added prediction variance (tau2_prediction): 0.0000000
#> Degrees of freedom: Inf
#> se = uncertainty in the average effect; prediction_se includes added variance.
#> lower/upper = prediction limits.
#> 
#>  contrast  estimate        se prediction_se     lower     upper
#>     B - A 0.3000000 0.1154701     0.1154701 0.0736829 0.5263171
#>     C - A 0.6333333 0.1154701     0.1154701 0.4070162 0.8596505
#>     C - B 0.3333333 0.1290994     0.1290994 0.0803031 0.5863636

For basic treatment effects B versus A and C versus A, common contrast heterogeneity uses \Omega=\tau^2\left(\begin{smallmatrix}1&1/2\\1/2&1\end{smallmatrix}\right), where \tau^2 is the between-study variance of every pairwise treatment contrast. The resulting variance of C versus B is also \tau^2. The one-half factor is unrelated to the sampling correlation in S.

A supplied covariance gives contrast-specific prediction variances:

Omega <- matrix(c(.04,.01,.01,.09),2,
                dimnames=list(c("d_B","d_C"),c("d_B","d_C")))
flexible <- network_meta_coherent(d,"study","a","b","g","v",
            observation_id="id",sampling_covariance=S,
            heterogeneity="unstructured",tau2=Omega)
network_prediction_intervals(flexible)
#> Network prediction intervals (95%)
#> Question: What true treatment effect could occur in new random units?
#> Prediction intervals are descriptive; no additional null-hypothesis test.
#> Prediction target: New study
#> Degrees of freedom: Inf
#> se = uncertainty in the average effect; prediction_se includes added variance.
#> lower/upper = prediction limits.
#> 
#>  contrast  estimate        se prediction_se      lower     upper
#>     B - A 0.3000000 0.1632993     0.2581989 -0.2060605 0.8060605
#>     C - A 0.6333333 0.2081666     0.3651484 -0.0823443 1.3490110
#>     C - B 0.3333333 0.2309401     0.4041452 -0.4587767 1.1254433
#>  tau2_prediction
#>        0.0400000
#>        0.0900000
#>        0.1100000

Prediction intervals describe a true contrast in a new study, at the specified moderators and stratum. They add its heterogeneity variance to coefficient uncertainty, not the sampling variance of a future measured effect. With additional random levels they describe a new unit at each specified level.

Shared-control Hedges SMDs

arms <- data.frame(study=rep(1:3,each=3),
                   treatment=rep(c("A","B","C"),3),
                   mean=c(0,.4,.7,0,.5,.6,0,.3,.8),sd=1,n=50)
smd <- network_smd_data(arms,"study","treatment","mean","sd","n")
smd$data
#>   study_id treatment_1 treatment_2    effect outcome    time denominator_df
#> 1        1           A           B 0.3969296 overall overall             98
#> 2        1           A           C 0.6946269 overall overall             98
#> 3        2           A           B 0.4961620 overall overall             98
#> 4        2           A           C 0.5953945 overall overall             98
#> 5        3           A           B 0.2976972 overall overall             98
#> 6        3           A           C 0.7938593 overall overall             98
#>   hedges_correction standardizer_sd observation_id   variance
#> 1         0.9923241               1           1::1 0.04019213
#> 2         0.9923241               1           1::2 0.04185005
#> 3         0.9923241               1           2::1 0.04064429
#> 4         0.9923241               1           2::2 0.04119693
#> 5         0.9923241               1           3::1 0.03984045
#> 6         0.9923241               1           3::2 0.04260365
smd_fit <- network_meta_coherent(smd$data,"study_id","treatment_1","treatment_2",
             "effect","variance",observation_id="observation_id",
             sampling_covariance=smd$sampling_covariance)
smd_fit$effects
#>   treatment_1 treatment_2     total  total_se  df total_ci_lower total_ci_upper
#> 1           A           B 0.3958641 0.1157909 Inf     0.16891821      0.6228100
#> 2           A           C 0.6921645 0.1181409 Inf     0.46061254      0.9237164
#> 3           B           C 0.2963004 0.1173852 Inf     0.06622964      0.5263711
#>   total_df    direct direct_se  indirect indirect_se direct_indirect_covariance
#> 1      Inf 0.3962692 0.1157914        NA          NA                         NA
#> 2      Inf 0.6935167 0.1181463        NA          NA                         NA
#> 3      Inf        NA        NA 0.2963004   0.1173852                         NA
#>   incoherence_factor if_se direct_n_effects direct_n_studies direct_ci_lower
#> 1                 NA    NA                3                3       0.1693222
#> 2                 NA    NA                3                3       0.4619541
#> 3                 NA    NA                0                0              NA
#>   direct_ci_upper indirect_ci_lower indirect_ci_upper total_p_value
#> 1       0.6232161                NA                NA  6.290125e-04
#> 2       0.9250792                NA                NA  4.662119e-09
#> 3              NA        0.06622964         0.5263711  1.159712e-02
#>   total_p_adjusted
#> 1     6.290125e-04
#> 2     4.662119e-09
#> 3     1.159712e-02

network_smd_data() returns baseline contrasts within each study/outcome/time. It uses a joint delta method, including SD estimation uncertainty, under normal measurements and independent arms. It supports pair-pooled, study-pooled, and control SD denominators. The Hedges gamma-ratio correction is exact for its stated degrees of freedom; the sampling covariance is still an approximation.

Pair-pooled SMDs need scientifically comparable population standardizers for an additive network interpretation. With unequal underlying SDs, network coherence need not follow from coherence of raw mean differences. Sample SMDs with different denominators need not satisfy exact loop closure, so all_contrasts=TRUE does not by itself justify discarding a contrast as algebraically redundant.

Repeated outcomes and times

Provide individual-level correlation matrices for repeated measurements within an arm. Give participant overlap matrices when correlated measurements have unequal sample sizes. Omitting overlap for equal-size correlated measurements assumes the same participants. Different randomized arms must have zero overlap and covariance.

a <- data.frame(id=letters[1:4],study="s1",treatment=rep(c("A","B"),each=2),
                mean=c(0,0,.4,.7),sd=1,n=50,time=rep(c(0,1),2))
R <- diag(4)
R[1,2] <- R[2,1] <- R[3,4] <- R[4,3] <- .6
dimnames(R) <- list(a$id,a$id)
repeated <- network_meta_repeated(a,"study","treatment","mean","sd","n",
               time="time",measure="SMD",arm_observation_id="id",
               correlations=list(s1=R),treatment_effects="by_time")
repeated$effects
#>   treatment_1 treatment_2 time     total  total_se  df total_ci_lower
#> 1           A           B    0 0.3969296 0.2004797 Inf    0.003996564
#> 2           A           B    1 0.6946269 0.2045729 Inf    0.293671440
#>   total_ci_upper total_df    direct direct_se indirect indirect_se
#> 1      0.7898627      Inf 0.3969296 0.2004797       NA          NA
#> 2      1.0955823      Inf 0.6946269 0.2045729       NA          NA
#>   direct_indirect_covariance incoherence_factor if_se direct_n_effects
#> 1                         NA                 NA    NA                1
#> 2                         NA                 NA    NA                1
#>   direct_n_studies direct_ci_lower direct_ci_upper indirect_ci_lower
#> 1                1     0.003996564       0.7898627                NA
#> 2                1     0.293671440       1.0955823                NA
#>   indirect_ci_upper total_p_value total_p_adjusted
#> 1                NA  0.0477148802     0.0477148802
#> 2                NA  0.0006850369     0.0006850369

The same constructor supports an outcome column and combinations of outcome and time. Select by_outcome, by_time, or by_outcome_time to estimate distinct network means. Each requested stratum must support an identifiable network. Default random treatment deviations are independent across strata; a supplied or estimated unstructured basic-effect matrix can model their between-study covariance. Sampling correlations and heterogeneity correlations remain separate.

Numeric moderator columns enter as interactions with every basic treatment effect. For fixed time trends, provide time and its scientifically chosen basis functions as moderator columns. The network_meta() formula interface expands categorical moderators; the direct engine accepts encoded numeric columns.

For sites nested in studies, random_levels="site" adds signed site-specific treatment deviations; for crossed grouping factors provide multiple columns. The grouping IDs are interpreted within study. Identical or aliased covariance components produce an identification error. This is different from adding an unsigned random intercept to every contrast.

Coherence, inference, and sensitivity

network_design_incoherence(fit)
#> Higgins design-by-treatment incoherence
#> =======================================
#> Question: Do treatment effects disagree across designs after accounting for heterogeneity?
#> H0 (global): All identifiable design-by-treatment interaction parameters are zero.
#> Method: Design-by-treatment Wald tests with heterogeneity refitted by REML
#> Assumption: Asymptotic model-based tests; transitivity requires substantive assessment.
#> Null-model heterogeneity: study 0
#> Local p-value adjustment: none (family size: 3; includes nonestimable hypotheses)
#> 
#> Global test
#> The global design-by-treatment test is not estimable.
#> 
#> Symmetric side-splitting Wald tests
#> Local coefficient covariance: GLS (conditions on fitted heterogeneity)
#> Question: Is a symmetric departure needed for each treatment pair?
#> H0 (each pair): All identifiable symmetric side-splitting gamma coefficients are zero.
#> Gamma direction: treatment 2 minus treatment 1 (see contrast).
#> Intervals: pointwise 95% normal Wald; p-value adjustment does not adjust intervals.
#> No estimable local design-deviation tests are available.
#> 
#> Use detailed=TRUE for variance-component and convergence details;
#> combine with estimable_only=FALSE to inspect unavailable tests and reasons.
network_design_incoherence(fit,method="ML")
#> Higgins design-by-treatment incoherence
#> =======================================
#> Question: Do treatment effects disagree across designs after accounting for heterogeneity?
#> H0 (global): All identifiable design-by-treatment interaction parameters are zero.
#> Method: ML likelihood-ratio tests with heterogeneity refitted
#> Assumption: Asymptotic model-based tests; transitivity requires substantive assessment.
#> Null-model heterogeneity: study 0
#> Local p-value adjustment: none (family size: 3; includes nonestimable hypotheses)
#> 
#> Global test
#> The global design-by-treatment test is not estimable.
#> 
#> Symmetric side-splitting likelihood-ratio tests
#> Local coefficient covariance: GLS (conditions on fitted heterogeneity)
#> Question: Is a symmetric departure needed for each treatment pair?
#> H0 (each pair): All identifiable symmetric side-splitting gamma coefficients are zero.
#> Gamma direction: treatment 2 minus treatment 1 (see contrast).
#> Intervals: pointwise 95% normal Wald; p-value adjustment does not adjust intervals.
#> No estimable local design-deviation tests are available.
#> 
#> Use detailed=TRUE for variance-component and convergence details;
#> combine with estimable_only=FALSE to inspect unavailable tests and reasons.

Construct an independent covariance scenario with explicitly named dimensions:

S_ind <- diag(d$v); dimnames(S_ind) <- list(d$id,d$id)
sensitivity <- network_covariance_sensitivity(fit,list(independent=S_ind,shared_control=S))
sensitivity$independent$effects
#>   treatment_1 treatment_2     total  total_se  df total_ci_lower total_ci_upper
#> 1           A           B 0.3000000 0.1154701 Inf     0.07368285      0.5263171
#> 2           A           C 0.6333333 0.1154701 Inf     0.40701619      0.8596505
#> 3           B           C 0.3333333 0.1632993 Inf     0.01327255      0.6533941
#>   total_df    direct direct_se  indirect indirect_se direct_indirect_covariance
#> 1      Inf 0.3000000 0.1154701        NA          NA                         NA
#> 2      Inf 0.6333333 0.1154701        NA          NA                         NA
#> 3      Inf        NA        NA 0.3333333   0.1632993                         NA
#>   incoherence_factor if_se direct_n_effects direct_n_studies direct_ci_lower
#> 1                 NA    NA                3                3      0.07368285
#> 2                 NA    NA                3                3      0.40701619
#> 3                 NA    NA                0                0              NA
#>   direct_ci_upper indirect_ci_lower indirect_ci_upper total_p_value
#> 1       0.5263171                NA                NA  9.374768e-03
#> 2       0.8596505                NA                NA  4.138729e-08
#> 3              NA        0.01327255         0.6533941  4.122683e-02
#>   total_p_adjusted
#> 1     9.374768e-03
#> 2     4.138729e-08
#> 3     4.122683e-02

Conditional Wald tests refit the mean design with heterogeneity held fixed. ML likelihood-ratio tests re-estimate heterogeneity in both models. Both retain within-study covariance and report nonestimable tests. Neither is proof of transitivity. Compare effect modifiers and measurement definitions across study designs; network_transitivity() provides numeric and categorical modifier summaries.

inference="CR1" uses study-cluster sandwich covariance with a K/(K-1) adjustment and t inference with K-1 degrees of freedom, where K is the number of independent studies. It requires more studies than fixed coefficients. This is a basic small-sample adjustment, not CR2/Satterthwaite inference. Incoherence tests remain model-based even for a CR1 primary fit. Model-based SEs condition on estimated heterogeneity; prediction intervals are plug-in intervals.

Study bootstrap and jackknife helpers rebuild complete covariance blocks and observation IDs. Effect-wise permutation with supplied dependent covariance is rejected because that permutation scheme does not establish exchangeability.

Validation

tools/validate-network.R reproduces Gaussian network recovery and normal-arm SMD covariance simulations. Tests compare the common-heterogeneity model with an equivalent metafor::rma.mv() specification and verify row, sign, and reference invariance, repeated-category indexing, prediction variances, and resampling.

All interfaces use the same likelihood and downstream result structure. Use network_nodesplit() for independently allocated direct and indirect evidence; the descriptive conditional differences above can share study information.