Merge branch 'main' into plot-surface

.readthedocs.yml → .readthedocs.yaml

@@ -5,13 +5,17 @@
 # Required
 version: 2
 
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.8"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
   fail_on_warning: false
 
 python:
-  version: 3.8
   install:
     - requirements: docs/requirements.txt
     - method: pip

gradec/decode.py

@@ -23,7 +23,7 @@
 )
 from gradec.model import _get_counts, annotate_lda
 from gradec.stats import _permtest_pearson
-from gradec.transform import _mni152_to_fslr
+from gradec.transform import _vol_to_surf
 from gradec.utils import _check_ncores, _conform_features, get_data_dir
 
 
@@ -61,9 +61,21 @@ def _get_dataset(dset_nm, data_dir):
 class Decoder(metaclass=ABCMeta):
     """Base class for decoders in :mod:`~gradec.decode`."""
 
-    def __init__(self, feature_group=None, use_fetchers=True, data_dir=None, n_cores=1):
+    def __init__(
+        self,
+        space="fsLR",
+        density="32k",
+        feature_group=None,
+        use_fetchers=True,
+        calc_pvals=True,
+        data_dir=None,
+        n_cores=1,
+    ):
+        self.space = space
+        self.density = density
         self.feature_group = feature_group
         self.use_fetchers = use_fetchers
+        self.calc_pvals = calc_pvals
         self.data_dir = op.abspath(data_dir) if data_dir else op.abspath(".")
         self.neuromaps_dir = get_data_dir(op.join(self.data_dir, "neuromaps"))
         self.n_cores = _check_ncores(n_cores)
@@ -87,24 +99,53 @@ def fit(self, dset_nm, dset=None):
         self.dset_nm = dset_nm
 
         if self.use_fetchers:
-            metamaps_fslr = _fetch_metamaps(self.dset_nm, self.model_nm, self.data_dir)
-            features = _fetch_features(self.dset_nm, self.model_nm, self.data_dir)
+            metamaps_surf = _fetch_metamaps(
+                self.dset_nm,
+                self.model_nm,
+                space=self.space,
+                density=self.density,
+                data_dir=self.data_dir,
+            )
+            features = _fetch_features(self.dset_nm, self.model_nm, data_dir=self.data_dir)
+
         else:
             self.dset = dset or _get_dataset(dset_nm, self.data_dir)
             metamaps = self._train_decoder()
 
-            metamaps_fslr = _mni152_to_fslr(metamaps, neuromaps_dir=self.neuromaps_dir)
+            metamaps_surf = _vol_to_surf(
+                metamaps,
+                space=self.space,
+                density=self.density,
+                neuromaps_dir=self.neuromaps_dir,
+            )
             features = self._get_features()
-            # This feature is desabled for now because it takes too long.
-            # spinsamples_fslr = _gen_spinsamples(self.neuromaps_dir, self.n_samples, self.n_cores)
 
-        spinsamples_fslr = _fetch_spinsamples(self.n_samples, self.data_dir)
+            # This feature is desabled for now because it takes too long.
+            """
+            if self.calc_pvals:
+                spinsamples_surf = _gen_spinsamples(
+                    self.space,
+                    self.density,
+                    self.neuromaps_dir,
+                    self.n_samples,
+                    self.n_cores,
+                )
+            """
+
+        if self.calc_pvals:
+            spinsamples_surf = _fetch_spinsamples(
+                n_samples=self.n_samples,
+                space=self.space,
+                density=self.density,
+                data_dir=self.data_dir,
+            )
+            self.spinsamples_ = spinsamples_surf
+        else:
+            self.spinsamples_ = None
 
-        self.maps_ = metamaps_fslr
+        self.maps_ = metamaps_surf
         self.features_ = _conform_features(features, self.model_nm, self.n_top_words)
 
-        self.spinsamples_ = spinsamples_fslr
-
 
 class CorrelationDecoder(Decoder):
     """Decode an unthresholded image by correlating the image with meta-analytic maps."""
@@ -139,7 +180,11 @@ def transform(self, grad_maps):
             data = np.array(results).T
             data_df = pd.DataFrame(index=self.features_, data=data)
             data_df.index.name = "feature"
-            data_df_lst.append(data_df)
+
+            if self.calc_pvals:
+                data_df_lst.append(data_df)
+            else:
+                return data_df
 
         return data_df_lst
 

gradec/fetcher.py

