Package 'cdmeta'

Vitamin K antagonists for prevention of stroke in non-valvular atrial fibrillation

Description

A pairwise subset extracted from a network meta-analysis of antithrombotic treatments for prevention of stroke in patients with non-valvular atrial fibrillation. The dataset includes direct comparisons of vitamin K antagonists versus placebo or control, with study-specific log odds ratios and standard errors for the stroke outcome.

Usage

data(af_vka)

Format

A data frame with 6 rows and 11 variables:

study_id

Study identifier.

study

Trial name.

treatment

Label for the treatment group.

control

Label for the control group.

treatment_events

Number of stroke events in the treatment group.

treatment_total

Number of participants in the treatment group.

control_events

Number of stroke events in the control group.

control_total

Number of participants in the control group.

yi

Study-specific log odds ratio comparing vitamin K antagonists with placebo or control.

sei

Standard error of yi.

vi

Sampling variance of yi, equal to sei^2.

Source

Dogliotti, A., Paolasso, E., and Giugliano, R. P. (2014). Current and new oral antithrombotics in non-valvular atrial fibrillation: a network meta-analysis of 79808 patients. Heart, 100(5), 396–405. doi:10.1136/heartjnl-2013-304347

---

Confidence-distribution-based inference for random-effects meta-analysis

Description

Performs unified confidence-distribution-based inference for random-effects meta-analysis. The function provides inference for the overall mean effect $\mu$, heterogeneity variance $\tau^2$, heterogeneity standard deviation $\tau$, heterogeneity proportion $I^2$, and the effect in a future study $\theta_{\mathrm{new}}$.

Usage

cdmeta(
  y,
  se,
  alpha = 0.05,
  B = 25000,
  seed = NULL,
  parallel = FALSE,
  tau2_samples = NULL,
  i2_method = c("typical_se2", "mean_se2", "harmonic_mean_se2"),
  mu_dist = c("normal", "t"),
  df = NULL,
  qtype = 8,
  transf = NULL,
  transf_name = NULL,
  ...
)

Arguments

y	A numeric vector of study-specific effect estimates (e.g., MD, SMD, log OR, log RR, or log HR).
se	A numeric vector of within-study standard errors of y.
alpha	The significance level for interval estimation. Default is 0.05; the alpha/2th and 1-alpha/2th quantiles are used as the lower and upper limits of the interval estimates.
B	The number of Monte Carlo samples. When tau2_samples is not supplied, this value is also passed to pimeta::pima() as the number of bootstrap samples. Default is 25000.
seed	An optional numeric value that determines the random seed for reproducibility. Default is NULL.
parallel	Either FALSE for single-threaded computation or a positive integer specifying the number of threads passed to pimeta::pima(). Default is FALSE.
tau2_samples	An optional numeric vector of externally supplied $\tau^2$ samples. If supplied, pimeta::pima() is not called.
i2_method	A character string specifying the reference within-study variance used for calculating $I^2$. Available options are "typical_se2", "mean_se2", and "harmonic_mean_se2". Default is "typical_se2".
mu_dist	A character string specifying the distribution used for conditional sampling of the overall mean effect $\mu$. Available options are "normal" and "t". Default is "normal".
df	The degrees of freedom used when mu_dist = "t". If NULL, the default is $K - 1$, where $K$ is the number of studies.
qtype	The quantile type used in stats::quantile(). Default is 8.
transf	An optional transformation function applied to effect-scale summaries. For example, transf = exp can be used when y is on the log odds ratio, log risk ratio, or log hazard ratio scale. The transformation is applied to mu, theta_new, and mu_plugin, but not to heterogeneity measures.
transf_name	An optional character string giving the name of the transformation function. For example, transf_name = "exp". If NULL, the name is inferred when possible.
...	Additional arguments passed to pimeta::pima().

Details

The function first obtains Monte Carlo samples of the between-study variance $\tau^2$. These samples are obtained either from pimeta::pima(..., method = "boot") or from a user-supplied vector tau2_samples.

Given sampled values of $\tau^2$, the function performs conditional sampling of the overall mean effect. If mu_dist = "normal", then

$\mu \mid \tau^2, y \sim N\{\hat{\mu}(\tau^2), V_{\mu}(\tau^2)\}.$

If mu_dist = "t", then a $t$ distribution with df degrees of freedom is used instead. The predictive distribution for a future study effect is then generated as

$\theta_{\mathrm{new}} \mid \mu, \tau^2 \sim N(\mu, \tau^2).$

For $I^2$, the sampled $\tau^2$ values are transformed using a reference within-study variance specified by i2_method.

