[DOC 📄] improved documentation, added methodological details, new imp…

…ort/export module

docs/build/html/genindex.html

@@ -103,6 +103,12 @@
 <li class="toctree-l1"><a class="reference internal" href="pages/03.loadct/index.html">Individual site data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pages/04.crossdisorder/index.html">Cross-disorder effect</a></li>
 </ul>
+<p class="caption"><span class="caption-text">Compatibility with other datasets</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="pages/16.import/index.html">Import vertexwise or parcellated data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="pages/17.parcellate_vw/index.html">Vertexwise ↔ parcellated data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="pages/18.export/index.html">Export data results</a></li>
+</ul>
 <p class="caption"><span class="caption-text">Surface data visualization</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="pages/12.visualization/index.html">Surface data visualization</a></li>
@@ -202,8 +208,10 @@ <h1 id="index">Index</h1>
  | <a href="#C"><strong>C</strong></a>
  | <a href="#E"><strong>E</strong></a>
  | <a href="#F"><strong>F</strong></a>
+ | <a href="#G"><strong>G</strong></a>
  | <a href="#L"><strong>L</strong></a>
  | <a href="#M"><strong>M</strong></a>
+ | <a href="#N"><strong>N</strong></a>
  | <a href="#P"><strong>P</strong></a>
  | <a href="#R"><strong>R</strong></a>
  | <a href="#S"><strong>S</strong></a>
@@ -327,6 +335,14 @@ <h2 id="F">F</h2>
  </ul></td>
 </tr></table>
 
+<h2 id="G">G</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="pages/13.01.apireference/generated/enigmatoolbox.datasets.getaffine.html#enigmatoolbox.datasets.getaffine">getaffine() (in module enigmatoolbox.datasets)</a>
+</li>
+ </ul></td>
+</tr></table>
+
 <h2 id="L">L</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>
@@ -378,6 +394,14 @@ <h2 id="M">M</h2>
  </ul></td>
 </tr></table>
 
+<h2 id="N">N</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="pages/13.01.apireference/generated/enigmatoolbox.datasets.nfaces.html#enigmatoolbox.datasets.nfaces">nfaces() (in module enigmatoolbox.datasets)</a>
+</li>
+ </ul></td>
+</tr></table>
+
 <h2 id="P">P</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
  <td style="width: 33%; vertical-align: top;"><ul>

docs/build/html/search.html

@@ -105,6 +105,12 @@
 <li class="toctree-l1"><a class="reference internal" href="pages/03.loadct/index.html">Individual site data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="pages/04.crossdisorder/index.html">Cross-disorder effect</a></li>
 </ul>
+<p class="caption"><span class="caption-text">Compatibility with other datasets</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="pages/16.import/index.html">Import vertexwise or parcellated data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="pages/17.parcellate_vw/index.html">Vertexwise ↔ parcellated data</a></li>
+<li class="toctree-l1"><a class="reference internal" href="pages/18.export/index.html">Export data results</a></li>
+</ul>
 <p class="caption"><span class="caption-text">Surface data visualization</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="pages/12.visualization/index.html">Surface data visualization</a></li>

docs/index.rst

@@ -45,52 +45,77 @@
 |
 
 
