vlt.stats.power.power2corrcoef

  VLT.STATS.POWER.POWER2CORRCOEF - Calculate statistical power for a correlation test by simulation

    P = VLT.STATS.POWER.POWER2CORRCOEF(SAMPLE1, SAMPLE2, CORRELATIONS, ...)

    Calculates the statistical power of a correlation test by simulation.

    This function assesses the probability of correctly detecting a significant
    correlation of a specified magnitude. For each target correlation value in
    the `correlations` vector, it runs multiple simulations. In each simulation,
    it generates new data by re-pairing `sample1` and `sample2` to have that
    target rank correlation, and then performs a statistical test to see if a
    significant correlation is found. The fraction of simulations that yield a
    significant result is the estimated power.

    This method preserves the exact marginal distributions of the original samples.

    Inputs:
    - SAMPLE1: A numerical vector of samples.
    - SAMPLE2: A numerical vector of samples, same size as SAMPLE1.
    - CORRELATIONS: A vector of target correlation coefficients to examine.

    Optional Name-Value Pairs:
    - 'test' ('corrcoef' | 'corrcoefResample'): The statistical test to use.
      'corrcoef' uses MATLAB's built-in `corr` function (t-test based).
      'corrcoefResample' uses `vlt.stats.corrcoefResample` for a permutation-based test.
      Default is 'corrcoef'.
    - 'alpha' (0 < alpha < 1): The significance level. Default is 0.05.
    - 'numSimulations' (integer > 0): The number of simulations. Default is 1000.
    - 'resampleNum' (integer > 0): Number of resamples for 'corrcoefResample'. Default is 1000.
    - 'verbose' (logical): If true, displays progress. Default is true.
    - 'plot' (logical): If true, plots the power curve. Default is true.
    - 'titleText' (string): The title for the plot.
    - 'xLabel' (string): The x-axis label for the plot.
    - 'yLabel' (string): The y-axis label for the plot.

    Output:
    - P: A vector the same size as CORRELATIONS, indicating the fraction of
      simulations where the test yielded a significant correlation.

    Example:
      % Generate some data and calculate power
      sample1 = randn(1, 20);
      sample2 = randn(1, 20);
      correlations = -1:0.2:1;
      p = vlt.stats.power.power2corrcoef(sample1, sample2, correlations, 'test', 'corrcoef');

    See also: VLT.STATS.POWER.IMPOSECORRELATIONBYREORDERING, CORR, VLT.STATS.CORRCOEFRESAMPLE