If transf is supplied, all calculations are still performed on the original analysis scale of y. The transformation is applied after Monte Carlo sampling. Heterogeneity measures $\tau^2$, $\tau$, and $I^2$ are not transformed.

Value

An object of class "cdmeta". The main components include the matched call, study and Monte Carlo counts, point estimates, interval estimates, Monte Carlo draws, input data, the pimeta result (when used), and transformation information.

See Also

forest.cdmeta, plot.cdmeta

Examples

data(hf_iron)

fit_hf <- cdmeta(
  y = hf_iron$yi,
  se = hf_iron$sei,
  B = 10000,
  seed = 11111,
  transf = exp,
  transf_name = "exp"
)

fit_hf

forest(
  fit_hf,
  slab = hf_iron$study,
  at = log(c(0.25, 0.5, 1, 2, 4)),
  xlab = "Risk ratio",
  mark_summary_estimate = TRUE,
  mark_prediction_estimate = TRUE
)

---

Forest plot for cdmeta objects

Description

Draws a forest plot from an object of class "cdmeta". The plot shows study-specific effect estimates and confidence intervals, the confidence-distribution-based summary estimate for the overall mean effect, and optionally the prediction interval for the effect in a future study.

Usage

## S3 method for class 'cdmeta'
forest(
  x,
  slab = NULL,
  order = c("none", "increasing", "decreasing", "precision", "weight"),
  level = NULL,
  summary_stat = c("mean", "median"),
  refline = 0,
  xlab = "Effect size",
  main = NULL,
  atransf = NULL,
  at = NULL,
  alim = NULL,
  xlim = NULL,
  digits = 2,
  ci_digits = digits,
  weight_digits = 1,
  show_weights = TRUE,
  show_pi = TRUE,
  show_het = TRUE,
  header = TRUE,
  annotate = TRUE,
  cex = 0.85,
  psize = NULL,
  pch = 22,
  box_col = "black",
  box_bg = "white",
  ci_col = "black",
  summary_col = "black",
  summary_bg = "gray20",
  pi_col = "gray40",
  refline_col = "gray70",
  grid = TRUE,
  grid_col = "gray90",
  qtype = 8,
  symmetric_shapes = TRUE,
  mark_summary_estimate = FALSE,
  mark_prediction_estimate = FALSE,
  estimate_mark_col = "black",
  estimate_mark_lwd = 1,
  mar = c(4.5, 1, 3, 1),
  ...
)

forest(x, ...)

Arguments

x	An object of class "cdmeta".
slab	An optional character vector of study labels. If NULL, the names of x$data$y are used when available; otherwise generic study labels are created.
order	A character string specifying the order of studies in the plot. Available options are "none", "increasing", "decreasing", "precision", and "weight".
level	Confidence level used for study-specific and summary intervals. If NULL, 1 - x$alpha is used.
summary_stat	Whether Monte Carlo means ("mean") or medians ("median") are used as point estimates for summary rows.
refline	Numeric location of the reference line.
xlab	Label for the x-axis.
main	Optional main title.
atransf	Optional function used to transform axis labels and printed estimates while plotting coordinates remain on the original analysis scale.
at	Optional numeric vector specifying tick-mark locations on the original analysis scale.
alim	Optional numeric vector of length 2 specifying plotting limits for the effect-size axis on the original analysis scale.
xlim	Optional numeric vector of length 2 specifying full plotting limits including the text columns.
digits	Number of digits used for axis labels.
ci_digits	Number of digits used for effect estimates and intervals.
weight_digits	Number of digits used for study weights.
show_weights	Logical indicating whether study weights are shown.
show_pi	Logical indicating whether the prediction interval is shown.
show_het	Logical indicating whether heterogeneity statistics are shown.
header	Logical indicating whether column headers are shown.
annotate	Logical indicating whether estimates and intervals are printed on the right side of the plot.
cex	Character expansion factor.
psize	Optional point sizes for study-specific estimates. If NULL, point sizes are proportional to random-effects inverse-variance weights.
pch	Plotting symbol for study-specific estimates.
box_col	Border color of study-specific points.
box_bg	Fill color of study-specific points.
ci_col	Color of study-specific confidence intervals.
summary_col	Border color of the summary diamond.
summary_bg	Fill color of the summary diamond.
pi_col	Color of the prediction interval.
refline_col	Color of the reference line.
grid	Logical indicating whether vertical grid lines are drawn.
grid_col	Color of the grid lines.
qtype	Quantile type used in stats::quantile(). Default is 8.
symmetric_shapes	Logical indicating whether the summary diamond and prediction-interval marker are drawn symmetrically around interval midpoints.
mark_summary_estimate	Logical indicating whether the actual summary point estimate is marked inside the summary diamond.
mark_prediction_estimate	Logical indicating whether the actual predictive point estimate is marked on the prediction-interval row.
estimate_mark_col	Color of the actual-estimate marks.
estimate_mark_lwd	Line width of the actual-estimate marks.
mar	Plot margins passed to graphics::par().
...	Additional arguments passed to graphics::plot().

