Model Specification

This page covers MCPower’s formula syntax for defining statistical models.

Formula Syntax

MCPower accepts R-style formulas. Three equivalent forms:

from mcpower import MCPower

model = MCPower("y = x1 + x2 + x1:x2")    # assignment style
model = MCPower("y ~ x1 + x2 + x1:x2")    # R-style formula
model = MCPower("x1 + x2 + x1:x2")         # predictors only (outcome auto-named)

The left side is the outcome variable; the right side lists predictors. The outcome name is optional – if omitted, MCPower creates one automatically.

---

Main Effects

List predictors separated by +:

model = MCPower("satisfaction = treatment + motivation + age")

Each predictor becomes a term in the regression model. By default, all variables are treated as continuous (standard normal). Use set_variable_type() to change types. See Variable Types.

---

Interactions

MCPower supports two interaction syntaxes:

Star notation (*) – main effects + interaction

"x1*x2"         # Equivalent to: x1 + x2 + x1:x2
"x1*x2*x3"      # All main effects + all 2-way + 3-way interactions

Colon notation (:) – interaction only

"x1:x2"          # Interaction term only (no main effects added)

Examples

# A/B test with interaction
model = MCPower("conversion = treatment + user_type + treatment:user_type")
model.set_variable_type("treatment=binary, user_type=binary")
model.set_effects("treatment=0.4, user_type=0.3, treatment:user_type=0.5")

# Equivalent using star notation
model = MCPower("conversion = treatment*user_type")

# Three-way interaction
model = MCPower("y = A*B*C")
# Expands to: A + B + C + A:B + A:C + B:C + A:B:C

Interaction effects must be set using the colon notation regardless of which formula syntax you used:

model.set_effects("treatment:user_type=0.2")

---

Mixed-Effects Formulas

MCPower supports R-style random effect specifications for clustered data:

Syntax	Structure
(1|school)	Random intercept per school
(1 + x|school)	Random intercept and slope for x per school
(1|school/classroom)	Nested random intercepts (classroom within school)

# Random intercept
model = MCPower("satisfaction ~ treatment + motivation + (1|school)")

# Random slopes
model = MCPower("y ~ x1 + (1 + x1|school)")

# Nested effects
model = MCPower("y ~ treatment + (1|school/classroom)")

Random effects require additional configuration via set_cluster(). See Mixed-Effects Models for full documentation.

---

Common Patterns

Study Design	Formula
Simple regression	"y = x1 + x2"
Binary treatment + covariate	"outcome = treatment + baseline"
Interaction	"y = treatment*covariate"
Multi-group (factor)	"wellbeing = group + age"
Two factors + interaction	"y = A*B + covariate"
Mixed model (random intercept)	"y ~ x + (1|school)"
Mixed model (random slopes)	"y ~ x + (1 + x|school)"
Mixed model (nested)	"y ~ x + (1|school/classroom)"