[DOC 📄] api matlab almost done

docs/pages/13.01.apireference/index.rst

@@ -183,24 +183,25 @@ Surface plotting
 
 .. currentmodule:: enigmatoolbox.utils
 
-Z-score data matrix
-^^^^^^^^^^^^^^^^^^^^^^^
+
+Re-order subcortical data matrix
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. autosummary::
    :template: function.rst
    :toctree: generated/
 
-   enigmatoolbox.utils.useful.zscore_matrix
+   enigmatoolbox.utils.useful.reorder_sctx
 
 
-Re-order subcortical data matrix
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Z-score data matrix
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. autosummary::
    :template: function.rst
    :toctree: generated/
 
-   enigmatoolbox.utils.useful.reorder_sctx
+   enigmatoolbox.utils.useful.zscore_matrix
 
 
 Parcellation

docs/pages/13.02.apireferencematlab/generated/centroid_extraction_sphere.rst

@@ -7,15 +7,21 @@
 centroid_extraction_sphere()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/permutation_testing/centroid_extraction_sphere.m>`_]:
     .. function:: 
-        centroid_extraction_sphere = centroid_extraction_sphere()
+        centroid = centroid_extraction_sphere(sphere_coords, annotfile)
 
 **Description**:
-    ...
+    Extract centroids of a cortical parcellation on a surface sphere (authors: @frantisekvasa, @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **sphere_coords** (*double array*) – Sphere coordinates, size = [n x 3]
+    - **annotfile** (*string*) – Name of annotation file {‘fsa5_lh_aparc.annot’, ‘fsa5_rh_aparc.annot, ‘fsa5_with_sctx_lh_aparc_aseg.csv’, etc.}
+    - **ventricles** (*string, optional*) – Whether ventricle data are present. Only used when ‘annotfile’ is fsa5_with_sctx_lh_aparc_aseg or fsa5_with_sctx_lh_aparc_aseg``. Default is 'False'.
 
 **Outputs**:
-    **...** (*...*) – ...
+    **coord** (*double array*) – Coordinates of the centroid of each region on the sphere, size = [m x 3].
+
+**References**:
+    - Alexander-Bloch A, Shou H, Liu S, Satterthwaite TD, Glahn DC, Shinohara RT, Vandekar SN and Raznahan A (2018). On testing for spatial correspondence between maps of human brain structure and function. NeuroImage, 178:540-51.
+    - Váša F, Seidlitz J, Romero-Garcia R, Whitaker KJ, Rosenthal G, Vértes PE, Shinn M, Alexander-Bloch A, Fonagy P, Dolan RJ, Goodyer IM, the NSPN consortium, Sporns O, Bullmore ET (2017). Adolescent tuning of association cortex in human structural brain networks. Cerebral Cortex, 28(1):281–294.

docs/pages/13.02.apireferencematlab/generated/parcel_to_surface.rst

@@ -7,15 +7,17 @@
 parcel_to_surface()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/useful/parcel_to_surface.m>`_]:
     .. function:: 
-        parcel_to_surface = parcel_to_surface()
+        parcel2surf = parcel_to_surface(parcel_data, parcellation, fill)
 
 **Description**:
-    ...
+    Map parcellated data to the surface (authors : @MICA-MNI, @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **parcel_data** (*double array*) - Parcel vector, size = [p x 1]. For example, if Desikan Killiany from ENIGMA data, then parcel_data is size =  [68 x 1].
+    - **parcellation** (*string, optional*) - Default is 'aparc_fsa5'
+    - **fill** (*double, optional*) - Value for mask. Default is 0.
 
 **Outputs**:
-    **...** (*...*) – ...
+    **parcel2surf** (*double array*) – Vector of values mapped from a parcellation to the surface

docs/pages/13.02.apireferencematlab/generated/perm_sphere_p.rst

@@ -7,15 +7,23 @@
 perm_sphere_p()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/permutation_testing/perm_sphere_p.m>`_]:
     .. function:: 
-        perm_sphere_p = perm_sphere_p()
+        [p_perm, null_dist] = perm_sphere_p(x, y, perm_id, corr_type)
 
 **Description**:
-    ...
+    Generate a p-value for the spatial correlation between two parcellated cortical surface maps (authors: @frantisekvasa, @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **x** (*double array*) – One of two map to be correlated
+    - **y** (*double array*) – The other map to be correlated
+    - **perm_id** (*double array*) – Array of permutations, size = [m x nrot]
+    - **corr_type** (*string, optional*) - Correlation type {‘pearson’, ‘spearman’}. Default is ‘pearson’.
 
 **Outputs**:
-    **...** (*...*) – ...
+    - **p_perm** (*double*) – Permutation p-value
+    - **null_dist** (*double array*) - Null correlations, size = [n_rot*2 x 1].
+
+**References**:
+    - Alexander-Bloch A, Shou H, Liu S, Satterthwaite TD, Glahn DC, Shinohara RT, Vandekar SN and Raznahan A (2018). On testing for spatial correspondence between maps of human brain structure and function. NeuroImage, 178:540-51.
+    - Váša F, Seidlitz J, Romero-Garcia R, Whitaker KJ, Rosenthal G, Vértes PE, Shinn M, Alexander-Bloch A, Fonagy P, Dolan RJ, Goodyer IM, the NSPN consortium, Sporns O, Bullmore ET (2017). Adolescent tuning of association cortex in human structural brain networks. Cerebral Cortex, 28(1):281–294.

docs/pages/13.02.apireferencematlab/generated/plot_cortical.rst

@@ -7,15 +7,23 @@
 plot_cortical()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/surface_viewer/plot_cortical.m>`_]:
     .. function:: 
