Variable types for power simulation

Every predictor you set up has a type that tells MCPower how to draw its simulated values: continuous for numbers on a scale, binary for two 0/1 groups, or factor for a category with three or more levels. The type also decides how the predictor enters the model. A predictor you don't classify defaults to continuous standard normal.

The three core types

• Continuous — numeric values on a scale. Default shape is standard normal, \(N(0,1)\).
• Binary — two groups coded 0/1 (treatment/control, yes/no). Default split is 50/50; custom proportions are supported.
• Factor — a category with three or more levels, dummy-coded against a reference level. Each non-reference level becomes its own term with its own effect size.

A predictor left unspecified defaults to continuous standard normal.

Continuous distribution shapes

Continuous predictors don't have to be normal. Choosing a realistic shape makes your power estimate robust to the messiness of real data.

Statistical properties

Every shape is standardized to mean 0 and variance 1, so swapping shapes changes only the shape — never the scale of your effect sizes. No synthetic shape ever emits a value beyond ±6 SD, so a single simulated point can't dominate the fit.

The skewed shapes sit at the upper edge of skewness observed in large surveys of real psychological and biomedical data, and high-kurtosis is the heaviest-tailed shape in the family.

Factors and the reference level

A factor is a category with three or more levels, and one level is the reference that every other level is compared against — the first level you list, or the first sorted value in uploaded data. Each non-reference level becomes its own dummy variable with its own effect size. When you simulate from uploaded data, dummies keep the original data values in their names — cyl[6], cyl[8], origin[Japan] — rather than integer indices, so the output reads the way your data does.

How a type is determined

Declared designs (no uploaded data) involve no inference: every predictor is continuous standard normal unless you declare it binary, a factor, or a different continuous shape.

Uploaded data is auto-detected per column:

A factor — detected or declared — can have at most 20 levels; a column with more is rejected as a factor. You can override any detection with an explicit declaration. See using empirical data for how detection and overrides work when simulating from a real dataset.

Common patterns

Pin rule. Declaring any explicit continuous distribution — including explicit "normal" — pins that predictor against scenario distribution swaps. An unpinned predictor (left at the default) may be swapped to a non-normal shape by the distribution_change_prob knob. If you want a predictor to stay normal regardless of scenario, declare it explicitly.

Residual distribution

The residual distribution is the shape of the noise term — the unexplained scatter MCPower adds to each simulated outcome around its predicted value. The five choices are the same shapes as for predictors (normal, right_skewed, left_skewed, high_kurtosis, uniform), and the default is normal. Setting it with set_residual_distribution(name) pins the shape so scenario swaps leave it alone.

The five valid names:

There is no df= parameter on set_residual_distribution. The df for high_kurtosis is always scenario-supplied — set it via set_scenario_configs({"your_scenario": {"residual_df": 5}}). Calling set_residual_distribution with any name, including "normal", pins the residual: scenario residual swaps leave it alone. The unpinned default — not calling set_residual_distribution at all — is the only state where swaps can fire.

The conceptual point is that type, distribution shape, and residual shape are all part of your design assumptions — perturbing the unpinned ones is exactly what scenario analysis does. For the exact syntax in each port, see the tutorials.

Residuals and heteroskedasticity

Heteroskedasticity means the residual variance is not constant — the spread of the noise depends on a predictor instead of being the same everywhere. Linear models assume the opposite (constant variance), so this is an assumption violation worth stress-testing. The driver control names the continuous predictor whose value scales that variance; set it with set_heteroskedasticity_driver(var), where var is a continuous predictor or the predicted value (the default).

The driver only says which predictor governs the spread. How much the variance changes along it is the ratio λ, which comes from the active scenario, not the model — so heteroskedasticity is exercised through scenario analysis. The driver is restricted to continuous predictors and applies to linear models only.

model.set_heteroskedasticity_driver("x1")

model$set_heteroskedasticity_driver("x1")

See the heteroskedasticity section of scenario analysis for what λ means, the preset values, and how to set a known ratio.