Package {RaCE.NMA}

Title: Rank-Clustered Estimation for Network Meta-Analysis
Version: 1.0.3
Description: An implementation of the RaCE-NMA (Rank-Clustered Estimation for Network Meta-Analysis) model for post-hoc clustering of treatments or interventions by rank in network meta-analysis data. Functions for model estimation, assessment, and displaying results are provided. For more details, see Pearce and Zhou (2025) <doi:10.1017/rsm.2025.10049>.
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.3.3
LazyData: TRUE
Imports: utils, magrittr, dplyr, invgamma, mvtnorm, coda, reshape2, ggplot2
Suggests: knitr, rmarkdown, devtools, cowplot, gridExtra
VignetteBuilder: knitr
URL: https://pearce790.github.io/RaCE.NMA/, https://github.com/pearce790/RaCE.NMA/
BugReports: https://github.com/pearce790/RaCE.NMA/issues
NeedsCompilation: no
Packaged: 2026-05-28 23:15:08 UTC; michaelpearce
Author: Michael Pearce ORCID iD [aut, cre, cph], Shouhao Zhou ORCID iD [aut]
Maintainer: Michael Pearce <michaelpearce@reed.edu>
Depends: R (≥ 3.5.0)
Repository: CRAN
Date/Publication: 2026-06-02 07:50:42 UTC

Calculate Gelman Diagnostics for Fitted RaCE NMA Models

Description

This function applies MCMC outputs from the mcmc_RCMVN package to the gelman.diag function in the coda package.

Usage

calculate_Rhat(mcmc, names = NULL, level = 0.95, multivariate = FALSE)

Arguments

mcmc

MCMC draws from the RaCE NMA model, in the form of the model output of the mcmc_RCMVN function.

names

A vector of intervention names (optional)

level

The level parameter from the gelman.diag function in the coda package. Defaults to 0.95.

multivariate

The multivariate parameter from the gelman.diag function in the coda package. Defaults to FALSE.

Value

Gelman diagnostics for the inputted MCMC chains, in the format of the output of the gelman.diag function in the coda package.

Examples

mcmc <- mcmc_raceNMA(mu_hat=c(0,0,1,1), s=c(.1,.1,.1,.1), seed=1)
calculate_Rhat(mcmc,names=paste0("Treatment ",1:4))

Calculate SUCRA and MNBT based on MCMC draws in NMA or RaCE-NMA models

Description

This function creates a results table of SUCRA and Median Number of Better Treatments (MNBT) based on MCMC draws from a standard NMA model or a fitted RaCE-NMA model.

Usage

calculate_SUCRA_MNBT(data = NULL, mcmc = NULL, level = 0.5, names = NULL)

Arguments

data

A NxJ matrix of data, where N is the number of observations and J the number of treatments. This feature is designed to display results from a standard NMA study.

mcmc

MCMC draws from the RaCE NMA model, in the form of the model output of the mcmc_RCMVN function.

level

The level level for the interval estimate of MNBT. Defaults to 0.50.

names

A vector of intervention names (optional)

Value

A table containing SUCRA and MNBT values for each treatment, ordered by descending SUCRA values.

Examples

mcmc <- mcmc_raceNMA(mu_hat=c(0,0,1,1), s=c(.1,.1,.1,.1), seed=1)
calculate_SUCRA_MNBT(mcmc=mcmc)

Create a posterior clustering matrix for the interventions based on RaCE NMA models

Description

This function creates a posterior clustering matrix for the interventions in the form of a ggplot.

Usage

clusterplot_ranks(data = NULL, mcmc = NULL, names = NULL, label_ranks = NULL)

Arguments

data

A NxJ matrix of data, where N is the number of observations and J the number of treatments. This feature is designed to display results from a standard NMA study.

mcmc

MCMC draws from the RaCE NMA model, in the form of the model output of the mcmc_RCMVN function.

names

A vector of intervention names (optional)

label_ranks

A vector containing rank levels for which posterior rank probabilities should be displayed within the clustering matrix. Only non-zero probabilities are displayed. Defaults to NULL, indicating no probabilities are displayed as text.

Value

A ggplot of a posterior clustering matrix for the interventions.

Examples

