Merge pull request #15 from nicholst/snpm_rel

SnPM release 13.1.04
SnPM-toolbox · Jul 22, 2016 · 5b66750 · 5b66750
2 parents 475275e + 6e2c4e3
commit 5b66750
Show file tree

Hide file tree

Showing 37 changed files with 656 additions and 302 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,199 @@
-### SnPM: Statistical nonParametric Mapping
+## SnPM: Statistical nonParametric Mapping
 
-The <b>S</b>tatistical <b>n</b>on-<b>P</b>arametric <b>M</b>apping (SnPM) toolbox provides an extensible framework for voxel level non-parametric permutation/randomisation tests of functional Neuroimaging experiments with independent observations. 
+The Statistical non-Parametric Mapping (SnPM) toolbox provides an extensible framework for voxel level non-parametric permutation/randomisation tests of functional Neuroimaging experiments with independent observations. 
 
 The SnPM toolbox provides an alternative to the Statistics section of [SPM](http://www.fil.ion.ucl.ac.uk/spm/). SnPM uses the General Linear Model to construct pseudo t-statistic images, which are then assessed for significance using a standard non-parametric multiple comparisons procedure based on randomisation/permutation testing. It is most suitable for single subject PET/SPECT analyses, or designs with low degrees of freedom available for variance estimation. In these situations the freedom to use weighted locally pooled variance estimates, or variance smoothing, makes the non-parametric approach considerably more powerful than conventional parametric approaches, as are implemented in SPM. Further, the non-parametric approach is always valid, given only minimal assumptions.
+
+**More information at: www.warwick.ac.uk/snpm**
+
+ - [Getting started](http://www.warwick.ac.uk/snpm/man)
+ - [fMRI example](http://www.warwick.ac.uk/snpm/man/exnew)
+ - [PET example](http://www.warwick.ac.uk/snpm/man/ex)
+ - [Download](http://www.warwick.ac.uk/snpm/snpmreg)
+
+
+### Testing
+
+#### Initial set up 
+The first time you run the tests, you will first have to create a set of ground truth data and a file named `snpm_test_config.m` containing the reference SnPM version you used to compute the ground truth and the path to the ground truth folder. For example:
+```
+global testDataDir;
+testDataDir = '~/snpm_test_data';
+global SnPMrefVersion;
+SnPMrefVersion = 'SnPM8';
+```
+
+#### Run the test suite
+Then, the tests can be started (from the test data folder) with:
+```
+import matlab.unittest.TestSuite;
+suite = TestSuite.fromFolder(fullfile(spm_str_manip(which('snpm'), 'h'), 'test'));
+result = run(suite);
+```
+
+#### Run a single test
+```
+run(test_oneSample, 'test_onesample_1')
+```
+
+### SnPM13: Bugs & Fixes
+
+This section describes the bugs that have been reported, along with the appropriate fixes. 
+Updated versions of appropriate SnPM functions are available at [snpm13_updates](http://warwick.ac.uk/snpm/distribution/snpm13_updates)
+
+####  SnPM 13.1.04
+* snpm
+SnPM version 13.1.04
+
+* snpm_bch_ui, snpm_cp, snpm_ui
+Fix: implicit masking for non-float datatypes
+
+* snpm_pi_ANOVAbtwnS, snpm_pi_ANOVAwithinS, snpm_pi_Corr, snpm_pi_Corr1S, 
+snpm_pi_OneSampT, snpm_pi_TwoSampPairT, snpm_pi_TwoSampT, snpm_pi_TwoSampTss
+Update syntax to set the seed of the random number generator (rng) 
+
+* snpm_defaults
+New SnPM global parameter shuffle_seed. If true, the rng uses a 'shuffle' seed providing different results for each run. If false Matlab's 'default' seed or any seed defined by the user will be used .
+
+* snpm_pi_TwoSampT
+Allows MC permutation (with reptitions) for large enough nPerms 
+
+* snpm_pp, snpm_ui
+Do not display figures in command-line mode
+
+* snpm, snpm_check_nperm, snpm_combo, snpm_cp, snpm_init, snpm_pi_ANOVAbtwnS,
+snpm_pi_ANOVAwithinS, snpm_pi_Corr, snpm_pi_Corr1S, snpm_pi_OneSampT, 
+snpm_pi_PairT, snpm_pi_PairTrand, snpm_pi_TwoSampPairT, snpm_pi_TwoSampT, 
+snpm_pi_TwoSampTss, snpm_pp, snpm_t2z, snpm_uc_FDR, snpm_ui, spm_append_96
+Add identifiers to errors and warnings
+
+* snpm_cp
+Fix: Do not assume statistic is T when computing cluster forming threshold from P-value
+
+* generic_test_snpm, skeleton_class, test_ANOVAbetween, 
+test_multisub_withinsubanova, test_multisubpaired2cond, 
+test_multisubsimpleregression, test_oneSample, test_onesub_regression, 
+test_onesub_twocondrepl, test_twoSample, test_twosample_twocond
+Test in command-line mode with no shuffling for the random seed, using new rng
+ syntax.
+
+####  Updates from SnPM 13.1.03
+* snpm
+SnPM version 13.1.03
+
+* snpm_pi_PairT
+Now allows more than 52 subjects, as previously that would generate a "Maximum variable size allowed by the program" error message.
+
+####  Updates from SnPM 13.1.02
+* snpm
+SnPM version 13.1.02
+
+* snpm_pp, snpm_combo_pp
+Update contrast display for compatibility with Matlab R2014b.
+
+* generic_test_snpm
+Updates affecting tests only.
+
+####  Updates from SnPM 13.1.01
+* snpm
+SnPM version 13.1.01
+
+* snpm_pp
+Check that 'Locs_vox' is integer according to a pre-defined tolerance level (as in snpm_cp).
+
+####  Updates from SnPM13.1.00
+* snpm_cp, snpm_pp, generic_test_snpm, test_oneSample
+Cluster-forming threshold defined by a P-value are now extended to pseudo-T statistic (with variance smoothing). The Z-score corresponding to the selected P-value is used as an approximation of pseudo-T values.
+
+####  Updates from SnPM13.0.14
+* snpm_bch_ui_Corr, snpm_bch_ui_Corr1S, snpm_pi_Corr, snpm_pi_Corr1S, test_multisubsimpleregression, test_onesub_regression
+Introduce nuisance covariates in simple-subject and multi-subject regressions.
+
+####  Updates from SnPM13.0.13
+* snpm_combo_pp
+Fix: Set bNeg to 0 for F-tests.
+
+####  Updates from SnPM13.0.12
+* snpm_pi_OneSampT
+Fix: Added new random mode for sampling of sign flips (Above 53 scans the binary-coding fails as Matlab's double significand runs out of precision).
+
+####  Updates from SnPM13.0.11
+* snpm_ui
+Fix: When relative thresholding is set, then global calculation (user defined or mean) must be computed.
+
+* snpm_pi_TwoSampPairT, snpm_pi_TwoSampT
+Fix: Unbalanced two-sample tests were wrongly aborted.
+
+* test_multisubpaired2cond, test_oneSample, test_twoSample, test_twosample_twocond
+Updates affecting tests only.
+
+####  Updates from SnPM13.0.10 
+* snpm_ui
+Fix: ANCOVA normalisation (with an image presenting negative mean using spm_globals).
+
+####  Updates from SnPM13.09
+* snpm_cp
+Increase tolerance in checking that 'Locs_vox' is integer.
+
+####  Updates from SnPM13.08
+* snpm_cp, spm_append_96
+Display warning message if SnPM_ST file becomes very large. Display more meaningful error message when Locs_vox is not interger.
+
+* snpm_pp
+Display warning message if SnPM_ST can not be loaded.
+
+####  Updates from SnPM13.07
+* snpm
+For backward-compatibility, open SPM batch window and display where to find SnPM tools when 'snpm' in called at the Matlab prompt.
+
+* snpm_pp
+Fix: slow cluster inference with variance smoothing.
+
+* generic_test_snpm, test_oneSample, test_twoSample
+Updates affecting tests only.
+
+####  Updates from SnPM13.06
+* snpm_ui
+Apply user-defined scaling.
+
+* generic_test_snpm, test_oneSample, test_onesub_twocondrepl, test_twoSample
+Updates affecting tests only.
+
+####  Updates from SnPM13.05
+* snpm_STcalc
+Cluster labels from spm_max are not necessarily continuous.
+
+* snpm_pi_ANOVAbtwnS, snpm_pi_ANOVAwithinS, snpm_pi_Corr, snpm_pi_Corr1S, snpm_pi_OneSampT, snpm_pi_PairT, snpm_pi_TwoSampPairT, snpm_pi_TwoSampT, snpm_pi_TwoSampTss
+Fix: if number of requested permutations is equal to the maximum number of possible permutations.
+
+* snpm_pi_TwoSampTss, snpm_pi_TwoSampPairT, snpm_pi_TwoSampT
+Compute possible permutations (PiCond) in a more efficient way to avoid potential memory faults for large groups.
+
+####  Updates from SnPM13.04
+* snpm_ui
+Apply absolute and relative masking.
+
+####  Updates from SnPM13.03
+* snpm_pi_TwoSampT
+Compute possible permutations (PiCond) in a more efficient way to avoid potential memory faults for large groups.
+
+####  Updates from SnPM13.02
+* snpm_pp
+Fix: if the extension is missing in the provided result file name, use .nii by default.
+Use NaNs in thresholded map background instead of zeros.
+
+* [deleted spm_SnPM13]
+SnPM is now only accessible through the Batch window (SPM -> Tools -> SnPM).
+
+* snpm_pi_ANOVAbtwnS, snpm_pi_ANOVAwithinS, snpm_pi_Corr1S, snpm_pi_OneSampT, snpm_pi_PairT, snpm_pi_TwoSampPairT, snpm_pi_TwoSampT
+Minor update in the display.
+
+* test/
+Miror corrections affecting tests procedure only.
+
+####  Updates from SnPM13.01
+* snpm_cp 
+Synopsis: When half the permutations are computed (i.e. bhPerms is true) and StartPerm is 2 then the initial number of permutation could be 2 depending on sign of T0.
+
+* snpm_test_config, snpm_test_gound_truth and generic_test_snpm
+Miror corrections affecting tests procedure only.
diff --git a/config/snpm_bch_ui.m b/config/snpm_bch_ui.m
@@ -283,7 +283,9 @@
               ''
               'For image data-types without a representation of NaN, zero is the mask value, and the user can choose whether zero voxels should be masked out or not.'
               ''
-              'By default, an implicit mask is used. '
+              'By default, an implicit mask is used.'
+              ''
+              'It is ill-advised to mix input images, but if data are a mix of integer (no NaN''s) and float/double datatypes, implicit masking will only occur with NaN''s.'
               ''
 }';
 im.labels = {

diff --git a/snpm.m b/snpm.m
@@ -49,7 +49,7 @@
 
 %-Parameters
 %-----------------------------------------------------------------------
-SnPMver    = 'SnPM13.1.03';
+SnPMver    = 'SnPM13.1.04';
 
 %-Format arguments
 %-----------------------------------------------------------------------
@@ -106,7 +106,7 @@
 
 else
 %=======================================================================
-error('Unknown action string')
+error('SnPM:UnknownAction', 'Unknown action string')
 
 %=======================================================================
 end
diff --git a/snpm_check_nperm.m b/snpm_check_nperm.m
@@ -16,17 +16,21 @@ function snpm_check_perm(nPerm,TotPerm)
 if nPerm<100 & nPerm>=0.9*TotPerm
   str = sprintf(['Very few (%d) permutations used, nonparametric P-values are very coarse (but exact).\n'...
 		 'Smallest possible P-value is %0.4f.'],nPerm,1/nPerm);
+  id = 'SnPM:VeryFewPermsCoarseExactPValues';
 elseif nPerm<100 & nPerm<0.9*TotPerm
   str = sprintf(['Very few (%d) permutations used, nonparametric P-values are very coarse will vary \n'...
 		 'substantially over repeated re-analyses.'...
 		 'Smallest possible P-value is %0.4f.'],nPerm,1/nPerm);
+  id = 'SnPM:VeryFewPermsCoarseVaryingPValues';
 elseif nPerm>10000
   str = sprintf(['Many (%d) permutations used, analysis may take a very long time\n'...
 		 'to complete.  Consiser running fewer permutations.'],nPerm,1/nPerm);
+  id = 'SnPM:ManyPerms';     
 elseif nPerm>25000
   str = sprintf(['%cInsane nummber of permutations requested (%d)!\n'...
 		 'Are you sure!?'],7,nPerm);
+  id = 'SnPM:ManyManyPerms';
 end
 if ~isempty(str)
-  warning(str)
+  warning(id, str)
 end
diff --git a/snpm_combo.m b/snpm_combo.m
@@ -126,7 +126,7 @@
 
 else
 %=======================================================================
-error('Unknown action string')
+error('SnPM:UnknownAction', 'Unknown action string')
 
 %=======================================================================
 end
diff --git a/snpm_combo_pp.m b/snpm_combo_pp.m
@@ -179,10 +179,10 @@ function snpm_combo_pp(CWD, job)
   str = 'Voxelwise corrected threshold = %g, which is smaller ';
   str = [str 'than minimum saved suprathreshold information (%g)'];
   str = [str '\nAll results significant voxelwise.'];
-  warning(sprintf(str,C_MaxT,ST_Ut))
+  warning('SnPM:VoxelwiseCorrThreshSmaller', sprintf(str,C_MaxT,ST_Ut))
 end
 if bSpatEx~=1
-  error('Suprathreshold stats not collected!  Cannot do cluster-combining!')
+  error('SnPM:SupraStatMissing', 'Suprathreshold stats not collected!  Cannot do cluster-combining!')
 end
 
 %-Get primary threshold for STC analysis if requested
@@ -202,12 +202,14 @@ function snpm_combo_pp(CWD, job)
         % upper tail p-values to specify primary threshold
         if alpha == 1	% Not filtering on significance
             if ~(primaryThresh>=ST_Ut)
-                error(['Using pseudo-statistics you can''t use (uncorrected)'... 
+                error('SnPM:PseudoStatWithPValueThreshold', ...
+                    ['Using pseudo-statistics you can''t use (uncorrected)'... 
                         'upper tail p-values to specify primary threshold']);
             end   
         else
             if ~(primaryThresh>=ST_Ut && primaryThresh<C_MaxT)
-                        error(['Using pseudo-statistics you can''t use (uncorrected)'... 
+                        error('SnPM:PseudoStatWithPValueThreshold', ...
+                            ['Using pseudo-statistics you can''t use (uncorrected)'... 
                                 'upper tail p-values to specify primary threshold']);
             end  
         end
@@ -216,14 +218,14 @@ function snpm_combo_pp(CWD, job)
         pU_ST_Ut  = 1-spm_Tcdf(ST_Ut,df);
         if alpha==1	% Not filtering on significance
             if ~( primaryThresh>=ST_Ut || (primaryThresh>0 && primaryThresh<=pU_ST_Ut_filt))
-                error(['Primary threshold must be >=' num2str(ST_Ut) ...
+                error('SnPM:InvalidPrimaryThresh', ['Primary threshold must be >=' num2str(ST_Ut) ...
                     ' and >0 and <=' num2str(pU_ST_Ut_filt) ]);
             end  
         else
             pU_C_MaxT = 1-spm_Tcdf(C_MaxT,df);
             if ~((primaryThresh>=ST_Ut && primaryThresh<C_MaxT) || ...
                     (primaryThresh>pU_C_MaxT && primaryThresh<=pU_ST_Ut_filt))
-                error(['Primary threshold must be >=' num2str(ST_Ut) ...
+                error('SnPM:InvalidPrimaryThresh', ['Primary threshold must be >=' num2str(ST_Ut) ...
                     ' and <' num2str(C_MaxT) ' or >' num2str(pU_C_MaxT) ...
                     ' and <= ' num2str(pU_ST_Ut_filt)]);
             end
@@ -241,7 +243,7 @@ function snpm_combo_pp(CWD, job)
     %
     Theta = job.Thr.Clus.ClusMass.Theta;
     if (Theta<0+tol || Theta>1-tol)
-        error('Theta should be between 0 and 1');
+        error('SnPM:InvalidTheta', 'Theta should be between 0 and 1');
     end
     mTheta = Theta/(1-Theta);  %-Weight for mass combining
 
@@ -385,7 +387,7 @@ function snpm_combo_pp(CWD, job)
 	%-Check XYZ for points > ST_Ut in perm 1 matches
 	% XYZ computed above for SnPMt > ST_Ut
 	if ~all(all( SnPM_ST(1:3,SnPM_ST(5,:)==1) == XYZ ))
-		error('ST XYZ don''t match between STCS & thresh')
+		error('SnPM:InvalidSTXYZ', 'ST XYZ don''t match between STCS & thresh')
 	end
 
         %-- VOXEL CLUSTER COMBINED TEST STATISTICS ----