
Consistent networks with dependent standardized mean differences
network-dependent-smd.RmdChoosing 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-03The 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.5863636For 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.1100000Prediction 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-02network_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.0006850369The 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-02Conditional 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.