-        plot_cortical = plot_cortical()
+        [a, cb] = plot_cortical(data, varargin);
 
 **Description**:
-    ...
+    Plot cortical surface with lateral and medial views (authors: @MICA-MNI, @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **data** (*double array*) – vector of data, size = [1 x v]
+
+**Name/value pairs**:
+    - **surface_name** (*string, optional*) – Name of surface {‘fsa5’, ‘conte69}. Default is ‘fsa5’.
+    - **label_text** (*string, optional*) – Label text for colorbar. Default is empty.
+    - **background** (*string, double array, optional*) – Background color. Default is 'white'.
+    - **color_range** (*double array, optional*) – Range of colorbar. Default is [min(data) max(data)].
+    - **cmap** (*string, double array, optional*) – Colormap name. Default is ‘RdBu_r’.
 
 **Outputs**:
-    **...** (*...*) – ...
+    - **a** (*axes*) – vector of handles to the axes, left to right, top to bottom
+    - **cb** (*colorbar*) - colorbar handle

docs/pages/13.02.apireferencematlab/generated/plot_subcortical.rst

@@ -7,15 +7,23 @@
 plot_subcortical()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/surface_viewer/plot_subcortical.m>`_]:
     .. function:: 
-        plot_subcortical = plot_subcortical()
+       [a, cb] = plot_subcortical(data, varargin);
 
 **Description**:
-    ...
+    Plot subcortical surface with lateral and medial views (author: @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **data** (*double array*) – vector of data, size = [1 x v]. One value per subcortical structure, in this order: L-accumbens, L-amygdala, L-caudate, L-hippocampus, L-pallidum L-putamen, L-thalamus, L-ventricle, R-accumbens, R-amygdala, R-caudate, R-hippocampus, R-pallidum, R-putamen, R-thalamus, R-ventricle
+
+**Name/value pairs**:
+    - **ventricles** (*string, optional*) – If 'True' (default) shows the ventricles (``data must be size = [1 x 16]``). If 'False', then ventricles are not shown and ``data must be size = [1 x 14]``.
+    - **label_text** (*string, optional*) – Label text for colorbar. Default is empty.
+    - **background** (*string, double array, optional*) – Background color. Default is 'white'.
+    - **color_range** (*double array, optional*) – Range of colorbar. Default is [min(data) max(data)].
+    - **cmap** (*string, double array, optional*) – Colormap name. Default is ‘RdBu_r’.
 
 **Outputs**:
-    **...** (*...*) – ...
+    - **a** (*axes*) – vector of handles to the axes, left to right, top to bottom
+    - **cb** (*colorbar*) - colorbar handle

docs/pages/13.02.apireferencematlab/generated/reorder_sctx.rst

@@ -7,15 +7,15 @@
 reorder_sctx()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/useful/reorder_sctx.m>`_]:
     .. function:: 
-        reorder_sctx = reorder_sctx()
+        data_r = reorder_sctx(data)
 
 **Description**:
-    ...
+    Re-order subcortical volume data alphabetically and by hemisphere (left then right; author: @saratheriver)
 
 **Inputs**:
-    **...** ...
+    **data** (*table*) - Data matrix
 
 **Outputs**:
-    **...** (*...*) – ...
+    **data_r** (*table*) – Re-ordered data

docs/pages/13.02.apireferencematlab/generated/rotate_parcellation.rst

@@ -7,15 +7,21 @@
 rotate_parcellation()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/permutation_testing/rotate_parcellation.m>`_]:
     .. function:: 
-        rotate_parcellation = rotate_parcellation()
+        perm_id = rotate_parcellation(coord_l, coord_r, nrot)
 
 **Description**:
-    ...
+    Rotate parcellation (authors: @frantisekvasa, @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **coord_l** (*double array*) – Coordinates of left hemisphere regions on the sphere, size = [m x 3]
+    - **coord_r** (*double array*) – Coordinates of right hemisphere regions on the sphere, size = [m x 3]
+    - **nrot** (*int, optional*) – Number of rotations. Default is 100.
 
 **Outputs**:
-    **...** (*...*) – ...
+    **perm_id** (*double array*) – Array of permutations, size = [m x nrot]
+
+**References**:
+    - Alexander-Bloch A, Shou H, Liu S, Satterthwaite TD, Glahn DC, Shinohara RT, Vandekar SN and Raznahan A (2018). On testing for spatial correspondence between maps of human brain structure and function. NeuroImage, 178:540-51.
+    - Váša F, Seidlitz J, Romero-Garcia R, Whitaker KJ, Rosenthal G, Vértes PE, Shinn M, Alexander-Bloch A, Fonagy P, Dolan RJ, Goodyer IM, the NSPN consortium, Sporns O, Bullmore ET (2017). Adolescent tuning of association cortex in human structural brain networks. Cerebral Cortex, 28(1):281–294.

docs/pages/13.02.apireferencematlab/generated/shuf_test.rst

@@ -7,15 +7,21 @@
 shuf_test()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <https://github.com/MICA-MNI/ENIGMA/blob/master/matlab/scripts/permutation_testing/shuf_test.m>`_]:
     .. function:: 
