Skip to content

Commit eca8a44

Browse files
pollaropollaro
committed
documentation
1 parent f0eb324 commit eca8a44

13 files changed

Lines changed: 1054 additions & 0 deletions

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/bibliography.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.. rubric:: References
2+
3+
.. bibliography::

‎docs/source/conf.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import os
2+
# Configuration file for the Sphinx documentation builder.
3+
#
4+
# For the full list of built-in configuration values, see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
8+
9+
# -- Project information -----------------------------------------------------
10+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
11+
12+
project = 'Network Level Analysis Toolbox'
13+
copyright = '2024, Muriah Wheelock'
14+
author = 'Muriah Wheelock'
15+
16+
# -- General configuration ---------------------------------------------------
17+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
18+
19+
extensions = [
20+
'sphinx.ext.intersphinx',
21+
'sphinxcontrib.matlab',
22+
'sphinx_rtd_theme',
23+
'sphinxcontrib.bibtex',
24+
'sphinx.ext.autodoc'
25+
]
26+
this_dir = os.path.dirname(os.path.abspath(__file__))
27+
matlab_src_dir = os.path.abspath(os.path.join(this_dir, '../../+nla'))
28+
29+
templates_path = ['_templates']
30+
exclude_patterns = []
31+
32+
33+
34+
# -- Options for HTML output -------------------------------------------------
35+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
36+
37+
html_theme = 'sphinx_rtd_theme'
38+
html_static_path = ['_static']
39+
40+
41+
# -- Options for Intersphinx ------------------------------------------------------
42+
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx
43+
44+
intersphinx_mapping = {}
45+
46+
# -- Options for bibtex ----------------------------
47+
# https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation
48+
49+
bibtex_bibfiles = ['refs.bib']
50+
bibtex_default_style = 'plain'
51+
bibtex_reference_style = 'super'

‎docs/source/edge_level_tests.rst‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
Edge-level Statistical Tests
2+
==========================================
3+
4+
Methods
5+
-------------------------
6+
7+
The non-permuted method calculates the correlation of each Region Of Interest (ROI) to all other
8+
ROIs via the given test. These results are stored as a correlation coefficient, ``coeff``, a p-value, ``prob``,
9+
and a thresholded p-value, ``prob_sig``. The permuted method is identical except the variables have a ``_perm`` suffix.
10+
11+
Common Inputs
12+
--------------------------
13+
14+
:P: Edge-level p-value threshold
15+
:Network Atlas: :doc:`/network_atlases`
16+
:Functional Connectivity: Initial coorelation matrix if size N\ :sub:`ROIs`\ x N\ :sub:`ROIs`\ x N\ :sub:`scans`\.
17+
r-values or Fisher z-transformed r-values.
18+
:Behavior: MATLAB table (``.mat``) or tab seperated text file (``.txt``)
19+
20+
============== =================== ================
21+
Variable Name Next Variable Name More Variable...
22+
============== =================== ================
23+
1 5 1.5
24+
0 1 3
25+
1 7 2.6
26+
... ... ...
27+
============== =================== ================
28+
29+
Each column header is a name of a variable.
30+
Each column contains N\ :sub:`scans`\ entries.
31+
After loading this file, the table should display in the GUI.
32+
The user may mark one column as 'Behavior' for the score of interest.
33+
Other columns may be marked as 'Covariates' which are partialed prior to running statistics.
34+
(Note: Network Level Analysis cannot handle missing values for behavior or covariates. If there are ``NaNs`` or missing values, do not select this columns)
35+
36+
Provided Tests
37+
--------------------------------
38+
39+
* **Pearson's r**
40+
41+
* MATLAB `corr <https://www.mathworks.com/help/stats/corr.html>` function with ``type``, ``Pearson``
42+
* **Spearman's** :math:`\rho`\
43+
44+
* MATLAB `corr <https://www.mathworks.com/help/stats/corr.html>` function with ``type``, ``Spearman``
45+
* **Spearman's** :math:`\rho`\ **estimator**
46+
47+
* Faster approximation of the Spearman's rho function at the cost of slightly less accurate result.
48+
* Based on developer testing, rho values may differ by :math:`10^{-4}` and p-values by :math:`10^{-5}`.
49+
* This error is passed on to the network-level tests, and can cause p-value difference by :math:`10^{-4}`
50+
* These differences were found with 10,000 permutations. Less permutations results in higher error in a less evenly distributed fashion.
51+
* This is recommended for exploratory research with the Spearman's rho function for publications
52+
* **Kendall's** :math:`\tau`\ **-b**
53+
54+
* Implements Kendall's :math:`\tau`\ -b using C code in a MATLAB MEX file (``+mex/+src/kendallTauB.c``)
55+
* Faster implementation that stardard MATLAB code providing identical :math:`\tau`\ and p-values.
56+
* Run-time difference from *O*\ (*n*\ :sup:`2`) to *O*\ (*n* log *n*)
57+
* This is done with a red-black tree.
58+
* **Welch's t-test``
59+
60+
* Implements an optomized Welch's t-test comparing the functional connectivity of two groups.
61+
* Extra imports compared to other edge level tests
62+
:Group name(s): Names associated with each group. (For example, 'Male' and 'Female')
63+
:Group val(s): Behavioral value associated with each group. If 'Female' is donated as '0', and 'Male' as '1', set the vals to the numerical values.
64+
65+
* **Pre-calculated data loader**
66+
67+
* Allows loading of observed and permuted edge-level data the user has pre-calculated outside the NLA.
68+
* Four ``.mat`` files needed as inputs
69+
* p-values should be thresholded
70+
:Observed p: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x 1 matrix of logical values, the observed, thresholded edge-level p-values.
71+
N\ :sub:`ROI_pairs`\ are the lower triangle values of a N\ :sub:`ROIs`\ x N\ :sub:`ROIs`\ matrix.
72+
:Observed coeff: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x 1 matrix of observed edge-level coefficients.
73+
:Permuted p: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x N\ :sub:`permutations`\ of logical values. Observed, thresholded, permuted p-values.
74+
:Permuted coeff: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x N\ :sub:`permutations`\ of permuted edge-level coefficients.
75+
76+
Creating additional edge-level tests
77+
-----------------------------------------------
78+

