SIMPLELMEM Calculates statistical power for an LMEM using shuffle-based simulation.
stats = simpleLMEM(T, Observation, Replicate, FixedFactors, Mask, TargetFactor, TargetLevel, EffectSize)
stats = simpleLMEM(..., 'Simulations', 1000, 'useInteractionTerms', true)
PURPOSE:
Estimates the statistical power (probability of correctly rejecting H0)
for a specific Fixed Factor in a Linear Mixed Effects Model.
It uses a "Shuffle-First" workflow to sanitize the pilot data before
injecting the target Effect Size.
INPUTS:
T (Table)
Pilot data table.
Observation (String)
Column name for the dependent variable (Y).
If set to "" (empty string), the function attempts to auto-detect
the first numeric column not listed in FixedFactors or Replicate.
Replicate (String)
Column name for the Random Effect (e.g., "AnimalID").
FixedFactors (String Array)
List of Fixed Factors in the model (e.g., ["Strain", "Drug"]).
FactorShuffleMask (Logical Array)
The shuffle configuration. 1=Shuffle, 0=Stratify.
CRITICAL: The index corresponding to TargetFactor MUST be 1.
TargetFactor (String)
The name of the factor you are testing (e.g., "Drug").
TargetLevel (String/Numeric)
The specific group to receive the signal (e.g., "Drug_A").
EffectSize (Numeric Vector)
The magnitude(s) of the signal to inject.
If a vector is provided, power is calculated for each effect size.
OPTIONAL PARAMETERS:
'Simulations' (Integer, Default: 1000)
Number of iterations.
'Alpha' (Double, Default: 0.05)
Significance threshold.
'useConstantTerm' (Boolean, Default: true)
If true, fits 'Y ~ 1 + ...'. If false, fits 'Y ~ -1 + ...' (no intercept).
'useInteractionTerms' (Boolean, Default: false)
If true, fits full interactions between fixed factors (e.g., 'A*B').
If false, fits only main effects (e.g., 'A + B').
'verbose' (Boolean, Default: false)
If true, prints progress to command line.
'useProgressBar' (Boolean, Default: true)
If true, displays a graphical waitbar (only in serial mode).
'useRanks' (Boolean, Default: false)
If true, transforms the Observation values to ranks before computing.
'useLog' (Boolean, Default: false)
If true, transforms the Observation values to log10 before computing.
'useParallel' (Boolean, Default: true)
If true, uses parfor to run simulations in parallel.
OUTPUTS:
stats (Struct)
.power - Vector of fractions of simulations with p < Alpha (one per EffectSize)
.pValues - Matrix of p-values (Simulations x NumEffectSizes)
.successCount - Vector of number of significant hits
.simulations - Vector of total valid simulations run
.formula - The LMEM formula used
.effectSize - The input EffectSize vector
EXAMPLE:
mask = [0, 1]; % Stratify Strain, Shuffle Drug
res = vlt.stats.power.simpleLMEM(data, "ReactionTime", "MouseID", ...
["Strain", "Drug"], mask, "Drug", "Drug_A", [0, 5, 10], ...
'useInteractionTerms', true, 'useParallel', true);
See also VLT.STATS.PERMUTEREPLICATES, VLT.STATS.INJECTEFFECTTOTABLE.