Title: Simulation-Based Power Analysis for Mixed-Effects Models
Version: 0.1.0
Description: A comprehensive, simulation-based toolkit for power and sample-size analysis for linear and generalized linear mixed-effects models (LMMs and GLMMs). Supports Gaussian, binomial, Poisson, and negative binomial families via 'lme4'; Wald and likelihood-ratio tests; multi-parameter sensitivity grids; power curves and minimum sample-size solvers; parallel evaluation with deterministic seeds; and full reproducibility (manifests, result bundling, and export to CSV/JSON). Delivers thorough diagnostics per run (failure rate, singular-fit rate, effective N) and publication-ready summary tables. References: Bates et al. (2015) "Fitting Linear Mixed-Effects Models Using lme4" <doi:10.18637/jss.v067.i01>; Green and MacLeod (2016) "SIMR: an R package for power analysis of generalized linear mixed models by simulation" <doi:10.1111/2041-210X.12504>.
License: MIT + file LICENSE
Encoding: UTF-8
Language: en-US
RoxygenNote: 7.3.3
Depends: R (≥ 4.1.0)
Imports: stats, lme4
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown, digest, jsonlite
VignetteBuilder: knitr
Config/testthat/edition: 3
URL: https://github.com/alitovchenko/mixpower
BugReports: https://github.com/alitovchenko/mixpower/issues
NeedsCompilation: no
Packaged: 2026-02-10 06:29:07 UTC; alexanderlitovchenko
Author: Mixpower Alex Litovchenko [aut, cre]
Maintainer: Mixpower Alex Litovchenko <al4877@columbia.edu>
Repository: CRAN
Date/Publication: 2026-02-12 08:20:18 UTC

Fit a model for a single simulated dataset

Description

Fit a model for a single simulated dataset

Usage

fit_model(data, formula)

Arguments

data

A data.frame of simulated data.

formula

A model formula.

Value

A fitted model object.


Create modeling assumptions for simulation-based power

Description

Assumptions encode effect sizes and nuisance parameters. Values may be scalars or vectors (for later sensitivity workflows), but mp_power() expects scalars unless used inside a grid wrapper.

Usage

mp_assumptions(fixed_effects, icc = NULL, residual_sd = NULL, notes = NULL)

Arguments

fixed_effects

Named list of numeric values (e.g., list(condition = 0.4)).

icc

Optional named list of ICC values in [0, 1).

residual_sd

Optional non-negative numeric residual SD.

notes

Optional free text.

Value

An object of class mp_assumptions.

Examples

a <- mp_assumptions(fixed_effects = list(condition = 0.4), residual_sd = 1)
a

Build an lme4 backend for MixPower scenarios

Description

Build an lme4 backend for MixPower scenarios

Usage