‎docs/source/getting_started.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Getting Started
2+
================================================
3+
4+
Running with example data
5+
--------------------------------------------------
6+
7+
First, open the NLA software (as described in :doc:`setup`). Select 'Pearson's r' as the edge-level
8+
test from the edge-level test dropdown.
9+
10+
Click 'Select' to choose a network atlas, navigating to the ``support_files`` folder withing your
11+
'NetworkLevelAnalysis' installation and selecting ``Wheelock_2020_CerebralCortex_15nets_288ROI_on_MNI.mat``.
12+
This file is used to parcellate the data.
13+
14+
Then, select the functional connectivity, located in the ``examples/fc_and_behavior`` folder under the name
15+
``sample_func_conn.mat``. Click 'Yes' to Fisher z-transform the data. Take a moment to visualize the functional
16+
connectivity (FC) average by clicking 'View'. Note that the FC appears to match the parcellation, (effects
17+
generally line up with network boundaries) - this can be a useful diagnostic tool if you are having issues
18+
with parcellations not matching data.
19+
20+
Finally, load the behavior ``sample_behavior.mat`` from the ``examples/fc_and_behavior`` folder (The 'file type' drop-down
21+
will need to be changed from 'Text' to 'MATLAB table' in the file browser). Set the behavioral variable to 'Flanker_AgeAdj' by
22+
clicking on that column in the table and then the 'Set Behavior' button.
23+
24+
Having finished our edge-level inputs, we now move over to the network-level panel on the right side. Select all the tests by clicking
25+
the top one, and then shift+clicking the bottom one.
26+
27+
_running_network_tests:
28+
Run the tests using the 'Run' button on the bottom-right. The number of permutations can be changed with the input field
29+
to the left of the 'Run' button. After pushing the 'Run' button, a result window will open. The edge-level test will be run
30+
and the results can be visualized by pressing 'View' in the upper-left of the result window. To run the network-level tests,
31+
push the 'Run' button in the results window. This will take longer, a progress window will show up displaying the progress.
32+
To visualize the results, expand the lists in the reloaded (automatically) panel, and highlight a test. Press the 'View figures'
33+
button. Other visualization options, such as chord plots and convergence maps, can also be shown. The results can be saved using the
34+
'File' menu in the top-left. These results can be loaded into MATLAB or opened in the NLA main window also using the 'File' menu on that
35+
window.
36+
37+
Running with example pre-calculated data
38+
----------------------------------------------------------
39+
40+
Similarly to the previous example, open the NLA window and load the ``Wheelock_2020_CerebralCortex_15nets_288ROI_on_MNI.mat`` parcellation. This
41+
time, select the 'Precalculated data' edge-level test. Load the four input matrices in the ``examples/precalculated`` folder.
42+
43+
* Observed coefficients: ``SIM_obs_coeff.mat``
44+
* Observed, thresholded p-values: ``SIM_obs_p.mat``
45+
* Permuted coefficients: ``SIM_perm_coeff.mat``
46+
* Permuted, thresholded p-values: ``SIM_perm_p.mat``
47+
48+
Set the lower and upper coefficient bounds to the range of the coefficients. For this case, the range is [-2, 2]. These bounds can be checked
49+
with the 'View' button for the edge-level results button. In the bottom right corner, set the ``perm_count`` to the desired amount of
50+
permutations. The example data provided has a maximums of 600 permutations. Run the tests using the procedure described in the
51+
:ref:`previous section <running_network_tests>`.