-Data archiving and accessing 🗝
-------------------------------------
-The **ENIGMA TOOLBOX** has a *No data, No problem* policy! We provide a central repository for archiving meta-analytical :ref:`case-control 
-comparisons<load_sumstats>` across a wide range of disorders. As many ENIGMA groups have moved beyond meta-analysis 
-towards ‘mega’-analysis of subject-level data, the **ENIGMA TOOLBOX** also includes subject-level :ref:`example data<load_ct>` 
-from an individual site that have been processed according to ENIGMA protocols.
+100+ ENIGMA-derived statistical maps 💯
+-------------------------------------------------
+The **ENIGMA TOOLBOX** provides a centralized, and continuously updated, repository of meta-analytical :ref:`case-control 
+comparisons <load_sumstats>` across a wide range of disorders. As many ENIGMA groups have moved beyond meta-analysis 
+towards ‘mega’-analysis of subject-level data, the **ENIGMA TOOLBOX** also includes an example of subject-level :ref:`example data<load_ct>` 
+from an individual site that have been processed according to `ENIGMA protocols <http:https://enigma.ini.usc.edu/protocols/>`_. 
+It should be noted, however, that subject-level or raw imaging data are not yet available for dissemination to the scientific community. 
+Interested scientists are encouraged to visit the `ENIGMA website <http:https://enigma.ini.usc.edu/>`_ to learn more about 
+current projects, joining and contributing to an active Working Group, 
+or proposing a new group.
+
+.. raw:: html
+
+ <br>
+
+Compatible with any neuroimaging datasets and software 💌
+--------------------------------------------------------------------
+To increase generalizability and usability, every function within the **ENIGMA TOOLBOX** is compatible with any 
+neuroimaging data parcellated according to the `Desikan-Killiany <https://www.sciencedirect.com/science/article/abs/pii/S1053811906000437?via%3Dihub>`_, 
+`Glasser <https://www.nature.com/articles/nature18933>`_, and 
+`Schaefer <https://academic.oup.com/cercor/article/28/9/3095/3978804>`_ parcellations. 
+
+To simplify things, we provide tutorials on how to (*i*) :ref:`import vertexwise and/or parcellated data <import_data>`, 
+(*ii*) :ref:`parcellate vertexwise cortical data <vw_to_parc>`, (*iii*) :ref:`map parcellated data to the surface <parc_to_vw>`, and 
+(*iv*) :ref:`export data results <export_data>`. Import/export file formats include: .txt/.csv, 
+FreeSurfer/"curv". mgh/.mgz, GIfTI/.gii. Cortical and subcortical surfaces are also available in FreeSurfer/surface, GIfTI/.gii, .vtk, and .obj 
+formats, allowing cross-software compatibility.
 
 .. raw:: html
 
  <br>
 
-Visualization tools 🎨
--------------------------------------
+Cortical and subcortical visualization tools 🎨
+---------------------------------------------------------
 Tired of displaying your surface findings in tables? Look no further! The **ENIGMA TOOLBOX** has got you 
-covered! Check out our :ref:`visualization tools<surf_visualization>` and project your cortical and subcortical data to the surface!
+covered! Check out our :ref:`visualization tools<surf_visualization>` to project cortical and subcortical data results 
+to the surface and generate publication-ready figures.
 
 .. raw:: html
 
  <br>
 
-Data sharing and exploiting 💌
-------------------------------------
-As part of the **ENIGMA TOOLBOX**, we are 
-also making several data matrices openly available! As of now, these include :ref:`functional and structural 
-connectivity data<hcp_connectivity>` and :ref:`transcriptomic data<gene_maps>`.
+Preprocessed micro- and macroscale data 🤹🏼‍♀️
+------------------------------------------------------------------------
+The emergence of open databases yields new opportunities to link human gene expression, cytoarchitecture, and connectome data. 
+As part of the **ENIGMA TOOLBOX**, we have generated and made available a range of preprocessed and parcellated data, including: 
+(*i*) :ref:`transcriptomic data <gene_maps>` from the `Allen Human Brain Atlas <https://human.brain-map.org/>`_, 
+(*ii*) :ref:`cytoarchitectural data <big_brain>` from the `BigBrain Project <https://science.sciencemag.org/content/340/6139/1472>`_, 
+(*iii*) a :ref:`digitized parcellation <economo_koskinas>` of the `von Economo and Koskinas cytoarchitectonic map <https://www.karger.com/Article/Abstract/103258>`_, and 
+(*iv*) :ref:`functional and structural connectivity data <hcp_connectivity>` from the `Human Connectome Project <http:https://www.humanconnectomeproject.org/>`_.
 
 .. raw:: html
 
  <br>
 
