Package {stepwedgepower}

stepwedgepower: Tools for stepped-wedge clinical trial analysis and power simulation

Description

The stepwedgepower package refactors a one-off academic analysis script into reusable tools for physician-level data preparation, specialty-level rate modeling, and simulation-based planning for stepped-wedge studies.

Reproduce the core Lp(a) outcome analyses

Description

Fits the main outcome models from the original script for both overall Lp(a) testing and Lp(a) testing among patients with elevated LDL.

Usage

analyze_lpa_outcomes(
  data,
  provider_var = "prov_id",
  specialty_var = "specialty",
  outcomes = list(
    overall = list(successes = "n_lpa_pat", trials = "n_total_pat"),
    high_ldl = list(successes = "n_ldl_lpa_pat", trials = "n_ldl_pat")
  ),
  links = c("logit", "identity"),
  nAGQ = 10
)

Arguments

Value

A nested list containing fitted models and specialty-rate tables.

Convert a random-intercept standard deviation to a logistic-model ICC

Description

Convert a random-intercept standard deviation to a logistic-model ICC

Usage

cluster_sd_to_icc(cluster_sd)

Arguments

Value

The corresponding latent-scale intraclass correlation coefficient.

Examples

cluster_sd_to_icc(0.416)

Estimate power by repeated stepped-wedge simulation

Description

Monte Carlo uncertainty is reported as an exact (Clopper-Pearson) interval, which retains nominal coverage when the estimated power is at or near the boundary.

Usage

estimate_power(
  n_simulations = 100,
  alpha = 0.05,
  treatment_or = 2,
  n_clusters_per_sequence = c(10, 10, 10, 10),
  sequence_names = paste0("Sequence ", seq_along(n_clusters_per_sequence)),
  cluster_sd = 1.21,
  icc = NULL,
  baseline_probs = c(0.07, 0.04, 0.03, 0.02),
  n_per_cluster_period = 20,
  n_periods = length(n_clusters_per_sequence) + 1L,
  fit_link = c("logit", "identity"),
  seed = NULL,
  nAGQ = 1,
  effect_size_or = NULL,
  n_providers_per_specialty = NULL,
  specialty_names = NULL,
  tau_provider = NULL,
  base_probs = NULL,
  pts_per_step = NULL,
  n_steps = NULL
)

Arguments

Value

An object of class stepwedge_power containing estimated power, Monte Carlo uncertainty, fit diagnostics, and simulation p-values.

Examples

estimate_power(
  n_simulations = 20, treatment_or = 2,
  n_clusters_per_sequence = c(10, 10, 10, 10),
  baseline_probs = rep(0.05, 4), icc = 0.05,
  n_per_cluster_period = 20, seed = 1
)

Estimate specialty-specific probabilities from a fitted model

Description

Extracts specialty-level probabilities from a fitted specialty model.

Usage

estimate_specialty_rates(
  model,
  specialty_levels = NULL,
  specialty_var = "specialty",
  link = c("logit", "identity"),
  approximate_marginal = TRUE,
  logit_scale_factor = 0.346
)

Arguments

Value

A data frame with specialty-level linear predictors and probabilities.

Estimate type I error by repeated stepped-wedge simulation

Description

Equivalent to estimate_power with the treatment odds ratio set to 1.

Usage

estimate_type1_error(
  n_simulations = 100,
  alpha = 0.05,
  n_clusters_per_sequence = c(10, 10, 10, 10),
  sequence_names = paste0("Sequence ", seq_along(n_clusters_per_sequence)),
  cluster_sd = 1.21,
  icc = NULL,
  baseline_probs = c(0.07, 0.04, 0.03, 0.02),
  n_per_cluster_period = 20,
  n_periods = length(n_clusters_per_sequence) + 1L,
  fit_link = c("logit", "identity"),
  seed = NULL,
  nAGQ = 1,
  n_providers_per_specialty = NULL,
  specialty_names = NULL,
  tau_provider = NULL,
  base_probs = NULL,
  pts_per_step = NULL,
  n_steps = NULL
)

Arguments

Value

A stepwedge_power object with type1_error added.

Examples