‎docs/source/index.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. NetworkLevelAnalysis documentation master file, created by
2+
sphinx-quickstart on Mon Nov 18 13:00:09 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to NetworkLevelAnalysis's documentation!
7+
================================================
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
:caption: Table of Contents:
12+
13+
preface
14+
overview
15+
methodology
16+
setup
17+
getting_started
18+
network_atlases
19+
edge_level_tests
20+
bibliography
21+
22+
23+
Indices and tables
24+
==================
25+
26+
* :ref:`genindex`
27+
* :ref:`modindex`
28+
* :ref:`search`

‎docs/source/methodology.rst‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
Methodology
2+
================================
3+
4+
Brain Network Map Selection
5+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6+
7+
NLA requires the user to specify the network map that will be used to depict the known architecture of the
8+
human connectome, which is crucial given that the network map selection affects both statistical
9+
significance testing and interpretation :cite:p:`BellecP`. The current pipeline uses network maps that are generated with
10+
Infomap, due to its greater congruence with networks derived from task-activation and seed-based
11+
connectivity studies than alternative modularity algorithms :cite:p:`PowerJ,RosvallM`. Network maps can be generated using
12+
one's preferred algorithm or one of several published ROI and corresponding network map options that
13+
will be included in the NLA toolbox :cite:p:`GordonE,PowerJ,ThomasY,GlasserM,ShenX,CraddockR`. The use of standardized ROI and network maps creates a
14+
common, reproducible framework for testing brain-behavior associations across connectome research
15+
16+
General Linear Model / Edge-wise Statistical Model Selection
17+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
18+
19+
NLA also requires the user to specify the desired statistical model for testing associations between
20+
behavioral data and edge-wise�or ROI-pair connectivity�connectome data. The analysis pipeline within
21+
the NLA toolbox offers both parametric and non-parametric correlation.
22+
23+
Connectivity Matrices
24+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
25+
26+
Other software packages are used to create the connectivity matrices that are provided as input into the
27+
NLA toolbox. One useful option for mapping functional connectivity matrices is CONN - MATLAB-based
28+
software with the ability to compute, display, and analyze functional connectivity in fMRI.
29+
30+
The NLA Method
31+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
32+
33+
First, connectome-wide associations are calculated between ROI-pair connectivity and behavioral data,
34+
resulting in a set of standardized regression coefficients that specify the brain-behavior association at
35+
each ROI-pair of the connectome matrix. Next, network level analysis-consisting of transformation of the
36+
edge-wise test statistics and enrichment statistic calculation :cite:p:`AckermanM` - is done to determine which networks are
37+
strongly associated with the behavior of interest.
38+
39+
Both p-value and test-statistic binarization are offered in the current NLA pipeline :cite:p:`EggebrechtA,WheelockM:2018`. Prior research has
40+
supported the incorporation of a proportional edge density threshold, given that uneven edge density
41+
thresholds have been shown to unfairly bias results :cite:p:`vandenHeuvelM`.
42+
For enrichment statistic calculation, NLA offers a number of statistical tests. Prior research has relied on
43+
chi-square and Fisher's Exact test, as well as a Kolmogorov-Smirnov (KS) test and non-parametric tests
44+
based on ranks, which compare the distribution of test values within a region to other regions :cite:p:`WheelockM:2018,RudolphM,MoothaV,ZahnJ`. In
45+
addition, KS alternatives such as averaging or minmax have also shown promise in connectome
46+
applications :cite:p:`ChenJ,NewtonM,YaariG,EfronB`.
47+
48+
NLA then conducts data-driven permutation testing to establish significance. In the NLA toolbox, network
49+
level significance is determined by comparing each measured enrichment statistic to permuted
50+
enrichment p-values which are calculated by randomly shuffling behavior vector labels and computing
51+
the enrichment statistic many times to produce a null distribution for each network. The FPR is controlled
52+
at the network level using Bonferroni correction. Therefore, NLA is able to retain edge-wise correlations
53+
within each network module, but network communities are used to reduce the number of comparisons
54+
and control the FPR at the network level. After significance is determined, the pipeline allows users to
55+
create publication quality images to visualize network level findings both in connectome format and on
56+
the surface of the brain.
57+
58+
**Note**: While the behavior vector labels are shuffled to conduct permutations in the enrichment pipeline,
59+
functional connectivity data are not shuffled in order to preserve the inherent covariant structure of the
60+
data across permutations
61+
62+
How Should the Test Statistic Threshold Be Chosen?
63+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
64+
65+
A nominal threshold is used for the thresholding and binarization step of the edge-level tests. The
66+
nominal threshold is uncorrected and is typically set at 0.05 or 0.01 in the edge-level prob_max field. In
67+
contrast, a network-level corrected threshold using the Bonferroni method is used in the net-level
68+
statistics, where the nominal threshold is divided by the number of tests being done to correct for
69+
multiple comparisons.
70+
71+
How Should the Networks Be Chosen?
72+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
73+
74+
There are many canonical ROI sets and there are many network definitions. Some of these network
75+
definitions include ROI that are not consistently assigned to any network. These ROI are typically removed
76+
prior to network level analysis, as is the case in the ``Seitzman_15nets_288ROI_on_TT`` and the
77+
``Gordon_12nets_286parcels_on_MNI`` network atlases included in this version of the toolbox. Network
78+
atlases that are not included in this package may also be used, but they must first be formatted into the
79+
correct structure