@@ -16,23 +16,77 @@
 
 OSF_URL = "https://osf.io/{}/download"
 OSF_DICT = {
-    "term_neurosynth_metamaps.npz": "ju2tk",
-    "term_neurosynth_features.csv": "hyjrk",
-    "term_neuroquery_metamaps.npz": "38fh4",
-    "term_neuroquery_features.csv": "xtjna",
-    "lda_neurosynth_metamaps.npz": "9ftkm",
-    "lda_neurosynth_features.csv": "ve3nj",
-    "lda_neuroquery_metamaps.npz": "k4xza",
-    "lda_neuroquery_features.csv": "u68w7",
-    "gclda_neurosynth_metamaps.npz": "hwdft",
-    "gclda_neurosynth_features.csv": "jcrkd",
+    "source-neuroquery_desc-gclda_features.csv": "trcxs",
+    "source-neuroquery_desc-gclda_frequencies.csv": "kcem9",
+    "source-neuroquery_desc-gclda_classification.csv": "93dvg",
+    "source-neuroquery_desc-gclda_space-civet_density-41k_metamaps.npz": "qbn7g",
+    "source-neuroquery_desc-gclda_space-fsLR_density-32k_metamaps.npz": "ey6cw",
+    "source-neuroquery_desc-gclda_space-fsLR_density-164k_metamaps.npz": "4erpq",
+    "source-neuroquery_desc-gclda_space-fsaverage_density-3k_metamaps.npz": "jg34m",
+    "source-neuroquery_desc-gclda_space-fsaverage_density-10k_metamaps.npz": "sh9eq",
+    "source-neuroquery_desc-gclda_space-fsaverage_density-41k_metamaps.npz": "ca2hp",
+    "source-neuroquery_desc-gclda_space-fsaverage_density-164k_metamaps.npz": "4ne7f",
+    "source-neuroquery_desc-lda_features.csv": "u68w7",
+    "source-neuroquery_desc-lda_frequencies.csv": "ygpxf",
+    "source-neuroquery_desc-lda_classification.csv": "mtwvc",
+    "source-neuroquery_desc-lda_space-civet_density-41k_metamaps.npz": "74trb",
+    "source-neuroquery_desc-lda_space-fsLR_density-32k_metamaps.npz": "k4xza",
+    "source-neuroquery_desc-lda_space-fsLR_density-164k_metamaps.npz": "wvznp",
+    "source-neuroquery_desc-lda_space-fsaverage_density-3k_metamaps.npz": "xbrgd",
+    "source-neuroquery_desc-lda_space-fsaverage_density-41k_metamaps.npz": "hu3y4",
+    "source-neuroquery_desc-lda_space-fsaverage_density-10k_metamaps.npz": "qwb5u",
+    "source-neuroquery_desc-lda_space-fsaverage_density-164k_metamaps.npz": "qzhrn",
+    "source-neuroquery_desc-term_features.csv": "xtjna",
+    "source-neuroquery_desc-term_classification.csv": "ypqzx",
+    "source-neuroquery_desc-term_space-civet_density-41k_metamaps.npz": "vw9fr",
+    "source-neuroquery_desc-term_space-fsLR_density-32k_metamaps.npz": "38fh4",
+    "source-neuroquery_desc-term_space-fsLR_density-164k_metamaps.npz": "",  # Updt
+    "source-neuroquery_desc-term_space-fsaverage_density-3k_metamaps.npz": "b5jme",
+    "source-neuroquery_desc-term_space-fsaverage_density-10k_metamaps.npz": "dt3j4",
+    "source-neuroquery_desc-term_space-fsaverage_density-41k_metamaps.npz": "9xsqb",
+    "source-neuroquery_desc-term_space-fsaverage_density-164k_metamaps.npz": "",  # Updt
+    "source-neurosynth_desc-gclda_features.csv": "jcrkd",
+    "source-neurosynth_desc-gclda_frequencies.csv": "48hbz",
+    "source-neurosynth_desc-gclda_classification.csv": "p7nd9",
+    "source-neurosynth_desc-gclda_space-civet_density-41k_metamaps.npz": "swp3c",
+    "source-neurosynth_desc-gclda_space-fsLR_density-32k_metamaps.npz": "hwdft",
+    "source-neurosynth_desc-gclda_space-fsLR_density-164k_metamaps.npz": "qzyvj",
+    "source-neurosynth_desc-gclda_space-fsaverage_density-3k_metamaps.npz": "r5p7x",
+    "source-neurosynth_desc-gclda_space-fsaverage_density-10k_metamaps.npz": "w2xj3",
+    "source-neurosynth_desc-gclda_space-fsaverage_density-41k_metamaps.npz": "dw3t9",
+    "source-neurosynth_desc-gclda_space-fsaverage_density-164k_metamaps.npz": "mw2pa",
+    "source-neurosynth_desc-lda_features.csv": "ve3nj",
+    "source-neurosynth_desc-lda_frequencies.csv": "485je",
+    "source-neurosynth_desc-lda_classification.csv": "9mrxb",
+    "source-neurosynth_desc-lda_space-civet_density-41k_metamaps.npz": "86u59",
+    "source-neurosynth_desc-lda_space-fsLR_density-32k_metamaps.npz": "9ftkm",
+    "source-neurosynth_desc-lda_space-fsLR_density-164k_metamaps.npz": "bxefz",
+    "source-neurosynth_desc-lda_space-fsaverage_density-3k_metamaps.npz": "pb9mw",
+    "source-neurosynth_desc-lda_space-fsaverage_density-10k_metamaps.npz": "urg3a",
+    "source-neurosynth_desc-lda_space-fsaverage_density-41k_metamaps.npz": "dbv4z",
+    "source-neurosynth_desc-lda_space-fsaverage_density-164k_metamaps.npz": "7rw8c",
+    "source-neurosynth_desc-term_features.csv": "hyjrk",
+    "source-neurosynth_desc-term_classification.csv": "sd4wy",
+    "source-neurosynth_desc-term_space-civet_density-41k_metamaps.npz": "rwxta",
+    "source-neurosynth_desc-term_space-fsLR_density-32k_metamaps.npz": "ju2tk",
+    "source-neurosynth_desc-term_space-fsLR_density-164k_metamaps.npz": "dzm39",
+    "source-neurosynth_desc-term_space-fsaverage_density-3k_metamaps.npz": "hvw6x",
+    "source-neurosynth_desc-term_space-fsaverage_density-10k_metamaps.npz": "q2txn",
+    "source-neurosynth_desc-term_space-fsaverage_density-41k_metamaps.npz": "cyuqn",
+    "source-neurosynth_desc-term_space-fsaverage_density-164k_metamaps.npz": "s8txr",
+    "source-vasa2018_desc-null1000_space-civet_density-41k_metamaps.npz": "8svr2",  # Updt
+    "source-vasa2018_desc-null1000_space-fsLR_density-32k_spinsamples.npz": "q5yv6",
+    "source-vasa2018_desc-null1000_space-fsLR_density-164k_spinsamples.npz": "nj3cr",  # Updt
+    "source-vasa2018_desc-null1000_space-fsaverage_density-3k_spinsamples.npz": "8vjxm",  # Updt
+    "source-vasa2018_desc-null1000_space-fsaverage_density-10k_spinsamples.npz": "yz59g",  # Updt
+    "source-vasa2018_desc-null1000_space-fsaverage_density-41k_spinsamples.npz": "esr9y",  # Updt
+    "source-vasa2018_desc-null1000_space-fsaverage_density-164k_spinsamples.npz": "e956f",  # Updt
     "gclda_neurosynth_model.pkl.gz": "bg8ef",
-    "gclda_neuroquery_metamaps.npz": "ey6cw",
-    "gclda_neuroquery_features.csv": "trcxs",
     "gclda_neuroquery_model.pkl.gz": "vsm65",
+    "lda_neurosynth_model.pkl.gz": "3kgfe",
+    "lda_neuroquery_model.pkl.gz": "wevdn",
     "hcp-s1200_gradients.npy": "t95gk",
     "principal_gradient.npy": "5th7c",
-    "spinsamples_fslr.npz": "q5yv6",
     "neuroquery_counts": "p39mg",
 }
 
