Package {drmeta}

Type:	Package
Title:	Design-Indexed Location-Scale Meta-Analysis
Version:	0.2.2
Description:	Fits constrained and unrestricted meta-analytic location-scale models in which residual between-study heterogeneity is modeled as an exponential function of a prespecified design-robustness score. The package supports maximum-likelihood (ML) and restricted maximum-likelihood (REML) estimation, location moderators, the conventional random-effects model as a nested special case, exact estimation at the nonnegative scale-gradient boundary, design-indexed heterogeneity summaries, scale-attenuation measures, prediction of fitted heterogeneity, leave-one-out influence diagnostics, and parametric-bootstrap inference for the scale gradient. Because the scale-gradient null lies on the boundary of the constrained parameter space, standard chi-square likelihood-ratio references do not apply (Self and Liang, 1987, <doi:10.1080/01621459.1987.10478472>). The general location-scale parent model is described in Viechtbauer and Lopez-Lopez (2022, <doi:10.1002/jrsm.1562>). A scale model reweights studies and does not adjust the mean for design-linked bias.
License:	MIT + file LICENSE
URL:	https://github.com/causalfragility-lab/drmeta
BugReports:	https://github.com/causalfragility-lab/drmeta/issues
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
Imports:	grDevices, graphics, parallel, stats, utils
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
Config/roxygen2/markdown:	TRUE
NeedsCompilation:	no
Config/roxygen2/version:	8.0.0
Packaged:	2026-08-24 18:43:29 UTC; subir
Author:	Subir Hait [aut, cre, cph]
Maintainer:	Subir Hait <haitsubi@msu.edu>
Repository:	CRAN
Date/Publication:	2026-08-24 19:10:02 UTC

S3 methods for drmeta objects

Description

S3 methods for drmeta objects

Usage

## S3 method for class 'drmeta'
coef(object, ...)

## S3 method for class 'drmeta'
vcov(object, ...)

## S3 method for class 'drmeta'
fitted(object, ...)

## S3 method for class 'drmeta'
residuals(object, ...)

## S3 method for class 'drmeta'
print(x, ...)

## S3 method for class 'drmeta'
summary(object, ...)

## S3 method for class 'summary.drmeta'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

## S3 method for class 'drmeta'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'drmeta'
logLik(object, REML = NULL, ...)

Arguments

Value

coef and fitted and residuals return numeric vectors; vcov returns the location covariance matrix; confint returns a matrix of confidence limits; logLik returns an object of class logLik carrying df and nobs attributes; summary returns an object of class summary.drmeta; the print methods return their argument invisibly.

Map study design labels to illustrative design-robustness scores

Description

Provides a convenience mapping from design-type labels to numeric scores.

Usage

dr_from_design(
  design,
  custom_map = NULL,
  default_score = 0.25,
  warn_unknown = TRUE
)

Arguments

Details

This mapping is a demonstration default, not a validated measurement model and not a universal hierarchy of study quality. A design label does not determine the magnitude or direction of bias in a particular evidence base. For substantive work the index should be constructed for the specific synthesis, outcome, and identification problem at hand, ordinarily with dr_score, and reported under alternative defensible codings.

Value

A numeric vector of scores in [0, 1], the same length as design.

See Also

dr_score

Examples

dr_from_design(c("RCT", "DiD", "OLS", "IV", "matching"))
dr_from_design("house_method", custom_map = c(house_method = 0.65))

Classical heterogeneity diagnostics and design-indexed summaries

Description

Reports the classical fixed-effect residual Q statistic and I^2 alongside the fitted design-indexed scale parameters. Unlike version 0.1.0, this function does not return a design-explained variance decomposition; that quantity was not identified by the model and has been replaced by dr_scale_attenuation.

Usage

dr_heterogeneity(object)

Arguments

Value

A list with components Q, df, p, I2, tau0sq, gamma, attenuation_observed, and tau2_by_study.

Examples

path <- system.file("extdata", "bcg_design_robustness.csv", package = "drmeta")
bcg <- utils::read.csv(path)
fit <- drmeta(yi = bcg[["yi"]], vi = bcg[["vi"]], dr = bcg[["dr"]])
dr_heterogeneity(fit)

