Perelman School of Medicine at the University of Pennsylvania

Section for Biomedical Image Analysis (SBIA)

SCPLearn: Identification of Sparse Connectivity Patterns in rsfMRI


This software is used to calculate Sparse Connectivity Patterns (SCPs) from resting state fMRI connectivity data. SCPs consist of those regions whose between-region connectivity co-varies across subjects.

This algorithm was developed as a complementary approach to existing network identification methods.

SCPLearn has the following advantages:

  • Does not require thresholding of correlation matrices
  • Allows for both positive and negative correlations
  • Does not constrain the SCPs to have spatial/temporal orthogonality/independence
  • Provides group-common SCPs and subject-specific measures of average correlation within each SCP
  • Can be run within a hierarchical framework to get "primary" (large spatial extent) and "secondary" level (small spatial extent) SCPs

This user-friendly software takes as input either NIFTI format files or MATLAB mat files with time-series data. It returns a set of SCPs, also in NIFTI format, and subject-specific SCP coefficients saved in a csv file. Subject-level coefficients can be used for subsequent group-level analysis.

The following figure shows a result from SCPLearn applied to aging data acquired as a part of the Baltimore Longitudinal study of Aging (BLSA). Some of the SCPs were found to have strong aging-related effects.

 

Please cite [NeuroImage2014] when you used SCPLearn in your research

Download

Software License

SCPLearn software is freely available under a BSD-style open source license that is compatible with the Open Source Definition by The Open Source Initiative and contains no restrictions on use of the software. The full license text is included with the distribution package and available online.

 

To Download visit our NITRC page for SCPLearn

Close


Documentation

1. INTRODUCTION

This software generates Sparse Connectivity Patterns from resting state fmri connectivity data. It applies sparse matrix decomposition to rsfMRI connectivity matrices to obtain group-common Sparse Connectivity Patterns (SCPs) and subject-specific SCP coefficients. SCP coefficients encode the total connectivity of a pattern within a subject. Each SCP can be further sub-divided into smaller SCPs, along with their associated subject level coefficients.

For details see the following paper: http://www.sciencedirect.com/science/article/pii/S1053811914008003

2. SOFTWARE

This software has been tested on Linux operating systems only. It is implemeted primarily in MATLAB. For command-line argument parsing, and nifti I/O operations, python code is used.

3. INSTALL

3.1 Dependencies
  • MATLAB Compiler mcc version 5.2 (R2014B)
  • MATLAB R2014B
  • Python 2.7.9
  • Python library numpy 1.7.2
  • Python library scipy 0.15.1
  • Python library pandas 0.16.2
  • Python library nibabel 2.0.1

Make sure all dependencies are met before proceeding with install.

3.2 Generating standalone executables

1) Within the src/ directory, run makeAll.py with the location of the install directory as the argument:

makeAll.py <installDir>

2) Add the install directory to your path by running the following command.

Replace ${installDir} with the location of the install directory from step 1 above.

export PATH=${PATH}:${installDir}
3.3 Generating documentation

Run "doxygen Doxyfile" from the parent directory. The documentation is built in "docs/*". Open "docs/html/index.html" in your favorite browser to begin.

4. TEST

To test the software, we have provided synthetic nifti as well as mat data for ten 'subjects'. These are located in src/test.

To run the software on the synthetic data, run any of the following the following command from the src/ folder

SCPLearn.py -d test/nifti_list.txt -p test_2d -m test/test_2d_mask.nii.gz -o test/ -n 3 -s 10

or

SCPLearn.py -d test/mat_list.txt -p test_2d -m test/test_2d_mask.nii.gz -o test/ -n 3 -s 10

This command should return three SCPs, saved as nifti files in src/test/test_2d_SCP_{1,2,3}.nii.gz along with other output.

By design, three patterns were used as 'ground-truth' SCPs to generate the synthetic data; a cross, a circle and a square.Was SCPLearn able to clearly separate these three patterns in the output? You can compare your result to the results in src/test/Test_2d_all.png

5. Usage

Usage: SCPLearn.py [OPTIONS]

