Disable computation of probabilities by default for MKDAChi2

nimare/meta/cbma/mkda.py

@@ -302,6 +302,11 @@ class MKDAChi2(PairwiseCBMAEstimator):
 
     .. versionchanged:: 0.2.1
 
+        - Make `prior` parameter default to None, which controls if posterior probabilities
+            pFgA, pAgF_prior and pFgA_prior are calculated. This is useful because probability
+            maps are difficult to interpret and for speeding up the algorithm.
+        - Rename ``consistency`` to ``uniformity`` and ``specificity`` to ``association`` to match
+          Neurosynth's terminology
         - New parameters: ``memory`` and ``memory_level`` for memory caching.
 
     .. versionchanged:: 0.0.12
@@ -476,26 +481,26 @@ def _fit(self, dataset1, dataset2):
 
         del n_mappables
 
-        # Conditional probabilities
         pAgF = n_selected_active_voxels / n_selected
         pAgU = n_unselected_active_voxels / n_unselected
         pFgA = pAgF * pF / pA
 
         del pF
 
-        # Recompute conditionals with uniform prior
-        pAgF_prior = self.prior * pAgF + (1 - self.prior) * pAgU
-        pFgA_prior = pAgF * self.prior / pAgF_prior
+        if self.prior is not None:
+            # Recompute conditionals with uniform prior
+            pAgF_prior = self.prior * pAgF + (1 - self.prior) * pAgU
+            pFgA_prior = pAgF * self.prior / pAgF_prior
 
-        # One-way chi-square test for consistency of activation
+        # One-way chi-square test for uniformity of activation
         pAgF_chi2_vals = one_way(np.squeeze(n_selected_active_voxels), n_selected)
         pAgF_p_vals = chi2.sf(pAgF_chi2_vals, 1)
         pAgF_sign = np.sign(n_selected_active_voxels - np.mean(n_selected_active_voxels))
         pAgF_z = p_to_z(pAgF_p_vals, tail="two") * pAgF_sign
 
         del pAgF_sign
 
