isc: Add caveats about false positive rates (#480)

brainiak/isc.py

@@ -668,10 +668,9 @@ def bootstrap_isc(iscs, pairwise=False, summary_statistic='median',
     distribution of summary statistics. The p-value corresponds to either a
     'two-sided', 'left'-, or 'right'-sided (default) test, as specified by
     side. According to Chen et al., 2016, this is the preferred nonparametric
-    approach for controlling false positive rates (FPR) for one-sample tests
-    in the pairwise approach. The efficacy of this approach for controlling
-    FPRs in the leave-one-out approach has not yet been systematically
-    evaluated.
+    approach for controlling false positive rates (FPRs) for one-sample tests
+    in the pairwise approach. Note that the bootstrap hypothesis test may not
+    strictly control FPRs in the leave-one-out approach.
 
     The implementation is based on the work in [Chen2016]_ and
     [HallWilson1991]_.
@@ -714,8 +713,8 @@ def bootstrap_isc(iscs, pairwise=False, summary_statistic='median',
     p : float, p-value
         p-value based on bootstrap hypothesis test
 
-    distribution : ndarray, bootstraps by voxels (optional)
-        Bootstrap distribution if return_bootstrap=True
+    distribution : ndarray, n_bootstraps by voxels
+        Bootstrap distribution
 
     """
 
@@ -1088,8 +1087,8 @@ def permutation_isc(iscs, group_assignment=None, pairwise=False,  # noqa: C901
     The p-value corresponds to either a 'two-sided', 'left'-, or 'right'-sided
     (default) test, as specified by side. According to Chen et al., 2016,
     this is the preferred nonparametric approach for controlling false
-    positive rates (FPR) for two-sample tests. This approach may yield
-    inflated FPRs for one-sample tests.
+    positive rates (FPRs) for two-sample tests. Note that the permutation test
+    may not strictly control FPRs for one-sample tests.
 
     The implementation is based on the work in [Chen2016]_.
 
@@ -1124,8 +1123,8 @@ def permutation_isc(iscs, group_assignment=None, pairwise=False,  # noqa: C901
     p : float, p-value
         p-value based on permutation test
 
-    distribution : ndarray, permutations by voxels (optional)
-        Permutation distribution if return_bootstrap=True
+    distribution : ndarray, n_permutations by voxels
+        Permutation distribution
     """
 
     # Standardize structure of input data
@@ -1281,7 +1280,8 @@ def timeshift_isc(data, pairwise=False, summary_statistic='median',
     False. Returns the observed ISC and p-values, as well as the null
     distribution of ISCs computed on randomly time-shifted data. The p-value
     corresponds to either a 'two-sided', 'left'-, or 'right'-sided (default)
-    test, as specified by side.
+    test, as specified by side. Note that circular time-shift randomization
+    may not strictly control false positive rates (FPRs).
 
     The implementation is based on the work in [Kauppi2010]_ and
     [Kauppi2014]_.
@@ -1323,8 +1323,8 @@ def timeshift_isc(data, pairwise=False, summary_statistic='median',
     p : float, p-value
         p-value based on time-shifting randomization test
 
-    distribution : ndarray, time-shifts by voxels (optional)
-        Time-shifted null distribution if return_bootstrap=True
+    distribution : ndarray, n_shifts by voxels
+        Time-shifted null distribution
     """
 
     # Check response time series input format
@@ -1349,7 +1349,7 @@ def timeshift_isc(data, pairwise=False, summary_statistic='median',
         else:
             prng = np.random.RandomState(random_state)
 
-        # Get a random set of shifts based on number of TRs,
+        # Get a random set of shifts based on number of TRs
         shifts = prng.choice(np.arange(n_TRs), size=n_subjects,
                              replace=True)
 
@@ -1436,7 +1436,8 @@ def phaseshift_isc(data, pairwise=False, summary_statistic='median',
     to False. Returns the observed ISC and p-values, as well as the null
     distribution of ISCs computed on phase-randomized data. The p-value
     corresponds to either a 'two-sided', 'left'-, or 'right'-sided (default)
-    test, as specified by side.
+    test, as specified by side. Note that phase randomization may not
+    strictly control false positive rates (FPRs).
 
     The implementation is based on the work in [Lerner2011]_ and
     [Simony2016]_.
@@ -1477,8 +1478,8 @@ def phaseshift_isc(data, pairwise=False, summary_statistic='median',
     p : float, p-value
         p-value based on time-shifting randomization test
 
-    distribution : ndarray, time-shifts by voxels (optional)
-        Time-shifted null distribution if return_bootstrap=True
+    distribution : ndarray, n_shifts by voxels
+        Phase-shifted null distribution
     """
 
     # Check response time series input format