-Advanced analytical workflows 🦾
+Multiscale analytical workflows 🦾
 --------------------------------------------------------
-The main goal of the **ENIGMA TOOLBOX** is
-to provide the ENIGMA community with open-access pipelines and analytical tools for 
-conducting advanced secondary analyses, offering a platform to facilitate results reproducibility both 
-*within* and *across* ENIGMA Working Groups. From these workflows, users can gain further neurobiological 
-insights into how disease-related regional susceptibility patterns are anchored to multiple scales of 
-cortical and subcortical brain network architecture.
+The **ENIGMA Toolbox** comprises two neural scales for the contextualization of findings: (*i*) using microscale properties, namely 
+:ref:`gene expression <ep_genes>` and :ref:`cytoarchitecture <big_brain>`, and (*ii*) using macroscale network models, such as 
+:ref:`regional hub susceptibility analysis <hubs_susceptibility>` and :ref:`disease epicenter mapping <epi_mapping>`. Moreover, our 
+Toolbox includes non-parametric :ref:`spatial permutation models <spin_perm>` to assess statistical significance while preserving 
+the spatial autocorrelation of parcellated brain maps. From these comprehensive workflows, users can gain a deeper understanding 
+of the molecular, cellular, and macroscale network organization of the healthy and diseased brains.
 
 .. raw:: html
 
  <br>
 
 Step-by-step tutorials 👣
 ------------------------------------
-The **ENIGMA TOOLBOX** includes ready-to-use and easy-to-follow code snippets
+The **ENIGMA TOOLBOX** includes ready-to-use and easy-to-follow code snippets 
 for every functionality and analytical workflow! Owing to its comprehensive tutorials, detailed functionality descriptions, 
 and visual reports, the **ENIGMA TOOLBOX** is easy to use for researchers and clinicians without extensive programming expertise. 
 
@@ -101,12 +126,17 @@ and visual reports, the **ENIGMA TOOLBOX** is easy to use for researchers and cl
 Development and getting involved ⚙️
 -------------------------------------------
 Should you have any problems, questions, or suggestions about the **ENIGMA TOOLBOX**, please do not
-hesitate to post them to our `mailing list <https://groups.google.com/g/enigma-toolbox>`_! Or are you interested in collaborating 
-or sharing your ENIGMA-related codes/tools? `Noice <https://www.urbandictionary.com/define.php?term=noice>`_! 
+hesitate to post them to our `mailing list <https://groups.google.com/g/enigma-toolbox>`_! Are you interested in collaborating 
+or sharing your ENIGMA-related data/codes/tools? `Noice <https://www.urbandictionary.com/define.php?term=noice>`_! 
 Make sure you familiarize yourself with our `contributing guidelines <https://github.com/MICA-MNI/ENIGMA/blob/master/CONTRIBUTING.md>`_ 
 first and then discuss your ideas on our Github `issues <https://github.com/MICA-MNI/ENIGMA/issues>`_ and 
 `pull request <https://github.com/MICA-MNI/ENIGMA/pulls>`_.
 
+.. raw:: html
+
+ <br>
+
+
 .. toctree::
  :maxdepth: 1
  :hidden:
@@ -127,6 +157,16 @@ first and then discuss your ideas on our Github `issues <https://github.com/MICA
  pages/04.crossdisorder/index
 
 
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+ :caption: Compatibility with other datasets 
+
+ pages/16.import/index
+ pages/17.parcellate_vw/index
+ pages/18.export/index
+
+
 .. toctree::
  :maxdepth: 1
  :hidden:

docs/pages/02.whatsnew/index.rst

@@ -5,6 +5,15 @@
 What's new?
 ======================================
 
+v1.1.0 (March XX, 2021)
+------------------------------------------
+New import/export features allowing compatibility with other dataset formats and neuroimaging softwares. Improved documentation.
+::
+
+ ↪ [NEW 💾] New import/export module | @saratheriver
+ ↪ [DOC 📄] Update documentations | @saratheriver
+
+
 v1.0.3 (February 25, 2021)
 ------------------------------------------
 OCD subcortical volume measures were not loading when using ``load_summary_stats('ocd')``; this issue is now resolved.

docs/pages/04.crossdisorder/index.rst

@@ -12,8 +12,9 @@ brain structural abnormalities that are common or different across disorders.
 
 Principal component analysis
 -----------------------------------------
-We can explore shared and disease-specific morphometric signatures by applying a principal component 
-analysis (PCA) to any combination of disease-specific summary statistics (or other pre-loaded ENIGMA-type data), 
+To yield novel insights into brain structural abnormalities that are common or different across disorders, 
+we can explore shared and disease-specific morphometric signatures by applying a principal component 
+analysis (PCA) to any combination of disease-specific summary statistics (or other imported data), 
 resulting in shared latent components that can be used for further analysis.
 
 .. tabs::

docs/pages/04.loadsumstats/index.rst

@@ -11,10 +11,20 @@ for case-control differences** (d_icv), **standard error** (se_icv), **lower bou
 (low_ci_icv), **upper bound of the confidence interval** (up_ci_icv), **number of controls** (n_controls), 
 **number of patiens** (n_patients), **observed p-values** (pobs), **false discovery rate (FDR)-corrected p-value** (fdr_p).
 
+ENIGMA’s standardized protocols for data processing, quality assurance, and meta-analysis of individual subject data were 
+conducted at each site. For site-level meta-analysis, all research centres within a given specialized Working Group tested 
+for case *vs*. control differences using multiple linear regressions, where diagnosis (*e.g.*, healthy controls vs. individuals 
+with epilepsy) was the predictor of interest, and subcortical volume, cortical thickness, or surface area of a given brain region 
+was the outcome measure. Case-control differences were computed across all regions using either Cohen’s *d* effect sizes or *t*-values, 
+after adjusting for different combinations of age, sex, site/scan/dataset, intracranial volume, IQ (see below for disease-specific 
+models). 
+
 .. admonition:: Can't find the data you're searching for? 🙈
 
  Let us know what's missing and we'll try and fetch that data for you and implement it in our toolbox. 
- Get in touch with us `here <https://github.com/MICA-MNI/ENIGMA/issues>`_.
+ Get in touch with us `here <https://github.com/MICA-MNI/ENIGMA/issues>`_. If you have locally stored 
+ summary statistics on your computer, check out our tutorials on :ref:`how to import data <import_data>`
+ and accordingly take advantage of all the **ENIGMA TOOLBOX** functions.
 
 
 \* 📸 *indicates case-control tables used in the code snippets.*

docs/pages/05.HCP/index.rst

@@ -7,11 +7,43 @@ Connectivity data
 
 This page contains descriptions and examples to use Human Connectome Project (HCP) connectivity data.
 