estimate_type1_error(
  n_simulations = 20,
  n_clusters_per_sequence = c(10, 10, 10, 10),
  baseline_probs = rep(0.05, 4), icc = 0.05,
  n_per_cluster_period = 20, seed = 1
)

Fit a specialty-level testing-rate model

Description

Fits either a binomial GLM or a provider-random-intercept binomial GLMM for aggregated success/trial data.

Usage

fit_specialty_rate_model(
  data,
  successes,
  trials,
  specialty_var = "specialty",
  provider_var = NULL,
  link = c("logit", "identity"),
  random_intercept = !is.null(provider_var),
  nAGQ = 10
)

Arguments

Value

A fitted glm or merMod object.

Convert a logistic-model ICC to a random-intercept standard deviation

Description

Uses the latent-variable approximation for a logistic random-intercept model, where the level-1 variance is pi^2 / 3.

Usage

icc_to_cluster_sd(icc)

Arguments

Value

The corresponding random-intercept standard deviation.

Examples

icc_to_cluster_sd(0.05)

Prepare physician-level stepped-wedge analysis data

Description

Filters the input data to the specialties of interest, applies panel-size thresholds, removes extreme outliers, and sorts the output.

Usage

prepare_physician_data(
  data,
  specialties = c("CARDIOLOGY", "FAMILY MEDICINE", "INTERNAL MEDICINE", "NEUROLOGY"),
  min_patients = 100,
  max_patients = 10000,
  specialty_var = "specialty",
  patient_var = "n_total_pat",
  provider_name_var = "PROV_NAME"
)

Arguments

Value

A filtered and sorted data frame.

Read the bundled example physician data

Description

Reads a small synthetic physician-level example dataset bundled with the package.

Usage

read_example_physician_data()

Value

A data frame.

Fit the stepped-wedge analysis model to a simulated dataset

Description

Accepts either the generic column names (events, n, intervention, period, sequence_index, cluster_id) or the legacy 0.1.0 column names (n_positive, n_patients, treat, step, specialty_idx, PID).

Usage

run_stepwedge_analysis(sim_data, fit_link = c("logit", "identity"), nAGQ = 1)

Arguments

Value

A list with fitted model, treatment coefficient table, p-value, and convergence diagnostics.

Examples

sim <- simulate_stepwedge_trial(n_clusters_per_sequence = c(5, 5, 5, 5),
                                baseline_probs = rep(0.1, 4),
                                icc = 0.05, seed = 1)
run_stepwedge_analysis(sim)$p_value

Simulate one stepped-wedge trial dataset

Description

Generates aggregated cluster-by-period binomial data for a stepped-wedge design in which cluster sequences cross over sequentially.

Usage

simulate_stepwedge_trial(
  treatment_or = 1.5,
  n_clusters_per_sequence = c(40, 40, 40, 40),
  sequence_names = paste0("Sequence ", seq_along(n_clusters_per_sequence)),
  cluster_sd = 1.21,
  icc = NULL,
  baseline_probs = c(0.06, 0.04, 0.03, 0.02),
  n_per_cluster_period = 20,
  n_periods = length(n_clusters_per_sequence) + 1L,
  seed = NULL,
  effect_size_or = NULL,
  n_providers_per_specialty = NULL,
  specialty_names = NULL,
  tau_provider = NULL,
  base_probs = NULL,
  pts_per_step = NULL,
  n_steps = NULL
)

Arguments

Value

A data frame with one row per cluster-period combination. Generic column names are supplied together with legacy aliases for compatibility.

Examples

sim <- simulate_stepwedge_trial(
  treatment_or = 1.5,
  n_clusters_per_sequence = c(10, 10, 10, 10),
  baseline_probs = rep(0.05, 4),
  icc = 0.05,
  n_per_cluster_period = 20,
  seed = 1
)
head(sim[, c("cluster_id", "sequence", "period", "intervention", "n", "events")])

Summarize physician counts by specialty

Description

Computes common summary statistics for one or more numeric variables within each specialty.

Usage

summarize_by_specialty(
  data,
  specialty_var = "specialty",
  vars = c("n_total_pat", "n_ldl_pat"),
  na.rm = TRUE
)

Arguments

Value

A data frame with one row per specialty-variable combination.