@@ -111,7 +165,7 @@ def _fetch_features(dset_nm, model_nm, data_dir=None, overwrite=False, resume=Tr
     data_dir = get_data_dir(data_dir)
     dec_dir = get_data_dir(os.path.join(data_dir, "decoding"))
 
-    filename = f"{model_nm}_{dset_nm}_features.csv"
+    filename = f"source-{dset_nm}_desc-{model_nm}_features.csv"
     url = _get_osf_url(filename)
 
     features_fn = _my_fetch_file(
@@ -127,7 +181,109 @@ def _fetch_features(dset_nm, model_nm, data_dir=None, overwrite=False, resume=Tr
     return df.values.tolist()
 
 
-def _fetch_metamaps(dset_nm, model_nm, data_dir=None, overwrite=False, resume=True, verbose=1):
+def _fetch_frequencies(dset_nm, model_nm, data_dir=None, overwrite=False, resume=True, verbose=1):
+    """Fetch frequencies from OSF.
+
+    Parameters
+    ----------
+    dset_nm : :obj:`str`
+        Name of dataset.
+    model_nm : :obj:`str`
+        Name of model.
+    data_dir : :obj:`pathlib.Path` or :obj:`str`, optional
+        Path where data should be downloaded. By default,
+        files are downloaded in home directory
+    resume : :obj:`bool`, optional
+        Whether to resume download of a partly-downloaded file.
+        Default=True.
+    verbose : :obj:`int`, optional
+        Verbosity level (0 means no message).
+        Default=1.
+
+    Returns
+    -------
+    :class:`list` of list
+        List of frequency values.
+    """
+    data_dir = get_data_dir(data_dir)
+    dec_dir = get_data_dir(os.path.join(data_dir, "decoding"))
+
+    filename = f"source-{dset_nm}_desc-{model_nm}_frequencies.csv"
+    url = _get_osf_url(filename)
+
+    features_fn = _my_fetch_file(
+        dec_dir,
+        filename,
+        url,
+        overwrite=overwrite,
+        resume=resume,
+        verbose=verbose,
+    )
+
+    df = pd.read_csv(features_fn)
+    return df.values.tolist()
+
+
+def _fetch_classification(
+    dset_nm,
+    model_nm,
+    data_dir=None,
+    overwrite=False,
+    resume=True,
+    verbose=1,
+):
+    """Fetch classification from OSF.
+
+    Parameters
+    ----------
+    dset_nm : :obj:`str`
+        Name of dataset.
+    model_nm : :obj:`str`
+        Name of model.
+    data_dir : :obj:`pathlib.Path` or :obj:`str`, optional
+        Path where data should be downloaded. By default,
+        files are downloaded in home directory
+    resume : :obj:`bool`, optional
+        Whether to resume download of a partly-downloaded file.
+        Default=True.
+    verbose : :obj:`int`, optional
+        Verbosity level (0 means no message).
+        Default=1.
+
+    Returns
+    -------
+    :class:`list` of list
+        List of classification values.
+    """
+    data_dir = get_data_dir(data_dir)
+    dec_dir = get_data_dir(os.path.join(data_dir, "decoding"))
+
+    filename = f"source-{dset_nm}_desc-{model_nm}_classification.csv"
+    url = _get_osf_url(filename)
+
+    features_fn = _my_fetch_file(
+        dec_dir,
+        filename,
+        url,
+        overwrite=overwrite,
+        resume=resume,
+        verbose=verbose,
+    )
+
+    df = pd.read_csv(features_fn, index_col="Classification")
+    return df.index.tolist(), df.values.tolist()
+
+
+def _fetch_metamaps(
+    dset_nm,
+    model_nm,
+    space="fsLR",
+    density="32k",
+    data_dir=None,
+    overwrite=False,
+    resume=True,
+    verbose=1,
+):
     """Fetch meta-analytic maps from OSF.
 
     Parameters
@@ -154,7 +310,7 @@ def _fetch_metamaps(dset_nm, model_nm, data_dir=None, overwrite=False, resume=Tr
     data_dir = get_data_dir(data_dir)
     dec_dir = get_data_dir(os.path.join(data_dir, "decoding"))
 
-    filename = f"{model_nm}_{dset_nm}_metamaps.npz"
+    filename = f"source-{dset_nm}_desc-{model_nm}_space-{space}_density-{density}_metamaps.npz"
     url = _get_osf_url(filename)
 
     metamaps_fn = _my_fetch_file(
@@ -169,7 +325,15 @@ def _fetch_metamaps(dset_nm, model_nm, data_dir=None, overwrite=False, resume=Tr
     return np.load(metamaps_fn)["arr"]
 
 
-def _fetch_spinsamples(n_samples=1000, data_dir=None, overwrite=False, resume=True, verbose=1):
+def _fetch_spinsamples(
+    n_samples=1000,
+    space="fsLR",
+    density="32k",
+    data_dir=None,
+    overwrite=False,
+    resume=True,
+    verbose=1,
+):
     """Fetch spin samples from OSF.
 
     Parameters
@@ -191,7 +355,7 @@ def _fetch_spinsamples(n_samples=1000, data_dir=None, overwrite=False, resume=Tr
     """
     data_dir = get_data_dir(data_dir)
 
-    filename = "spinsamples_fslr.npz"
+    filename = f"source-vasa2018_desc-null1000_space-{space}_density-{density}_spinsamples.npz"
     url = _get_osf_url(filename)
 
     spinsamples_fn = _my_fetch_file(