-        shuf_test = shuf_test()
+        [p_shuf, r_dist] = shuf_test(map1, map2, varargin)
 
 **Description**:
-    ...
+    Shuf permuation (author: @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **map1** (*double array*) – One of two map to be correlated
+    - **map2** (*double array*) – The other map to be correlated
+
+**Name/value pairs**:
+    - **n_rot** (*int, optional*) – Number of shuffles. Default is 100.
+    - **type** (*string, optional*) – Correlation type {‘pearson’, ‘spearman’}. Default is ‘pearson’.
 
 **Outputs**:
-    **...** (*...*) – ...
+    - **p_shuf** (*double*) – Permutation p-value
+    - **r_dist** (*double array*) - Null correlations, size = [n_rot*2 x 1].

docs/pages/13.02.apireferencematlab/generated/spin_test.rst

@@ -15,21 +15,19 @@ spin_test()
     Spin permutation (author: @saratheriver)
 
 **Inputs**:
-    **map1** (array) – One of two map to be correlated
-    **map2** (array) – The other map to be correlated
+    - **map1** (*double array*) – One of two map to be correlated
+    - **map2** (*double array*) – The other map to be correlated
 
 **Name/value pairs**:
-    **surface_name** (string, optional) – Surface name {‘fsa5’, ‘fsa5_with_sctx’, ‘conte69’}. Default is ‘fsa5’.
-    **parcellation_name** (string, optional) – Parcellation name {‘aparc’, ‘aparc_aseg’}. Default is ‘aparc’.
-    **n_rot** (int, optional) – Number of spin rotations. Default is 100.
-    **type** (string, optional) – Correlation type {‘pearson’, ‘spearman’}. Default is ‘pearson’.
-    **null_dist** (string, optional) – If 'True', output null correlations. Default is 'False'.
-    **ventricles** (string, optional) – Whether ventricles are present in map1, map2. Only used when ``parcellation_name is 
-    'aparc_aseg'``. Default is 'False' (other option is 'True')
+    - **surface_name** (*string, optional*) – Surface name {‘fsa5’, ‘fsa5_with_sctx’, ‘conte69’}. Default is ‘fsa5’.
+    - **parcellation_name** (*string, optional*) – Parcellation name {‘aparc’, ‘aparc_aseg’}. Default is ‘aparc’.
+    - **n_rot** (*int, optional*) – Number of spin rotations. Default is 100.
+    - **type** (*string, optional*) – Correlation type {‘pearson’, ‘spearman’}. Default is ‘pearson’.
+    - **ventricles** (*string, optional*) – Whether ventricles are present in map1, map2. Only used when ``parcellation_name is 'aparc_aseg'``. Default is 'False' (other option is 'True')
 
 **Outputs**:
     - **p_spin** (*double*) – Permutation p-value
-    - **r_dist** (*double array*) - Null correlations, size = [n_rot*2 x 1]. Only if ``null_dist is 'True'``.
+    - **r_dist** (*double array*) - Null correlations, size = [n_rot*2 x 1].
 
 **References**:
     - Alexander-Bloch A, Shou H, Liu S, Satterthwaite TD, Glahn DC, Shinohara RT, Vandekar SN and Raznahan A (2018). On testing for spatial correspondence between maps of human brain structure and function. NeuroImage, 178:540-51.

docs/pages/13.02.apireferencematlab/generated/surface_to_parcel.rst

@@ -7,15 +7,16 @@
 surface_to_parcel()
 ------------------------------------
 
-**Usage** [`source <>>`_]:
+**Usage** [`source <>`_]:
     .. function:: 
-        surface_to_parcel = surface_to_parcel()
+        surf2parcel = surface_to_parcel(surf_data, parcellation)
 
 **Description**:
-    ...
+    Map surface data to a parcellation (authors : @MICA-MNI, @saratheriver)
 
 **Inputs**:
-    **...** ...
+    - **surf_data** (*double array*) - Surface vector, size = [v x 1].
+    - **parcellation** (*string, optional*) - Default is 'aparc_fsa5'
 
 **Outputs**:
-    **...** (*...*) – ...
+    **surf2parcel** (*double array*) – Vector of values mapped from a surface to a parcellation