Quick Start

This page walks you through your first Monte Carlo power analysis with MCPower, from defining a model to interpreting the results.

Your First Power Analysis

Suppose you are planning a study to test whether a binary treatment improves satisfaction, controlling for motivation.

Step 1: Define the Model

from mcpower import MCPower

model = MCPower("satisfaction = treatment + motivation")
model.set_simulations(400)

MCPower accepts both = and ~ as separators. For full formula syntax details, see Model Specification.

Step 2: Set Effect Sizes

model.set_effects("treatment=0.5, motivation=0.3")

  • treatment=0.5 – receiving the treatment increases satisfaction by 0.5 SD (medium-large effect)

  • motivation=0.3 – each 1 SD increase in motivation increases satisfaction by 0.3 SD

For guidelines on choosing effect sizes, see Effect Sizes.

Step 3: Set Variable Types

model.set_variable_type("treatment=binary")

This tells MCPower that treatment is a 0/1 variable. For all available types, see Variable Types.

Step 4: Check Power

model.find_power(sample_size=100, target_test="treatment")

Variable types: treatment=(binary,0.5)
Effects: treatment=0.5, motivation=0.3
Model settings applied successfully

================================================================================
MONTE CARLO POWER ANALYSIS RESULTS
================================================================================

Power Analysis Results (N=100):
Test                                     Power    Target   Status  
-------------------------------------------------------------------
treatment                                72.5     80       ✗       

Result: 0/1 tests achieved target power

The target_test parameter specifies which effect to test:

Value

What It Tests

"treatment"

Power for the treatment coefficient

"overall"

F-test for the entire model

"all"

All individual coefficients + overall F-test

"treatment, motivation"

Multiple specific effects

Interpreting the Output

  • Power – percentage of simulations where the test was significant. 70.7 means the effect was detected in 70.7% of 1,600 simulated datasets.

  • Target – target power level (default: 80%).

  • Status – ✓ if power meets the target, ✗ if it falls short.

Finding the Required Sample Size

Search for the smallest sample size that achieves your target power:

model.find_sample_size(
    target_test="treatment",
    from_size=50,
    to_size=200,
    by=20,
)

This evaluates power at each sample size from 50 to 200 and reports where target power is first reached.

Control the search grid:

model.find_sample_size(
    target_test="treatment",
    from_size=50,
    to_size=300,
    by=30,  # step size
)

Add summary="long" for a full table and power curve plot:

model.find_sample_size(
    target_test="treatment",
    from_size=50,
    to_size=200,
    by=20,
    summary="long",
)

Using Variable Types

Binary Variables

model.set_variable_type("treatment=binary")          # 50/50 split
model.set_variable_type("treatment=(binary,0.3)")     # 30% receive treatment

Factor Variables

Factor variables represent categorical predictors with 3+ levels. MCPower automatically creates dummy variables (level 1 is the reference).

model = MCPower("outcome = condition + age")
model.set_simulations(400)
model.set_variable_type("condition=(factor,3)")
model.set_effects("condition[2]=0.4, condition[3]=0.6, age=0.2")

For custom group proportions:

model.set_variable_type("condition=(factor,0.2,0.5,0.3)")  # 20%, 50%, 30%

For pairwise comparisons between factor levels, see ANOVA & Post-Hoc Tests. For all variable types, see Variable Types.

Scenario Analysis

Test how robust your power is under realistic conditions:

model.find_sample_size(
    target_test="treatment",
    from_size=50,
    to_size=300,
    by=30,
    scenarios=True,
)

Variable types: treatment=(binary,0.5)
Effects: treatment=0.5, motivation=0.3
Model settings applied successfully

================================================================================
SCENARIO-BASED MONTE CARLO POWER ANALYSIS RESULTS
================================================================================

================================================================================
SCENARIO SUMMARY
================================================================================

Uncorrected Sample Sizes:
Test                                     Optimistic   Realistic    Doomer      
-------------------------------------------------------------------------------
treatment                                140          140          140         
================================================================================

Scenario

What It Simulates

When to Use

Optimistic

Your exact settings

Best-case planning

Realistic

Mild effect variations, small assumption violations

Recommended for most studies

Doomer

Larger variations, stronger violations

Conservative planning

You can also add custom scenarios with set_scenario_configs() and run specific ones by name:

model.set_scenario_configs({"extreme": {"heterogeneity": 0.6}})
model.find_power(sample_size=100, scenarios=["optimistic", "extreme"])

For details, see Scenario Analysis.

Using Your Own Data

Upload pilot data so MCPower samples from empirical distributions:

import pandas as pd

data = pd.read_csv("my_data.csv")

model = MCPower("mpg = hp + wt + cyl")
model.upload_data(data[["hp", "wt", "cyl"]])
model.set_effects("hp=0.5, wt=0.3, cyl[6]=0.2, cyl[8]=0.4")
model.find_power(sample_size=100)

MCPower auto-detects variable types based on unique values: 2 = binary, 3-6 = factor, 7+ = continuous. Override with data_types parameter. For details, see Uploading Data.

Programmatic Access to Results

Use return_results=True to get a Python dictionary:

result = model.find_power(
    sample_size=100,
    target_test="all",
    return_results=True,
    print_results=False,
)

power_treatment = result["results"]["individual_powers"]["treatment"]

Reproducibility

model.set_seed(42)
model.find_power(sample_size=100, target_test="treatment")

Next Steps