mp_backend_lme4(
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_method

Inference method: "wald" (default) or "lrt".

null_formula

Optional null-model formula required when test_method = "lrt".

Value

A list containing simulate_fun, fit_fun, and test_fun.


Build an lme4 backend for binomial GLMM scenarios

Description

Build an lme4 backend for binomial GLMM scenarios

Usage

mp_backend_lme4_binomial(
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_method

Inference method ("wald" or "lrt").

null_formula

Optional null model formula for "lrt" tests.

Value

A list containing simulate_fun, fit_fun, and test_fun.


Build an lme4 backend for Negative Binomial GLMM scenarios

Description

Build an lme4 backend for Negative Binomial GLMM scenarios

Usage

mp_backend_lme4_nb(
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_method

Inference method ("wald" or "lrt").

null_formula

Optional null model formula for "lrt" tests.

Value

A list containing simulate_fun, fit_fun, and test_fun.


Build an lme4 backend for Poisson GLMM scenarios

Description

Build an lme4 backend for Poisson GLMM scenarios

Usage

mp_backend_lme4_poisson(
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_method

Inference method ("wald" or "lrt").

null_formula

Optional null model formula for "lrt" tests.

Value

A list containing simulate_fun, fit_fun, and test_fun.


Bundle results with manifest and optional labels

Description

Combines a single result object (mp_power, mp_sensitivity, or mp_power_curve), a reproducibility manifest, and optional user labels into one object. Diagnostics and result structure are retained unchanged.

Usage

mp_bundle_results(
  result,
  manifest,
  study_id = NULL,
  analyst = NULL,
  notes = NULL
)

Arguments

result

An object of class mp_power, mp_sensitivity, or mp_power_curve.

manifest

An mp_manifest object (from mp_manifest()).

study_id

Optional character; study or run identifier.

analyst

Optional character; analyst name or ID.

notes

Optional character; free-form notes.

Value

An object of class mp_bundle with components result, manifest, and labels (list with study_id, analyst, notes).


Create a study design specification

Description

mp_design() encodes how data will be collected: cluster sizes and repeated measurements. It does not encode effect sizes or analysis decisions.

Usage

mp_design(clusters, trials_per_cell = 1, notes = NULL)

Arguments

clusters

Named list of positive integers. Example: list(subject = 50, item = 30).

trials_per_cell

Positive integer. Number of repeated observations per design cell.

notes

Optional free text.

Value

An object of class mp_design.

Examples

d <- mp_design(clusters = list(subject = 40), trials_per_cell = 10)
d

Reproducibility manifest for power analyses

Description

Captures scenario fingerprint, seed strategy, session info, timestamp, and optional git SHA so results can be reproduced or audited. Output is a plain list (and one-row data frame via as.data.frame()) suitable for saving alongside results.

Usage

mp_manifest(scenario, seed = NULL, session = TRUE)

Arguments

scenario

An mp_scenario object (used for digest).

seed

The seed value used (or NULL). Stored as-is; strategy is inferred as "fixed" if non-null else "none".

session

Include full sessionInfo() (default TRUE). If FALSE, only R version and mixpower version are stored.

Value

A list with components: scenario_digest, seed, seed_strategy, timestamp, r_version, mixpower_version, session_info (if requested), git_sha (if in a git repo). Use as.data.frame() on the list for a single-row table (list components become columns where possible).


Simulation-based power estimation (engine-agnostic core)

Description

mp_power() runs repeated simulations under a scenario and estimates power for the scenario's test decision rule (typically p < alpha).

Usage

mp_power(
  scenario,
  nsim,
  alpha = 0.05,
  seed = NULL,
  failure_policy = c("count_as_nondetect", "exclude"),
  keep = c("minimal", "fits", "data"),
  conf_level = 0.95
)

Arguments

scenario

An mp_scenario.

nsim

Positive integer number of simulations.

alpha

Significance threshold for a detection (default 0.05).

seed

Optional seed for reproducibility.

failure_policy

How to treat failed fits / missing p-values:

  • "count_as_nondetect" (default): failures count as non-detections.

  • "exclude": drop failures from the denominator (always reported).

keep

What to store:

  • "minimal": only per-sim summary rows.

  • "fits": also store fit objects (may be large).

  • "data": also store simulated data (can be very large).

conf_level

Confidence level for the Wald interval (default 0.95).

Details

In Phase 4 core, the scenario must provide engine functions: simulate_fun, fit_fun, and test_fun. Later phases will supply defaults based on specific backends (e.g., lme4).

Value

An object of class mp_power.

Examples

# A tiny toy engine (not mixed models) just to demonstrate the workflow:
d <- mp_design(list(subject = 30), trials_per_cell = 1)
a <- mp_assumptions(list(condition = 0.3), residual_sd = 1)

sim_fun <- function(scn, seed) {
  n <- scn$design$clusters$subject
  x <- stats::rbinom(n, 1, 0.5)
  y <- scn$assumptions$fixed_effects$condition * x +
    stats::rnorm(n, sd = scn$assumptions$residual_sd)
  data.frame(y = y, condition = x)
}
fit_fun <- function(dat, scn) stats::lm(scn$formula, data = dat)
test_fun <- function(fit, scn) {
  sm <- summary(fit)
  p <- sm$coefficients["condition", "Pr(>|t|)"]
  list(p_value = as.numeric(p))
}

s <- mp_scenario(
  y ~ condition, d, a,
  simulate_fun = sim_fun,
  fit_fun = fit_fun,
  test_fun = test_fun
)
res <- mp_power(s, nsim = 50, seed = 1)
summary(res)

Power curve for a single design/assumption parameter

Description

Runs mp_power() across a one-dimensional grid of values for one parameter (e.g. cluster size) via mp_sensitivity(). Results include power estimates and per-grid-point diagnostics: failure rate, singular rate, and effective N.

Usage

mp_power_curve(
  scenario,
  vary,
  nsim = 100,
  alpha = 0.05,
  seed = NULL,
  failure_policy = c("count_as_nondetect", "exclude"),
  conf_level = 0.95
)

Arguments

scenario

An mp_scenario.

vary

Named list with a single key (e.g. clusters.subject).

nsim

Number of simulations per grid point (default 100).

alpha

Significance level (default 0.05).

seed

Optional seed for reproducibility.

failure_policy

How to treat failed fits: "count_as_nondetect" or "exclude".

conf_level

Confidence level for power intervals (default 0.95).

Value

An object of class mp_power_curve with components vary, grid, results (estimate, mcse, conf_low, conf_high, failure_rate, singular_rate, n_effective, nsim, plus the varying parameter column), alpha, failure_policy, and conf_level.


Parallel power curve evaluation

Description

Evaluates power over a one-parameter grid by running mp_power() for each grid cell in parallel. Uses explicit per-cell seeds (seed + cell_index - 1L) so results are deterministic and match serial mp_power_curve() for the same seed. Does not modify mp_power(); parallelization is at the scenario-grid level only.

Usage

mp_power_curve_parallel(
  scenario,
  vary,
  workers = 2L,
  nsim = 100,
  alpha = 0.05,
  seed = NULL,
  failure_policy = c("count_as_nondetect", "exclude"),
  conf_level = 0.95,
  progress = FALSE,
  ...
)

Arguments

scenario

An mp_scenario.

vary

Named list with exactly one parameter (e.g. clusters.subject).

workers

Number of parallel workers (default 2).

nsim

Number of simulations per grid point (default 100).

alpha

Significance level (default 0.05).

seed

Optional base seed; each cell gets seed + cell_index - 1L.

failure_policy

How to treat failed fits: "count_as_nondetect" or "exclude".

conf_level

Confidence level for power intervals (default 0.95).

progress

If TRUE, run serially with a progress bar; if FALSE, run in parallel.

...

Unused; reserved for future arguments.

Value

An object of class mp_power_curve (same structure as mp_power_curve()).

Note

Parallel execution requires the parallel package (base R) and that mixpower is installed (e.g. install.packages() or devtools::install()) so that workers can load it.


Publication-ready summary table for power results

Description

Returns a flat data frame with power estimate, CI, failure/singularity rates, and effective simulation counts. Works with mp_power, mp_sensitivity, mp_power_curve, or the result of mp_bundle_results() (uses the bundled result).

Usage

mp_report_table(x, ...)

Arguments

x

An object of class mp_power, mp_sensitivity, mp_power_curve, or from mp_bundle_results().

...

Unused; reserved for future arguments.

Value

A data frame: for mp_power one row; for sensitivity/curve one row per grid cell with parameter column(s), power_estimate, ci_low, ci_high, failure_rate, singular_rate, n_effective, nsim.


Create a power-analysis scenario

Description

A scenario combines: (1) a design, (2) assumptions, (3) a model specification, and (4) an analysis engine.

Usage

mp_scenario(
  formula,
  design,
  assumptions,
  test = c("wald", "lrt", "custom"),
  simulate_fun = NULL,
  fit_fun = NULL,
  test_fun = NULL,
  notes = NULL
)

Arguments

formula

A model formula (stored for later backends).

design

An mp_design.

assumptions

An mp_assumptions.

test

Character string or list identifying the test type (metadata).

simulate_fun

Function or NULL.

fit_fun

Function or NULL.

test_fun

Function or NULL.

notes

Optional free text.

Details

In Phase 1, the engine is pluggable via three functions:

This allows mp_power() to run before selecting a specific backend (e.g., lme4).

Value

An object of class mp_scenario.

Examples

d <- mp_design(list(subject = 20), trials_per_cell = 5)
a <- mp_assumptions(list(condition = 0.3), residual_sd = 1)
s <- mp_scenario(y ~ condition, d, a, test = "wald")
s

Create a fully specified MixPower scenario with the lme4 backend

Description

Create a fully specified MixPower scenario with the lme4 backend

Usage

mp_scenario_lme4(
  formula,
  design,
  assumptions,
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_term = predictor,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

formula

Model formula.

design

A mp_design object.

assumptions

A mp_assumptions object.

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_term

Optional explicit term to test. Defaults to predictor.

test_method

Inference method: "wald" (default) or "lrt".

null_formula

Optional null-model formula required for test_method = "lrt".

Value

An object of class mp_scenario.


Create a fully specified MixPower scenario with the binomial lme4 backend

Description

Create a fully specified MixPower scenario with the binomial lme4 backend

Usage

mp_scenario_lme4_binomial(
  formula,
  design,
  assumptions,
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_term = predictor,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

formula

Model formula.

design

A mp_design object.

assumptions

A mp_assumptions object.

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_term

Optional explicit term to test. Defaults to predictor.

test_method

Inference method ("wald" or "lrt").

null_formula

Optional null model formula for "lrt" tests.

Value

An object of class mp_scenario.


Create a fully specified MixPower scenario with the NB lme4 backend

Description

Create a fully specified MixPower scenario with the NB lme4 backend

Usage

mp_scenario_lme4_nb(
  formula,
  design,
  assumptions,
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_term = predictor,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

formula

Model formula.

design

A mp_design object.

assumptions

A mp_assumptions object.

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_term

Optional explicit term to test. Defaults to predictor.

test_method

Inference method ("wald" or "lrt").

null_formula

Optional null model formula for "lrt" tests.

Value

An object of class mp_scenario.


Create a fully specified MixPower scenario with the Poisson lme4 backend

Description

Create a fully specified MixPower scenario with the Poisson lme4 backend

Usage

mp_scenario_lme4_poisson(
  formula,
  design,
  assumptions,
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  test_term = predictor,
  test_method = c("wald", "lrt"),
  null_formula = NULL
)

Arguments

formula

Model formula.

design

A mp_design object.

assumptions

A mp_assumptions object.

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

test_term

Optional explicit term to test. Defaults to predictor.

test_method

Inference method ("wald" or "lrt").

null_formula

Optional null model formula for "lrt" tests.

Value

An object of class mp_scenario.


Run power sensitivity analysis over a parameter grid

Description

Run power sensitivity analysis over a parameter grid

Usage

mp_sensitivity(
  scenario,
  vary,
  nsim = 100,
  alpha = 0.05,
  seed = NULL,
  failure_policy = c("count_as_nondetect", "exclude"),
  conf_level = 0.95
)

Arguments

scenario

A base mp_scenario object.

vary

Named list of vectors. Names are dotted paths such as "fixed_effects.condition" or "clusters.subject".

nsim

Number of simulations for each grid cell.

alpha

Significance threshold.

seed

Optional seed for reproducible cell-wise execution.

failure_policy

Failure policy passed to mp_power().

conf_level

Confidence level passed to mp_power().

Value

An object of class mp_sensitivity.


Solve for minimum sample size achieving target power

Description

Evaluates power on a user-supplied grid of values for one parameter (e.g. cluster size) via mp_power_curve(), then returns the smallest grid value whose power estimate meets or exceeds the target. Diagnostics (failure rate, singular rate, n_effective) are exposed in the returned results table.

Usage

mp_solve_sample_size(
  scenario,
  parameter,
  grid,
  target_power = 0.8,
  nsim = 100,
  alpha = 0.05,
  seed = NULL,
  failure_policy = c("count_as_nondetect", "exclude"),
  conf_level = 0.95
)

Arguments

scenario

An mp_scenario.

parameter

Dotted path of the single parameter to vary (e.g. "clusters.subject").

grid

Numeric vector of candidate values.

target_power

Target power threshold (default 0.8).

nsim

Number of simulations per grid point (default 100).

alpha

Significance level (default 0.05).

seed

Optional seed for reproducibility.

failure_policy

How to treat failed fits: "count_as_nondetect" or "exclude".

conf_level

Confidence level for power intervals (default 0.95).

Value

A list with target_power, parameter, solution (numeric: minimum grid value achieving target power, or NA if none), and results (data frame with estimate, failure_rate, singular_rate, n_effective, etc., per grid point).


Write results or bundle to CSV or JSON

Description

Writes the report table (and for bundles, manifest/labels) to file. CSV writes the publication-ready table only; JSON writes report table plus manifest and labels when x is an mp_bundle.

Usage

mp_write_results(x, file, format = c("csv", "json"), ...)

Arguments

x

An object from mp_bundle_results(), or mp_power, mp_sensitivity, or mp_power_curve.

file

Path to output file (extension need not match format).

format

"csv" or "json".

...

For CSV, arguments passed to utils::write.csv() (e.g. row.names = FALSE).

Value

Invisibly the path file.


Plot a power curve

Description

Plot a power curve

Usage

## S3 method for class 'mp_power_curve'
plot(x, y = c("estimate", "failure_rate", "singular_rate", "n_effective"), ...)

Arguments

x

An mp_power_curve object.

y

What to plot on the y-axis: "estimate" (power), "failure_rate", "singular_rate", or "n_effective".

...

Arguments passed to graphics::plot().

Value

Invisibly returns the plotted data.


Plot a one-dimensional sensitivity curve

Description

Plot a one-dimensional sensitivity curve

Usage

## S3 method for class 'mp_sensitivity'
plot(x, y = c("estimate", "failure_rate"), ...)

Arguments

x

An mp_sensitivity object.

y

What to plot on the y-axis ("estimate" or "failure_rate").

...

Additional graphical arguments passed to graphics::plot().

Value

Invisibly returns the plotted data.


Plot power results

Description

Plot power results

Usage

plot_power(results, ...)

Arguments

results

A data.frame with effect and power columns.

...

Additional arguments passed to plot.

Value

Invisibly returns the plot data.


Placeholder for parallel execution

Description

Placeholder for parallel execution

Usage

run_parallel(fun, ...)

Arguments

fun

Function to run.

...

Additional arguments to pass to fun.

Value

The result of fun.


Simulate binary outcome data for a GLMM with random intercepts

Description

Simulate binary outcome data for a GLMM with random intercepts

Usage

simulate_glmm_binomial_data(
  scenario,
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL
)

Arguments

scenario

An mp_scenario object.

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

Value

A data.frame with outcome and predictors.


Simulate count outcome data for a Negative Binomial GLMM

Description

Simulate count outcome data for a Negative Binomial GLMM

Usage

simulate_glmm_nb_data(
  scenario,
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL,
  theta = NULL
)

Arguments

scenario

An mp_scenario object.

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

theta

NB dispersion parameter (size). Larger = less over-dispersion.

Value

A data.frame with outcome and predictors.


Simulate count outcome data for a Poisson GLMM with random intercepts

Description

Simulate count outcome data for a Poisson GLMM with random intercepts

Usage

simulate_glmm_poisson_data(
  scenario,
  predictor = "condition",
  subject = "subject",
  outcome = "y",
  item = NULL
)

Arguments

scenario

An mp_scenario object.

predictor

Predictor column name.

subject

Subject ID column name.

outcome

Outcome column name.

item

Optional item ID column name.

Value

A data.frame with outcome and predictors.


Run a simple simulation-based power study

Description

Run a simple simulation-based power study

Usage

simulate_power(scenario, nsim = 100, seed = NULL)

Arguments

scenario

A scenario object.

nsim

Number of simulations.

seed

Optional random seed.

Value

A data.frame of simulated p-values.


Summarize simulation outputs

Description

Summarize simulation outputs

Usage

summarize_simulations(simulations)

Arguments

simulations

A data.frame of simulations.

Value

A summary data.frame.


Extract a test statistic for a model term

Description

Extract a test statistic for a model term

Usage

test_effect(fit, term)

Arguments

fit

A fitted model object.

term

Term name to test.

Value

A data.frame with coefficient information.