various further updates to sphericity correction functionality

Author: Eric Fields

FMUT_release_notes.md

@@ -1,4 +1,4 @@
-# 0.5.0-alpha
+# 0.5.0
 
 ## Installation instructions
 
@@ -13,11 +13,7 @@ The FMUT documentation can be found at: https://github.com/ericcfields/FMUT/wiki
 ## Release Notes
 
 ### New features
-* `FfdrGND` (and relevant sub-functions) can now include a sphericity correction as long as there are no more than two factors with more than two levels
-
-### Backwards compatibility
-* A new field, `sphericity_corr`, has been added to the `F_tests` struct. Attempts to add results to a GND or GRP with results missing this field (i.e., from a previous version of FMUT) will result in an error.
-* See also Refactoring section below
+* `FfdrGND` (and relevant sub-functions) can now include a sphericity correction as long as there are no more than two factors with more than two levels.
 
 ### Bug fixes
 * `get_mean_amplitude` now removes commas from group and bin names in csv output to avoid formatting issues

FclustGND.m

@@ -134,7 +134,7 @@
 %
 %
 %AUTHOR: Eric Fields
-%VERSION DATE: 9 June 2020
+%VERSION DATE: 11 June 2020
 %
 %NOTE: This function is provided "as is" and any express or implied warranties 
 %are disclaimed. 
@@ -441,6 +441,9 @@
     if ~isfield(GND, 'F_tests') || isempty(GND.F_tests)
         GND.F_tests = results;
     else
+        if ~isfield(GND.F_tests, 'sphericity_corr')
+            [GND.F_tests(:).sphericity_corr] = deal('none');
+        end
         GND.F_tests(end+1) = results;
     end
 

FclustGRP.m

@@ -144,7 +144,7 @@
 %
 %
 %AUTHOR: Eric Fields
-%VERSION DATE: 9 June 2020
+%VERSION DATE: 11 June 2020
 %
 %NOTE: This function is provided "as is" and any express or implied warranties 
 %are disclaimed. 
@@ -496,6 +496,9 @@
     if ~isfield(GRP, 'F_tests') || isempty(GRP.F_tests)
         GRP.F_tests = results;
     else
+        if ~isfield(GRP.F_tests, 'sphericity_corr')
+            [GRP.F_tests(:).sphericity_corr] = deal('none');
+        end
         GRP.F_tests(end+1) = results;
     end
 

FfdrGND.m

@@ -120,7 +120,7 @@
 %
 %
 %AUTHOR: Eric Fields
-%VERSION DATE: 9 June 2020
+%VERSION DATE: 11 June 2020
 %
 %NOTE: This function is provided "as is" and any express or implied warranties 
 %are disclaimed. 
@@ -269,6 +269,9 @@
     if ~all(all(GND.indiv_bin_ct(:, bins)))
         watchit(sprintf('Some subjects appear to be missing data from bins used in this test!\nSee: GND.indiv_bins_ct.'));
     end
+    if ~strcmpi(p.Results.sphericity_corr, 'none') && sum(factor_levels>2)>1
+        error('Sphericity corrections are currently not available for designs with more than one factor with more than two levels');
+    end
 
 
     %% ~~~~~ SET-UP ~~~~~
@@ -419,6 +422,11 @@
     if ~isfield(GND, 'F_tests') || isempty(GND.F_tests)
         GND.F_tests = results;
     else
+        %Add sphericity_corr field if existing results were generated with
+        %with FMUT version <0.5
+        if ~isfield(GND.F_tests, 'sphericity_corr')
+            [GND.F_tests(:).sphericity_corr] = deal('none');
+        end
         GND.F_tests(end+1) = results;
     end
 

FfdrGRP.m

@@ -131,7 +131,7 @@
 %
 %
 %AUTHOR: Eric Fields
-%VERSION DATE: 9 June 2020
+%VERSION DATE: 11 June 2020
 %
 %NOTE: This function is provided "as is" and any express or implied warranties 
 %are disclaimed.  
@@ -166,6 +166,7 @@
     p.addParameter('plot_raster',   'yes',    @(x) (any(strcmpi(x, {'yes', 'no', 'n', 'y'}))));
     p.addParameter('q',             0.05,     @(x) (isnumeric(x) && x<=1 && x>=0));
     p.addParameter('method',        'bh',     @(x) any(strcmpi(x, {'bh', 'by', 'bky', 'none', 'bonferroni', 'sidak'})));
+    p.addParameter('sphericity_corr', 'none', @(x) (any(strcmpi(x, {'gg', 'hf', 'lb', 'none'}))));
     p.addParameter('time_block_dur', []);
     p.addParameter('plot_gui',       []);
     p.addParameter('plot_mn_topo',   []);
@@ -292,6 +293,9 @@
     if max(time_wind(:)) > max(GRP.time_pts)
         error('Epoch ends at %.1f ms, but ''time_wind'' input ends at %.1f ms', max(GRP.time_pts), max(time_wind(:)));
     end
+    if ~strcmpi(p.Results.sphericity_corr, 'none')
+        error('Sphericity corrections are currently not available for designs with a between subject factor');
+    end
 
 
     %% ~~~~~ SET-UP ~~~~~
@@ -469,6 +473,9 @@
     if ~isfield(GRP, 'F_tests') || isempty(GRP.F_tests)
         GRP.F_tests = results;
     else