Leave-one-out influence diagnostics

Description

Refits the model with each study omitted in turn and records how the location and scale estimates move. Both components are reported, because a study can be uninfluential for the pooled mean while dominating the scale gradient.

Usage

dr_loo(object)

Arguments

Value

A data frame with one row per omitted study, containing the study index, its design-robustness value, the leave-one-out estimate of the first location coefficient and its change from the full fit, the leave-one-out tau0sq and gamma with their changes, a converged flag, and a logical influential column flagging changes in the first location coefficient exceeding twice its full-model standard error.

Examples

path <- system.file("extdata", "bcg_design_robustness.csv", package = "drmeta")
bcg <- utils::read.csv(path)
fit <- drmeta(yi = bcg[["yi"]], vi = bcg[["vi"]], dr = bcg[["dr"]])
dr_loo(fit)

Plot the fitted variance function

Description

Draws the fitted residual between-study variance against the design index, with study-level fitted variances overlaid. By default the curve is drawn only over the observed range of the design index, since the fitted function outside that range is an extrapolation.

Usage

dr_plot_vfun(
  object,
  extrapolate = FALSE,
  col_curve = "#D6604D",
  col_pts = "#2166AC",
  xlab = "Design robustness",
  ylab = "Fitted tau^2",
  main = "Fitted variance function",
  ...
)

Arguments

Value

Invisibly, the data frame of plotted grid values.

Examples

path <- system.file("extdata", "bcg_design_robustness.csv", package = "drmeta")
bcg <- utils::read.csv(path)
fit <- drmeta(yi = bcg[["yi"]], vi = bcg[["vi"]], dr = bcg[["dr"]])
dr_plot_vfun(fit)

Proportional attenuation in fitted heterogeneity

Description

Returns the proportional reduction in fitted residual between-study heterogeneity between two design-robustness values, A_\tau = 1 - \exp(-\gamma (d_H - d_L)). This is a summary of the fitted scale function only. It is not a causal R^2, not a proportion of heterogeneity explained, and not evidence that design quality caused a reduction in heterogeneity.

Usage

dr_scale_attenuation(object, d_low = min(object$dr), d_high = max(object$dr))

Arguments

Value

A single numeric value. For a constrained fit it lies in [0, 1); for an unrestricted fit with a negative gradient it is negative, indicating heterogeneity that increases with the design index.

Examples

path <- system.file("extdata", "bcg_design_robustness.csv", package = "drmeta")
bcg <- utils::read.csv(path)
fit <- drmeta(yi = bcg[["yi"]], vi = bcg[["vi"]], dr = bcg[["dr"]])
dr_scale_attenuation(fit)
dr_scale_attenuation(fit, d_low = 0.25, d_high = 0.75)

Predict the fitted between-study variance

Description

Evaluates the fitted variance function \tau^2(d) = \tau_0^2 \exp(-\gamma d) over a grid of design-robustness values. The default grid spans the observed range of the design index rather than the full interval [0, 1], because values outside the observed support are extrapolations of the fitted scale model.

Usage

dr_scale_predict(
  object,
  dr = seq(min(object$dr), max(object$dr), length.out = 100)
)

Arguments

Value

A data frame with columns dr and tau2, giving the fitted residual between-study variance at each supplied value.

Examples

path <- system.file("extdata", "bcg_design_robustness.csv", package = "drmeta")
bcg <- utils::read.csv(path)
fit <- drmeta(yi = bcg[["yi"]], vi = bcg[["vi"]], dr = bcg[["dr"]])
head(dr_scale_predict(fit))

Build a design-robustness index from sub-scores

Description

Combines user-supplied sub-score dimensions into a single index in [0, 1] as a normalised weighted average. The components, their coding rules, and their weights should be prespecified and reported.

Usage

dr_score(..., weights = NULL, warn_range = TRUE)

Arguments

Details

For confirmatory use, none of the sub-scores may be a function of the realized effect estimate, its standard error, its p-value, its confidence interval, or any outcome-dependent diagnostic. A score that uses such information defines an exploratory analysis, not a primary scale moderator. This function cannot verify that condition; it is the analyst's responsibility.