data("toy_data")
mcmc <- mcmc_raceNMA(posterior=toy_data,iter=500,nu_iter=2,chains=1)
clusterplot_ranks(mcmc=mcmc,names=paste0("Treatment ",1:10),label_ranks=1:3)

Create a cumulative ranking plot in RaCE NMA models

Description

This function creates a cumulative ranking plot in the form of a ggplot.

Usage

cumulativeprobplot_ranks(data = NULL, mcmc = NULL, names = NULL)

Arguments

data

A NxJ matrix of data, where N is the number of observations and J the number of treatments. This feature is designed to display results from a standard NMA study.

mcmc

MCMC draws from the RaCE NMA model, in the form of the model output of the mcmc_RCMVN function.

names

A vector of intervention names (optional)

Value

A ggplot of a cumulative ranking plot.

Examples

mcmc <- mcmc_raceNMA(mu_hat=c(0,0,1,1), s=c(.1,.1,.1,.1), seed=1)
cumulativeprobplot_ranks(mcmc=mcmc,names=paste0("Treatment ",1:4))

Fit a Bayesian Rank-Clustered Estimation model for Network Meta-Analysis (RaCE-NMA). Recommended for internal use only; use mcmc_RCMVN instead.

Description

This function fits a Bayesian RaCE-NMA model to data from a previous network meta-analysis.

Usage

fit_raceNMA(
  posterior = NULL,
  mu_hat = NULL,
  cov = NULL,
  s = NULL,
  mu0 = NULL,
  sigma0 = NULL,
  tau,
  nu0,
  iter,
  nu_iter
)

Arguments

posterior

A matrix of posterior draws of relative intervention effects based on a previous NMA. The (i,j) is the ith draw of the effect of intervention j.

mu_hat

A vector of estimated average relative intervention effects based on a previous NMA. The jth entry is the effect of intervention j. Ignored if posterior is supplied.

cov

A variance covariance matrix of relative intervention effects based on a previous NMA. The (i,j) entry is the covariane between intervention i and j's effects. Ignored if posterior is supplied.

s

A vector of the estimated standard deviations of each intervention. The jth entry is the standard deviation of intervention j. Ignored if posterior is supplied.

mu0

The hyperparameter mu0. If NULL, set to mean(mu_hat).

sigma0

The hyperparameter sigma_0. If NULL, set to sqrt(10*var(mu_hat)) which aims to be minimally informative.

tau

The standard deviation of the Metropolis Hastings proposal distribution. If NULL, set to min(|mu_hat_i-mu_hat_j|).

nu0

A numeric vector for the initialization of worth parameters, mu, in the MCMC algorithm. Default to NULL, indicating random initialization.

iter

A numeric indicating the total number of outer MCMC iterations (i.e., the number of times the partition is updated in the Gibbs sampler).

nu_iter

A numeric indicating the number of times each worth parameter is drawn per update of the parameter partition. There will be a total of iterxnu_iter samples from the posterior.

Value

A list of 4 elements: mu, a (iterxnu_iter)xJ matrix of approximate posterior draws of the intervention-specific worth parameters, mu; nu a (iterxnu_iter)xJ matrix of the unique parameter values corresponding to the jth partition cluster in posterior draw i, g a a (iterxnu_iter)xJ matrix indicating the cluster membership of object j in posterior draw i, and K a vector of the number of non-empty partition clusters in each posterior draw.

Examples

fit_raceNMA(mu_hat=c(0,0,1,1), s=c(.1,.1,.1,.1), mu0=0.5, sigma0=5, tau=0.5,
          nu0 = NULL, iter = 5000, nu_iter = 2)

Create posterior forest plots for relative treatment effect estimates from a standard or RaCE NMA study

Description

This function creates posterior forest plots for relative treatment effect estimates from a standard or RaCE NMA study.

Usage

forestplot_muhat(
  data = NULL,
  mcmc = NULL,
  names = NULL,
  level = 0.95,
  order_by_average = TRUE
)

Arguments

data

A NxJ matrix of data to display as a forest plot, where N is the number of observations and J the number of treatments. This feature is designed for use to display a forest plot of results from a standard NMA study.

mcmc

MCMC draws from the RaCE NMA model, in the form of the model output of the mcmc_RCMVN function.

names

