MCPower() Constructor¶

class mcpower.MCPower(data_generation_formula)[source]¶

Bases: object

Monte Carlo Power Analysis.

Conducts simulation-based power analysis for linear regression and linear mixed-effects models. Supports continuous, binary, and factor predictors, interactions, correlated predictors, non-normal distributions, and empirical data upload.

All configuration methods (set_*) use deferred application: settings are stored as pending and processed in the correct order when apply() is called (or automatically before find_power/find_sample_size). Most set_* methods return self for method chaining.

Parameters:: data_generation_formula (str)

seed¶: Random seed for reproducibility (default: 2137).

power¶: Target power level in percent (default: 80.0).

alpha¶: Significance level (default: 0.05).

n_simulations¶: Number of Monte Carlo simulations for OLS (default: 1600).

n_simulations_mixed_model¶: Simulations for mixed models (default: 800).

parallel¶: Parallel processing mode (default: "mixedmodels").

n_cores¶: Number of CPU cores for parallel execution.

max_failed_simulations¶: Maximum acceptable failure rate (default: 0.03).

heterogeneity¶: Standard deviation for random effect-size perturbation.

heteroskedasticity¶: Correlation between predictor and error variance.

Example

>>> model = MCPower("y = x1 + x2 + x1:x2")
>>> model.set_effects("x1=0.5, x2=0.3, x1:x2=0.2")
>>> model.find_power(sample_size=100)

>>> # Mixed model with clustered data
>>> model = MCPower("y ~ treatment + motivation + (1|school)")
>>> model.set_cluster("school", ICC=0.2, n_clusters=20)
>>> model.set_effects("treatment=0.5, motivation=0.3")
>>> model.find_power(sample_size=1000)

Formula Syntax¶

Both = and ~ are accepted as separators:

MCPower("y = x1 + x2")   # equals sign
MCPower("y ~ x1 + x2")   # tilde (R-style)

Formula Patterns¶

Pattern	Meaning	Example
`y = x1 + x2`	Two main effects	Additive model with two predictors
`y = x1 * x2`	Main effects + interaction	Expands to `x1 + x2 + x1:x2`
`y = x1 + x2 + x1:x2`	Explicit interaction	Same as above, specified manually
`y ~ x + (1\|school)`	Random intercept	Mixed model with per-school intercepts
`y ~ x + (1+x\|school)`	Random intercept + slope	Mixed model with per-school intercepts and slopes for `x`
`y ~ x + (1\|school/classroom)`	Nested random effects	Classrooms nested within schools

Naming Rules¶

Variable names can contain letters, digits, and underscores
Must start with a letter or underscore (not a digit)
Case-sensitive: Treatment and treatment are different variables
Unicode letters are supported

Examples¶

from mcpower import MCPower

# Simple two-predictor model
model = MCPower("score = treatment + age")

# Full factorial with interaction
model = MCPower("y = x1 * x2")

# Mixed-effects model with random intercepts
model = MCPower("satisfaction ~ treatment + motivation + (1|school)")

Defaults After Construction¶

Attribute	Default Value
`seed`	`2137`
`alpha`	`0.05`
`power`	`80.0` (percent)
`n_simulations`	`1600` (OLS)
`n_simulations_mixed_model`	`800`
`parallel`	`"mixedmodels"`
`max_failed_simulations`	`0.03` (3%)