Details

Study-specific confidence intervals are calculated using the normal approximation

$y_i \pm z_{1-\alpha/2} se_i,$

where $\alpha = 1 - level$. The summary interval for $\mu$ and the prediction interval are calculated from the Monte Carlo samples in the cdmeta object when available.

If the object was created with transf = exp, forest() uses this transformation automatically when atransf = NULL. Tick marks supplied through at remain on the original analysis scale.

Value

Invisibly returns a data frame containing the plotted study-specific estimates, standard errors, confidence intervals, and weights. Attributes contain the overall, prediction, and heterogeneity summaries on the original analysis scale.

See Also

cdmeta

Examples

data(hf_iron)
fit_hf <- cdmeta(
  y = hf_iron$yi,
  se = hf_iron$sei,
  B = 10000,
  seed = 11111,
  transf = exp,
  transf_name = "exp"
)

forest(
  fit_hf,
  slab = hf_iron$study,
  at = log(c(0.25, 0.5, 1, 2, 4)),
  xlab = "Risk ratio",
  mark_summary_estimate = TRUE,
  mark_prediction_estimate = TRUE
)

---

Intravenous iron therapy for patients with heart failure and iron deficiency

Description

A dataset from a systematic review and meta-analysis of randomized trials evaluating intravenous iron therapy for patients with heart failure and iron deficiency. The outcome is represented by study-specific log risk ratios and their standard errors.

Usage

data(hf_iron)

Format

A data frame with 6 rows and 5 variables:

study_id

Study identifier.

study

Trial name.

yi

Study-specific log risk ratio.

sei

Standard error of yi.

vi

Sampling variance of yi, equal to sei^2.

Source

Anker, S. D., et al. (2025). Systematic review and meta-analysis of intravenous iron therapy for patients with heart failure and iron deficiency. Nature Medicine, 31, 2640–2646. doi:10.1038/s41591-025-03671-1

---

Plot the predictive distribution from a cdmeta object

Description

Displays the Monte Carlo predictive distribution of the true effect in a future study and, optionally, its prediction interval.

Usage

## S3 method for class 'cdmeta'
plot(
  x,
  show_interval = TRUE,
  breaks = 40,
  main = NULL,
  xlab = NULL,
  hist_col = "grey85",
  border_col = "white",
  density_lwd = 2,
  pi_col = "firebrick",
  pi_lwd = 3,
  rug = FALSE,
  transf = NULL,
  transf_name = NULL,
  qtype = 8,
  ...
)

Arguments

x	An object of class "cdmeta".
show_interval	A logical value indicating whether a separate prediction- interval panel is shown below the predictive distribution.
breaks	Number of histogram breaks or another value accepted by graphics::hist().
main	Optional main title.
xlab	Optional x-axis label.
hist_col	Fill color of histogram bars.
border_col	Border color of histogram bars.
density_lwd	Line width of the kernel density curve.
pi_col	Color used for prediction-interval and predictive-estimate marks.
pi_lwd	Line width used for the prediction interval.
rug	A logical value indicating whether a rug of Monte Carlo draws is added.
transf	Optional transformation function for the predictive draws.
transf_name	Optional character string naming transf.
qtype	The quantile type used in stats::quantile(). Default is 8.
...	Additional arguments passed to graphics::hist().

Value

The input object x, invisibly.

Examples

data(hf_iron)
fit_hf <- cdmeta(hf_iron$yi, hf_iron$sei, B = 10000, seed = 11111)
plot(fit_hf)

---

Print a cdmeta object

Description

Prints point estimates, confidence intervals, and the prediction interval from an object of class "cdmeta".

Usage

## S3 method for class 'cdmeta'
print(x, digits = 4, transf = NULL, transf_name = NULL, qtype = 8, ...)

Arguments

x	An object of class "cdmeta".
digits	The number of digits to print.
transf	An optional transformation function applied to effect-scale summaries for printing.
transf_name	An optional character string naming transf.
qtype	The quantile type used in stats::quantile(). Default is 8.
...	Additional arguments; currently not used.

Value

The input object x, invisibly.

---