A vector of intervention names (optional)

level

A numeric indicating the desired credible level to be displayed, as a proportion. Defaults to 0.95.

order_by_average

A boolean indicating if plot should order treatments by their average treatment effect.

Value

A ggplot of posterior forest plots for the mu parameter.

Examples

data("toy_data")
forestplot_muhat(data=toy_data,names=paste0("Treatment ",1:4))

Fit a Bayesian Rank-Clustered Estimation model for Network Meta-Analysis (RaCE-NMA) using multiple MCMC chains

Description

This function fits a Bayesian RaCE-NMA model to data from a previous network meta-analysis. The function has input parameters to permit drawing multiple MCMC chains, as well as chain thinning and burn-in.

Usage

mcmc_raceNMA(
  posterior = NULL,
  mu_hat = NULL,
  cov = NULL,
  s = NULL,
  mu0 = NULL,
  sigma0 = NULL,
  tau = NULL,
  nu0 = NULL,
  iter = 4000,
  nu_iter = 5,
  chains = 2,
  burn_prop = 0.5,
  thin = 1,
  seed = NULL,
  verbose = TRUE
)

Arguments

posterior

A matrix of posterior draws of relative intervention effects based on a previous NMA. The (i,j) is the ith draw of the effect of intervention j.

mu_hat

A vector of estimated average relative intervention effects based on a previous NMA. The jth entry is the effect of intervention j. Ignored if posterior is supplied.

cov

A variance covariance matrix of relative intervention effects based on a previous NMA. The (i,j) entry is the covariane between intervention i and j's effects. Ignored if posterior is supplied.

s

A vector of the estimated standard deviations of each intervention. The jth entry is the standard deviation of intervention j. Ignored if posterior is supplied.

mu0

The hyperparameter mu0. If NULL, set to mean(mu_hat).

sigma0

The hyperparameter sigma_0. If NULL, set to sqrt(10*var(mu_hat)) which aims to be minimally informative.

tau

The standard deviation of the Metropolis Hastings proposal distribution. If NULL, set to min(|mu_hat_i-mu_hat_j|).

nu0

A numeric vector for the initialization of worth parameters, mu, in the MCMC algorithm. Default to NULL, indicating random initialization.

iter

A numeric indicating the total number of outer MCMC iterations (i.e., the number of times the partition is updated in the Gibbs sampler).

nu_iter

A numeric indicating the number of times each worth parameter is drawn per update of the parameter partition. There will be a total of iterxnu_iter samples from the posterior.

chains

A numeric indicating the total number of independent MCMC chains to be run.

burn_prop

A numeric between 0 and 1 indicating the proportion of MCMC samples in each chain to be removed as burn-in.

thin

A numeric indicating that only every thin-th sample should be retained, to save computational memory.

seed

A numeric indicating the random seed that should be set before running the first MCMC chain.

verbose

A boolean indicating if the function should print progress updates as the MCMC chains run. Default to TRUE.

Value

A (chainsxiter/thin)x(3J+3) matrix of posterior draws, one row per posterior sample of mu, nu, and g, with additional columns indicating the MCMC chain index, iteration index, and number of non-empty partition clusters K of each posterior sample.

Examples

mcmc <- mcmc_raceNMA(mu_hat=c(0,0,1,1), s=c(.1,.1,.1,.1), seed=1)
head(mcmc)

Partition sampling in Bayesian RaCE-NMA models (internal use only)

Description

This function implements a reversible jump MCMC procedure for updating the parameter partition in Bayesian Rank-Clustered Estimation for Network Meta-Analysis models in the case when we assume correlation among treatment effects. For internal use only.

Usage

sample_partition_correlation(
  mu_hat,
  J,
  nu,
  g,
  K,
  mu0,
  sigma0,
  cov,
  tau = tau,
  b_g = 0.5,
  d_g = 0.5
)

Arguments

mu_hat

A vector of estimated average relative intervention effects based on a previous NMA. The jth entry is the effect of intervention j.

J

A numeric indicating the total number of interventions being compared.

nu

A vector indicating current values for nu in the Gibbs sampler.

g

A vector indicating current values for g in the Gibbs sampler.

K

A vector indicating current values for K in the Gibbs sampler.

mu0

