Skip to content

Latest commit

 

History

History
243 lines (207 loc) · 14.6 KB

README.md

File metadata and controls

243 lines (207 loc) · 14.6 KB
Raw

pNet

pNet is a Python package of an algorithm for computing personalized, sparse, non-negative large-scale functional networks from functional magnetic resonance imaging (fMRI) data, facilitating effective characterization of individual variation in functional topography. The personalized functional networks are comparable across subjects while maintaining subject specific variation, reflected by their improved functional coherence compared with their group-level counterparts. The computation of personalized functional networks is accompanied by quality control, with visualization and quantification of their spatial correspondence and functional coherence in reference to their group-level counterparts.

The algorithm has been successfully applied to studies of individual variation in functional topography of association networks in youth, functional network topography of psychopathology in youth, sex differences in the functional topography of association networks in youth, dissociable multi-scale patterns of development in personalized brain networks, multiscale functional connectivity patterns of the aging brain, and personalized functional brain network topography in youth cognition.

pnet_image

Getting started

Follow the Installation Instructions to install pNet, and then check out the APIs and Examples to learn how to get up and running! For visualization issues that might be caused by VTK, please check TrobubleShooting.

Run with a docker image

docker pull mldataanalytics/fmripnet:latest

or

docker pull ghcr.io/mldataanalytics/fmripnet:latest

docker run mldataanalytics/fmripnet -h

Run with a singularity (SingularityCE) image

singularity pull --arch amd64 library://yongfan/collection/fmripnet:latest

singularity run fmripnet_latest.sif -h

Download and install pNet

1. Download pNet

git clone https://github.com/MLDataAnalytics/pNet.git

2. Create a new conda environment for pNet

cd pNet
conda env create --name fmripnet -f environment_pnet.yml

3. Install pNet

conda activate fmripnet
pip install .
# or pip install fmripnet

Script usages

1. Prepare data

  • A number of preprocessed fMRI scans that have been spatially aligned to a template space,
  • A mask image for excluding voxels/vertices of uninterest,
  • A brain template image/surface for visualization.
  • A script can be found in cli folder for preparing the brain template data and precomputed templates are avaiable for data preprocessed with HCP pipelines.
  • Precomputed group FNs are provided in Group_FNs. They can be used to guide the computation of personalized FNs.

2. Example files of scans and configuration

  • An example file with a list of preprocessed fMRI scans:
/cbica/projects/xxx/rfMRI_REST1_LR/rfMRI_REST1_LR_Atlas_MSMAll_hp2000_clean.dtseries.nii
...
/cbica/projects/xxx/rfMRI_REST1_LR/rfMRI_REST1_LR_Atlas_MSMAll_hp2000_clean.dts
eries.nii
  • An example configration file:
# This is a configuration file for computing personalized functional networks (FNs) given a set of preprocessed fMRI data
## input:
#   1. Provide a txt file with a list of preprocesed fMRI scans, one on each line, as Scan_List.txt
#   2. Specifiy a brain template file, provide by pnet or prepared with data provided
#   3. Specify the number of FNs
## output:
#   1. Specify the result folder directory in dir_pnet_result

[necessary_settings]
## Input:
# a txt file with a list of preprocessed fMRI scan file, one on each line
file_scans = "/cbica/home/fanyo/fmripnet/examples/HCP1200_10Surfs.txt"
# a brain template file. A HCP surface based template is set here, prepared by pnet
file_Brain_Template = "/cbica/home/fanyo/.conda/envs/fmripnet/lib/python3.8/site-packages/pnet/Brain_Template/HCP_Surface/Brain_Te
mplate.json.zip"
# the number of FNs to be computed, should be a positive integer number
K = 2
## Output: setup the output folder
dir_pnet_result = "/cbica/home/fanyo/comp_space/pNet/examples/FN2_Surface_hpc"

## specify the method for computing personalized FNs: SR-NMF or GIG-ICA
# for GIG-ICA group level FNs (file_gFN) have to be provided
# and gFN_settings will be ignored
method="SR-NMF"

## date type and format information
# data type is surface
dataType = "Surface"
# data format is HCP surface
dataFormat = "HCP Surface (*.cifti, *.mat)"

[pFN_settings]
## for computing personalized FNs based on given fMRI scans/cbica/home/fanyo/fmripnet/examples
# Specify group level FNs if avialable. If not, the group level FNs will be computed first
file_gFN = "None"