‎docs/source/network_atlases.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
Network Atlases
2+
==================================
3+
.. mat:module:: .
4+
5+
Overview
6+
------------------------------------
7+
8+
A network atlas is a data file describing networks of the brain, each containing a number of related
9+
regions of interest. It also contains metadata such as network colors and names, ROI spatial coordinates
10+
(with associtated mesh/space), and optionally, a surface parcellation.
11+
12+
.. mat:autoclass:: NetworkAtlas
13+
14+
.. mat:automethod:: numNets
15+
16+
.. mat:automethod:: numNetPairs
17+
18+
.. mat:automethod:: numROIs
19+
20+
.. mat:automethod:: numROIPairs
21+
22+
Provided Network Atlases
23+
--------------------------------
24+
25+
A number of network atlases are provided with the NLA software package in the ``support_files`` directory.
26+
Only NLA-specific details will be provided about them, if you wish to go into more depth on a particular atlas
27+
you should follow the link provided in its ``source`` field.
28+
29+
* ``Gordon_13nets_333parcels_on_MNI``
30+
* Surface space.
31+
* Consists of 333 parcels and corresponding 13 networks :cite:p:`GordonE`. Contains both the MNI centrois and surface parcels on a ``MNI_32k`` mesh.
32+
* ``Gordon_12nets_286parcels_on_MNI``
33+
* Surface space
34+
* Same as ``Gordon_13nets_333parcels_on_MNI`` with 'None' network and its ROIs removed :cite:p:`GordonE`.
35+
* ``Seitzman_17nets_300ROI_on_TT``
36+
* Volume space
37+
* 300 ROIs in 17 networks :cite:p:`SeitzmanB`. Contains TT centroids
38+
* ``Seitzman_15nets_288ROI_on_TT``
39+
* Volume space
40+
* Same as ``Seitzman_17nets_300ROI_on_TT`` with 12 ROI and 2 networks removed due inconsistent placement in a network :cite:p:`SeitzmanB`.

0 commit comments

Comments
 (0)