The hyperparameter mu0, usually specified as the grand mean of the average intervention effects.

sigma0

The hyperparameter sigma_0, usually a large number as to be minimally informative.

cov

A variance covariance matrix of relative intervention effects based on a previous NMA. The (i,j) entry is the covariane between intervention i and j's effects.

tau

The standard deviation of the Metropolis Hastings proposal distribution.

b_g

The probability of "birth"ing a new partition cluster, if possible. Default is 0.5.

d_g

The probability of "death"ing an existing partition cluster, if possible. Default is 0.5.

Value

A list containing updated values for g, nu, and K.

Examples

sample_partition_correlation(mu_hat=c(1,1,1),J=3,nu=1,g=c(1,1,1),K=1,mu0=1,sigma0=1,tau=0.1)

Partition sampling in Bayesian RaCE-NMA models (internal use only)

Description

This function implements a reversible jump MCMC procedure for updating the parameter partition in Bayesian Rank-Clustered Estimation for Network Meta-Analysis models in the case when we assume independence between treatment effects. For internal use only.

Usage

sample_partition_independence(
  mu_hat,
  J,
  nu,
  g,
  K,
  mu0,
  sigma0,
  s,
  tau = tau,
  b_g = 0.5,
  d_g = 0.5
)

Arguments

mu_hat

A vector of estimated average relative intervention effects based on a previous NMA. The jth entry is the effect of intervention j.

J

A numeric indicating the total number of interventions being compared.

nu

A vector indicating current values for nu in the Gibbs sampler.

g

A vector indicating current values for g in the Gibbs sampler.

K

A vector indicating current values for K in the Gibbs sampler.

mu0

The hyperparameter mu0, usually specified as the grand mean of the average intervention effects.

sigma0

The hyperparameter sigma_0, usually a large number as to be minimally informative.

s

A vector of the estimated standard deviations of each intervention. The jth entry is the standard deviation of intervention j.

tau

The standard deviation of the Metropolis Hastings proposal distribution.

b_g

The probability of "birth"ing a new partition cluster, if possible. Default is 0.5.

d_g

The probability of "death"ing an existing partition cluster, if possible. Default is 0.5.

Value

A list containing updated values for g, nu, and K.

Examples

sample_partition_independence(mu_hat=c(1,1,1),J=3,nu=1,g=c(1,1,1),
K=1,mu0=1,sigma0=1,s=c(1,1,1),tau=0.1)

Toy data of posterior relative treatment effects

Description

The dataset includes relative treatment effects for 4 treatments across 10k posterior draws, as studied in Simulation Study 2 of Pearce and Zhou (2025).

Usage

toy_data

Format

data.frame in which the (i,j) entry is the relative treatment effect of treatment j in posterior draw i.

Create trace plots for the K parameter in RaCE NMA models

Description

This function creates trace plots for the K parameter in the form of a ggplot.

Usage

traceplot_K(mcmc)

Arguments

mcmc

MCMC draws from the RaCE NMA model, in the form of the model output of the mcmc_RCMVN function.

Value

A ggplot of trace plots for the K parameter.

Examples

mcmc <- mcmc_raceNMA(mu_hat=c(0,0,1,1), s=c(.1,.1,.1,.1), seed=1)
traceplot_K(mcmc)

Create trace plots for the mu parameter in RaCE NMA models

Description

This function creates trace plots for the mu parameter in the form of a ggplot.

Usage

traceplot_mu(mcmc, names = NULL)

Arguments

mcmc

MCMC draws from the RaCE NMA model, in the form of the model output of the mcmc_RCMVN function.

names

A vector of intervention names (optional)

Value

A ggplot of trace plots for the mu parameter.

Examples

mcmc <- mcmc_raceNMA(mu_hat=c(0,0,1,1), s=c(.1,.1,.1,.1), seed=1)
traceplot_mu(mcmc,names=paste0("Treatment ",1:4))

Posterior relative treatment effects for non-baseline treatments based on Wang et. al (2022)

Description

The dataset includes relative treatment effects for 10 non-baseline treatments across 60k posterior draws based on an NMA study by Wang et. al (2022).

Usage

wang_posterior

Format

data.frame in which the (i,j) entry is the relative treatment effect of treatment j in posterior draw i.