vlt.stats.power.lme_power_effectsize

  LME_POWER_EFFECTSIZE - Finds the minimum detectable effect size (MDES) via simulation.

    This is the core worker function for the power analysis toolkit. It
    systematically searches for the smallest effect size that can be
    detected with a specified statistical power (the MDES).

    Process:
    1.  A baseline linear mixed-effects model is fit to the actual data to
        extract its variance components (random effects and residual error).
    2.  The function enters a loop, starting with a small hypothetical
        effect size.
    3.  In each loop iteration, it runs hundreds or thousands of simulations.
        Each simulation generates a new dataset with the same noise
        characteristics as the real data but with the current hypothetical
        effect "injected" into the specified category.
    4.  An LME model is fit to each simulated dataset, and the function
        checks if the p-value for the effect is significant (e.g., < 0.05).
    5.  The statistical power for the current effect size is calculated as
        the proportion of simulations that yielded a significant result.
    6.  If the calculated power is less than the `target_power`, the effect
        size is increased, and the loop repeats.
    7.  The loop terminates when the `target_power` is achieved, and the
        effect size from that iteration is returned as the MDES.

    Inputs:
        tbl              - The input data table.
        categories_name  - String name of the column with fixed-effect categories.
        y_name           - String name of the response variable column.
        reference_category - String name of the category to use as a baseline.
        group_name       - String name of a column for the random-effects grouping.
        category_to_test - String name of the specific category to test.
        target_power     - The desired statistical power (e.g., 0.80 for 80%).

    Name-Value Options:
        'Alpha'          - The significance level (p-value threshold). Default is 0.05.
        'NumSimulations' - The number of simulations to run at each step of the
                           effect-size search. More simulations lead to more
                           stable estimates but take longer. Default is 500.
        'EffectStep'     - The amount to increase the effect size at each
                           step of the search. If not specified (-1), it is
                           auto-calculated based on the data's standard deviation.
        'Method'         - The simulation method to use: 'gaussian', 'shuffle',
                           or 'hierarchical'. Default is 'gaussian'.

    Outputs:
        mdes        - The minimum detectable effect size for the target power.
        power_curve - A table containing the results of the search, with
                      columns 'EffectSize' and 'Power'. This is useful for
                      plotting how power changes with effect size.