```
███╗ ███╗ ██████╗ ██████╗
████╗ ████║ ██╔════╝ ██╔══██╗ ██████╗ ██╗ ██╗███████╗██████╗
██╔████╔██║ ██║ ██║ ██║██╔═══██╗██║ ██║██╔════╝██╔══██╗
██║╚██╔╝██║ ██║ ██████╔╝██║ ██║██║ █╗ ██║█████╗ ██████╔╝
██║ ╚═╝ ██║ ██║ ██╔═══╝ ██║ ██║██║███╗██║██╔══╝ ██╔══██╗
██║ ██║ ╚██████╗ ██║ ╚██████╔╝╚███╔███╔╝███████╗██║ ██║
╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═════╝ ╚══╝╚══╝ ╚══════╝╚═╝ ╚═╝
```
# MCPower
**Simple Monte Carlo power analysis for complex models.** Find the sample size you need or check if your study has enough power - even with complex models that traditional power analysis can't handle.
## Why MCPower?
**Traditional power analysis breaks down** with interactions, correlated predictors, categorical variables, or non-normal data. MCPower uses simulation instead of formulas - it generates thousands of datasets exactly like yours, then sees how often your analysis finds real effects.
✅ **Works with complexity**: Interactions, correlations, factors, any distribution
✅ **R-style formulas**: `outcome = treatment + covariate + treatment*covariate`
✅ **Categorical variables**: Multi-level factors automatically handled
✅ **Two simple commands**: Find sample size or check power
✅ **Scenario analysis**: Test robustness under realistic conditions
✅ **Minimal math required**: Just specify your model and effects
## Get Started in 2 Minutes
### Install
```bash
pip install mcpower
```
### Update to the latest version (every few days).
```bash
pip install --upgrade mcpower
```
### Your First Power Analysis
```python
# 0. Import installed package
import mcpower
# 1. Define your model (just like R)
model = mcpower.LinearRegression("satisfaction = treatment + motivation")
# 2. Set effect sizes (how big you expect effects to be)
model.set_effects("treatment=0.5, motivation=0.3")
# 3. Change the treatment to "binary" (people receive treatment or not).
model.set_variable_type("treatment=binary")
# 4. Find the sample size you need
model.find_sample_size(target_test="treatment", from_size=50, to_size=200, summary="long")
```
**Output**: "You need N=75 for 80% power to detect the treatment effect"
That's it! 🎉
## 🎯 Scenario Analysis: Test Your Assumptions
**Real studies rarely match perfect assumptions.** MCPower's scenario analysis tests how robust your power calculations are under realistic conditions.
```python
# Test robustness with scenario analysis
model.find_sample_size(
target_test="treatment",
from_size=50, to_size=300,
scenarios=True # 🔥 The magic happens here
)
```
**Output:**
```
SCENARIO SUMMARY
================================================================================
Uncorrected Sample Sizes:
Test Optimistic Realistic Doomer
-------------------------------------------------------------------------------
treatment 75 85 100
================================================================================
```
**What each scenario means:**
- **Optimistic**: Your ideal conditions (original settings)
- **Realistic**: Moderate real-world complications (small effect variations, mild assumption violations)
- **Doomer**: Conservative estimate (larger effect variations, stronger assumption violations)
**💡 Pro tip**: Use the **Realistic** scenario for planning. If **Doomer** is acceptable, you're really safe!
## Understanding Effect Sizes
**Effect sizes tell you how much the outcome changes when predictors change.**
- **Effect size = 0.5** means the outcome increases by **0.5 standard deviations** when:
- **Continuous variables**: Predictor increases by 1 standard deviation
- **Binary variables**: Predictor changes from 0 to 1 (e.g., control → treatment)
- **Factor variables**: Each level compared to reference level (first level)
**Practical examples:**
```python
model.set_effects("treatment=0.5, age=0.3, income=0.2")
```
- **`treatment=0.5`**: Treatment increases outcome by 0.5 SD (medium-large effect)
- **`age=0.3`**: Each 1 SD increase in age → 0.3 SD increase in outcome
- **`income=0.2`**: Each 1 SD increase in income → 0.2 SD increase in outcome
**Effect size guidelines:**
- **0.1** = Small effect (detectable but modest)
- **0.25** = Medium effect (clearly noticeable)
- **0.4** = Large effect (substantial impact)
**Effect size guidelines (binary variables):**
- **0.2** = Small effect (detectable but modest)
- **0.5** = Medium effect (clearly noticeable)
- **0.8** = Large effect (substantial impact)
**Your uploaded data is automatically standardized** (mean=0, SD=1) so effect sizes work the same way whether you use synthetic or real data.
## Copy-Paste Examples for Common Studies
### Randomized Controlled Trial
```python
import mcpower
# RCT with treatment + control variables
model = mcpower.LinearRegression("outcome = treatment + age + baseline_score")
model.set_effects("treatment=0.6, age=0.2, baseline_score=0.8")
model.set_variable_type("treatment=binary") # 0/1 treatment
# Find sample size for treatment effect with scenario analysis
model.find_sample_size(target_test="treatment", from_size=100, to_size=500,
by=50, scenarios=True)
```
### A/B Test with Interaction
```python
import mcpower
# Test if treatment effect depends on user type
model = mcpower.LinearRegression("conversion = treatment + user_type + treatment*user_type")
model.set_effects("treatment=0.4, user_type=0.3, treatment:user_type=0.5")
model.set_variable_type("treatment=binary, user_type=binary")
# Check power robustness for the interaction
model.find_power(sample_size=400, target_test="treatment:user_type", scenarios=True)
```
### Multi-Group Study with Categorical Variables
```python
import mcpower
# Study with 3 treatment groups and 4 education levels
model = mcpower.LinearRegression("wellbeing = treatment + education + age")
model.set_variable_type("treatment=(factor,3), education=(factor,4)")
# Set effects for each factor level (vs. reference level 1)
model.set_effects("treatment[2]=0.4, treatment[3]=0.6, education[2]=0.3, education[3]=0.5, education[4]=0.7, age=0.2")
# Find sample size for treatment effects
model.find_sample_size(target_test="treatment[2], treatment[3]", scenarios=True)
```
### Survey with Correlated Predictors
```python
import mcpower
# Predictors are often correlated in real data
model = mcpower.LinearRegression("wellbeing = income + education + social_support")
model.set_effects("income=0.4, education=0.3, social_support=0.6")
model.set_correlations("corr(income, education)=0.5, corr(income, social_support)=0.3")
# Find sample size for any effect
model.find_sample_size(target_test="all", from_size=200, to_size=800,
by=100, scenarios=True)
```
## Customize for Your Study
### Different Variable Types
```python
# Binary, factors, skewed, or other distributions
model.set_variable_type("treatment=binary, condition=(factor,3), income=right_skewed, age=normal")
# Binary with custom proportions (30% get treatment)
model.set_variable_type("treatment=(binary,0.3)")
# Factors with custom group sizes (20%, 50%, 30%)
model.set_variable_type("condition=(factor,0.2,0.5,0.3)")
```
### Working with Factors (Categorical Variables)
```python
# Factors automatically create dummy variables
model = mcpower.LinearRegression("outcome = treatment + education")
model.set_variable_type("treatment=(factor,3), education=(factor,4)")
# Set effects for specific levels (level 1 is always reference)
model.set_effects("treatment[2]=0.5, treatment[3]=0.7, education[2]=0.3, education[3]=0.4, education[4]=0.6")
```
### Your Own Data
```python
import pandas as pd
# Use your pilot data for realistic simulations
df = pd.read_csv('examples/cars.csv')
model.upload_own_data(df) # Automatically preserves correlations
```
### Multiple Testing
```python
# Testing multiple effects? Control false positives
model.find_power(
sample_size=200,
target_test="treatment,covariate,treatment:covariate",
correction="Benjamini-Hochberg",
scenarios=True # Test robustness too!
)
```
### Test the single violation of assumptions.
```python
# Customize how much "messiness" to add in scenarios
model.set_heterogeneity(0.2) # Effect sizes vary between people
model.set_heteroskedasticity(0.15) # Violation of equal variance assumption
# Then run scenario analysis
model.find_sample_size(target_test="treatment", scenarios=False)
```
### More precision
```python
# To make a more precise estimation, consider increasing the number of simulations.
model.set_simulations(10000)
# MCPower is already heavily optimized, but there is old code that allows for parallelization. Use it to speed up your largest simulations.
model.set_parallel(True)
```
## Quick Reference
| **Want to...** | **Use this** |
|-----------------|--------------|
| Find required sample size | `model.find_sample_size(target_test="effect_name")` |
| Check power for specific N | `model.find_power(sample_size=150, target_test="effect_name")` |
|**Test robustness** | **Add `scenarios=True` to either method** |
|**Detailed output with plots** | **Add `summary="long"` to either method** |
| Test overall model | `target_test="overall"` |
| Test multiple effects | `target_test="effect1, effect2"` or `"all"` |
| Binary variables | `model.set_variable_type("var=binary")` |
| **Factor variables** | **`model.set_variable_type("var=(factor,3)")`** |
| **Factor effects** | **`model.set_effects("var[2]=0.5, var[3]=0.7")`** |
| Correlated predictors | `model.set_correlations("corr(var1, var2)=0.4")` |
| Multiple testing correction | Add `correction="FDR", or "Holm" pr "Bonferroni"`|
## When to Use MCPower
**✅ Use MCPower when you have:**
- Interaction terms (`treatment*covariate`)
- **Categorical variables with multiple levels**
- Binary or non-normal variables
- Correlated predictors
- Multiple effects to test
- **Need to test assumption robustness**
- Complex models where traditional power analysis fails
**✅ Use Scenario Analysis when:**
- Planning important studies (grants, dissertations)
- Working with messy real-world data
- Effect sizes are uncertain
- Want conservative sample size estimates
- Stakeholders need confidence in your numbers
**❌ Use traditional power analysis for:**
- For models that are not yet implemented
- When all assumptions are clearly met
## What Makes Scenarios Different? (Be careful, unvalidated, preliminary scenarios)
**Traditional power analysis assumes perfect conditions.** MCPower's scenarios add realistic "messiness":
| **Scenario** | **What's Different** | **When to Use** |
|-------------|---------------------|------------------|
| **Optimistic** | Your exact settings | Best-case planning |
| **Realistic** | Mild effect variations, small assumption violations | **Recommended for most studies** |
| **Doomer** | Larger effect variations, stronger assumption violations | Conservative/worst-case planning |
**Behind the scenes**, scenarios randomly vary:
- Effect sizes between participants
- Correlation strengths
- Variable distributions
- Assumption violations
This gives you a **range of realistic outcomes** instead of a single optimistic estimate.
⚠️ **Important**: Scenario analysis and uploaded data features are experimental.
Use with caution for critical decisions.
<details>
<summary><strong>📚 Advanced Features (Click to expand)</strong></summary>
## Advanced Options
### All Variable Types
```python
model.set_variable_type("""
treatment=binary, # 0/1 with 50% split
ses=(binary,0.3), # 0/1 with 30% split
condition=(factor,3), # 3-level factor (equal proportions)
education=(factor,0.2,0.5,0.3), # 3-level factor (custom proportions)
age=normal, # Standard normal (default)
income=right_skewed, # Positively skewed
depression=left_skewed, # Negatively skewed
response_time=high_kurtosis, # Heavy-tailed
rating=uniform # Uniform distribution
""")
```
### Factor Variables in Detail
```python
# Factor variables are categorical with multiple levels
model = mcpower.LinearRegression("outcome = treatment + education")
# Create factors
model.set_variable_type("treatment=(factor,3), education=(factor,4)")
# This creates dummy variables automatically:
# treatment[2], treatment[3] (treatment[1] is reference)
# education[2], education[3], education[4] (education[1] is reference)
# Set effects for specific levels
model.set_effects("treatment[2]=0.5, treatment[3]=0.7, education[2]=0.3")
# Or set same effect for all levels of a factor
model.set_effects("treatment=0.5") # Applies to treatment[2] and treatment[3]
# Important: Factors cannot be used in correlations
# This will error: model.set_correlations("corr(treatment, education)=0.3")
# Use continuous variables only: model.set_correlations("corr(age, income)=0.3")
```
### Complex Correlation Structures
```python
import numpy as np
# Full correlation matrix for 3 CONTINUOUS variables only
# (Factors are excluded from correlation matrices)
corr_matrix = np.array([
[1.0, 0.4, 0.6], # Variable 1 with others
[0.4, 1.0, 0.2], # Variable 2 with others
[0.6, 0.2, 1.0] # Variable 3 with others
])
model.set_correlations(corr_matrix)
```
### Performance Tuning
```python
# Adjust for your needs
model.set_power(90) # Target 90% power instead of 80%
model.set_alpha(0.01) # Stricter significance (p < 0.01)
model.set_simulations(10000) # High precision (slower)
```
### Formula Syntax
```python
# These are equivalent:
"y = x1 + x2 + x1*x2" # Assignment style
"y ~ x1 + x2 + x1*x2" # R-style formula
"x1 + x2 + x1*x2" # Predictors only
# Interactions:
"x1*x2" # Main effects + interaction (x1 + x2 + x1:x2)
"x1:x2" # Interaction only
"x1*x2*x3" # All main effects + all interactions
```
### Correlation Syntax (Continuous Variables Only)
```python
# String format (recommended)
model.set_correlations("corr(x1, x2)=0.3, corr(x1, x3)=-0.2")
# Shorthand format
model.set_correlations("(x1, x2)=0.3, (x1, x3)=-0.2")
# Note: Factor variables cannot be correlated
# Only use continuous/binary variables in correlations
```
</details>
## Requirements
- Python ≥ 3.7
- NumPy, SciPy, scikit-learn, matplotlib
- joblib (optional, for parallel processing)
## Need Help?
- **Issues**: [GitHub Issues](https://github.com/pawlenartowicz/MCPower/issues)
- **Questions**: pawellenartowicz@europe.com
## Aim for future (waiting for suggestions)
- ✅ Linear Regression
- ✅ Scenarios, robustness analysis
- ✅ Factor variables (categorical predictors)
- 🚧 Logistic Regression (coming soon)
- 🚧 ANOVA (coming soon)
- 🚧 Guide about methods, corrections (coming soon)
- 📋 Rewriting to Cython (backend change)
- 📋 Mixed Effects Models
- 📋 2 groups comparision with alternative tests
- 📋 Robust regression methods
## License & Citation
GPL v3. If you use MCPower in research, please cite:
```bibtex
@software{mcpower2025,
author = {Pawel Lenartowicz},
title = {MCPower: Monte Carlo Power Analysis for Statistical Models},
year = {2025},
url = {https://github.com/pawlenartowicz/MCPower}
}
```
---
**🚀 Ready to start?** Copy one of the examples above and adapt it to your study!
Raw data
{
"_id": null,
"home_page": "https://github.com/pawlenartowicz/MCPower",
"name": "MCPower",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "power analysis, statistics, monte carlo, linear regression",
"author": "Pawe\u0142 Lenartowicz",
"author_email": "pawellenartowicz@europe.com",
"download_url": "https://files.pythonhosted.org/packages/79/ce/a267be9691d58349b515fc41708c70426014c8b63e30199e1b5eab5184a7/mcpower-0.3.2.tar.gz",
"platform": null,
"description": "\n\n\n\n\n\n```\n\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \n\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \n\u2588\u2588\u2554\u2588\u2588\u2588\u2588\u2554\u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\n\u2588\u2588\u2551\u255a\u2588\u2588\u2554\u255d\u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\n\u2588\u2588\u2551 \u255a\u2550\u255d \u2588\u2588\u2551 \u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u2550\u255d \u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2551\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255d \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\n\u2588\u2588\u2551 \u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\u255a\u2588\u2588\u2588\u2554\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551 \u2588\u2588\u2551\n\u255a\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d \u255a\u2550\u2550\u255d\u255a\u2550\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u255d\n```\n# MCPower\n\n**Simple Monte Carlo power analysis for complex models.** Find the sample size you need or check if your study has enough power - even with complex models that traditional power analysis can't handle.\n\n## Why MCPower?\n\n**Traditional power analysis breaks down** with interactions, correlated predictors, categorical variables, or non-normal data. MCPower uses simulation instead of formulas - it generates thousands of datasets exactly like yours, then sees how often your analysis finds real effects.\n\n\u2705 **Works with complexity**: Interactions, correlations, factors, any distribution \n\u2705 **R-style formulas**: `outcome = treatment + covariate + treatment*covariate` \n\u2705 **Categorical variables**: Multi-level factors automatically handled \n\u2705 **Two simple commands**: Find sample size or check power \n\u2705 **Scenario analysis**: Test robustness under realistic conditions \n\u2705 **Minimal math required**: Just specify your model and effects\n\n## Get Started in 2 Minutes\n\n### Install\n```bash\npip install mcpower\n```\n\n### Update to the latest version (every few days).\n```bash\npip install --upgrade mcpower\n```\n\n### Your First Power Analysis\n```python\n\n# 0. Import installed package\nimport mcpower\n\n# 1. Define your model (just like R)\nmodel = mcpower.LinearRegression(\"satisfaction = treatment + motivation\")\n\n# 2. Set effect sizes (how big you expect effects to be)\nmodel.set_effects(\"treatment=0.5, motivation=0.3\")\n\n# 3. Change the treatment to \"binary\" (people receive treatment or not).\nmodel.set_variable_type(\"treatment=binary\")\n\n# 4. Find the sample size you need\nmodel.find_sample_size(target_test=\"treatment\", from_size=50, to_size=200, summary=\"long\")\n```\n**Output**: \"You need N=75 for 80% power to detect the treatment effect\"\n\nThat's it! \ud83c\udf89\n\n## \ud83c\udfaf Scenario Analysis: Test Your Assumptions\n\n**Real studies rarely match perfect assumptions.** MCPower's scenario analysis tests how robust your power calculations are under realistic conditions.\n\n```python\n# Test robustness with scenario analysis\nmodel.find_sample_size(\n target_test=\"treatment\", \n from_size=50, to_size=300,\n scenarios=True # \ud83d\udd25 The magic happens here\n)\n```\n\n**Output:**\n```\nSCENARIO SUMMARY\n================================================================================\n\nUncorrected Sample Sizes:\nTest Optimistic Realistic Doomer \n-------------------------------------------------------------------------------\ntreatment 75 85 100 \n================================================================================\n```\n\n**What each scenario means:**\n- **Optimistic**: Your ideal conditions (original settings)\n- **Realistic**: Moderate real-world complications (small effect variations, mild assumption violations)\n- **Doomer**: Conservative estimate (larger effect variations, stronger assumption violations)\n\n**\ud83d\udca1 Pro tip**: Use the **Realistic** scenario for planning. If **Doomer** is acceptable, you're really safe!\n\n## Understanding Effect Sizes\n\n**Effect sizes tell you how much the outcome changes when predictors change.**\n\n- **Effect size = 0.5** means the outcome increases by **0.5 standard deviations** when:\n - **Continuous variables**: Predictor increases by 1 standard deviation \n - **Binary variables**: Predictor changes from 0 to 1 (e.g., control \u2192 treatment)\n - **Factor variables**: Each level compared to reference level (first level)\n\n**Practical examples:**\n```python\nmodel.set_effects(\"treatment=0.5, age=0.3, income=0.2\")\n```\n\n- **`treatment=0.5`**: Treatment increases outcome by 0.5 SD (medium-large effect)\n- **`age=0.3`**: Each 1 SD increase in age \u2192 0.3 SD increase in outcome \n- **`income=0.2`**: Each 1 SD increase in income \u2192 0.2 SD increase in outcome\n\n**Effect size guidelines:**\n- **0.1** = Small effect (detectable but modest)\n- **0.25** = Medium effect (clearly noticeable) \n- **0.4** = Large effect (substantial impact)\n\n**Effect size guidelines (binary variables):**\n- **0.2** = Small effect (detectable but modest)\n- **0.5** = Medium effect (clearly noticeable) \n- **0.8** = Large effect (substantial impact)\n\n**Your uploaded data is automatically standardized** (mean=0, SD=1) so effect sizes work the same way whether you use synthetic or real data.\n\n## Copy-Paste Examples for Common Studies\n\n### Randomized Controlled Trial\n```python\nimport mcpower\n\n# RCT with treatment + control variables\nmodel = mcpower.LinearRegression(\"outcome = treatment + age + baseline_score\")\nmodel.set_effects(\"treatment=0.6, age=0.2, baseline_score=0.8\")\nmodel.set_variable_type(\"treatment=binary\") # 0/1 treatment\n\n# Find sample size for treatment effect with scenario analysis\nmodel.find_sample_size(target_test=\"treatment\", from_size=100, to_size=500, \n by=50, scenarios=True)\n```\n\n### A/B Test with Interaction\n```python\nimport mcpower\n\n# Test if treatment effect depends on user type\nmodel = mcpower.LinearRegression(\"conversion = treatment + user_type + treatment*user_type\")\nmodel.set_effects(\"treatment=0.4, user_type=0.3, treatment:user_type=0.5\")\nmodel.set_variable_type(\"treatment=binary, user_type=binary\")\n\n# Check power robustness for the interaction\nmodel.find_power(sample_size=400, target_test=\"treatment:user_type\", scenarios=True)\n```\n\n### Multi-Group Study with Categorical Variables\n```python\nimport mcpower\n\n# Study with 3 treatment groups and 4 education levels\nmodel = mcpower.LinearRegression(\"wellbeing = treatment + education + age\")\nmodel.set_variable_type(\"treatment=(factor,3), education=(factor,4)\")\n\n# Set effects for each factor level (vs. reference level 1)\nmodel.set_effects(\"treatment[2]=0.4, treatment[3]=0.6, education[2]=0.3, education[3]=0.5, education[4]=0.7, age=0.2\")\n\n# Find sample size for treatment effects\nmodel.find_sample_size(target_test=\"treatment[2], treatment[3]\", scenarios=True)\n```\n\n### Survey with Correlated Predictors\n```python\nimport mcpower\n\n# Predictors are often correlated in real data\nmodel = mcpower.LinearRegression(\"wellbeing = income + education + social_support\")\nmodel.set_effects(\"income=0.4, education=0.3, social_support=0.6\")\nmodel.set_correlations(\"corr(income, education)=0.5, corr(income, social_support)=0.3\")\n\n# Find sample size for any effect\nmodel.find_sample_size(target_test=\"all\", from_size=200, to_size=800, \n by=100, scenarios=True)\n```\n\n## Customize for Your Study\n\n### Different Variable Types\n```python\n# Binary, factors, skewed, or other distributions\nmodel.set_variable_type(\"treatment=binary, condition=(factor,3), income=right_skewed, age=normal\")\n\n# Binary with custom proportions (30% get treatment)\nmodel.set_variable_type(\"treatment=(binary,0.3)\")\n\n# Factors with custom group sizes (20%, 50%, 30%)\nmodel.set_variable_type(\"condition=(factor,0.2,0.5,0.3)\")\n```\n\n### Working with Factors (Categorical Variables)\n```python\n# Factors automatically create dummy variables\nmodel = mcpower.LinearRegression(\"outcome = treatment + education\")\nmodel.set_variable_type(\"treatment=(factor,3), education=(factor,4)\")\n\n# Set effects for specific levels (level 1 is always reference)\nmodel.set_effects(\"treatment[2]=0.5, treatment[3]=0.7, education[2]=0.3, education[3]=0.4, education[4]=0.6\")\n```\n\n### Your Own Data\n```python\nimport pandas as pd\n\n# Use your pilot data for realistic simulations\ndf = pd.read_csv('examples/cars.csv')\nmodel.upload_own_data(df) # Automatically preserves correlations\n```\n\n### Multiple Testing\n```python\n# Testing multiple effects? Control false positives\nmodel.find_power(\n sample_size=200, \n target_test=\"treatment,covariate,treatment:covariate\",\n correction=\"Benjamini-Hochberg\",\n scenarios=True # Test robustness too!\n)\n```\n\n### Test the single violation of assumptions.\n```python\n# Customize how much \"messiness\" to add in scenarios\nmodel.set_heterogeneity(0.2) # Effect sizes vary between people\nmodel.set_heteroskedasticity(0.15) # Violation of equal variance assumption\n\n# Then run scenario analysis\nmodel.find_sample_size(target_test=\"treatment\", scenarios=False)\n```\n\n### More precision\n```python\n# To make a more precise estimation, consider increasing the number of simulations.\nmodel.set_simulations(10000)\n\n# MCPower is already heavily optimized, but there is old code that allows for parallelization. Use it to speed up your largest simulations.\nmodel.set_parallel(True)\n\n```\n\n## Quick Reference\n\n| **Want to...** | **Use this** |\n|-----------------|--------------|\n| Find required sample size | `model.find_sample_size(target_test=\"effect_name\")` |\n| Check power for specific N | `model.find_power(sample_size=150, target_test=\"effect_name\")` |\n|**Test robustness** | **Add `scenarios=True` to either method** |\n|**Detailed output with plots** | **Add `summary=\"long\"` to either method** |\n| Test overall model | `target_test=\"overall\"` |\n| Test multiple effects | `target_test=\"effect1, effect2\"` or `\"all\"` |\n| Binary variables | `model.set_variable_type(\"var=binary\")` |\n| **Factor variables** | **`model.set_variable_type(\"var=(factor,3)\")`** |\n| **Factor effects** | **`model.set_effects(\"var[2]=0.5, var[3]=0.7\")`** |\n| Correlated predictors | `model.set_correlations(\"corr(var1, var2)=0.4\")` |\n| Multiple testing correction | Add `correction=\"FDR\", or \"Holm\" pr \"Bonferroni\"`|\n\n## When to Use MCPower\n\n**\u2705 Use MCPower when you have:**\n- Interaction terms (`treatment*covariate`)\n- **Categorical variables with multiple levels**\n- Binary or non-normal variables\n- Correlated predictors\n- Multiple effects to test\n- **Need to test assumption robustness**\n- Complex models where traditional power analysis fails\n\n**\u2705 Use Scenario Analysis when:**\n- Planning important studies (grants, dissertations)\n- Working with messy real-world data\n- Effect sizes are uncertain\n- Want conservative sample size estimates\n- Stakeholders need confidence in your numbers\n\n**\u274c Use traditional power analysis for:**\n- For models that are not yet implemented\n- When all assumptions are clearly met\n\n## What Makes Scenarios Different? (Be careful, unvalidated, preliminary scenarios)\n\n**Traditional power analysis assumes perfect conditions.** MCPower's scenarios add realistic \"messiness\":\n\n| **Scenario** | **What's Different** | **When to Use** |\n|-------------|---------------------|------------------|\n| **Optimistic** | Your exact settings | Best-case planning |\n| **Realistic** | Mild effect variations, small assumption violations | **Recommended for most studies** |\n| **Doomer** | Larger effect variations, stronger assumption violations | Conservative/worst-case planning |\n\n**Behind the scenes**, scenarios randomly vary:\n- Effect sizes between participants\n- Correlation strengths \n- Variable distributions\n- Assumption violations\n\nThis gives you a **range of realistic outcomes** instead of a single optimistic estimate.\n\u26a0\ufe0f **Important**: Scenario analysis and uploaded data features are experimental. \nUse with caution for critical decisions.\n\n<details>\n<summary><strong>\ud83d\udcda Advanced Features (Click to expand)</strong></summary>\n\n## Advanced Options\n\n### All Variable Types\n```python\nmodel.set_variable_type(\"\"\"\n treatment=binary, # 0/1 with 50% split\n ses=(binary,0.3), # 0/1 with 30% split \n condition=(factor,3), # 3-level factor (equal proportions)\n education=(factor,0.2,0.5,0.3), # 3-level factor (custom proportions)\n age=normal, # Standard normal (default)\n income=right_skewed, # Positively skewed\n depression=left_skewed, # Negatively skewed\n response_time=high_kurtosis, # Heavy-tailed\n rating=uniform # Uniform distribution\n\"\"\")\n```\n\n### Factor Variables in Detail\n```python\n# Factor variables are categorical with multiple levels\nmodel = mcpower.LinearRegression(\"outcome = treatment + education\")\n\n# Create factors\nmodel.set_variable_type(\"treatment=(factor,3), education=(factor,4)\")\n\n# This creates dummy variables automatically:\n# treatment[2], treatment[3] (treatment[1] is reference)\n# education[2], education[3], education[4] (education[1] is reference)\n\n# Set effects for specific levels\nmodel.set_effects(\"treatment[2]=0.5, treatment[3]=0.7, education[2]=0.3\")\n\n# Or set same effect for all levels of a factor\nmodel.set_effects(\"treatment=0.5\") # Applies to treatment[2] and treatment[3]\n\n# Important: Factors cannot be used in correlations\n# This will error: model.set_correlations(\"corr(treatment, education)=0.3\")\n# Use continuous variables only: model.set_correlations(\"corr(age, income)=0.3\")\n```\n\n### Complex Correlation Structures\n```python\nimport numpy as np\n\n# Full correlation matrix for 3 CONTINUOUS variables only\n# (Factors are excluded from correlation matrices)\ncorr_matrix = np.array([\n [1.0, 0.4, 0.6], # Variable 1 with others\n [0.4, 1.0, 0.2], # Variable 2 with others\n [0.6, 0.2, 1.0] # Variable 3 with others\n])\nmodel.set_correlations(corr_matrix)\n```\n\n### Performance Tuning\n```python\n# Adjust for your needs\nmodel.set_power(90) # Target 90% power instead of 80%\nmodel.set_alpha(0.01) # Stricter significance (p < 0.01)\nmodel.set_simulations(10000) # High precision (slower)\n```\n\n### Formula Syntax\n```python\n# These are equivalent:\n\"y = x1 + x2 + x1*x2\" # Assignment style\n\"y ~ x1 + x2 + x1*x2\" # R-style formula \n\"x1 + x2 + x1*x2\" # Predictors only\n\n# Interactions:\n\"x1*x2\" # Main effects + interaction (x1 + x2 + x1:x2)\n\"x1:x2\" # Interaction only\n\"x1*x2*x3\" # All main effects + all interactions\n```\n\n### Correlation Syntax (Continuous Variables Only)\n```python\n# String format (recommended)\nmodel.set_correlations(\"corr(x1, x2)=0.3, corr(x1, x3)=-0.2\")\n\n# Shorthand format \nmodel.set_correlations(\"(x1, x2)=0.3, (x1, x3)=-0.2\")\n\n# Note: Factor variables cannot be correlated\n# Only use continuous/binary variables in correlations\n```\n\n</details>\n\n## Requirements\n\n- Python \u2265 3.7\n- NumPy, SciPy, scikit-learn, matplotlib\n- joblib (optional, for parallel processing)\n\n## Need Help?\n\n- **Issues**: [GitHub Issues](https://github.com/pawlenartowicz/MCPower/issues)\n- **Questions**: pawellenartowicz@europe.com\n\n## Aim for future (waiting for suggestions)\n- \u2705 Linear Regression\n- \u2705 Scenarios, robustness analysis\n- \u2705 Factor variables (categorical predictors)\n- \ud83d\udea7 Logistic Regression (coming soon)\n- \ud83d\udea7 ANOVA (coming soon)\n- \ud83d\udea7 Guide about methods, corrections (coming soon)\n- \ud83d\udccb Rewriting to Cython (backend change)\n- \ud83d\udccb Mixed Effects Models\n- \ud83d\udccb 2 groups comparision with alternative tests\n- \ud83d\udccb Robust regression methods\n\n\n## License & Citation\n\nGPL v3. If you use MCPower in research, please cite:\n\n```bibtex\n@software{mcpower2025,\n author = {Pawel Lenartowicz},\n title = {MCPower: Monte Carlo Power Analysis for Statistical Models},\n year = {2025},\n url = {https://github.com/pawlenartowicz/MCPower}\n}\n```\n\n---\n\n**\ud83d\ude80 Ready to start?** Copy one of the examples above and adapt it to your study!\n",
"bugtrack_url": null,
"license": null,
"summary": "Monte Carlo Power Analysis for Statistical Models",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/pawlenartowicz/MCPower"
},
"split_keywords": [
"power analysis",
" statistics",
" monte carlo",
" linear regression"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8f0f8f9cf45709a68b8464b8cb95861e02e67bd73ecf0459901955a163bfa843",
"md5": "9419cb0bc8bd4301d6b5af22b50dbc6f",
"sha256": "03ad7e443aead499f36397b5238b54a8b9128b558f6873d84ed94141e9a3859e"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp310-cp310-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "9419cb0bc8bd4301d6b5af22b50dbc6f",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 240379,
"upload_time": "2025-07-27T17:57:42",
"upload_time_iso_8601": "2025-07-27T17:57:42.693601Z",
"url": "https://files.pythonhosted.org/packages/8f/0f/8f9cf45709a68b8464b8cb95861e02e67bd73ecf0459901955a163bfa843/mcpower-0.3.2-cp310-cp310-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b4e76e9f15583b21080f16b4c6bd4b21a1689dc58b8190d0a6d6db02832671a",
"md5": "1989df9cac714ac18236991a91d121c1",
"sha256": "11c3044ba4c9470eea3ce3e48f3837e826a46c08d9c0834a6935c096335e0229"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "1989df9cac714ac18236991a91d121c1",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 617916,
"upload_time": "2025-07-27T17:57:44",
"upload_time_iso_8601": "2025-07-27T17:57:44.039556Z",
"url": "https://files.pythonhosted.org/packages/5b/4e/76e9f15583b21080f16b4c6bd4b21a1689dc58b8190d0a6d6db02832671a/mcpower-0.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "44433e168b4e154d4e22f77fdecb51441c369a3bf9dcb8d1807a87685b073ca9",
"md5": "c9b0b82d17a74734880f32a5e36e7ab4",
"sha256": "a8826eda30dc9ffdcbbce2562ff57a6f5ee59c4a70c20f6c2799f57e89d04d74"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "c9b0b82d17a74734880f32a5e36e7ab4",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 186207,
"upload_time": "2025-07-27T17:57:44",
"upload_time_iso_8601": "2025-07-27T17:57:44.957582Z",
"url": "https://files.pythonhosted.org/packages/44/43/3e168b4e154d4e22f77fdecb51441c369a3bf9dcb8d1807a87685b073ca9/mcpower-0.3.2-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c29704178181ba8d3962badb6a5e133b399a1803a032a85f35db4164a81b945d",
"md5": "50d27973fa8a900a0facd0a43ef6e2ec",
"sha256": "39aec3baf20cb0050453c6cc40ab9450c6183a38860e711b1774fe6054b96845"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp311-cp311-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "50d27973fa8a900a0facd0a43ef6e2ec",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 416894,
"upload_time": "2025-07-27T17:57:46",
"upload_time_iso_8601": "2025-07-27T17:57:46.298615Z",
"url": "https://files.pythonhosted.org/packages/c2/97/04178181ba8d3962badb6a5e133b399a1803a032a85f35db4164a81b945d/mcpower-0.3.2-cp311-cp311-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "531ec76bb2175e7d37e31e9d459b5d290b0a481b483d7cd9a09277fb142f1047",
"md5": "408c7f05c97c75f776d33478876ef762",
"sha256": "c2b21f4b5a57140147334509dedc3e5ec314d00bf15756b5cc96f13d72c7f923"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "408c7f05c97c75f776d33478876ef762",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 1180484,
"upload_time": "2025-07-27T17:57:47",
"upload_time_iso_8601": "2025-07-27T17:57:47.665808Z",
"url": "https://files.pythonhosted.org/packages/53/1e/c76bb2175e7d37e31e9d459b5d290b0a481b483d7cd9a09277fb142f1047/mcpower-0.3.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b06e9d7a848b361593804463a9b5af8e45ef6263888650faf004d55b2f58b35e",
"md5": "4bb7d4559c4428ee578b8f01ba16149b",
"sha256": "5073e06e1406ae39dba61847707a7b36729efcbcb3cd49cc11d0554cb239e0ae"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp311-cp311-win_amd64.whl",
"has_sig": false,
"md5_digest": "4bb7d4559c4428ee578b8f01ba16149b",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 307495,
"upload_time": "2025-07-27T17:57:48",
"upload_time_iso_8601": "2025-07-27T17:57:48.615611Z",
"url": "https://files.pythonhosted.org/packages/b0/6e/9d7a848b361593804463a9b5af8e45ef6263888650faf004d55b2f58b35e/mcpower-0.3.2-cp311-cp311-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "477f21e874dbc2e5c60a28b809371b1a65e397eb61c1c43aaba0f613a43aab0c",
"md5": "73f074eebcd147cee32b1a81bb50229f",
"sha256": "f45dd0014e1ce2e00a65d0c021271446b53d58a6ee883476ada96ed320d45e72"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp312-cp312-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "73f074eebcd147cee32b1a81bb50229f",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 593088,
"upload_time": "2025-07-27T17:57:49",
"upload_time_iso_8601": "2025-07-27T17:57:49.802772Z",
"url": "https://files.pythonhosted.org/packages/47/7f/21e874dbc2e5c60a28b809371b1a65e397eb61c1c43aaba0f613a43aab0c/mcpower-0.3.2-cp312-cp312-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "baf69abbb3f86477fc1215c678b8222f0b40f11d9ac6a76e2d54f6b182a7c859",
"md5": "81ae1c3c706525a5390df67bff829d51",
"sha256": "3ac2b15c8af694ea3437ff8490d6bf74b1ef70ccd6f5df18bcd795f15114c32d"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "81ae1c3c706525a5390df67bff829d51",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 1746780,
"upload_time": "2025-07-27T17:57:51",
"upload_time_iso_8601": "2025-07-27T17:57:51.108157Z",
"url": "https://files.pythonhosted.org/packages/ba/f6/9abbb3f86477fc1215c678b8222f0b40f11d9ac6a76e2d54f6b182a7c859/mcpower-0.3.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "888b459fec4f9f2b73c7a078741036d2894c4828f3fd45a1efa69f8ba585d4c2",
"md5": "74076e7cdcde57c892c7889f2214325e",
"sha256": "ad02d5b50a8f5a5db03e2b71ccaaecf9a0b232c26536e811c50e601b13581915"
},
"downloads": -1,
"filename": "mcpower-0.3.2-cp312-cp312-win_amd64.whl",
"has_sig": false,
"md5_digest": "74076e7cdcde57c892c7889f2214325e",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 428877,
"upload_time": "2025-07-27T17:57:52",
"upload_time_iso_8601": "2025-07-27T17:57:52.426972Z",
"url": "https://files.pythonhosted.org/packages/88/8b/459fec4f9f2b73c7a078741036d2894c4828f3fd45a1efa69f8ba585d4c2/mcpower-0.3.2-cp312-cp312-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "79cea267be9691d58349b515fc41708c70426014c8b63e30199e1b5eab5184a7",
"md5": "a9e0335bc48ead65de13f560db860058",
"sha256": "4903f809dbe5e479e06aae145fd6357ddd846d68d561bc0f0bd266d55982f7bb"
},
"downloads": -1,
"filename": "mcpower-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "a9e0335bc48ead65de13f560db860058",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 67411,
"upload_time": "2025-07-27T17:57:53",
"upload_time_iso_8601": "2025-07-27T17:57:53.633842Z",
"url": "https://files.pythonhosted.org/packages/79/ce/a267be9691d58349b515fc41708c70426014c8b63e30199e1b5eab5184a7/mcpower-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 17:57:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pawlenartowicz",
"github_project": "MCPower",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcpower"
}
JSON