Required Options:
[-d --data]    Specify the text file with list of nifti files (required)              
               *** OR ***                
               Specify the text file with list of mat files (required)               
               Each mat file must contain a variable named 'ts'               
               'ts' must be a matrix of time-series, size (# of ROIs X # of timepoints)

[-m --mask]    Specify the nifti ROI/parcel/atlas file (required)
[-p --prefix]      Specify the prefix of the output file  (required)

Options:
[-t --type]   Specify the data type of input with either "matlab" or "nii".
[-s --sparsity]   Specify the sparsity constraint as positive value. Default = nROIs/8
[-n --numberOfSCPs]   Specify the number of SCPs as a number. Default = 10.    
[-r --pruning]   Specify the pruning threshold as a value between [0,1]. Default = 0.7.    
[-l --levels]   Hierarchical learning of SCPs. Not run by default.

[-o --outputDir]       The output directory to write the results. Defaults to the location of the input file
[-w --workingDir]      Specify a working directory. By default a tmp dir is created and used
[-u --usage | -h --help]    Display this message
[-v --verbose]              Verbose output
[-V --Version]              Display version information

Example:
SCPLearn.py -d list_of_nifti_files.txt -t nii -m Grasp_level5.nii -p SCP_results -n 10 -s 50 -o /sbia/sbiaprj/BLSA 
-vSCPLearn.py -d list_of_mat_files.txt -m Grasp_level5.nii -p SCP_results -n 10 -r 0.5 -o /sbia/sbiaprj/BLSA -v
SCPLearn.py -d list_of_mat_files.txt -t matlab -m Grasp_level5.nii -p SCP_results -l -n 10 -o /sbia/sbiaprj/BLSA -v

Example list_of_nifti_files.txt without sample weights:
ProjName_subj_165464.nii.gz
ProjName_subj_26464.nii.gz
ProjName_subj_1054.nii.gz......

Example list_of_nifti_files.txt with sample weights:
ProjName_subj_165464.nii.gz,172
ProjName_subj_26464.nii.gz,160
ProjName_subj_1054.nii.gz,120......    

SCPLearn software takes as input a text file with the list of nifti/mat files. If input is nifti, each nifti file must be pre-processed rsfMRI 4D scan in a common template/standard space. If input is mat files, each mat file must contain a variable named 'ts'. 'ts' must be a matrix of time-series, size (# of ROIs X # of timepoints) It also requires the "node" definitions (e.g. atlas, parcellation, ROI definition, etc) to be input as a nifti file. The node definitions need to be in the same template space as the other nifti files.

Optional arguments are:

  • Number of SCPs at the primary level. Default = 10.
  • Sparsity level of SCPs. Default = Number of ROIs / 8.
  • Pruning threshold. Default = 0.7. SCPs with inner-product overlap greater than this threshold are discarded
  • Hierarchical decomposition? Default: Not used.

In the output directory, the software returns:

  • One NIFTI file for each SCP that is generated, with file name <prefix>_SCP_#.nii.gz
  • A <prefix>_SCP_Coeffs.csv file with the SCP coefficients for all the subjects, indexed by the NIFTI filename that was input
  • A <prefix>_SCP_basis.csv file with the SCP basis, in csv format
  • A <prefix>_SCPs.mat file with all the outputs in MATLAB '.mat' format
  • A <prefix>_ts.mat file with the average time-series from all the subjects in MATLAB '.mat' format
  • A <subject>_<atlas>.mat file with the average time-series for each subject

6. LICENSING

See License 

Close


Changelog

Version 1.0.0 (September, 2015)
  • First public release of the SCPLearn software.

Close


People

Advisor
  • Christos Davatzikos
Software Authors
  • Harini Eavani
    • Developed the algorithm, implemented the software.

Close


Publications

[NeuroImage2014]: Eavani, H., Satterthwaite, T. D., Filipovych, R., Gur, R. E., Gur, R. C., & Davatzikos, C. (2015). Identifying Sparse Connectivity Patterns in the brain using resting-state fMRI. Neuroimage, 105, 286-299.

Close