-        # Two-way chi-square for specificity of activation
+        # Two-way chi-square for association of activation
         cells = np.squeeze(
             np.array(
                 [
@@ -523,6 +528,12 @@ def _fit(self, dataset1, dataset2):
         del pFgA_sign, pAgU
 
         maps = {
+            "z_desc-uniformity": pAgF_z,
+            "z_desc-association": pFgA_z,
+            "chi2_desc-uniformity": pAgF_chi2_vals,
+            "chi2_desc-association": pFgA_chi2_vals,
+            "p_desc-uniformity": pAgF_p_vals,
+            "p_desc-association": pFgA_p_vals,
             "prob_desc-A": pA,
             "prob_desc-AgF": pAgF,
             "prob_desc-FgA": pFgA,
@@ -535,9 +546,7 @@ def _fit(self, dataset1, dataset2):
             "p_desc-consistency": pAgF_p_vals,
             "p_desc-specificity": pFgA_p_vals,
         }
-        description = self._generate_description()
-
-        return maps, {}, description
+        return maps, {}
 
     def _run_fwe_permutation(self, iter_xyz1, iter_xyz2, iter_df1, iter_df2, conn, voxel_thresh):
         """Run a single permutation of the Monte Carlo FWE correction procedure.
@@ -612,7 +621,7 @@ def _run_fwe_permutation(self, iter_xyz1, iter_xyz2, iter_df1, iter_df2, conn, v
         # pAgF = n_selected_active_voxels / n_selected
         # pAgU = n_unselected_active_voxels / n_unselected
 
-        # One-way chi-square test for consistency of activation
+        # One-way chi-square test for uniformity of activation
         pAgF_chi2_vals = one_way(np.squeeze(n_selected_active_voxels), n_selected)
 
         # Voxel-level inference
@@ -624,7 +633,7 @@ def _run_fwe_permutation(self, iter_xyz1, iter_xyz2, iter_df1, iter_df2, conn, v
             pAgF_chi2_map, voxel_thresh, conn, tail="two"
         )
 
-        # Two-way chi-square for specificity of activation
+        # Two-way chi-square for association of activation
         cells = np.squeeze(
             np.array(
                 [
@@ -769,42 +778,42 @@ def correct_fwe_montecarlo(self, result, voxel_thresh=0.001, n_iters=5000, n_cor
             the correction procedure. The following arrays are generated by
             this method:
 
-            -   ``p_desc-consistency_level-voxel``: Voxel-level FWE-corrected p-values from the
-                consistency/forward inference analysis.
-            -   ``z_desc-consistency_level-voxel``: Voxel-level FWE-corrected z-values from the
-                consistency/forward inference analysis.
-            -   ``logp_desc-consistency_level-voxel``: Voxel-level FWE-corrected -log10 p-values
-                from the consistency/forward inference analysis.
-            -   ``p_desc-consistencyMass_level-cluster``: Cluster-level FWE-corrected p-values
-                from the consistency/forward inference analysis, using cluster mass.
-            -   ``z_desc-consistencyMass_level-cluster``: Cluster-level FWE-corrected z-values
-                from the consistency/forward inference analysis, using cluster mass.
-            -   ``logp_desc-consistencyMass_level-cluster``: Cluster-level FWE-corrected -log10
-                p-values from the consistency/forward inference analysis, using cluster mass.
-            -   ``p_desc-consistencySize_level-cluster``: Cluster-level FWE-corrected p-values
-                from the consistency/forward inference analysis, using cluster size.
-            -   ``z_desc-consistencySize_level-cluster``: Cluster-level FWE-corrected z-values
-                from the consistency/forward inference analysis, using cluster size.
-            -   ``logp_desc-consistencySize_level-cluster``: Cluster-level FWE-corrected -log10
-                p-values from the consistency/forward inference analysis, using cluster size.
-            -   ``p_desc-specificity_level-voxel``: Voxel-level FWE-corrected p-values from the
-                specificity/reverse inference analysis.
-            -   ``z_desc-specificity_level-voxel``: Voxel-level FWE-corrected z-values from the
-                specificity/reverse inference analysis.
-            -   ``logp_desc-specificity_level-voxel``: Voxel-level FWE-corrected -log10 p-values
-                from the specificity/reverse inference analysis.
-            -   ``p_desc-specificityMass_level-cluster``: Cluster-level FWE-corrected p-values
-                from the specificity/reverse inference analysis, using cluster mass.
-            -   ``z_desc-specificityMass_level-cluster``: Cluster-level FWE-corrected z-values
-                from the specificity/reverse inference analysis, using cluster mass.
-            -   ``logp_desc-specificityMass_level-cluster``: Cluster-level FWE-corrected -log10
-                p-values from the specificity/reverse inference analysis, using cluster mass.
-            -   ``p_desc-specificitySize_level-cluster``: Cluster-level FWE-corrected p-values
-                from the specificity/reverse inference analysis, using cluster size.
-            -   ``z_desc-specificitySize_level-cluster``: Cluster-level FWE-corrected z-values
-                from the specificity/reverse inference analysis, using cluster size.
-            -   ``logp_desc-specificitySize_level-cluster``: Cluster-level FWE-corrected -log10
-                p-values from the specificity/reverse inference analysis, using cluster size.
+            -   ``p_desc-uniformity_level-voxel``: Voxel-level FWE-corrected p-values from the
+                uniformity/forward inference analysis.
+            -   ``z_desc-uniformity_level-voxel``: Voxel-level FWE-corrected z-values from the
+                uniformity/forward inference analysis.
+            -   ``logp_desc-uniformity_level-voxel``: Voxel-level FWE-corrected -log10 p-values
+                from the uniformity/forward inference analysis.
+            -   ``p_desc-uniformityMass_level-cluster``: Cluster-level FWE-corrected p-values
+                from the uniformity/forward inference analysis, using cluster mass.
+            -   ``z_desc-uniformityMass_level-cluster``: Cluster-level FWE-corrected z-values
+                from the uniformity/forward inference analysis, using cluster mass.
+            -   ``logp_desc-uniformityMass_level-cluster``: Cluster-level FWE-corrected -log10
+                p-values from the uniformity/forward inference analysis, using cluster mass.
+            -   ``p_desc-uniformitySize_level-cluster``: Cluster-level FWE-corrected p-values
+                from the uniformity/forward inference analysis, using cluster size.
+            -   ``z_desc-uniformitySize_level-cluster``: Cluster-level FWE-corrected z-values
+                from the uniformity/forward inference analysis, using cluster size.
+            -   ``logp_desc-uniformitySize_level-cluster``: Cluster-level FWE-corrected -log10
+                p-values from the uniformity/forward inference analysis, using cluster size.
+            -   ``p_desc-association_level-voxel``: Voxel-level FWE-corrected p-values from the
+                association/reverse inference analysis.
+            -   ``z_desc-association_level-voxel``: Voxel-level FWE-corrected z-values from the
+                association/reverse inference analysis.
+            -   ``logp_desc-association_level-voxel``: Voxel-level FWE-corrected -log10 p-values
+                from the association/reverse inference analysis.
+            -   ``p_desc-associationMass_level-cluster``: Cluster-level FWE-corrected p-values
+                from the association/reverse inference analysis, using cluster mass.
+            -   ``z_desc-associationMass_level-cluster``: Cluster-level FWE-corrected z-values
+                from the association/reverse inference analysis, using cluster mass.
+            -   ``logp_desc-associationMass_level-cluster``: Cluster-level FWE-corrected -log10
+                p-values from the association/reverse inference analysis, using cluster mass.
+            -   ``p_desc-associationSize_level-cluster``: Cluster-level FWE-corrected p-values
+                from the association/reverse inference analysis, using cluster size.
+            -   ``z_desc-associationSize_level-cluster``: Cluster-level FWE-corrected z-values
+                from the association/reverse inference analysis, using cluster size.
+            -   ``logp_desc-associationSize_level-cluster``: Cluster-level FWE-corrected -log10
+                p-values from the association/reverse inference analysis, using cluster size.
 
         Notes
         -----
@@ -844,10 +853,10 @@ def correct_fwe_montecarlo(self, result, voxel_thresh=0.001, n_iters=5000, n_cor
             np.vstack(np.where(self.masker.mask_img.get_fdata())).T,
             self.masker.mask_img.affine,
         )
-        pAgF_chi2_vals = result.get_map("chi2_desc-consistency", return_type="array")
-        pFgA_chi2_vals = result.get_map("chi2_desc-specificity", return_type="array")
-        pAgF_z_vals = result.get_map("z_desc-consistency", return_type="array")
-        pFgA_z_vals = result.get_map("z_desc-specificity", return_type="array")
+        pAgF_chi2_vals = result.get_map("chi2_desc-uniformity", return_type="array")
+        pFgA_chi2_vals = result.get_map("chi2_desc-association", return_type="array")
+        pAgF_z_vals = result.get_map("z_desc-uniformity", return_type="array")
+        pFgA_z_vals = result.get_map("z_desc-association", return_type="array")
         pAgF_sign = np.sign(pAgF_z_vals)
         pFgA_sign = np.sign(pFgA_z_vals)
 
@@ -962,26 +971,26 @@ def correct_fwe_montecarlo(self, result, voxel_thresh=0.001, n_iters=5000, n_cor
         pFgA_logp_csfwe_vals[np.isinf(pFgA_logp_csfwe_vals)] = -np.log10(eps)
 
         maps = {
-            # Consistency analysis
-            "p_desc-consistency_level-voxel": pAgF_p_vfwe_vals,
-            "z_desc-consistency_level-voxel": pAgF_z_vfwe_vals,
-            "logp_desc-consistency_level-voxel": pAgF_logp_vfwe_vals,
-            "p_desc-consistencyMass_level-cluster": pAgF_p_cmfwe_vals,
-            "z_desc-consistencyMass_level-cluster": pAgF_z_cmfwe_vals,
-            "logp_desc-consistencyMass_level-cluster": pAgF_logp_cmfwe_vals,
-            "p_desc-consistencySize_level-cluster": pAgF_p_csfwe_vals,
-            "z_desc-consistencySize_level-cluster": pAgF_z_csfwe_vals,
-            "logp_desc-consistencySize_level-cluster": pAgF_logp_csfwe_vals,
-            # Specificity analysis
-            "p_desc-specificity_level-voxel": pFgA_p_vfwe_vals,
-            "z_desc-specificity_level-voxel": pFgA_z_vfwe_vals,
-            "logp_desc-specificity_level-voxel": pFgA_logp_vfwe_vals,
-            "p_desc-specificityMass_level-cluster": pFgA_p_cmfwe_vals,
-            "z_desc-specificityMass_level-cluster": pFgA_z_cmfwe_vals,
-            "logp_desc-specificityMass_level-cluster": pFgA_logp_cmfwe_vals,
-            "p_desc-specificitySize_level-cluster": pFgA_p_csfwe_vals,
-            "z_desc-specificitySize_level-cluster": pFgA_z_csfwe_vals,
-            "logp_desc-specificitySize_level-cluster": pFgA_logp_csfwe_vals,
+            # uniformity analysis
+            "p_desc-uniformity_level-voxel": pAgF_p_vfwe_vals,
+            "z_desc-uniformity_level-voxel": pAgF_z_vfwe_vals,
+            "logp_desc-uniformity_level-voxel": pAgF_logp_vfwe_vals,
+            "p_desc-uniformityMass_level-cluster": pAgF_p_cmfwe_vals,
+            "z_desc-uniformityMass_level-cluster": pAgF_z_cmfwe_vals,
+            "logp_desc-uniformityMass_level-cluster": pAgF_logp_cmfwe_vals,
+            "p_desc-uniformitySize_level-cluster": pAgF_p_csfwe_vals,
+            "z_desc-uniformitySize_level-cluster": pAgF_z_csfwe_vals,
+            "logp_desc-uniformitySize_level-cluster": pAgF_logp_csfwe_vals,
+            # association analysis
+            "p_desc-association_level-voxel": pFgA_p_vfwe_vals,
+            "z_desc-association_level-voxel": pFgA_z_vfwe_vals,
+            "logp_desc-association_level-voxel": pFgA_logp_vfwe_vals,
+            "p_desc-associationMass_level-cluster": pFgA_p_cmfwe_vals,
+            "z_desc-associationMass_level-cluster": pFgA_z_cmfwe_vals,
+            "logp_desc-associationMass_level-cluster": pFgA_logp_cmfwe_vals,
+            "p_desc-associationSize_level-cluster": pFgA_p_csfwe_vals,
+            "z_desc-associationSize_level-cluster": pFgA_z_csfwe_vals,
+            "logp_desc-associationSize_level-cluster": pFgA_logp_csfwe_vals,
         }
 
         description = ""
@@ -1009,7 +1018,7 @@ def correct_fdr_indep(self, result, alpha=0.05):
         maps : :obj:`dict`
             Dictionary of 1D arrays corresponding to masked maps generated by
             the correction procedure. The following arrays are generated by
-            this method: 'z_desc-consistency_level-voxel' and 'z_desc-specificity_level-voxel'.
+            this method: 'z_desc-uniformity_level-voxel' and 'z_desc-association_level-voxel'.
 
         See Also
         --------
@@ -1022,10 +1031,10 @@ def correct_fdr_indep(self, result, alpha=0.05):
         >>> corrector = FDRCorrector(method='indep', alpha=0.05)
         >>> cresult = corrector.transform(result)
         """
-        pAgF_p_vals = result.get_map("p_desc-consistency", return_type="array")
-        pFgA_p_vals = result.get_map("p_desc-specificity", return_type="array")
-        pAgF_z_vals = result.get_map("z_desc-consistency", return_type="array")
-        pFgA_z_vals = result.get_map("z_desc-specificity", return_type="array")
+        pAgF_p_vals = result.get_map("p_desc-uniformity", return_type="array")
+        pFgA_p_vals = result.get_map("p_desc-association", return_type="array")
+        pAgF_z_vals = result.get_map("z_desc-uniformity", return_type="array")
+        pFgA_z_vals = result.get_map("z_desc-association", return_type="array")
         pAgF_sign = np.sign(pAgF_z_vals)
         pFgA_sign = np.sign(pFgA_z_vals)
         pAgF_p_FDR = fdr(pAgF_p_vals, q=alpha, method="bh")
@@ -1035,8 +1044,8 @@ def correct_fdr_indep(self, result, alpha=0.05):
         pFgA_z_FDR = p_to_z(pFgA_p_FDR, tail="two") * pFgA_sign
 
         maps = {
-            "z_desc-consistency_level-voxel": pAgF_z_FDR,
-            "z_desc-specificity_level-voxel": pFgA_z_FDR,
+            "z_desc-uniformity_level-voxel": pAgF_z_FDR,
+            "z_desc-association_level-voxel": pFgA_z_FDR,
         }
 
         description = ""