From 0593ca4c5a34084340ef8ce8b0537cdaa94e0040 Mon Sep 17 00:00:00 2001 From: Sam Nastase Date: Fri, 31 Jul 2020 13:44:34 -0400 Subject: [PATCH 1/4] Fix pairwise bootstrap to tolerate NaNs --- brainiak/isc.py | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/brainiak/isc.py b/brainiak/isc.py index 27d14a223..4e6b48f76 100644 --- a/brainiak/isc.py +++ b/brainiak/isc.py @@ -19,7 +19,7 @@ as statistical tests designed specifically for ISC analyses. The implementation is based on the work in [Hasson2004]_, [Kauppi2014]_, -[Simony2016]_, and [Chen2016]_. +[Simony2016]_, [Chen2016]_, and [Nastase2019]_. .. [Chen2016] "Untangling the relatedness among correlations, part I: nonparametric approaches to inter-subject correlation analysis at the @@ -41,6 +41,11 @@ during narrative comprehension.", E. Simony, C. J. Honey, J. Chen, O. Lositsky, Y. Yeshurun, A. Wiesel, U. Hasson, 2016, Nature Communications, 7, 12141. https://doi.org/10.1038/ncomms12141 + +.. [Nastase2019] "Measuring shared responses across subjects using + intersubject correlation." S. A. Nastase, V. Gazzola, U. Hasson, + C. Keysers, 2019, Social Cognitive and Affective Neuroscience, 14, + 667-685. https://doi.org/10.1093/scan/nsz037 """ # Authors: Sam Nastase, Christopher Baldassano, Qihong Lu, @@ -405,7 +410,7 @@ def _check_isc_input(iscs, pairwise=False): # Check if incoming pairwise matrix is vectorized triangle if pairwise: try: - test_square = squareform(iscs[:, 0]) + test_square = squareform(iscs[:, 0], force='tomatrix') n_subjects = test_square.shape[0] except ValueError: raise ValueError("For pairwise input, ISCs must be the " @@ -744,13 +749,13 @@ def bootstrap_isc(iscs, pairwise=False, summary_statistic='median', for voxel_iscs in iscs.T: # Square the triangle and fill diagonal - voxel_iscs = squareform(voxel_iscs) + try: + voxel_iscs = squareform(voxel_iscs, force='tomatrix') + except ValueError as e: + raise Exception("Pairwise ISC input must be " + "distance-vector format") from e np.fill_diagonal(voxel_iscs, 1) - # Check that pairwise ISC matrix is square and symmetric - assert voxel_iscs.shape[0] == voxel_iscs.shape[1] - assert np.allclose(voxel_iscs, voxel_iscs.T) - # Shuffle square correlation matrix and get triangle voxel_sample = voxel_iscs[subject_sample, :][:, subject_sample] voxel_sample = squareform(voxel_sample, checks=False) From a721dde7a836e39be7774e2735e3e56b96ff8e99 Mon Sep 17 00:00:00 2001 From: Sam Nastase Date: Fri, 31 Jul 2020 14:19:19 -0400 Subject: [PATCH 2/4] Remove extraneous try/except error message (oops) --- brainiak/isc.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/brainiak/isc.py b/brainiak/isc.py index 4e6b48f76..5250b7505 100644 --- a/brainiak/isc.py +++ b/brainiak/isc.py @@ -749,11 +749,7 @@ def bootstrap_isc(iscs, pairwise=False, summary_statistic='median', for voxel_iscs in iscs.T: # Square the triangle and fill diagonal - try: - voxel_iscs = squareform(voxel_iscs, force='tomatrix') - except ValueError as e: - raise Exception("Pairwise ISC input must be " - "distance-vector format") from e + voxel_iscs = squareform(voxel_iscs, force='tomatrix') np.fill_diagonal(voxel_iscs, 1) # Shuffle square correlation matrix and get triangle From 8e557d48c54d6118e678415bc0f60930f95fa1b7 Mon Sep 17 00:00:00 2001 From: Sam Nastase Date: Fri, 31 Jul 2020 15:05:27 -0400 Subject: [PATCH 3/4] Update ISC permutation doc on pairwise groups clarity --- brainiak/isc.py | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/brainiak/isc.py b/brainiak/isc.py index 5250b7505..e383bd1f1 100644 --- a/brainiak/isc.py +++ b/brainiak/isc.py @@ -1056,25 +1056,29 @@ def permutation_isc(iscs, group_assignment=None, pairwise=False, # noqa: C901 For ISCs from one or more voxels or ROIs, permute group assignments to construct a permutation distribution. Input is a list or ndarray of - ISCs for a single voxel/ROI, or an ISCs-by-voxels ndarray. If two groups, - ISC values should stacked along first dimension (vertically), and a - group_assignment list (or 1d array) of same length as the number of - subjects should be provided to indicate groups. If no group_assignment - is provided, one-sample test is performed using a sign-flipping procedure. - Performs exact test if number of possible permutations (2**N for one-sample - sign-flipping, N! for two-sample shuffling) is less than or equal to number - of requested permutation; otherwise, performs approximate permutation test - using Monte Carlo resampling. ISC values should either be N ISC values for - N subjects in the leave-one-out approach (pairwise=False) or N(N-1)/2 ISC - values for N subjects in the pairwise approach (pairwise=True). In the - pairwise approach, ISC values should correspond to the vectorized upper - triangle of a square corrlation matrix (scipy.stats.distance.squareform). - Note that in the pairwise approach, group_assignment order should match the - row/column order of the subject-by-subject square ISC matrix even though - the input ISCs should be supplied as the vectorized upper triangle of the - square ISC matrix. Returns the observed ISC and permutation-based p-value - (two-tailed test), as well as the permutation distribution of summary - statistic. According to Chen et al., 2016, this is the preferred + ISCs for a single voxel/ROI, or an ISCs-by-voxels ndarray. In the + leave-one-out approach, ISC values for two groups should be stacked + along first dimension (vertically) and a group_assignment list (or 1d + array) of same length as the number of subjects should be provided to + indicate groups. In the pairwise approach, pairwise ISCs should be + computed the across both groups at once; i.e. the pairwise ISC matrix + should be shaped N x N where N is the total number of subjects across + both groups, and should contain between-group ISC pairs. Pairwise ISC + input should correspond to the vectorized upper triangle of the square + pairwise ISC correlation matrix containing both groups. In the pairwise + approach, group_assignment order should match the row/column order of the + subject-by-subject square ISC matrix even though the input ISCs should be + supplied as the vectorized upper triangle of the square ISC matrix. If no + group_assignment is provided, one-sample test is performed using a sign- + flipping procedure. Performs exact test if number of possible permutations + (2**N for one-sample sign-flipping, N! for two-sample shuffling) is less + than or equal to number of requested permutation; otherwise, performs + approximate permutation test using Monte Carlo resampling. ISC values + should either be N ISC values for N subjects in the leave-one-out approach + (pairwise=False) or N(N-1)/2 ISC values for N subjects in the pairwise + approach (pairwise=True). Returns the observed ISC and permutation-based + p-value (two-tailed test), as well as the permutation distribution of + summary statistic. 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. From f7514b45f75756a3b44e3a2e6bd19701717da41c Mon Sep 17 00:00:00 2001 From: Sam Nastase Date: Tue, 11 Aug 2020 12:56:25 -0400 Subject: [PATCH 4/4] Fix tense in permutation_isc documentation --- brainiak/isc.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/brainiak/isc.py b/brainiak/isc.py index e383bd1f1..60b0adaaa 100644 --- a/brainiak/isc.py +++ b/brainiak/isc.py @@ -1060,8 +1060,8 @@ def permutation_isc(iscs, group_assignment=None, pairwise=False, # noqa: C901 leave-one-out approach, ISC values for two groups should be stacked along first dimension (vertically) and a group_assignment list (or 1d array) of same length as the number of subjects should be provided to - indicate groups. In the pairwise approach, pairwise ISCs should be - computed the across both groups at once; i.e. the pairwise ISC matrix + indicate groups. In the pairwise approach, pairwise ISCs should have + been computed across both groups at once; i.e. the pairwise ISC matrix should be shaped N x N where N is the total number of subjects across both groups, and should contain between-group ISC pairs. Pairwise ISC input should correspond to the vectorized upper triangle of the square