Package 'spima'

Description

A dataset of study-level summary statistics for continuous outcomes (blood pressure) from multiple clinical trials. Contains mean, standard deviation, and sample size per arm, suitable for the continuous module.

Usage

bp_cont

Format

A data frame with columns:

study

Study identifier.

group

Treatment group indicator (0 = control, 1 = treatment).

n

Sample size per arm.

mean

Mean blood pressure.

sd

Standard deviation of blood pressure.

Description

Each module exports a distance function that compares simulated summary statistics to the observed summary statistics.

Usage

spima_bin_distance(sim_stats, obs_stats)

spima_cont_distance(sim_stats, obs_stats)

Arguments

Value

A non-negative scalar distance.

Functions

• spima_bin_distance(): Binary outcome: Euclidean distance on (possibly weighted) log-odds scale.

• spima_cont_distance(): Continuous outcome: inverse-variance weighted Euclidean distance on study-level mean differences.

Description

Draws a forest plot showing study-level effect estimates with 95% CIs and the SPI-MA pooled posterior estimate.

Usage

## S3 method for class 'spima'
forest(
  x,
  log_scale = FALSE,
  study_labels = NULL,
  col = "grey40",
  pooled_col = "#2166AC",
  xlab = NULL,
  ...
)

spima_forest(x, ...)

Arguments

Description

A dataset of study-level summary statistics for generic (continuous) effect sizes. Contains effect size estimates and their standard errors, suitable for the generic module.

Usage

gen_effect

Format

A data frame with columns:

study

Study identifier.

yi

Effect size estimate.

sei

Standard error of the effect size.

Description

A dataset of study-level summary statistics for binary outcomes (kidney disease) from multiple clinical trials. Contains event counts and sample sizes per arm, suitable for the binary module.

Usage

kidney_bin

Format

A data frame with columns:

study

Study identifier.

group

Treatment group indicator (0 = control, 1 = treatment).

n

Sample size per arm.

event

Number of events per arm.

Description

Evaluate log-prior density for a parameter vector

Usage

log_prior_density(theta, prior_obj)

Arguments

Value

Log-density value (summed across independent priors).

Description

Generates a plot showing how the predicted treatment effect (absolute risk difference or risk ratio) varies across the range of a continuous covariate, based on interaction estimates from spima_int.

Usage

## S3 method for class 'spima_int'
plot(
  x,
  covariate = NULL,
  ci_level = 0.95,
  at = NULL,
  scale = c("absolute", "relative"),
  ...
)

Arguments

Details

The underlying model is either the pseudo-IPD individual-level GLMM (preferred) or the aggregate ecological GLMM (fallback). Uncertainty is propagated by sampling from the multivariate normal approximation of the fixed effects.

Value

A ggplot object.

Examples

## Not run: 
res <- spima_int(data, input_spec)
plot(res, covariate = "X1", scale = "absolute")

## End(Not run)

Description

Define Prior Distributions for ABC-SMC Parameters

Usage

prior(mu = "normal(0, 10)", tau = "halfnormal(0, 1)", ...)

Arguments

Value

A list of class spima_prior with elements name, pars, rfun (random generation), dfun (density), and default.

Examples

prior(mu = "normal(0, 10)", tau = "halfnormal(0, 1)")

Description

Run ABC-SMC Inference

Usage

run_abc_smc(prior_obj, sim_fn, distance_fn, obs_stats, ctrl, ...)

Arguments

Value

A list of class spima_abc containing posterior samples, weights, diagnostics, and generation records.

Description

Sample from the joint prior

Usage

sample_prior(n, prior_obj)

Arguments

Value

A matrix with n rows and one column per prior.

Description

Control Parameters for ABC-SMC

Usage

smc_control(
  n_particles = 2000,
  n_particles_max = 10000,
  n_generations = 10,
  epsilon_init = NULL,
  epsilon_decay = 0.85,
  ess_min = 0.3,
  kernel = "gaussian",
  accept_rate_target = 0.2,
  verbose = TRUE,
  parallel = FALSE,
  n_cores = NULL
)

Arguments

Value

A list of class smc_control.

Examples

smc_control(n_particles = 500, n_generations = 8)

Description

The main entry point. Dispatches to the appropriate module based on outcome_type and runs ABC-SMC for meta-analytic inference.

Usage

spima(
  data,
  outcome_type = c("binary", "continuous", "generic"),
  input_spec,
  prior,
  smc_control,
  parallel = FALSE,
  subgroup = NULL,
  family = c("gaussian", "Gamma"),
  ...
)

Arguments

Value

A spima object with components:

Examples

## Not run: 
# Binary outcome meta-analysis (two-arm per study)
data_bin <- data.frame(
  study = 1:4,
  group = c(0, 1, 0, 1, 0, 1, 0, 1),
  event = c(30, 45, 28, 32, 40, 58, 18, 22),
  n     = c(100, 100, 80, 80, 120, 120, 60, 60)
)
res <- spima(data_bin, "binary",
             input_spec = list(study = "study", event = "event",
                               n = "n", group = "group"),
             prior = prior(mu = "normal(0, 10)", tau = "halfnormal(0, 1)"),
             smc_control = smc_control(n_particles = 500, n_generations = 5))

## End(Not run)

Description

Computes per-study log odds ratios from the simulated pseudo-IPD by constructing 2x2 tables. Also fits a one-stage logistic mixed model (glmer) for the overall treatment effect estimate.

Usage

spima_bin_analyze(pseudo_ipd, input_spec)

Arguments

Value