-For details on HCP participants and data processing, please see our manuscript entitled 
-`Network-based atrophy modelling in the common epilepsies: a worldwide ENIGMA study <https://advances.sciencemag.org/content/6/47/eabc6457>`_.
-
-
-.. admonition:: one matrix 🎤
+Neuroimaging, particularly with functional and diffusion MRI, has become a leading tool to characterize 
+human brain network organization *in vivo* and to identify network alterations in brain disorders. 
+The **ENIGMA TOOLBOX** includes high-resolution structural (derived from diffusion-weighted tractography) 
+and functional (derived from resting-state functional MRI) connectivity data from a cohort of unrelated 
+healthy adults from the Human Connectome Project (HCP). Preprocessed cortico-cortical, subcortico-cortical, 
+and subcortico-subcortical functional and structural connectivity matrices can be easily retrieved using the 
+``load_fc()`` and ``load_sc()`` functions. 
+
+High-resolution functional and structural data were parcellated according to the `Desikan-Killiany 
+<https://www.sciencedirect.com/science/article/abs/pii/S1053811906000437?via%3Dihub>`_, 
+`Glasser <https://www.nature.com/articles/nature18933>`_, as well as 
+`Schaefer <https://academic.oup.com/cercor/article/28/9/3095/3978804>`_ 100, 200, 300, and 400 parcellations.
+
+Normative functional connectivity matrices were generated by computing pairwise correlations between the time 
+series of all cortical regions and subcortical (nucleus accumbens, amygdala, caudate, hippocampus, pallidum, 
+putamen, thalamus) regions; negative connections were set to zero. Subject-specific connectivity matrices were 
+then *z*-transformed and aggregated across participants to construct a group-average functional connectome. 
+Available cortico-cortical, subcortico-cortical, and subcortico-subcortical matrices are unthresholded. 
+
+Normative structural connectivity matrices were generated from preprocessed diffusion MRI data using `MRtrix3 <https://www.mrtrix.org/>`_. 
+Anatomical constrained tractography was performed using different tissue types derived from the T1-weighted image, 
+including cortical and subcortical gray matter, white matter, and cerebrospinal fluid. Multi-shell and multi-tissue 
+response functions were estimated104 and constrained spherical deconvolution and intensity normalization were performed. 
+The initial tractogram was generated with 40 million streamlines, with a maximum tract length of 250 and a fractional anisotropy cutoff of 0.06. 
+Spherical-deconvolution informed filtering of tractograms (SIFT2) was applied to reconstruct whole-brain streamlines weighted 
+by the cross-section multipliers. Reconstructed streamlines were mapped onto the 68 cortical and 14 subcortical 
+(including hippocampus) regions to produce subject-specific structural connectivity matrices. 
+The group-average normative structural connectome was defined using a distance-dependent thresholding 
+procedure, which preserved the edge length distribution in individual patients, and was log 
+transformed to reduce connectivity strength variance. As such, structural connectivity was defined by the 
+number of streamlines between two regions (*i.e.*, fiber density).
+
+Additional details on subject inclusion and data preprocessing are provided in the **ENIGMA TOOLBOX** `preprint 
+<https://doi.org/10.1101/2020.12.21.423838>`_.
+
+
+.. admonition:: One matrix 🎤
 
  Are you looking for subcortico-subcortical connectivity? Or do you want cortical and subcortical connectivity 
  in one matrix? If so, check out our functions: ``load_fc_as_one()`` 

docs/pages/06.hubs/index.rst

@@ -14,10 +14,12 @@ on hub susceptibility models, please see our manuscript entitled
 
 Cortical hubs
 ------------------------------------------
-Using the :ref:`HCP connectivity data <hcp_connectivity>`, we can then compute weighted (optimal for unthresholded connectivity
-matrices) degree centrality to identify structural and functional hub regions. This is done by simply 
-computing the sum of all weighted cortico-cortical connections for every region. Higher degree centrality 
-denotes increased hubness (*i.e.*, node with many connections).
+Normative structural and functional connectomes hold valuable information for relating macroscopic brain network 
+organization to patterns of disease-related atrophy. Using the :ref:`HCP connectivity data <hcp_connectivity>`, 
+we can first compute weighted (optimal for unthresholded connectivity
+matrices) degree centrality to identify structural and functional hub regions (*i.e.*, brain regions with many connections). 
+This is done by simply computing the sum of all weighted cortico-cortical connections for every region. Higher degree centrality 
+denotes increased hubness.
 
 
 .. parsed-literal:: 
@@ -78,7 +80,7 @@ denotes increased hubness (*i.e.*, node with many connections).
 
 Subcortical hubs
 ---------------------------------------------
-The :ref:`HCP connectivity data <surf_visualization>` can also be used to identify structural 
+The :ref:`HCP connectivity data <load_subcorticocortical>` can also be used to identify structural 
 and functional subcortico-cortical hub regions. As above, we simply compute the sum of all weighted 
 subcortico-cortical connections for every subcortical area. Once again, higher degree centrality 
 denotes increased hubness.