- This toolbox is designed to extract personalized functional networks from fMRI data.
- It is implemented with our spatial-regularized non-negative matrix factorization SR-NMF and Group-Information-Guided Independent Component Analysis GIG-ICA to compute personalized FNs.
- It works with both MATLAB and Python, and comes with a user-friendly GUI interface in MATLAB, as well as a step-by-step guide to setup a customized workflow script in Python.
- It supports both surface and volume based fMRI data, and multiple fMRI formats, including CIFTI, MGH, MGZ, NIFTI, and MAT.
- It allows input of precomputed group-level FN definition.
- It outputs results of both group-level and personalized FNs, and their visualization graphs, as well as quality control and web-based report.
- The MATLAB version requires MATLAB no older than 2021A. Its GUI version can be accessed by openning pNet.mlapp, or install the pNet.mlappinstall as a MATLAB APP. It can also be compiled into a software, which requires the free MATLAB runtime software at https://www.mathworks.com/products/compiler/matlab-runtime.html. Details can be found in the README.txt in each subfolder containing the compiled pNet.
- The Python version can run in Conda environment or with Docker (https://www.docker.com). The Python version is available at https://github.com/YuncongMa/pNet/tree/main/Python. Installation details can be found in the README located in the Python folder (https://github.com/YuncongMa/pNet/tree/main/Python#readme). The docker file can be downloaded from Google Drive.
- Additional installation information can be found in the help document (/MATLAB/Manual_MATLAB.pdf and /Python/Manual_Python.pdf).
The MATLAB version features an intuitive user interface (/MATLAB/GUI/pNet.mlapp) to configure the workflow, carry out the computation and check the results.
(A) The data input module for loading fMRI scans and brain template files.
(B) A module to setup computation parameters of our spatial-reguarlized NMF method.
(C) Surface-based visualization of both group and personalized FNs (k=17) using HCP S1200 dataset, with left panel showing a binarized atlas generated from the group FNs and the right panel showing five views of three personalized FNs. All the color bars of intensity maps were set from the maximum value of the map to its half value.
(D) Volume-based visualization of both group and personalized FNs (k=17) from Zhen’s multi-cohort iSTAGING study, with left panel showing a binarized functional atlas generated from the group FNs and the right panel showing a three-slice view of three personalized FNs.
(E) Surface-based visualization of a personalized FN.
(F) Surface-based visualization of the maximum t value (two sample t-test, FDR correction, p-value=0.001) of sex differences of individualized FNs (k=50) of the HCP S1200 dataset.
(G) A module for quality control, showing one scan with two FNs mismatched to their group-level counterparts.
The Python version features a customized workflow using command line This will generate a Python script to run a workflow
pNet provides bash scripts to interact with cluster environment for both MATLAB and Python versions.
The MATLAB version uses bash scripts (/MATLAB/Bash_Script) to perform customized pNet workflows. Users need to submit those bash jobs using terminal commands.
The Python version uses a Python script to generate bash scripts and submit bash jobs to the cluster.
Two manuals are provided for MATLAB and Python version respectively
https://github.com/YuncongMa/pNet/blob/main/MATLAB/Manual_MATLAB.pdf
https://github.com/YuncongMa/pNet/blob/main/Python/Manual_Python.pdf
pNet consists of five main modules and a customizable workflow.
- Data input module loads preprocessed fMRI data, with corresponding brain template files to extract coordination information and facilitate visualization.
- FN computation module is to carry out computation for group-level and personalized FNs.
- Visualization module can provide both preconfigured and interative displays
- Quality control module will ensure the reliability of the whole computation.
- Additionally, statistical analyses can be employed to investigate differences in personalized FNs between groups or their relation to behavioral traits.
pNet organizes data structure with respect to the six panels of its GUI version: Data Input, FN Computation, Group FN, Personalized FN, Statistics, Quality Control.
- Each folder contains setting files, data, or figure files.
- Group FNs and corresponding preconfigured visualization files are in Group_FN.
- Perosnalized FNs of each subject or fMRI scan are stored in sub-folders in Personalized_FN.
The brain template is to get the brain mask and overlay image (T1/T2) for volume data, 3D coordination for brain surface data. Five built-in brain templates are available in the subfolder "Brain_Template".
- HCP surface: subfolder "HCP_Surface". It contains 3D mesh shapes (vertices and faces) and brain masks for two hemishperes.
- FreeSurfer fsaverage5: "FreeSurfer_fsaverage5". It is similar to HCP surface .
- MNI volume space: subfolder "MNI_Volume". It contains two MATLAB files "Brain_Mask.mat" and "Overlay_Image.mat".
- HCP surface-volume: It contains both cortical surface information, and subcortical volume.
- HCP volume: It is similar to MNI volume space.
pNet can load existing group-level FNs as reference to obtain personalized FNs for individual fMRI data.
Here we provided 17 FN results (/Group_FN/HCP_Surface/gFN_17_HCP_Surface.mat) for HCP S1200.
And several sets of FN results (k=17, 25, 50, 75, 100, 125, 150) for iSTAGING (/Group_FN/iSTAGING_Volume/gFN_17_iSTAGING_Volume.mat).
More precomputed gFNs will come in future release.
Personalized FN modeling methods will enhance the functional homogeneity (ex. average functional connectivity with each network) with functional networks, suggesting better functional representation.
pNet generates a file report for the examination about the one-to-one match between gFNs and pFNs, with another figure about the spatial correspondence.
pNet generates a HTML-based report to check gFNs, all pFNs with hyperlinks, and quality control.
It is recommended to run pNet with CPU at least 4 cores, memory (RAM) at least 16GB, and free disk storage at least 10GB. Large dataset and parallel computation will require more CPU cores, memory space, and disk space. CPU and memory inf, as well as estimated memory usage can be found in the parallel section.The pNet UI requires screen displaying resolution at least 1280x960. It is recommended to use an external montior with reosolution at least 1920x1080. 2k and 4k displays are desirable.
We provided results of three examples for users to learn how to run the pFN computation, and navigate through the precomputed results. For each example, we provided examples of simulated fMRI data, and precomputed results of real fMRI data. Examples can be accessed on Google Drive: https://drive.google.com/drive/folders/1xkCy-0WqYvPA9ooq8txTdc0GsGC-YXMq?usp=share_link.
- HCP surface data. (2 subject, 2 scans per subject, 400 volumes per scan) in .mat format. Precomputed results of 10 subject data are stored in subfolder "Test_FN17".
- PNC surface data (2 subject, 1 scan per subject, 300 volumes per scan) in .mgh format. Precomputed results of 10 subject data are stored in subfolder "Test_FN17".
- UKBB volume data (2 subject, 1 scan per subject, 200 volumes per scan) in .nii.gz format. Precomputed results of 10 subject data are stored in subfolder "Test_FN17".
The data organization is as below.
[1] Li H, Satterthwaite TD, Fan Y (2017). Large-scale sparse functional networks from resting state fMRI. Neuroimage 156:1-13.
[2] Cui Z, et al (2020). Individual variation in functional topography of association networks in youth. Neuron, 106(2), 340-353.
[3] Du Y, Fan Y (2013). Group information guided ICA for fMRI data analysis.
[4] Cui Z, et al (2022). Linking Individual Differences in Personalized Functional Network Topography to Psychopathology in Youth. Biological Psychiatry.
[5] Shanmugan S, et al (2022). Sex differences in the functional topography of association networks in youth. Proceedings of the National Academy of Sciences, 119(33), e2110416119.
[6] Zhou Z, et al (2023). Multiscale functional connectivity patterns of the aging brain learned from harmonized rsfMRI data of the multi-cohort iSTAGING study. NeuroImage, 269, 119911.