A list with estimates (mixed-model fixed effects), summary_stats (named vector of per-study log ORs, matching the format from spima_bin_observed_stats), and converged (logical).

Description

Compute Observed Summary Statistics for Binary Data

Usage

spima_bin_observed_stats(data, input_spec)

Arguments

Value

Named vector of observed log-ORs (or log-odds) with optional inverse-variance weights as attribute.

Description

For each study, the control-group proportion is taken from observed data, and the treatment-group log-odds are shifted by a study-specific effect drawn from N(mu, tau^2). Individual Bernoulli outcomes are then generated.

Usage

spima_bin_simulate(study_spec, params, input_spec)

Arguments

Value

A data frame with columns study, group, y.

Description

Validate Binary Outcome Input

Usage

spima_bin_validate(data, input_spec)

Arguments

Value

TRUE invisibly; stops with a message on failure.

Description

Computes per-study mean differences from the simulated pseudo-IPD. Also attempts a linear mixed model (lmer) for overall estimate.

Usage

spima_cont_analyze(pseudo_ipd, input_spec)

Arguments

Value

A list with estimates, summary_stats (per-study mean differences and pooled SDs, matching observed_stats format), and converged.

Description

Compute Observed Summary Statistics for Continuous Data

Usage

spima_cont_observed_stats(data, input_spec)

Arguments

Value

A list with means and sds (named vectors).

Description

For each study, individual data are drawn from a normal (or skew-normal) distribution matching the observed mean and SD. The treatment group mean is shifted by a study-specific effect drawn from N(mu, tau^2).

Usage

spima_cont_simulate(study_spec, params, input_spec)

Arguments

Value

A data frame with columns study, group, y.

Description

Validate Continuous Outcome Input

Usage

spima_cont_validate(data, input_spec)

Arguments

Value

TRUE invisibly.

Description

Fits a one-stage Gamma GLMM via glmer(y ~ group + (1 | study), family = Gamma(link = "log")) on the simulated pseudo-IPD. Also returns per-study log-Rate Ratio values for use as summary statistics in the ABC distance computation.

Usage

spima_gamma_analyze(pseudo_ipd, input_spec, quick = TRUE)

Arguments

Details

Use quick = TRUE (default) during ABC-SMC sampling where only the per-study summary statistics are needed for distance computation. Set quick = FALSE to additionally fit the full GLMM (useful for external diagnostics).

Value

A list with components:

estimates

Named vector of fixed effects from the Gamma GLMM (or NULL if quick = TRUE or the model does not converge).

summary_stats

Named vector of per-study log-RR values.

converged

Logical indicating GLMM convergence (TRUE when quick = TRUE).

fit

The glmer fit object (or NULL).

Description

Weighted Euclidean distance on the per-study log-Rate Ratio vector. Delegates to spima_generic_distance.

Usage

spima_gamma_distance(sim_stats, obs_stats)

Arguments

Description

For each study, computes the observed log-Rate Ratio and its delta-method variance for inverse-variance weighting.

Usage

spima_gamma_observed_stats(data, input_spec)

Arguments

Value

A named vector of per-study log-RR values with an attribute "weights" containing inverse-variance weights.

Description

For each study, individual data are drawn from a Gamma distribution matching the observed mean and SD via method-of-moments. The treatment group mean is shifted by a multiplicative factor exp(theta_i) where theta_i ~ N(mu, tau^2) — this encodes the log-Rate Ratio treatment effect on the original scale. The shape parameter is held constant within each study, preserving the variance structure implied by the Gamma GLM with log link.

Usage

spima_gamma_simulate(study_spec, params, input_spec)

Arguments

Value

A data frame with columns study, group, y.

Description

Delegates to spima_cont_validate (same data format: mean, sd, n per arm) and additionally checks that all means are positive (Gamma distribution is supported on the positive real line).

Usage

spima_gamma_validate(data, input_spec)

Arguments

Value

TRUE invisibly.

Description

For the generic module, the "pseudo-IPD" is already the summary statistics (a vector of effect sizes). This function simply passes them through with converged = TRUE.

Usage

spima_generic_analyze(pseudo_ipd, input_spec)

Arguments

Value

A list with estimates = NULL, summary_stats (the effect-size vector), and converged = TRUE.

Description

Weighted Euclidean distance using inverse-variance weights.

Usage

spima_generic_distance(sim_stats, obs_stats)

spima_generic_distance(sim_stats, obs_stats)

Arguments

Description

Compute Observed Summary Statistics for Generic Effect-Size

Usage

spima_generic_observed_stats(data, input_spec)

Arguments

Value

Named vector of effect sizes with "weights" attribute (inverse-variance: 1/sei^2).

Description

No individual-level data is generated. Instead, study-level effect sizes are drawn from the random-effects model: theta_i ~ N(mu, tau^2) y_i* ~ N(theta_i, sei_i^2)

Usage

spima_generic_simulate(study_spec, params, input_spec)

Arguments

Details

The returned vector can be treated as "pseudo-IPD" since it directly represents the summary statistics needed for distance computation.

Value

A named numeric vector of simulated effect sizes (one per study).

Description

Validate Generic Effect-Size Input

Usage

spima_generic_validate(data, input_spec)

Arguments

Value

TRUE invisibly.

Description

Tests whether continuous covariate(s) modify the treatment effect using aggregate data only. The primary method fits a mixed-effects logistic regression on the aggregate data. A sensitivity analysis generates pseudo-IPD and fits an individual-level model.

Usage

spima_int(data, input_spec, rho = 0, ...)

spima_int_validate(data, input_spec)

Arguments

Value

spima_int object.