+        if ~isfield(GRP.F_tests, 'sphericity_corr')
+            [GRP.F_tests(:).sphericity_corr] = deal('none');
+        end
         GRP.F_tests(end+1) = results;
     end
 

FmaxGND.m

@@ -108,7 +108,7 @@
 %See the FMUT documentation for more information:
 %https://github.com/ericcfields/FMUT/wiki
 %
-%VERSION DATE: 9 June 2020
+%VERSION DATE: 11 June 2020
 %AUTHOR: Eric Fields
 %
 %NOTE: This function is provided "as is" and any express or implied warranties 
@@ -428,6 +428,9 @@
     if ~isfield(GND, 'F_tests') || isempty(GND.F_tests)
         GND.F_tests = results;
     else
+        if ~isfield(GND.F_tests, 'sphericity_corr')
+            [GND.F_tests(:).sphericity_corr] = deal('none');
+        end
         GND.F_tests(end+1) = results;
     end
 

FmaxGRP.m

@@ -121,7 +121,7 @@
 %https://github.com/ericcfields/FMUT/wiki
 %
 %
-%VERSION DATE: 9 June 2020
+%VERSION DATE: 11 June 2020
 %AUTHOR: Eric Fields
 %
 %NOTE: This function is provided "as is" and any express or implied warranties 
@@ -490,6 +490,9 @@
     if ~isfield(GRP, 'F_tests') || isempty(GRP.F_tests)
         GRP.F_tests = results;
     else
+        if ~isfield(GRP.F_tests, 'sphericity_corr')
+            [GRP.F_tests(:).sphericity_corr] = deal('none');
+        end
         GRP.F_tests(end+1) = results;
     end
 

estimate_epsilon.m

@@ -1,5 +1,5 @@
-%Calculate the Greenhouse-Geisser or Hyunh-Feldt estimate of epsilon at all 
-%time points and electrodes
+%Calculate the Greenhouse-Geisser, Hyunh-Feldt, or lower bound estimate 
+%of epsilon at all time points and electrodes
 %
 %EXAMPLE USAGE
 % >> epsilon = estimate_epsilon(data, [], 3, 'gg');
@@ -19,13 +19,13 @@
 %                 calculate the main effect of A, dims = 3. If you want to
 %                 calculate the AxB interaciton, dims  = [3, 4].
 % method        - 'gg': Greenhouse-Geisser, 'hf':Hyunh-Feldt, or 'lb':
-%                 lower bound
+%                 lower bound {default: 'gg'}
 %
 %OUTPUT
-% epsilon      - electrode x time point array of GG estimate of epsilon
+% epsilon      - electrode x time point array of epsilon estimate
 %
 %
-%VERSION DATE: 9 June 2020
+%VERSION DATE: 11 June 2020
 %AUTHOR: Eric Fields
 %
 %NOTE: This function is provided "as is" and any express or implied warranties 
@@ -50,11 +50,6 @@
     %Get data reduced for analysis
     reduced_data = reduce_data(data, dims);
 
-    %Get some useful numbers
-    assert(ndims(reduced_data)==4);
-    [n_electrodes, n_time_pts, n_conds, n_subs] = size(reduced_data);
-    df_effect = n_conds - 1;
-    
     %This function currently only works for one-way fully repeated measures designs
     if ~isempty(cond_subs) && ~isequal(cond_subs, 0) && length(cond_subs) > 1
         error('estimate_epsilon curently only implemented for fully repetaed measures ANOVA');
@@ -63,6 +58,10 @@
         error('estimate_epsilon currently does not support more than one factor with more than 2 levels');
     end
 
+    %Get some useful numbers
+    [n_electrodes, n_time_pts, n_conds, n_subs] = size(reduced_data);
+    df_effect = n_conds - 1;
+    
     if strcmpi(method, 'lb')
 
         %Lower bound on epsilon

get_mean_amplitude.m

@@ -3,9 +3,12 @@
 %returned for each subject and bin involved in the test.
 %
 %Note that care should be taken with regard to analyses conducted on such
-%mean amplitudes: if analyses are not statistically indpendent of the
-%original mass univariate test, results will be biased. See:
-%Kriegeskorte, N., Simmons, W. K., Bellgowan, P. S., & Baker, C. I. (2009). Circular analysis in systems neuroscience: the dangers of double dipping. Nature Neuroscience, 12(5), 535.
+%mean amplitudes: 
+%If analyses are not statistically indpendent of the original mass univariate 
+%test, results will be biased. See:
+%Kriegeskorte, N., Simmons, W. K., Bellgowan, P. S., & Baker, C. I. (2009). 
+%Circular analysis in systems neuroscience: the dangers of double dipping. 
+%Nature Neuroscience, 12(5), 535. https://doi.org/10.1038/nn.2303
 %
 %EXAMPLE USAGE
 % >> mean_amp_data = get_mean_amplitude(GND, 2, 'effect', 'Congruency');

testing/A_setupTest.m

@@ -3,6 +3,8 @@
 %AUTHOR: Eric Fields
 %VERSION DATE: 4 March 2020
 
+clear all; close all; path(pathdef);
+
 %Add EEGLAB and MUT to path
 [ALLEEG, EEG, CURRENTSET, ALLCOM] = eeglab;