From 79b20c08afac0b6c43d556095fe2c40c72a045d7 Mon Sep 17 00:00:00 2001
From: Sam Nastase <sam.nastase@gmail.com>
Date: Fri, 4 Sep 2020 12:55:18 -0400
Subject: [PATCH 1/2] Remove leftover 'optional' bootstrap return

---
 brainiak/isc.py | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/brainiak/isc.py b/brainiak/isc.py
index 99b9a69b4..5ca750938 100644
--- a/brainiak/isc.py
+++ b/brainiak/isc.py
@@ -714,8 +714,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
 
     """
 
@@ -1124,8 +1124,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
@@ -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)
 
@@ -1477,8 +1477,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

From 73fab38c4e26f9bb64ed3d4421d626d5b2e41d21 Mon Sep 17 00:00:00 2001
From: Sam Nastase <sam.nastase@gmail.com>
Date: Sat, 5 Sep 2020 14:14:07 -0400
Subject: [PATCH 2/2] Add caveat about FPRs to ISC tests

---
 brainiak/isc.py | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/brainiak/isc.py b/brainiak/isc.py
index 5ca750938..df2e858f4 100644
--- a/brainiak/isc.py
+++ b/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]_.
@@ -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]_.
 
@@ -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]_.
@@ -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]_.