vlt.stats.permuteReplicates

  PERMUTEREPLICATES Permutes factor labels across biological replicates.

    T_shuffled = permuteReplicates(T, Observation, Factors, Replicate, FactorShuffleMask)
    T_shuffled = permuteReplicates(..., 'shuffleReplicates', true)

    PURPOSE:
    This function creates "shuffled" datasets for Null Hypothesis testing 
    and Power Analysis in Linear Mixed Models (LMMs). It preserves the 
    hierarchical structure of the data (the nesting of observations within 
    replicates) by shuffling the LABELS of whole replicates (e.g., Animals) 
    rather than shuffling individual observations.

    INPUTS:
    T (Table)
        The input data table containing raw observations.

    Observation (String)
        The column name of the dependent variable (Y).

    Factors (String Array)
        A list of column names representing the Fixed Factors in the design.
        Example: ["Strain", "Drug", "BehTrt"]

    Replicate (String)
        The column name of the Random Grouping Factor (the "Unit"). 
        This is typically AnimalID or SubjectID. 
        CRITICAL: The function assumes that observations sharing this ID 
        cannot be split apart physically.

    FactorShuffleMask (Logical Array)
        A boolean vector matching the length of Factors.
        1 (true)  = TARGET. These labels are permuted across Replicates.
        0 (false) = STRATIFIER. These labels are held fixed. Shuffling
                    is restricted to occur WITHIN groups defined by these.

    OPTIONAL PARAMETERS:
    'shuffleReplicates' (Boolean, Default: false)
        false: STANDARD MODE. Preserves Replicate integrity. Observations 
               from "Mouse A" stay together; only the Factor labels assigned 
               to "Mouse A" change. Preserves within-subject correlation.
        true:  NAIVE MODE (Destructive). Ignores the Replicate grouping 
               entirely. All observations are shuffled freely. This destroys 
               the random effect structure. Use only to test if the 
               Random Effect itself is significant.

    -----------------------------------------------------------------------
    EXAMPLE USAGE:
    -----------------------------------------------------------------------
    Suppose you have a table 'experimentData' with the following columns:
      - 'MouseID' (The biological replicate)
      - 'ReactionTime' (The observation)
      - 'Strain', 'Drug', 'Therapy' (The fixed factors)

    Goal: You want to randomize the influence of the 'Drug' factor to 
    create a null distribution, but you must ensure you only swap Drug 
    labels between mice of the same Strain and Therapy (Stratification).

        factors   = ["Strain", "Drug", "Therapy"];
        replicate = "MouseID";
        obs       = "ReactionTime";

        % Mask Definition: 0 = Stratify/Hold Fixed, 1 = Shuffle
        % We shuffle 'Drug' (index 2), keeping 'Strain' and 'Therapy' fixed.
        mask = [false, true, false]; 

        % Run the permutation
        T_null = permuteReplicates(experimentData, obs, factors, replicate, mask);

    -----------------------------------------------------------------------

    See also UNIQUE, RANDPERM, FINDGROUPS.