Value

A numeric vector in [0, 1], carrying an attribute "subscores" that holds the clipped inputs and the resulting index.

Examples

dr_score(balance = c(0.9, 0.6, 0.4),
         overlap = c(0.8, 0.7, 0.5),
         weights = c(2, 1))

Fit a design-indexed meta-analytic location-scale model

Description

Fit a design-indexed meta-analytic location-scale model

Usage

drmeta(
  yi,
  vi,
  dr,
  mods = NULL,
  method = c("REML", "ML"),
  constrained = TRUE,
  gamma_max = 8,
  gamma_fixed = NULL,
  control = list(),
  .quiet = FALSE
)

Arguments

Value

An object of class drmeta: a list whose components include beta (location coefficients), vcov, ci_beta, tau0sq, gamma, tau2i, sigma2, weights, residuals, logLik, method, constrained, convergence, and the supplied data.

Examples

path <- system.file("extdata", "bcg_design_robustness.csv", package = "drmeta")
bcg <- utils::read.csv(path)
fit <- drmeta(yi = bcg[["yi"]], vi = bcg[["vi"]], dr = bcg[["dr"]])
summary(fit)

Parametric-bootstrap test of the constrained scale gradient

Description

Tests H0: gamma = 0 against H1: gamma > 0. The null lies on the boundary of the constrained parameter space, so the likelihood-ratio statistic does not have an asymptotic chi-square distribution and a parametric bootstrap is used instead. Data are simulated from the fitted null model, in which between-study heterogeneity is constant in the design-robustness index.

Usage

drmeta_bootstrap_gamma(
  object,
  B = 999,
  seed = NULL,
  parallel = FALSE,
  ncpus = 2L,
  tol = 1e-08
)

Arguments

Details

Replicates in which either refit fails to converge are discarded rather than contributing a statistic computed at a non-optimal point. The p-value uses the number of usable replicates as its denominator, and the discarded count is returned so the loss is visible.

When the constrained estimate is already at the boundary, the null and alternative fits coincide and the observed statistic is zero by construction. Bootstrapping in that situation would compare zero against a simulated distribution with a large point mass at zero, and would return a p-value that looks like evidence but only records the proportion of replicates that also reached the boundary. The function therefore short-circuits, returns p.value = 1 with boundary = TRUE, and runs no replicates. A boundary estimate means the data provide no support for a positive scale gradient; it is not a measured degree of evidence. Fit with constrained = FALSE to see whether the unrestricted gradient is negative, which would contradict the substantive constraint rather than merely fail to support it.

When parallel = TRUE, reproducibility across cores requires the L'Ecuyer-CMRG generator, which this function sets and restores when a seed is supplied.

Value

An object of class drmeta_bootstrap_gamma, a list with components statistic (observed likelihood-ratio statistic), p.value, B (requested replicates), B_used (replicates in which both refits converged), n_failed (replicates discarded), simulated (the simulated statistics, with NA for failed replicates), null (the fitted null model), alternative (the supplied fit), and boundary, a logical flag that is TRUE when the constrained estimate already lies at gamma = 0 and no bootstrap was run.

Examples

path <- system.file("extdata", "bcg_design_robustness.csv", package = "drmeta")
bcg <- utils::read.csv(path)
fit <- drmeta(yi = bcg[["yi"]], vi = bcg[["vi"]], dr = bcg[["dr"]])
drmeta_bootstrap_gamma(fit, B = 100, seed = 1)

Rescale a numeric vector to the unit interval

Description

Rescale a numeric vector to the unit interval

Usage

normalize_01(x)

Arguments

Value

A numeric vector of the same length rescaled to [0, 1]. If all non-missing values are equal, a zero vector is returned.

Examples

normalize_01(c(2, 5, 8))
normalize_01(c(1, 1, 1))

Print a parametric-bootstrap scale-gradient test

Description

Print a parametric-bootstrap scale-gradient test

Usage

## S3 method for class 'drmeta_bootstrap_gamma'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Value

Invisibly returns x. Called for its printed output.