From f300c6f9eaf8e1edb12a0a243be1a6e5c9417325 Mon Sep 17 00:00:00 2001 From: Jim Pollaro Date: Tue, 19 Nov 2024 09:43:50 -0600 Subject: [PATCH 1/7] trying out the sphinx and read the docs --- README.rst | 0 docs/Makefile | 20 ++++ docs/make.bat | 35 ++++++ docs/source/bibliography.rst | 3 + docs/source/conf.py | 46 ++++++++ docs/source/index.rst | 26 +++++ docs/source/overview.rst | 162 ++++++++++++++++++++++++++ docs/source/preface.rst | 20 ++++ docs/source/references.rst | 0 docs/source/refs.bib | 0 pyproject.toml | 0 requirements.txt | 218 +++++++++++++++++++++++++++++++++++ 12 files changed, 530 insertions(+) create mode 100644 README.rst create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/bibliography.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/overview.rst create mode 100644 docs/source/preface.rst create mode 100644 docs/source/references.rst create mode 100644 docs/source/refs.bib create mode 100644 pyproject.toml create mode 100644 requirements.txt diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..747ffb7b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/bibliography.rst b/docs/source/bibliography.rst new file mode 100644 index 00000000..1096f096 --- /dev/null +++ b/docs/source/bibliography.rst @@ -0,0 +1,3 @@ +.. rubric:: References + +.. bibliography:: \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..9272b750 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,46 @@ +import os +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Network Level Analysis Toolbox' +copyright = '2024, Muriah Wheelock' +author = 'Muriah Wheelock' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinxcontrib.matlab', + 'sphinx_rtd_theme', + 'sphinxcontrib.bibtex' +] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] + + +# -- Options for Intersphinx ------------------------------------------------------ +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx + +intersphinx_mapping = {} + +# -- Options for bibtex ---------------------------- +# https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation + +bibtex_bibfiles = ['refs.bib'] \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..46f261f6 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,26 @@ +.. NetworkLevelAnalysis documentation master file, created by + sphinx-quickstart on Mon Nov 18 13:00:09 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to NetworkLevelAnalysis's documentation! +================================================ + +.. toctree:: + :maxdepth: 2 + :caption: Table of Contents: + + Preface + Network Level Analysis Overview + Network Level Analysis Methodology + Setup + Getting Started + Biblography + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 00000000..2120aa78 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,162 @@ +Network Level Analysis Overview +==================================== + +The connectome and network structure +------------------------------------------- + + The term connectome essentially describes any network description of whole brain connectivity, from the +microscale of single neurons and synapses up to the macroscale of entire brain regions and pathways.5 +Connectomics is an ever-advancing field, and large-scale scientific endeavors such as the NIH�s Human +Connectome Project have made significant progress in mapping, analyzing, and understanding the +human connectome. Contemporary connectome research views the brain as an extensive, complex +network of non-adjacent, yet functionally and structurally connected brain regions.6,7 The connectome +can be utilized to assess whole-brain associations between behavior and spatially distinct neural +networks. + + MRI has traditionally been viewed as the gold standard for mapping the connectome and has been used +to demonstrate consistencies between the spatial topology of task-based activation studies and the brain +networks derived from task-free functional connectivity.7,8 Contemporary cluster correction approaches +do not utilize the spatial topology of brain networks when estimating cluster size significance.9�11 +Therefore, there is an urgent need for standardized tools that address the robust hierarchical network +structure of the brain and the limitations of contemporary neuroimaging analysis approaches by utilizing +this biologically informed network structure to increase reproducibility and biological interpretation of +neuroscience results + +Why use this toolbox? +---------------------------------------- + + The NLA toolbox is designed to address the multiple comparisons problem that occurs within +connectome research, wherein studies use hundreds of regions of interest (ROI) to create connectomes +with thousands of potential connections, yet they lack the tools to establish statistical significance when +analyzing associations between connectome and behavior. For example, previous research failed to find +any significant differences in brain connectivity that passed a connectome-wise false discovery rate (FDR) +correction between individuals with a neurological disorder and healthy controls�a finding which +contradicts the recognized role of the brain in neurological functioning.12 Other studies have found +connectome-behavior associations that pass the FDR correction, but lack the statistical tools necessary to +definitively establish these observations.13 NLA, therefore, serves as a valuable tool for the statistical +quantification of network-level associations with behavior. The toolbox relies on cross-disciplinary +biostatistical approaches to evaluate brain-behavior relationships within the connectome and allows for +control of FDR at the network level. In this way, NLA diverges from most contemporary tools with a focus +on single connection associations, in that it is not dependent on edgewise false positive rate (FPR) or +spatially contiguous brain regions. By organizing connectivity-behavior associations according to an a- +priori model of underlying neurobiology (i.e., networks), NLA leverages the structure of the human +connectome and provides a framework for rational interpretation and replication of findings across +research methodologies. Finally, the integration of connectome analysis and visualization techniques +within a single, extensible MATLAB-based pipeline makes NLA an expedient tool for statistical testing and +production of publication quality images all in one package. + +Introduction to NLA and enrichment +--------------------------------------------- + + Network Level Analysis uses enrichment to evaluate whether pairs of networks demonstrate significant +clustering of strong brain-behavior correlations. Enrichment applies common statistical tests to measure +the clustering of associations within a given network pair and reduces the number of comparisons to +those performed at the network level.4 Network level statistics such as the Chi-Square test, +Hypergeometric test, and Kolmogorov-Smirnov test have been used in numerous network-level +investigations including joint attention and motor function in infants and toddlers, maternal +inflammation during gestation, motor and attention development in very preterm children, sex +differences during fetal brain development, and autism in adults. + +Edge-level Statistic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + First, correlations are calculated between behavioral scores and Fisher z-transformed functional +connectivity correlation measures for each pair of ROI. For behavioral scores that are normally +distributed, Pearson r correlations are used to calculate the associations. Non-parametric Spearman rank +correlations are used to assess the relationship between functional connectivity and behavioral scores +that are not normally distributed. Other tests of correlation such as Kendall's tau and 2-sample Welch�s t +can also be used. Network pairs are then tested for enrichment of strong correlation values, defined as +only those values that remain after being nominally thresholded. An uncorrected p-threshold (e.g., 0.05 or +0.01) is applied and the remaining correlations are binarized. + +Network Level Statistics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + After the edge-level statistic matrix has been calculated, it is given as input to a variety of network-level +tests. First, it is input directly to the tests, and the resulting statistic is called the "non-permuted network +level statistic" (for every given network-level test). Then, permuted edge-level statistics are calculated via +the same method as described previously, but with the behavioral scores permuted across subjects. The +network-level test is performed on this as well, and the significance of permuted network-level statistics +ranked against the non-permuted, to calculate the permuted experiment-wide p-value (an empirical p- +value produced from this ranking). Additionally, "single-sample within-net-pair" statistics are calculated +for each test, which, rather than comparing a given network to the connectome over a number of +permutations (as in the permuted network-level test), performs a single-sample test on the network +alone, which is then ranked against permutations of said network similarly to the permuted network-level +test. + A number of statistic tests are utilized at the network level. The 1-degree-of-freedom :math:\chi^{2} test is used to +compare the observed number of strong (thresholded and binarized) brain-behavior correlations within +one pair of functional networks to the number of strong brain-behavior correlations that would be +expected if strong correlations were uniformly distributed across all possible network pairs. A large +resulting test statistic can indicate that the number of strong correlations within a specific network pair is +enriched. The hypergeometric test aims to assess the likelihood of observing a given number of strong +correlations within a pair of networks, given (1) the total number of strong correlations observed over the +entire connectome and (2) the total number of possible hits for that network pair (i.e., the total number or +ROI-pairs within a given network pair). Other tests such as Kolmogorov-Smirnov, Wilcoxon rank-sum, +Welch's t can be used, as well as Cohen's d to measure effect sizes. + As described, significance for all statistical tests is determined using permutation testing. Behavioral +labels are randomly permuted and correlated with the connectome data (typically 10k times) to create +null brain-behavior correlation matrices. Tests are calculated on these permuted brain-behavior +correlation matrices generating a null distribution of network level statistics. The measured (real) test +statistics are compared to this null distribution to establish network-level significance. + +NLA Alternatives / Comparison to other analysis methods +---------------------------------------------------------------------- + + The NLA toolbox's use of a novel enrichment approach makes it a transformative tool in connectome- +wide association studies, given that all current enrichment analysis methods are built for use with +genome data and NLA is the first enrichment tool designed to analyze the connectome. Many alternative +methods for connectome analysis rely on spatial extent cluster correction in order to control voxel-wise +whole brain connectome FPR. Despite mounting evidence that spatially non-contiguous brain regions +are strongly correlated and often co-activate to the same stimuli, cluster extent correction is often +regarded as the ideal thresholding approach in human connectome literature. By basing statistical +significance on contiguous voxels, however, cluster extent correction methods fail to account for this +covariance structure. Therefore, brain regions that are known to be highly correlated and part of the same +network - such as the anterior cingulate and posterior cingulate - may be thresholded separately, +resulting in one or both separate regions not meeting statistical thresholds. NLA is distinguished from +the cluster extent correction methodology in that it groups highly correlated, non-contiguous brain +regions based on pre-defined network modules prior to estimating network-level significance. + +Network Based Statistic (NBS) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Given this deviation from the popular extent cluster correction thresholding method, the most +conceptually similar existing connectome analysis approach to NLA is the Network Based Statistic (NBS) +toolbox. NBS was the first tool control the edgewise FPR by leveraging graph-based estimates of +modularity. Still, several crucial differences exist between NLA and NBS: (a) the results from NBS focus on +edgewise significance as opposed to network-level significance, (b) NBS does not have a built-in +visualization functionality, and (c) NBS allows for different module sizes, number of network modules, +and configurations of edges assigned to network modules across various clinical populations, but draws +no conclusions regarding the biological relevance of identified networks. The NLA pipeline addresses this +issue by presenting a vast array of analysis and visualization options that utilize biologically informed +hierarchical organization models of the brain. + +Graph Theoretical Toolboxes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Graph Theoretical Toolboxes are another comparable approach to NLA, offering an analysis methodology +to quantify network characteristics such as integration, segregation, resilience, and relative contribution +of individual network nodes to overall information flow within the network. Various other toolboxes +have been created to address network thresholding, graph metric calculation, and graph visualization� +such as GRETNA, GEPHI, and BrainNet Viewer. Additional methodologies aim to determine network +topology differences by leveraging generalized estimating equations and generalized linear and nonlinear +mixed models. Each of these tools has helped to advance the application of graph theory approaches +to connectome analysis. The NLA toolbox estimates statistical associations edgewise, rather than on +network topology features, thereby providing a crucial and complementary approach to the existing +collection of brain network analysis tools + +Statistical Inference and the use of liberal primary thresholds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +NLA establishes statistical significance in the weak sense similar to traditional voxelwise cluster-level +inference. In voxelwise cluster correction, a liberal primary threshold is employed in addition to a +cluster-extent threshold (determined by e.g., random field theory or Monte Carlo simulations). The +resulting clusters are significant but inferences cannot be made about any particular sub-regions or +voxels within a cluster. Similarly, NLA employs a liberal primary threshold in order to calculate the +network-level statistic and significance is established with permutation testing, but claims cannot be +made about the significance of any given ROI-pair within the network. One could apply an FDR correction +within each network pair similar to the statistics outlined in the Network Based Statistics toolbox though +this would still only control the false positive rate in the weak sense. The motivation of all of these +approaches (cluster-level inference, network-level enrichment, network-based statistic) is to control the +false positive rate when a massive number of tests are performed. Controlling the false positive rate in the +strong sense with several thousand functional connections (e.g., 30k) will often result in no single ROI-pair +surviving OR a few scattered ROI-pairs surviving with no clear biological pattern. \ No newline at end of file diff --git a/docs/source/preface.rst b/docs/source/preface.rst new file mode 100644 index 00000000..d6863686 --- /dev/null +++ b/docs/source/preface.rst @@ -0,0 +1,20 @@ +Preface +============== + + This is the reference manual for the Network Level Analysis (NLA) Toolbox. NLA is an extensible MATLAB- +based software package for the analysis of behavioral associations with brain connectivity data. NLA +utilizes a model-based statistical approach known variously as 'pathway analysis', 'over-representation +analysis', or 'enrichment analysis', which was first used to describe behavioral or clinical associations in +genome-wide association studies. + + Enrichment is a model-based data reduction approach to elucidate statistically significant network- +features. The suite developed here includes data-driven permutation-based false-positive-rate +procedures that manage multiple comparisons corrections for one or two independent groups. + +Hardware and Software Requirements +------------------------------------------ + + NLA has been tested on MATLAB 2020b on Ubuntu 20.04. Current release of the GUI is not supported for +Windows. NLA requires the Parallel Processing and Statistics and Machine Learning Toolboxes. Best +performance will be achieved on a server setup with multiple cores to support parallel processing +(particularly for the permutation testing portion of the toolbox) \ No newline at end of file diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/source/refs.bib b/docs/source/refs.bib new file mode 100644 index 00000000..e69de29b diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..e69de29b diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..f02cc07b --- /dev/null +++ b/requirements.txt @@ -0,0 +1,218 @@ +alabaster==0.7.13 +anyio==4.1.0 +apturl==0.5.2 +argon2-cffi==23.1.0 +argon2-cffi-bindings==21.2.0 +arrow==1.3.0 +asttokens==2.4.1 +async-lru==2.0.4 +attrs==23.1.0 +Babel==2.13.1 +backcall==0.2.0 +bcrypt==3.1.7 +beautifulsoup4==4.12.2 +bids-validator==1.14.0 +bleach==6.1.0 +blinker==1.4 +Brlapi==0.7.0 +cajarename==19.7.15 +certifi==2019.11.28 +cffi==1.16.0 +cfgv==3.4.0 +chardet==3.0.4 +charset-normalizer==3.3.2 +chrome-gnome-shell==0.0.0 +Click==7.0 +colorama==0.4.3 +comm==0.2.0 +command-not-found==0.3 +configobj==5.0.6 +cryptography==2.8 +cupshelpers==1.0 +cycler==0.10.0 +dbus-python==1.2.16 +debugpy==1.8.0 +decorator==5.1.1 +defer==1.0.6 +defusedxml==0.7.1 +deja-dup-caja==0.0.6 +distlib==0.3.7 +distro==1.4.0 +distro-info==0.23+ubuntu1.1 +docutils==0.20.1 +duplicity==0.8.12.0 +Endgame-Singularity==1.0b1 +entrypoints==0.3 +exceptiongroup==1.2.0 +executing==2.0.1 +fasteners==0.14.1 +fastjsonschema==2.19.0 +filelock==3.13.1 +fmriprep-docker==24.1.0 +folder-color-caja==0.0.86 +folder-color-common==0.0.86 +fqdn==1.5.1 +future==0.18.2 +gpg==1.13.1 +httplib2==0.14.0 +identify==2.5.35 +idna==2.8 +imagesize==1.4.1 +importlib-metadata==6.8.0 +importlib-resources==6.1.1 +ipykernel==6.27.1 +ipython==8.12.3 +ipywidgets==8.1.1 +isoduration==20.11.0 +itsdangerous==1.1.0 +jedi==0.19.1 +Jinja2==3.1.2 +json5==0.9.14 +jsonpointer==2.4 +jsonschema==4.20.0 +jsonschema-specifications==2023.11.2 +jupyter==1.0.0 +jupyter-client==8.6.0 +jupyter-console==6.6.3 +jupyter-core==5.5.0 +jupyter-events==0.9.0 +jupyter-lsp==2.2.1 +jupyter-server==2.11.1 +jupyter-server-terminals==0.4.4 +jupyterlab==4.0.9 +jupyterlab-pygments==0.3.0 +jupyterlab-server==2.25.2 +jupyterlab-widgets==3.0.9 +keyring==18.0.1 +kiwisolver==1.0.1 +language-selector==0.1 +launchpadlib==1.10.13 +lazr.restfulclient==0.14.2 +lazr.uri==1.0.3 +lockfile==0.12.2 +louis==3.12.0 +macaroonbakery==1.3.1 +Magnus==1.0.3 +Mako==1.1.0 +MarkupSafe==2.1.3 +mate-hud==19.10.0 +mate-menu==20.4.1 +mate-tweak==20.4.0 +matplotlib-inline==0.1.6 +mistune==3.0.2 +monotonic==1.5 +nbclient==0.9.0 +nbconvert==7.11.0 +nbformat==5.9.2 +nest-asyncio==1.5.8 +netifaces==0.10.4 +nibabel==5.1.0 +niix2bids==2.5.0 +nodeenv==1.8.0 +notebook==7.0.6 +notebook-shim==0.2.3 +numpy==1.24.4 +oauthlib==3.1.0 +olefile==0.46 +onboard==1.4.1 +overrides==7.4.0 +packaging==23.2 +pandas==2.0.3 +pandocfilters==1.5.0 +paramiko==2.6.0 +parso==0.8.3 +pexpect==4.6.0 +pickleshare==0.7.5 +Pillow==7.0.0 +pkgutil-resolve-name==1.3.10 +platformdirs==4.0.0 +polib==1.1.0 +pre-commit==3.5.0 +prometheus-client==0.19.0 +prompt-toolkit==3.0.41 +protobuf==3.6.1 +psutil==5.5.1 +ptyprocess==0.7.0 +pulsemixer==1.5.0 +pure-eval==0.2.2 +pycairo==1.16.2 +pycparser==2.21 +pycrypto==2.6.1 +pycups==1.9.73 +pygame==1.9.6 +pygments==2.17.2 +PyGObject==3.36.0 +pyinotify==0.9.6 +PyJWT==1.7.1 +pymacaroons==0.13.0 +PyNaCl==1.3.0 +pyOpenSSL==19.0.0 +pyparsing==2.4.6 +pyRFC3339==1.1 +PySocks==1.7.1 +python-apt==2.0.1+ubuntu0.20.4.1 +python-dateutil==2.8.2 +python-debian==0.1.36+ubuntu1.1 +python-json-logger==2.0.7 +python-xapp==1.8.1 +python-xlib==0.23 +pytz==2024.2 +pyxattr==0.6.1 +pyxdg==0.26 +PyYAML==5.3.1 +pyzmq==25.1.1 +qtconsole==5.5.1 +QtPy==2.4.1 +referencing==0.31.1 +reportlab==3.5.34 +requests==2.31.0 +requests-unixsocket==0.2.0 +rfc3339-validator==0.1.4 +rfc3986-validator==0.1.1 +rpds-py==0.13.2 +SecretStorage==2.3.1 +Send2Trash==1.8.2 +setproctitle==1.1.10 +simplejson==3.16.0 +six==1.14.0 +sniffio==1.3.0 +snowballstemmer==2.2.0 +soupsieve==2.5 +sphinx==7.1.2 +sphinx-rtd-theme==3.0.2 +sphinxcontrib-applehelp==1.0.4 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==2.0.1 +sphinxcontrib-jquery==4.1 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-matlabdomain==0.22.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.5 +ssh-import-id==5.10 +stack-data==0.6.3 +systemd-python==234 +terminado==0.18.0 +tinycss2==1.2.1 +tomli==2.0.1 +tornado==6.4 +traitlets==5.14.0 +types-python-dateutil==2.8.19.14 +typing-extensions==4.8.0 +tzdata==2024.2 +ubuntu-advantage-tools==8001 +ubuntu-drivers-common==0.0.0 +ufw==0.36 +unattended-upgrades==0.1 +uri-template==1.3.0 +urllib3==1.25.8 +usb-creator==0.3.7 +virtualenv==20.24.7 +wadllib==1.3.3 +wcwidth==0.2.12 +webcolors==1.13 +webencodings==0.5.1 +websocket-client==1.6.4 +widgetsnbextension==4.0.9 +xkit==0.0.0 +youtube-dl==2020.3.24 +zipp==3.17.0 From 8f19089f5b848e638a496124a27b8d4ff638d6ea Mon Sep 17 00:00:00 2001 From: Jim Pollaro Date: Tue, 19 Nov 2024 12:51:35 -0600 Subject: [PATCH 2/7] adding more from previous manual and not saving build --- .gitignore | 4 ++ docs/source/index.rst | 12 +++--- docs/source/methodology.rst | 79 +++++++++++++++++++++++++++++++++++++ docs/source/overview.rst | 20 +++++----- docs/source/setup.rst | 38 ++++++++++++++++++ requirements.txt | 4 ++ 6 files changed, 141 insertions(+), 16 deletions(-) create mode 100644 docs/source/methodology.rst create mode 100644 docs/source/setup.rst diff --git a/.gitignore b/.gitignore index 6fba5d4f..7e0afc10 100755 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,9 @@ test/ +# we can build these on git +docs/build + + # Ignoring files by extension # All files with these extensions will be ignored in # this directory and all its sub-directories. diff --git a/docs/source/index.rst b/docs/source/index.rst index 46f261f6..5cd7b2ab 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,12 +10,12 @@ Welcome to NetworkLevelAnalysis's documentation! :maxdepth: 2 :caption: Table of Contents: - Preface - Network Level Analysis Overview - Network Level Analysis Methodology - Setup - Getting Started - Biblography + preface + overview + methodology + setup + getting_started + biblography Indices and tables diff --git a/docs/source/methodology.rst b/docs/source/methodology.rst new file mode 100644 index 00000000..79844aae --- /dev/null +++ b/docs/source/methodology.rst @@ -0,0 +1,79 @@ +Methodology +================================ + +Brain Network Map Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +NLA requires the user to specify the network map that will be used to depict the known architecture of the +human connectome, which is crucial given that the network map selection affects both statistical +significance testing and interpretation. The current pipeline uses network maps that are generated with +Infomap, due to its greater congruence with networks derived from task-activation and seed-based +connectivity studies than alternative modularity algorithms. Network maps can be generated using +one�s preferred algorithm or one of several published ROI and corresponding network map options that +will be included in the NLA toolbox. The use of standardized ROI and network maps creates a +common, reproducible framework for testing brain-behavior associations across connectome research + +General Linear Model / Edge-wise Statistical Model Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +NLA also requires the user to specify the desired statistical model for testing associations between +behavioral data and edge-wise�or ROI-pair connectivity�connectome data. The analysis pipeline within +the NLA toolbox offers both parametric and non-parametric correlation. + +Connectivity Matrices +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Other software packages are used to create the connectivity matrices that are provided as input into the +NLA toolbox. One useful option for mapping functional connectivity matrices is CONN - MATLAB-based +software with the ability to compute, display, and analyze functional connectivity in fMRI. + +The NLA Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First, connectome-wide associations are calculated between ROI-pair connectivity and behavioral data, +resulting in a set of standardized regression coefficients that specify the brain-behavior association at +each ROI-pair of the connectome matrix. Next, network level analysis-consisting of transformation of the +edge-wise test statistics and enrichment statistic calculation40 - is done to determine which networks are +strongly associated with the behavior of interest. + +Both p-value and test-statistic binarization are offered in the current NLA pipeline. Prior research has +supported the incorporation of a proportional edge density threshold, given that uneven edge density +thresholds have been shown to unfairly bias results. +For enrichment statistic calculation, NLA offers a number of statistical tests. Prior research has relied on +chi-square and Fisher's Exact test, as well as a Kolmogorov-Smirnov (KS) test and non-parametric tests +based on ranks, which compare the distribution of test values within a region to other regions. In +addition, KS alternatives such as averaging or minmax have also shown promise in connectome +applications. + +NLA then conducts data-driven permutation testing to establish significance. In the NLA toolbox, network +level significance is determined by comparing each measured enrichment statistic to permuted +enrichment p-values which are calculated by randomly shuffling behavior vector labels and computing +the enrichment statistic many times to produce a null distribution for each network. The FPR is controlled +at the network level using Bonferroni correction. Therefore, NLA is able to retain edge-wise correlations +within each network module, but network communities are used to reduce the number of comparisons +and control the FPR at the network level. After significance is determined, the pipeline allows users to +create publication quality images to visualize network level findings both in connectome format and on +the surface of the brain. + +**Note**: While the behavior vector labels are shuffled to conduct permutations in the enrichment pipeline, +functional connectivity data are not shuffled in order to preserve the inherent covariant structure of the +data across permutations + +How Should the Test Statistic Threshold Be Chosen? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A nominal threshold is used for the thresholding and binarization step of the edge-level tests. The +nominal threshold is uncorrected and is typically set at 0.05 or 0.01 in the edge-level prob_max field. In +contrast, a network-level corrected threshold using the Bonferroni method is used in the net-level +statistics, where the nominal threshold is divided by the number of tests being done to correct for +multiple comparisons. + +How Should the Networks Be Chosen? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are many canonical ROI sets and there are many network definitions. Some of these network +definitions include ROI that are not consistently assigned to any network. These ROI are typically removed +prior to network level analysis, as is the case in the ``Seitzman_15nets_288ROI_on_TT`` and the +``Gordon_12nets_286parcels_on_MNI`` network atlases included in this version of the toolbox. Network +atlases that are not included in this package may also be used, but they must first be formatted into the +correct structure \ No newline at end of file diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 2120aa78..a54e81fc 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -4,7 +4,7 @@ Network Level Analysis Overview The connectome and network structure ------------------------------------------- - The term connectome essentially describes any network description of whole brain connectivity, from the +The term connectome essentially describes any network description of whole brain connectivity, from the microscale of single neurons and synapses up to the macroscale of entire brain regions and pathways.5 Connectomics is an ever-advancing field, and large-scale scientific endeavors such as the NIH�s Human Connectome Project have made significant progress in mapping, analyzing, and understanding the @@ -13,7 +13,7 @@ network of non-adjacent, yet functionally and structurally connected brain regio can be utilized to assess whole-brain associations between behavior and spatially distinct neural networks. - MRI has traditionally been viewed as the gold standard for mapping the connectome and has been used +MRI has traditionally been viewed as the gold standard for mapping the connectome and has been used to demonstrate consistencies between the spatial topology of task-based activation studies and the brain networks derived from task-free functional connectivity.7,8 Contemporary cluster correction approaches do not utilize the spatial topology of brain networks when estimating cluster size significance.9�11 @@ -25,7 +25,7 @@ neuroscience results Why use this toolbox? ---------------------------------------- - The NLA toolbox is designed to address the multiple comparisons problem that occurs within +The NLA toolbox is designed to address the multiple comparisons problem that occurs within connectome research, wherein studies use hundreds of regions of interest (ROI) to create connectomes with thousands of potential connections, yet they lack the tools to establish statistical significance when analyzing associations between connectome and behavior. For example, previous research failed to find @@ -48,7 +48,7 @@ production of publication quality images all in one package. Introduction to NLA and enrichment --------------------------------------------- - Network Level Analysis uses enrichment to evaluate whether pairs of networks demonstrate significant +Network Level Analysis uses enrichment to evaluate whether pairs of networks demonstrate significant clustering of strong brain-behavior correlations. Enrichment applies common statistical tests to measure the clustering of associations within a given network pair and reduces the number of comparisons to those performed at the network level.4 Network level statistics such as the Chi-Square test, @@ -60,7 +60,7 @@ differences during fetal brain development, and autism in adults. Edge-level Statistic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - First, correlations are calculated between behavioral scores and Fisher z-transformed functional +First, correlations are calculated between behavioral scores and Fisher z-transformed functional connectivity correlation measures for each pair of ROI. For behavioral scores that are normally distributed, Pearson r correlations are used to calculate the associations. Non-parametric Spearman rank correlations are used to assess the relationship between functional connectivity and behavioral scores @@ -72,7 +72,7 @@ only those values that remain after being nominally thresholded. An uncorrected Network Level Statistics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - After the edge-level statistic matrix has been calculated, it is given as input to a variety of network-level +After the edge-level statistic matrix has been calculated, it is given as input to a variety of network-level tests. First, it is input directly to the tests, and the resulting statistic is called the "non-permuted network level statistic" (for every given network-level test). Then, permuted edge-level statistics are calculated via the same method as described previously, but with the behavioral scores permuted across subjects. The @@ -83,7 +83,7 @@ for each test, which, rather than comparing a given network to the connectome ov permutations (as in the permuted network-level test), performs a single-sample test on the network alone, which is then ranked against permutations of said network similarly to the permuted network-level test. - A number of statistic tests are utilized at the network level. The 1-degree-of-freedom :math:\chi^{2} test is used to +A number of statistic tests are utilized at the network level. The 1-degree-of-freedom :math:\chi^{2} test is used to compare the observed number of strong (thresholded and binarized) brain-behavior correlations within one pair of functional networks to the number of strong brain-behavior correlations that would be expected if strong correlations were uniformly distributed across all possible network pairs. A large @@ -93,7 +93,7 @@ correlations within a pair of networks, given (1) the total number of strong cor entire connectome and (2) the total number of possible hits for that network pair (i.e., the total number or ROI-pairs within a given network pair). Other tests such as Kolmogorov-Smirnov, Wilcoxon rank-sum, Welch's t can be used, as well as Cohen's d to measure effect sizes. - As described, significance for all statistical tests is determined using permutation testing. Behavioral +As described, significance for all statistical tests is determined using permutation testing. Behavioral labels are randomly permuted and correlated with the connectome data (typically 10k times) to create null brain-behavior correlation matrices. Tests are calculated on these permuted brain-behavior correlation matrices generating a null distribution of network level statistics. The measured (real) test @@ -102,7 +102,7 @@ statistics are compared to this null distribution to establish network-level sig NLA Alternatives / Comparison to other analysis methods ---------------------------------------------------------------------- - The NLA toolbox's use of a novel enrichment approach makes it a transformative tool in connectome- +The NLA toolbox's use of a novel enrichment approach makes it a transformative tool in connectome- wide association studies, given that all current enrichment analysis methods are built for use with genome data and NLA is the first enrichment tool designed to analyze the connectome. Many alternative methods for connectome analysis rely on spatial extent cluster correction in order to control voxel-wise @@ -119,7 +119,7 @@ regions based on pre-defined network modules prior to estimating network-level s Network Based Statistic (NBS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Given this deviation from the popular extent cluster correction thresholding method, the most +Given this deviation from the popular extent cluster correction thresholding method, the most conceptually similar existing connectome analysis approach to NLA is the Network Based Statistic (NBS) toolbox. NBS was the first tool control the edgewise FPR by leveraging graph-based estimates of modularity. Still, several crucial differences exist between NLA and NBS: (a) the results from NBS focus on diff --git a/docs/source/setup.rst b/docs/source/setup.rst new file mode 100644 index 00000000..28e719dc --- /dev/null +++ b/docs/source/setup.rst @@ -0,0 +1,38 @@ +Setup +==================== + +Add NLA Folders to MATLAB Path +--------------------------- + +In order to for any NLA functions to work, MATLAB must be able to find them on the path. To do this, in +the MATLAB file explorer, navigate to where you have downloaded or cloned the NetworkLevelAnalysis +folder to. Right click the folder, hover over 'Add to Path' in the context menu, and click the 'Selected +Folders and Subfolders' option. +**NOTE**: If you only add the base 'NetworkLevelAnalysis' folder to the path the code will not work, you must +pick the 'Selected Folders and Subfolders' option + +Running the GUI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To open the GUI, navigate to the root directory of the NetworkLevelAnalysis package in MATLAB and run +the command ``NLA_GUI`` via the MATLAB command line. +**Note**: Running the GUI through an X11-based remote connection (eg: MobaXTerm or similar) can be very +laggy in some cases. It is strongly recommended to use the GUI through a more modern remote protocol +such as VNC instead. + +Running as a Pipeline Script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To run NLA via a script instead, open the file main_pipeline.m (located in the root directory of the +NetworkLevelAnalysis package) in MATLAB, and proceed through the stages of the pipeline. There is also +a pipeline for precalculated data located in precalculated_pipeline.m +**Note**: The pipeline scripts are more complex and easy-to-mess-up than the GUI, and should only be used +if you have a good reason to do so. + +Using Individual NLA Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To use NLA functions within your own code or scripts, add the ``NetworkLevelAnalysis`` folder to your +path. Most NLA functions are contained within the ``+nla`` namespace and its sub-namespaces. +Functions and packages can also be imported. ``import nla.TestPool`` imports the ``TestPool`` allowing +the user to just type ``TestPool()`` to initialize it. \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index f02cc07b..cdce0ed3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -86,6 +86,7 @@ jupyterlab-widgets==3.0.9 keyring==18.0.1 kiwisolver==1.0.1 language-selector==0.1 +latexcodec==3.0.0 launchpadlib==1.10.13 lazr.restfulclient==0.14.2 lazr.uri==1.0.3 @@ -135,6 +136,8 @@ psutil==5.5.1 ptyprocess==0.7.0 pulsemixer==1.5.0 pure-eval==0.2.2 +pybtex==0.24.0 +pybtex-docutils==1.0.3 pycairo==1.16.2 pycparser==2.21 pycrypto==2.6.1 @@ -181,6 +184,7 @@ soupsieve==2.5 sphinx==7.1.2 sphinx-rtd-theme==3.0.2 sphinxcontrib-applehelp==1.0.4 +sphinxcontrib-bibtex==2.6.3 sphinxcontrib-devhelp==1.0.2 sphinxcontrib-htmlhelp==2.0.1 sphinxcontrib-jquery==4.1 From 4288e37accb08a20e77e4c276a5c3d8677ea1db8 Mon Sep 17 00:00:00 2001 From: Jim Pollaro Date: Tue, 3 Dec 2024 10:55:40 -0600 Subject: [PATCH 3/7] added a "getting Started" --- docs/source/getting_started.rst | 51 +++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/source/getting_started.rst diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 00000000..19c7bf7a --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,51 @@ +Getting Started +================================================ + +Running with example data +-------------------------------------------------- + +First, open the NLA software (as described in :doc:`setup`). Select 'Pearson's r' as the edge-level +test from the edge-level test dropdown. + +Click 'Select' to choose a network atlas, navigating to the ``support_files`` folder withing your +'NetworkLevelAnalysis' installation and selecting ``Wheelock_2020_CerebralCortex_15nets_288ROI_on_MNI.mat``. +This file is used to parcellate the data. + +Then, select the functional connectivity, located in the ``examples/fc_and_behavior`` folder under the name +``sample_func_conn.mat``. Click 'Yes' to Fisher z-transform the data. Take a moment to visualize the functional +connectivity (FC) average by clicking 'View'. Note that the FC appears to match the parcellation, (effects +generally line up with network boundaries) - this can be a useful diagnostic tool if you are having issues +with parcellations not matching data. + +Finally, load the behavior ``sample_behavior.mat`` from the ``examples/fc_and_behavior`` folder (The 'file type' drop-down +will need to be changed from 'Text' to 'MATLAB table' in the file browser). Set the behavioral variable to 'Flanker_AgeAdj' by +clicking on that column in the table and then the 'Set Behavior' button. + +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 +the top one, and then shift+clicking the bottom one. + +_running_network_tests: +Run the tests using the 'Run' button on the bottom-right. The number of permutations can be changed with the input field +to the left of the 'Run' button. After pushing the 'Run' button, a result window will open. The edge-level test will be run +and the results can be visualized by pressing 'View' in the upper-left of the result window. To run the network-level tests, +push the 'Run' button in the results window. This will take longer, a progress window will show up displaying the progress. +To visualize the results, expand the lists in the reloaded (automatically) panel, and highlight a test. Press the 'View figures' +button. Other visualization options, such as chord plots and convergence maps, can also be shown. The results can be saved using the +'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 +window. + +Running with example pre-calculated data +---------------------------------------------------------- + +Similarly to the previous example, open the NLA window and load the ``Wheelock_2020_CerebralCortex_15nets_288ROI_on_MNI.mat`` parcellation. This +time, select the 'Precalculated data' edge-level test. Load the four input matrices in the ``examples/precalculated`` folder. + +* Observed coefficients: ``SIM_obs_coeff.mat`` +* Observed, thresholded p-values: ``SIM_obs_p.mat`` +* Permuted coefficients: ``SIM_perm_coeff.mat`` +* Permuted, thresholded p-values: ``SIM_perm_p.mat`` + +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 +with the 'View' button for the edge-level results button. In the bottom right corner, set the ``perm_count`` to the desired amount of +permutations. The example data provided has a maximums of 600 permutations. Run the tests using the procedure described in the +:ref:`previous section `. \ No newline at end of file From 77ac857147aa72293510efca96a1245fa1a58736 Mon Sep 17 00:00:00 2001 From: Jim Pollaro Date: Wed, 4 Dec 2024 13:28:31 -0600 Subject: [PATCH 4/7] added bib --- docs/source/conf.py | 4 +- docs/source/overview.rst | 16 +- docs/source/preface.rst | 9 +- docs/source/refs.bib | 441 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 456 insertions(+), 14 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 9272b750..491ef52d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -43,4 +43,6 @@ # -- Options for bibtex ---------------------------- # https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation -bibtex_bibfiles = ['refs.bib'] \ No newline at end of file +bibtex_bibfiles = ['refs.bib'] +bibtex_default_style = 'plain' +bibtex_reference_style = 'super' \ No newline at end of file diff --git a/docs/source/overview.rst b/docs/source/overview.rst index a54e81fc..e0e8f63d 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -5,18 +5,18 @@ The connectome and network structure ------------------------------------------- The term connectome essentially describes any network description of whole brain connectivity, from the -microscale of single neurons and synapses up to the macroscale of entire brain regions and pathways.5 -Connectomics is an ever-advancing field, and large-scale scientific endeavors such as the NIH�s Human +microscale of single neurons and synapses up to the macroscale of entire brain regions and pathways +:cite:p:`SpornsO`. Connectomics is an ever-advancing field, and large-scale scientific endeavors such as the NIH's Human Connectome Project have made significant progress in mapping, analyzing, and understanding the human connectome. Contemporary connectome research views the brain as an extensive, complex -network of non-adjacent, yet functionally and structurally connected brain regions.6,7 The connectome +network of non-adjacent, yet functionally and structurally connected brain regions :cite:p:`GordonE,PowerJ`. The connectome can be utilized to assess whole-brain associations between behavior and spatially distinct neural networks. MRI has traditionally been viewed as the gold standard for mapping the connectome and has been used to demonstrate consistencies between the spatial topology of task-based activation studies and the brain -networks derived from task-free functional connectivity.7,8 Contemporary cluster correction approaches -do not utilize the spatial topology of brain networks when estimating cluster size significance.9�11 +networks derived from task-free functional connectivity :cite:p:`PowerJ,GrattonC`. Contemporary cluster correction approaches +do not utilize the spatial topology of brain networks when estimating cluster size significance :cite:p:`FormanS,FristonK,VieiraS`. Therefore, there is an urgent need for standardized tools that address the robust hierarchical network structure of the brain and the limitations of contemporary neuroimaging analysis approaches by utilizing this biologically informed network structure to increase reproducibility and biological interpretation of @@ -30,10 +30,10 @@ connectome research, wherein studies use hundreds of regions of interest (ROI) t with thousands of potential connections, yet they lack the tools to establish statistical significance when analyzing associations between connectome and behavior. For example, previous research failed to find any significant differences in brain connectivity that passed a connectome-wise false discovery rate (FDR) -correction between individuals with a neurological disorder and healthy controls�a finding which -contradicts the recognized role of the brain in neurological functioning.12 Other studies have found +correction between individuals with a neurological disorder and healthy controls - a finding which +contradicts the recognized role of the brain in neurological functioning :cite:p:`GreeneD`. Other studies have found connectome-behavior associations that pass the FDR correction, but lack the statistical tools necessary to -definitively establish these observations.13 NLA, therefore, serves as a valuable tool for the statistical +definitively establish these observations :cite:p:`ShirerW`. NLA, therefore, serves as a valuable tool for the statistical quantification of network-level associations with behavior. The toolbox relies on cross-disciplinary biostatistical approaches to evaluate brain-behavior relationships within the connectome and allows for control of FDR at the network level. In this way, NLA diverges from most contemporary tools with a focus diff --git a/docs/source/preface.rst b/docs/source/preface.rst index d6863686..081d6108 100644 --- a/docs/source/preface.rst +++ b/docs/source/preface.rst @@ -1,20 +1,19 @@ Preface ============== - This is the reference manual for the Network Level Analysis (NLA) Toolbox. NLA is an extensible MATLAB- +This is the reference manual for the Network Level Analysis (NLA) Toolbox. NLA is an extensible MATLAB- based software package for the analysis of behavioral associations with brain connectivity data. NLA utilizes a model-based statistical approach known variously as 'pathway analysis', 'over-representation analysis', or 'enrichment analysis', which was first used to describe behavioral or clinical associations in -genome-wide association studies. +genome-wide association studies :cite:p:`RivalsI,KhatriP,BackesC,SubramanianA`. - Enrichment is a model-based data reduction approach to elucidate statistically significant network- +Enrichment is a model-based data reduction approach to elucidate statistically significant network- features. The suite developed here includes data-driven permutation-based false-positive-rate procedures that manage multiple comparisons corrections for one or two independent groups. Hardware and Software Requirements ------------------------------------------ - - NLA has been tested on MATLAB 2020b on Ubuntu 20.04. Current release of the GUI is not supported for +NLA has been tested on MATLAB 2020b on Ubuntu 20.04. Current release of the GUI is not supported for Windows. NLA requires the Parallel Processing and Statistics and Machine Learning Toolboxes. Best performance will be achieved on a server setup with multiple cores to support parallel processing (particularly for the permutation testing portion of the toolbox) \ No newline at end of file diff --git a/docs/source/refs.bib b/docs/source/refs.bib index e69de29b..3b302b8b 100644 --- a/docs/source/refs.bib +++ b/docs/source/refs.bib @@ -0,0 +1,441 @@ +@Article{RivalsI, + title = {Enrichment or depletion of a GO category within a class +of genes: which test?}, + author = {Rivals I. Personnaz L. Taing L. & Potier M.-C.}, + journal = {Bioinformatics}, + year = {2007}, + volume = {23}, + pages = {401-407}, +} + +@Article{KhatriP, + title = {Ten Years of Pathway Analysis: Current Approaches and Outstanding +Challenges.}, + author = {Khatri P. Sirota M. & Butte A. J.}, + journal = {PloS Comput Biol}, + year = {2012}, + volume = {8}, + pages = {e1002375} +} + +@Article{BackesC, + title = {Systemic permutation testing in GWAS pathway analysis: identification of genetic networks +in dilated cardiomyopathy and ulcerative colitis.}, + author = {Backes C.}, + journal = {BMC Genomics}, + year = {2014}, + volume = {15}, + pages = {622} +} + +@Article{SubramanianA, + title = {Gene set enrichment analysis: A knowledge-based approach for interpreting genome-wide +expression profiles.}, + author = {Subramanian A.}, + journal = {Proc Natl Acad Sci}, + year = {2005}, + volume = {102}, + pages = {15545-15550} +} + +@Article{SpornsO, + title = {The Human Connectome: A Structural Description of the Human Brain}, + author = {Sporns O. Tononi G. K |oumlaut| tter R.}, + journal = {PLoS Comput Biol}, + year = {2005}, + volume = {1}, + pages = {42} +} + +@Article{GordonE, + title = {Generation and Evaluation of a Cortical Area Parcellation from Resting-State +Correlations.}, + author = {Gordon E.M.}, + journal = {Cereb Cortex}, + year = {2016}, + volume = {26}, + pages = {288-303} +} + +@Article{PowerJ, + title = {Functional Network Organization of the Human Brain.}, + author = {Power J.D.}, + journal = {Neuron}, + year = {2011}, + volume = {72}, + pages = {665-678} +} + +@Article{GrattonC, + title = {Funcational Brain Networks Are Dominated by Stable Group and Individual Factors, +Not Cognitive or Daily Variation}, + author = {Gratton C.}, + journal = {Neuron}, + year = {2018}, + volume = {98}, + pages = {439-452} +} + +@Article{FormanS, + title = {Improved Assessment of Significant Activation in Funcational Magnetic Resonance Imaging +(fMRI): Use of Cluster-Size Threshold.}, + author = {Forman S.D.}, + journal = {Magn Reson Med}, + year = {1995}, + volume = {33}, + pages = {636-647} +} + +@Article{FristonK, + title = {Assessing the significance of focal activations using their spatial extent: Assessing Focal +Activations by Spatial Extent}, + author = {Friston K.J. Worsley K.J. Frackowiak R.S.J. Mazziotta J.C. & Evans A.C.}, + journal = {Hum Brain Mapp}, + year = {1994}, + volume = {1}, + pages = {210-220} +} + +@Article{VieiraS, + title = {Using deep learning to investigate the neuroimaging correlates of psychiatric and neurological +disorders: Methods and applications.}, + author = {Vieira S. Pinaya W.H.L. & Mechelli A.}, + journal = {Neurosci Biobehav Rev}, + year = {2017}, + volume = {74}, + pages = {58-75} +} + +@Article{GreeneD, + title = {Multivariate pattern classification of pediatric Tourette syndrome using functional connectivity +MRI.}, + author = {Greene D.J.}, + journal = {Dev Sci}, + year = {2016}, + volume = {19}, + pages = {581-598} +} + +@Article{ShirerW, + title = {Decoding Subject-Driven Cognitive States with Whole-Brain Connectivity Patterns.}, + author = {Shirer W.R. Ryali S. Rykhlevskaia E. Menon V. & Greicius M.D.}, + journal = {Cereb Cortex}, + year = {2012}, + volume = {22}, + pages = {158-165} +} + +@Article{EggebrechtA, + title = {Joint Attention and Brain Functional Connectivity in Infants and Toddlers.}, + author = {Eggebrecht A.T.}, + journal = {Cereb Cortex}, + year = {2017}, + volume = {27}, + pages = {1709-1720} +} + +@Article{WheelockM:2018, + title = {Altered functional network connectivity relates to motor development in children born +very preterm.}, + author = {Wheelock M.D.}, + journal = {NeuroImage}, + year = {2018}, + volume = {183}, + pages = {574-583} +} + +@Article{WheelockM:2019, + title = {Sex differences in functional connectivity during fetal brain development.}, + author = {Wheelock M.D.}, + journal = {Neurosci}, + year = {2019}, + volume = {36}, + pages = {100632} +} + +@Article{RudolphM, + title = {Maternal IL-6 during pregnancy can be estimated from newborn brain connectivity and +predicts future working memory in offspring.}, + author = {Rudolph M.D.}, + journal = {Nat Neurosci}, + year = {2018}, + volume = {21}, + pages = {765-772} +} + +@Article{MaronKatz, + title = {A large-scale perspective on stress-induced alterations in resting-state networks.}, + author = {Maron-Katz A. Vaisvaser S. Lin T. Hendler T. & Shamir R.A.}, + journal = {Sci Rep}, + year = {2016}, + volume = {6}, + pages = {21503} +} + +@Article{MarrusN, + title = {Walking, Gross Motor Development, and Brain Functional Connectivity in Infants and Toddlers.}, + author = {Marrus N.}, + journal = {Cereb Cortex}, + year = {2018}, + volume = {28}, + pages = {750-763} +} + +@Article{FeczkoE, + title = {Subtyping cognitive profiles in Autism Spectrum Disorder using a Functional Random Forest +algorithm.}, + author = {Feczko E.}, + journal = {NeuroImage}, + year = {2018}, + volume = {172}, + pages = {674-688} +} + +@Article{ThomasonM, + title = {Prenatal lead exposure impacts cross-hemispheric and long-rage connectivity in the human +fetal brain.}, + author = {Thomason M.E.}, + journal = {NeuroImage}, + year = {2019}, + volume = {191}, + pages = {186=192} +} + +@Article{McKinnonC, + title = {Restricted and Repetitive Behavior and Brain Functional Connectivity in Infants at Risk +for Developing Autism Spectrum Disorder}, + author = {McKinnon C.J.}, + journal = {Biol Psychiatry Cogn Neurosci Neuroimaging}, + year = {2019}, + volume = {4}, + pages = {50-61} +} + +@Article{MarekS, + title = {Identifying reproducible individual differences in childhood funcational brain networks: +An ABCD study}, + author = {Marek S.}, + journal = {Dev Cogn Neurosci}, + year = {2019}, + volume = {40}, + pages = {100706} +} + +@Article{ShehzadZ, + title = {A multivariate distance-based analytic framework for connectome-wide association studies}, + author = {Shehzad Z.}, + journal = {NeuroImage}, + year = {2014}, + volume = {93}, + pages = {74-94} +} + +@Article{SharmaA, + title = {Common Dimensional Reward Deficits Across Mood and Psychotic Disorders: A Connectome-Wide +Association Study.}, + author = {Sharma A.}, + journal = {Am J Psychiatry}, + year = {2017}, + volume = {174}, + pages = {657-666} +} + +@Article{RaichleM, + title = {The Brain's Default Mode Network}, + author = {Raichle M.E.}, + journal = {Annu Rev Neurosci}, + year = {2015}, + volume = {38}, + pages = {433-447} +} + +@Article{ZaleskyA, + title = {Network-based statistic: Identifying differences in brain networks}, + author = {Zalesky A. Fornito A. & Bullmore E.T.}, + journal = {NeuroImage}, + year = {2010}, + volume = {53}, + pages = {1197-1207} +} + +@Article{RubinovM, + title = {Complex network measures of brain connectivity: Uses and interpretations.}, + author = {Rubinov M. & Sporns O.}, + journal = {NeuroImage}, + year = {2010}, + volume = {52}, + pages = {1059-1069} +} + +@Article{BahramiM, + title = {A MATLAB toolbox for multivariate analysis of brain networks.}, + author = {Bahrami M. Laurienti P.J. & Simpson S.L.}, + journal = {Hum Brain Mapp}, + year = {2019}, + volume = {40}, + pages = {175-186} +} + +@Article{GinestetC, + title = {Statistical network analysis for functional MRI: summary networks and group comparisons.}, + author = {Ginestet C.E. Fournal A.P. & Simmons A.}, + journal = {Front Comput Neurosci}, + year = {2014}, + volume = {8} +} + +@Article{SimpsonS, + title = {A permutation testing framework to compare groups of brain networks.}, + author = {Simpson S.L. Lyday R.G. Hayasaka S. Marsh A.P. & Laurienti P.J.}, + journal = {Front Comput Neurosci}, + year = {2013}, + volume = {7} +} + +@Article{NicholsT, + title = {Controlling the familywise error rate in functional neuroimaging: a comparative review.}, + author = {Nichols T. & Hayasaka S.}, + journal = {Stat Methods Med Res}, + year = {2003}, + volume = {12}, + pages = {419-446} +} + +@Article{BellecP, + title = {Impact of the resolutation of brain parcels on connectome-wide association studines in fMRI.}, + author = {Bellec. P.}, + journal = {NeuroImage}, + year = {2015}, + volume = {123}, + pages = {212-228} +} + +@Article{RosvallM, + title = {Maps of random walks on complex networks reveal community structure.}, + author = {Rosvall M. & Bergstrom C.T.}, + journal = {Proc Natl Acad Sci}, + year = {2008}, + volume = {105}, + pages = {1118-1123} +} + +@Article{ThomasY, + title = {The organization of the human cerebral cortex.}, + author = {Thomas Yeo B.T.}, + journal = {J Neurophysical}, + year = {2011}, + volume = {106}, + pages = {1125-1165} +} + +@Article{GlasserM, + title = {A multi-modal parcellation of human cerebral cortex.}, + author = {Glasser M.F.}, + journal = {Nature}, + year = {2016}, + volume = {536}, + pages = {171-178} +} + +@Article{ShenX, + title = {Groupwise whole-brain parcellation from resting-state fMRI data for network node identification.}, + author = {Shen X. Tokoglu F. Papademetris X. & Constable R.T.}, + journal = {NeuroImage}, + year = {2013}, + volume = {82}, + pages = {403-415} +} + +@Article{CraddockR, + title = {A whole brain fMRI atlas generated via spatially constrained spectral clustering.}, + author = {Craddock R.C. James G.A. Holtzheimer P.E. Hu X.P. & Mayberg H.S.}, + journal = {Hum Brain Mapp}, + year = {2012}, + volume = {33}, + pages = {1914-1928} +} + +@Article{AckermanM, + title = {A general modular framework for gene set enrichment analysis.}, + author = {Ackermann M. & Strimmer K.}, + journal = {BMC Bioinformatics}, + year = {2009}, + volume = {10}, + pages = {47} +} + +@Article{vandenHeuvelM, + title = {Proportional thresholding in resting-state fMRI functional connectivity networks and +consequences for patient-control connectome studies: Issues and recommendations.}, + author = {van den Heuval M.P.}, + journal = {NeuroImage}, + year = {2017}, + volume = {152}, + pages = {437-449} +} + +@Article{MoothaV, + title = {PGC-1 |alpha| -responsive genes involved in oxidative phosphorylation are coordinately +downregulated in human diabetes.}, + author = {Mootha V.K.}, + journal = {Nat Genet}, + year = {2003}, + volume = {34}, + pages = {267-273} +} + +@Article{ZahnJ, + title = {Transcriptional Profiling of Aging in Human Muscle Reveals a Common Aging Signature.}, + author = {Zahn J.M.}, + journal = {PLoS Genet}, + year = {2006}, + volume = {2}, + pages = {115} +} + +@Article{ChenJ, + title = {Significance analysis of groups of genes in expression profiling studies.}, + author = {Chen J.J. Lee T. Delongchamp R.R. Chen T. & Tsai C.-A.}, + journal = {Bioinformatics}, + year = {2007}, + volume = {23}, + pages = {2104-2112} +} + +@Article{NewtonM, + title = {Random-set methods identify distinct aspects of the enrichment signal in gene-set analysis.}, + author = {Newton M.A. Quintana F.A. Boon J. Sengupta S. & Ahlquist P.}, + journal = {Ann Appl Stat}, + year = {2007}, + volume = {1} +} + +@Article{YaariG, + title = {Quantitative set analysis for gene expression: a method to quantify gene set differential expression +including gene-gene correlations.}, + author = {Yaari G. Bolen C.R. Thakar J. & Kleinstein S.H.}, + journal = {Nucleic Acids Res}, + year = {2013}, + volume = {41}, + pages = {170-170} +} + +@Article{EfronB, + title = {On testing the significance of sets of genes.}, + author = {Efron B. & Tibshirani R.}, + journal = {Ann Appl Stat}, + year = {2007}, + volume = {1} +} + +@Article{SeitzmanB, + title = {A set of functionally-defined brain regions with improved representation of the subcortex and cerebellum.}, + author = {Seitzman B.A.}, + journal = {NeuroImage}, + year = {2020}, + volume = {206}, + pages = {116290} +} + +.. |oumlat| unicode:: U+00D6 .. O umlaut +.. |alpha| unicode:: U+03B1 .. alpha \ No newline at end of file From 2305b35f7c7851060cdcd75e35cdf42e44c33fe8 Mon Sep 17 00:00:00 2001 From: Jim Pollaro Date: Wed, 4 Dec 2024 14:47:15 -0600 Subject: [PATCH 5/7] Added citations to methodology overview preface --- docs/source/methodology.rst | 18 +++++++++--------- docs/source/overview.rst | 18 +++++++++--------- docs/source/refs.bib | 9 +++++++++ 3 files changed, 27 insertions(+), 18 deletions(-) diff --git a/docs/source/methodology.rst b/docs/source/methodology.rst index 79844aae..20cc4c0f 100644 --- a/docs/source/methodology.rst +++ b/docs/source/methodology.rst @@ -6,11 +6,11 @@ Brain Network Map Selection NLA requires the user to specify the network map that will be used to depict the known architecture of the human connectome, which is crucial given that the network map selection affects both statistical -significance testing and interpretation. The current pipeline uses network maps that are generated with +significance testing and interpretation :cite:p:`BellecP`. The current pipeline uses network maps that are generated with Infomap, due to its greater congruence with networks derived from task-activation and seed-based -connectivity studies than alternative modularity algorithms. Network maps can be generated using -one�s preferred algorithm or one of several published ROI and corresponding network map options that -will be included in the NLA toolbox. The use of standardized ROI and network maps creates a +connectivity studies than alternative modularity algorithms :cite:p:`PowerJ,RosvallM`. Network maps can be generated using +one's preferred algorithm or one of several published ROI and corresponding network map options that +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 common, reproducible framework for testing brain-behavior associations across connectome research General Linear Model / Edge-wise Statistical Model Selection @@ -33,17 +33,17 @@ The NLA Method First, connectome-wide associations are calculated between ROI-pair connectivity and behavioral data, resulting in a set of standardized regression coefficients that specify the brain-behavior association at each ROI-pair of the connectome matrix. Next, network level analysis-consisting of transformation of the -edge-wise test statistics and enrichment statistic calculation40 - is done to determine which networks are +edge-wise test statistics and enrichment statistic calculation :cite:p:`AckermanM` - is done to determine which networks are strongly associated with the behavior of interest. -Both p-value and test-statistic binarization are offered in the current NLA pipeline. Prior research has +Both p-value and test-statistic binarization are offered in the current NLA pipeline :cite:p:`EggebrechtA,WheelockM:2018`. Prior research has supported the incorporation of a proportional edge density threshold, given that uneven edge density -thresholds have been shown to unfairly bias results. +thresholds have been shown to unfairly bias results :cite:p:`vandenHeuvelM`. For enrichment statistic calculation, NLA offers a number of statistical tests. Prior research has relied on chi-square and Fisher's Exact test, as well as a Kolmogorov-Smirnov (KS) test and non-parametric tests -based on ranks, which compare the distribution of test values within a region to other regions. In +based on ranks, which compare the distribution of test values within a region to other regions :cite:p:`WheelockM:2018,RudolphM,MoothaV,ZahnJ`. In addition, KS alternatives such as averaging or minmax have also shown promise in connectome -applications. +applications :cite:p:`ChenJ,NewtonM,YaariG,EfronB`. NLA then conducts data-driven permutation testing to establish significance. In the NLA toolbox, network level significance is determined by comparing each measured enrichment statistic to permuted diff --git a/docs/source/overview.rst b/docs/source/overview.rst index e0e8f63d..9a4779fa 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -51,11 +51,11 @@ Introduction to NLA and enrichment Network Level Analysis uses enrichment to evaluate whether pairs of networks demonstrate significant clustering of strong brain-behavior correlations. Enrichment applies common statistical tests to measure the clustering of associations within a given network pair and reduces the number of comparisons to -those performed at the network level.4 Network level statistics such as the Chi-Square test, +those performed at the network level :cite:p:`SubramanianA`. Network level statistics such as the Chi-Square test, Hypergeometric test, and Kolmogorov-Smirnov test have been used in numerous network-level investigations including joint attention and motor function in infants and toddlers, maternal inflammation during gestation, motor and attention development in very preterm children, sex -differences during fetal brain development, and autism in adults. +differences during fetal brain development, and autism in adults :cite:p:`EggebrechtA,WheelockM:2018,WheelockM:2019,RudolphM,WheelockM:2021,MaronKatz,MarrusN,FeczkoE`. Edge-level Statistic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -106,13 +106,13 @@ The NLA toolbox's use of a novel enrichment approach makes it a transformative t wide association studies, given that all current enrichment analysis methods are built for use with genome data and NLA is the first enrichment tool designed to analyze the connectome. Many alternative methods for connectome analysis rely on spatial extent cluster correction in order to control voxel-wise -whole brain connectome FPR. Despite mounting evidence that spatially non-contiguous brain regions +whole brain connectome FPR :cite:p:`ShehzadZ,SharmaA`. Despite mounting evidence that spatially non-contiguous brain regions are strongly correlated and often co-activate to the same stimuli, cluster extent correction is often regarded as the ideal thresholding approach in human connectome literature. By basing statistical significance on contiguous voxels, however, cluster extent correction methods fail to account for this covariance structure. Therefore, brain regions that are known to be highly correlated and part of the same network - such as the anterior cingulate and posterior cingulate - may be thresholded separately, -resulting in one or both separate regions not meeting statistical thresholds. NLA is distinguished from +resulting in one or both separate regions not meeting statistical thresholds :cite:p:`RaichleM`. NLA is distinguished from the cluster extent correction methodology in that it groups highly correlated, non-contiguous brain regions based on pre-defined network modules prior to estimating network-level significance. @@ -121,7 +121,7 @@ Network Based Statistic (NBS) Given this deviation from the popular extent cluster correction thresholding method, the most conceptually similar existing connectome analysis approach to NLA is the Network Based Statistic (NBS) -toolbox. NBS was the first tool control the edgewise FPR by leveraging graph-based estimates of +toolbox :cite:p:`ZaleskyA`. NBS was the first tool control the edgewise FPR by leveraging graph-based estimates of modularity. Still, several crucial differences exist between NLA and NBS: (a) the results from NBS focus on edgewise significance as opposed to network-level significance, (b) NBS does not have a built-in visualization functionality, and (c) NBS allows for different module sizes, number of network modules, @@ -135,11 +135,11 @@ Graph Theoretical Toolboxes Graph Theoretical Toolboxes are another comparable approach to NLA, offering an analysis methodology to quantify network characteristics such as integration, segregation, resilience, and relative contribution -of individual network nodes to overall information flow within the network. Various other toolboxes +of individual network nodes to overall information flow within the network :cite:p:`RubinovM`. Various other toolboxes have been created to address network thresholding, graph metric calculation, and graph visualization� such as GRETNA, GEPHI, and BrainNet Viewer. Additional methodologies aim to determine network topology differences by leveraging generalized estimating equations and generalized linear and nonlinear -mixed models. Each of these tools has helped to advance the application of graph theory approaches +mixed models :cite:p:`BahramiM,GinestetC,SimpsonS`. Each of these tools has helped to advance the application of graph theory approaches to connectome analysis. The NLA toolbox estimates statistical associations edgewise, rather than on network topology features, thereby providing a crucial and complementary approach to the existing collection of brain network analysis tools @@ -148,7 +148,7 @@ Statistical Inference and the use of liberal primary thresholds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ NLA establishes statistical significance in the weak sense similar to traditional voxelwise cluster-level -inference. In voxelwise cluster correction, a liberal primary threshold is employed in addition to a +inference :cite:p:`NicholsT`. In voxelwise cluster correction, a liberal primary threshold is employed in addition to a cluster-extent threshold (determined by e.g., random field theory or Monte Carlo simulations). The resulting clusters are significant but inferences cannot be made about any particular sub-regions or voxels within a cluster. Similarly, NLA employs a liberal primary threshold in order to calculate the @@ -159,4 +159,4 @@ this would still only control the false positive rate in the weak sense. The mot approaches (cluster-level inference, network-level enrichment, network-based statistic) is to control the false positive rate when a massive number of tests are performed. Controlling the false positive rate in the strong sense with several thousand functional connections (e.g., 30k) will often result in no single ROI-pair -surviving OR a few scattered ROI-pairs surviving with no clear biological pattern. \ No newline at end of file +surviving OR a few scattered ROI-pairs surviving with no clear biological pattern :cite:p:`GreeneD`. \ No newline at end of file diff --git a/docs/source/refs.bib b/docs/source/refs.bib index 3b302b8b..0f4e0d1c 100644 --- a/docs/source/refs.bib +++ b/docs/source/refs.bib @@ -153,6 +153,15 @@ @Article{WheelockM:2019 pages = {100632} } +@Article{WheelockM:2021, + title = {Altered brain-behavior relationships underlie attention impairment in very preterm children.}, + author = {Wheelock M.D.}, + journal = {Cereb Cortex}, + year = {2021}, + volume = {31}, + pages = {1383-1394} +} + @Article{RudolphM, title = {Maternal IL-6 during pregnancy can be estimated from newborn brain connectivity and predicts future working memory in offspring.}, From bb1b7991d1bf210d16334fb650e959b819d5767a Mon Sep 17 00:00:00 2001 From: Jim Pollaro Date: Tue, 10 Dec 2024 09:42:00 -0600 Subject: [PATCH 6/7] adding network atlas documentation --- +nla/NetworkAtlas.m | 20 ++++++++++++++--- docs/source/conf.py | 5 ++++- docs/source/index.rst | 3 ++- docs/source/methodology.rst | 2 +- docs/source/network_atlases.rst | 40 +++++++++++++++++++++++++++++++++ docs/source/references.rst | 0 docs/source/setup.rst | 2 +- 7 files changed, 65 insertions(+), 7 deletions(-) create mode 100644 docs/source/network_atlases.rst delete mode 100644 docs/source/references.rst diff --git a/+nla/NetworkAtlas.m b/+nla/NetworkAtlas.m index f40b2a65..df18c9a0 100755 --- a/+nla/NetworkAtlas.m +++ b/+nla/NetworkAtlas.m @@ -1,9 +1,19 @@ classdef NetworkAtlas < nla.DeepCopyable - %NETWORKATLAS Network atlas(also known as infomap) - % Defines ROI positions/information and networks + % Network atlas (also known as infomap) + % Defines ROI positions/information and networks + % + % :param name: The name of the atlas + % :param net_names: N\ :sub:`nets`\ x 3 matrix. The names of the networks + % :param ROI_key: N\ :sub:`ROIs`\ x 2 matrix. First column is ROI (Region Of Interest) indexes, second column is the network they belong to + % :param ROI_order: N\ :sub:`ROIs`\ x 1 vector. Functional Connectivity data indexes corresponding to ROIs + % :param ROI_pos: N\ :sub:`ROIs`\ x 3 matrix. Centroid positions for each ROI. + % :param net_colors: N\ :sub:`nets`\ x 3 matrix. The color of each network when plotted. + % :param parcels: Optional MATLAB struct field for surface parcellations. Contains two sub-fields ``ctx_l`` and ``ctx_r``. N\ :sub:`verts`\ x 1 vectors. Each element of a vector corresponds to a vertex within the spatial mesh and contains the index of the ROI for that vertex. + % :param space: Optional The mesh that the atlas` ROI locations/parcels are in. Two options - ``TT`` or ``MNI`` + properties (SetAccess = private) - nets + nets % This is the net_names ROIs ROI_order name @@ -102,18 +112,22 @@ end function val = numNets(obj) + % :returns: The number of networks val = numel(obj.nets); end function val = numNetPairs(obj) + % :returns: The number of network pairs val = nla.helpers.triNum(numel(obj.nets)); end function val = numROIs(obj) + % :returns: The number of Regions Of Interest (ROIT) val = numel(obj.ROIs); end function val = numROIPairs(obj) + % :returns: The number of ROI pairs val = nla.helpers.triNum(numel(obj.ROIs) - 1); end end diff --git a/docs/source/conf.py b/docs/source/conf.py index 491ef52d..cb9e299a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -20,8 +20,11 @@ 'sphinx.ext.intersphinx', 'sphinxcontrib.matlab', 'sphinx_rtd_theme', - 'sphinxcontrib.bibtex' + 'sphinxcontrib.bibtex', + 'sphinx.ext.autodoc' ] +this_dir = os.path.dirname(os.path.abspath(__file__)) +matlab_src_dir = os.path.abspath(os.path.join(this_dir, '../../+nla')) templates_path = ['_templates'] exclude_patterns = [] diff --git a/docs/source/index.rst b/docs/source/index.rst index 5cd7b2ab..bc4d9624 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,7 +15,8 @@ Welcome to NetworkLevelAnalysis's documentation! methodology setup getting_started - biblography + network_atlases + bibliography Indices and tables diff --git a/docs/source/methodology.rst b/docs/source/methodology.rst index 20cc4c0f..89823ee6 100644 --- a/docs/source/methodology.rst +++ b/docs/source/methodology.rst @@ -14,7 +14,7 @@ will be included in the NLA toolbox :cite:p:`GordonE,PowerJ,ThomasY,GlasserM,She common, reproducible framework for testing brain-behavior associations across connectome research General Linear Model / Edge-wise Statistical Model Selection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ NLA also requires the user to specify the desired statistical model for testing associations between behavioral data and edge-wise�or ROI-pair connectivity�connectome data. The analysis pipeline within diff --git a/docs/source/network_atlases.rst b/docs/source/network_atlases.rst new file mode 100644 index 00000000..bb7c2fde --- /dev/null +++ b/docs/source/network_atlases.rst @@ -0,0 +1,40 @@ +Network Atlases +================================== +.. mat:module:: . + +Overview +------------------------------------ + +A network atlas is a data file describing networks of the brain, each containing a number of related +regions of interest. It also contains metadata such as network colors and names, ROI spatial coordinates +(with associtated mesh/space), and optionally, a surface parcellation. + +.. mat:autoclass:: NetworkAtlas + + .. mat:automethod:: numNets + + .. mat:automethod:: numNetPairs + + .. mat:automethod:: numROIs + + .. mat:automethod:: numROIPairs + +Provided Network Atlases +-------------------------------- + +A number of network atlases are provided with the NLA software package in the ``support_files`` directory. +Only NLA-specific details will be provided about them, if you wish to go into more depth on a particular atlas +you should follow the link provided in its ``source`` field. + +* ``Gordon_13nets_333parcels_on_MNI`` + * Surface space. + * Consists of 333 parcels and corresponding 13 networks :cite:p:`GordonE`. Contains both the MNI centrois and surface parcels on a ``MNI_32k`` mesh. +* ``Gordon_12nets_286parcels_on_MNI`` + * Surface space + * Same as ``Gordon_13nets_333parcels_on_MNI`` with 'None' network and its ROIs removed :cite:p:`GordonE`. +* ``Seitzman_17nets_300ROI_on_TT`` + * Volume space + * 300 ROIs in 17 networks :cite:p:`SeitzmanB`. Contains TT centroids +* ``Seitzman_15nets_288ROI_on_TT`` + * Volume space + * Same as ``Seitzman_17nets_300ROI_on_TT`` with 12 ROI and 2 networks removed due inconsistent placement in a network :cite:p:`SeitzmanB`. diff --git a/docs/source/references.rst b/docs/source/references.rst deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/source/setup.rst b/docs/source/setup.rst index 28e719dc..5aeda87f 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -2,7 +2,7 @@ Setup ==================== Add NLA Folders to MATLAB Path ---------------------------- +------------------------------------- In order to for any NLA functions to work, MATLAB must be able to find them on the path. To do this, in the MATLAB file explorer, navigate to where you have downloaded or cloned the NetworkLevelAnalysis From 583917d9d5858c64e00423918df0c17b66ce6f04 Mon Sep 17 00:00:00 2001 From: Jim Pollaro Date: Wed, 11 Dec 2024 09:48:41 -0600 Subject: [PATCH 7/7] trying to make sense of edge level testing --- docs/source/edge_level_tests.rst | 78 ++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 79 insertions(+) create mode 100644 docs/source/edge_level_tests.rst diff --git a/docs/source/edge_level_tests.rst b/docs/source/edge_level_tests.rst new file mode 100644 index 00000000..257e125a --- /dev/null +++ b/docs/source/edge_level_tests.rst @@ -0,0 +1,78 @@ +Edge-level Statistical Tests +========================================== + +Methods +------------------------- + +The non-permuted method calculates the correlation of each Region Of Interest (ROI) to all other +ROIs via the given test. These results are stored as a correlation coefficient, ``coeff``, a p-value, ``prob``, +and a thresholded p-value, ``prob_sig``. The permuted method is identical except the variables have a ``_perm`` suffix. + +Common Inputs +-------------------------- + +:P: Edge-level p-value threshold +:Network Atlas: :doc:`/network_atlases` +:Functional Connectivity: Initial coorelation matrix if size N\ :sub:`ROIs`\ x N\ :sub:`ROIs`\ x N\ :sub:`scans`\. + r-values or Fisher z-transformed r-values. +:Behavior: MATLAB table (``.mat``) or tab seperated text file (``.txt``) + + ============== =================== ================ + Variable Name Next Variable Name More Variable... + ============== =================== ================ + 1 5 1.5 + 0 1 3 + 1 7 2.6 + ... ... ... + ============== =================== ================ + + Each column header is a name of a variable. + Each column contains N\ :sub:`scans`\ entries. + After loading this file, the table should display in the GUI. + The user may mark one column as 'Behavior' for the score of interest. + Other columns may be marked as 'Covariates' which are partialed prior to running statistics. + (Note: Network Level Analysis cannot handle missing values for behavior or covariates. If there are ``NaNs`` or missing values, do not select this columns) + +Provided Tests +-------------------------------- + +* **Pearson's r** + + * MATLAB `corr ` function with ``type``, ``Pearson`` +* **Spearman's** :math:`\rho`\ + + * MATLAB `corr ` function with ``type``, ``Spearman`` +* **Spearman's** :math:`\rho`\ **estimator** + + * Faster approximation of the Spearman's rho function at the cost of slightly less accurate result. + * Based on developer testing, rho values may differ by :math:`10^{-4}` and p-values by :math:`10^{-5}`. + * This error is passed on to the network-level tests, and can cause p-value difference by :math:`10^{-4}` + * These differences were found with 10,000 permutations. Less permutations results in higher error in a less evenly distributed fashion. + * This is recommended for exploratory research with the Spearman's rho function for publications +* **Kendall's** :math:`\tau`\ **-b** + + * Implements Kendall's :math:`\tau`\ -b using C code in a MATLAB MEX file (``+mex/+src/kendallTauB.c``) + * Faster implementation that stardard MATLAB code providing identical :math:`\tau`\ and p-values. + * Run-time difference from *O*\ (*n*\ :sup:`2`) to *O*\ (*n* log *n*) + * This is done with a red-black tree. +* **Welch's t-test`` + + * Implements an optomized Welch's t-test comparing the functional connectivity of two groups. + * Extra imports compared to other edge level tests + :Group name(s): Names associated with each group. (For example, 'Male' and 'Female') + :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. + +* **Pre-calculated data loader** + + * Allows loading of observed and permuted edge-level data the user has pre-calculated outside the NLA. + * Four ``.mat`` files needed as inputs + * p-values should be thresholded + :Observed p: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x 1 matrix of logical values, the observed, thresholded edge-level p-values. + N\ :sub:`ROI_pairs`\ are the lower triangle values of a N\ :sub:`ROIs`\ x N\ :sub:`ROIs`\ matrix. + :Observed coeff: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x 1 matrix of observed edge-level coefficients. + :Permuted p: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x N\ :sub:`permutations`\ of logical values. Observed, thresholded, permuted p-values. + :Permuted coeff: ``.mat`` file containing N\ :sub:`ROI_pairs`\ x N\ :sub:`permutations`\ of permuted edge-level coefficients. + +Creating additional edge-level tests +----------------------------------------------- + diff --git a/docs/source/index.rst b/docs/source/index.rst index bc4d9624..4ee1a48e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,7 @@ Welcome to NetworkLevelAnalysis's documentation! setup getting_started network_atlases + edge_level_tests bibliography