[gFN_settings]
## for computing FNs at a group level by boostrapping the input data
# Setup number of scans loaded for each bootstrap run for estimating gFNs
# a larger number is preferred for robustness, but should be no larger than the avaiable scans
sampleSize = 10  # typical value: 100
# Setup number of runs for bootstraps
# a larger number is preferred for robustness, but with increased computational cost
nBS = 5        #typical value: 50
# a number of time points for computing group FNs with bootstraps
# this is for reducing the computational cost by using a partion of all avaiable time points of each fMRI scan
# for short fMRI scans all available time points should be used for robustness
nTPoints = 300   # all avaiable time points will be used if seting a value larger than the available number of time points

####################################################################################
# the following is ignored if no HPC computation (with sge or slurm) will be used  #
####################################################################################
[hpc_settings]
[hpc_settings.pnet_env]
# specify pnet installation information
dir_pnet="/cbica/home/fanyo/.conda/envs/fmripnet/lib/python3.8/site-packages/pnet"
dir_env="/cbica/home/fanyo/.conda/envs/fmripnet"
dir_python="/cbica/home/fanyo/.conda/envs/fmripnet/bin/python"

# specify pnet
[hpc_settings.submit]
# Setup qsub commands
submit_command = "sbatch --parsable --time=0:50:00" # "qsub -terse -j y"
thread_command = "--ntasks-per-node=" #-pe threaded "
memory_command = "--mem="                   #"-l h_vmem="
log_command = "--output="  #"-o "

[hpc_settings.computation_resource]
# Computation resource request
memory_bootstrap= "100G"
thread_bootstrap= 2
memory_fusion= "10G"
thread_fusion= 4
memory_pFN= "10G"
thread_pFN= 1
memory_qc= "10G"
thread_qc= 1
memory_visualization= "20G"
thread_visualization= 1

3. Run the computation (examples can be found in examples folder)

  • a script (fmripnet.py) can be found in cli folder for running the computation, supplied with a configuration file (*.toml) for setting the input and output information
   run "python fmripnet.py -h " to get help information
   run "python fmripnet.py -c a_config.toml" to start the computation without HPC
   run "python fmripnet.py -c a_config.toml --hpc" to start the computation on a HPC cluster with sge or slurm

Code examples and usages

1. Prepare data

1) a number of preprocessed fMRI scans that have been spatially aligned to a template space,
2) a mask image for excluding voxels/vertices of uninterest,
3) a brain template image/surface for visualization

2. Setup the computation

1) the number of functional networks,
2) the output folder information,
3) optional parameters

3. Example code:

import pnet

# create a txt file of fMRI scans, each line with a fMRI scan 
file_scan = 'sbj_lst.txt'
# create a brain template file consisting of information of the mask image and the brain template for visualization or use a template that is distributed with the package) 
file_Brain_Template = pnet.Brain_Template.file_MNI_vol

# Setup
# data type is volume
dataType = 'Volume'
# data format is NIFTI, which stores a 4D matrix
dataFormat = 'Volume (*.nii, *.nii.gz, *.mat)'
# output folder
dir_pnet_result = 'Test_FN17_Results'

# number of FNs
K = 17

# Setup number of scans loaded for each bootstrap run for estimating group functional networks
sampleSize = 100 # The number should be no larger than the number of available fMRI scans. A larger number of samples can improve the computational robustness but also increase the computational cost.  Recommended: >=100
# Setup number of runs for bootstraps
nBS = 50         # A larger number of run can improve the computational robustness but also increase the computational cost. recommended: >=10
# Setup number of time points for computing group FNs with bootstraps
nTPoints = 200   # The number should be no larger than the number of available time points of the fMRI scans. A larger number of samples can improve the computational robustness but also increase the computational cost.  If not set or larger than the number of available time points (assuming smaller than 9999), all availabe time points will be used.

# Run pnet workflow
pnet.workflow_simple(
        dir_pnet_result=dir_pnet_result,
        dataType=dataType,
        dataFormat=dataFormat,
        file_scan=file_scan,
        file_Brain_Template=file_Brain_Template,
        K=K,
        sampleSize=sampleSize,
        nBS=nBS,
        nTPoints=nTPoints
    )

References

Troubleshooting

vtk-osmesa (off-screen MESA):

If vtk-osmesa (off-screen MESA) cannot be installed with conda (conda install -c conda-forge "vtk>=9.2=osmesa"), please have a try with pip (a solution provided by albertleemon):

pip install --extra-index-url https://wheels.vtk.org vtk-osmesa

Support

If you encounter problems or bugs with pNet, or have questions or improvement suggestions, please feel free to get in touch via the Github issues.

Acknowledgment

This project has been supported in part by NIH grants U24NS130411 and R01EB022573.

Previous versions:

Matlab and Python: https://github.com/MLDataAnalytics/pNet_Matlab

Matlab: https://github.com/MLDataAnalytics/Collaborative_Brain_Decomposition

GIG-ICA: https://www.nitrc.org/projects/gig-ica/