vlt.stats.spatialCorrelationSignificance

  SPATIALCORRELATIONSIGNIFICANCE Estimate significance of correlation between two spatial index maps

  This function estimates the significance of correlation between two spatial index maps
  (indexA and indexB) while accounting for spatial autocorrelation. It uses toroidal
  shifts (random X/Y offsets) of indexB to create a null distribution of correlation
  values that preserves the spatial structure of the data.

  Syntax:
    [p, r_observed, r_null_distribution] = spatialCorrelationSignificance(indexA, indexB)
    [p, r_observed, r_null_distribution] = spatialCorrelationSignificance(indexA, indexB, options)

  Inputs:
    indexA          - 2D matrix containing the first index values (e.g., response to stimulus A)
    indexB          - 2D matrix containing the second index values (e.g., response to stimulus B)
    options         - Structure with optional parameters:
        .mask           - Logical 2D matrix specifying pixels to include (default: all pixels)
        .n_permutations - Number of random toroidal shifts to perform (default: 1000)
        .max_shift     - Maximum allowed shift in pixels (default: size(indexA)/2)
        .alpha         - Significance level (default: 0.05)
        .plot_results  - Logical flag to generate summary plot (default: false)

  Outputs:
    p                 - p-value for the observed correlation
    r_observed        - Observed correlation coefficient between indexA and indexB
    r_null_distribution - Vector of correlation values from the null distribution

  Example:
    % Generate sample data
    indexA = randn(50, 50);
    indexB = indexA*0.3 + randn(50, 50)*0.9; % Related but noisy

    % Set options
    plot_results = true;
    n_permutations = 2000; % Increase number of permutations
    mask = indexA > -1; % Example: custom mask based on data values

    % Estimate significance
    [p, r_obs, r_null] = spatialCorrelationSignificance(indexA, indexB, ...
       'plot_results',plot_results,'n_permutations',n_permutations,...
       'mask',mask);
    fprintf('Observed correlation: %.3f, p-value: %.3f\n', r_obs, p);

  Notes:
    - Both index maps must be the same size
    - The function uses toroidal shifts (wrapping around edges) to maintain the
      spatial autocorrelation structure in the permutation test
    - NaN values in either index map will be excluded from analysis

  See also: CORRCOEF, CIRCSHIFT