qianshuqinghan/pals

Pipeline for Analyzing Lesions after Stroke (PALS)

Pipeline for Analyzing Lesions after Stroke (PALS)

Welcome to our github page!

What is PALS?

PALS is a scalable and user-friendly toolbox designed to facilitate standardized analysis and ensure quality in stroke research using T1-weighted MRIs. The PALS toolbox offers four moduels integrated into a single pipeline, including (1) reorientation to radiological convention, (2) lesion correction for healthy white matter voxels, (3) lesion load calculation, and (4) visual quality control.

Getting Started

There are two ways to use PALS: in a Docker Container or in a Manually Prepared Environment.

Docker Container

In order to run PALS in a Docker container, Docker must be installed. Once Docker is installed, follow the instructions here to prepare your local machine for running the PALS GUI.

Manually Prepared Environment

Prerequisites

• Linux or Mac OS
• Python 2.7
• pip
• FSL
  • If using a version of FSL older than 5.0.10, separate installion of FSLeyes is necessary.
• FreeSurfer

First-time users may be asked to specify a directory path to FSL and/or FreeSurfer binaries (see instructions for FSL and FreeSurfer setup).

Installing

Clone this github repository:

git clone https://github.com/npnl/PALS.git

Install python-tk

sudo apt-get install python-tk

Install python dependencies

cd PALS
pip install -r requirements.txt

---

Run

Open up your terminal and navigate to the directory containing PALS source code.

cd /PATH/TO/PALS
python2.7 run_pals.py

This will open up the PALS GUI.

To use PALS, the user must first use a method of their choice to generate initial lesion masks for their dataset.

Data Structure

Inputs

Required:
PALS requires the user to provide an Input Directory with separate Subject Directories containing:

• Subject's T1-weighted anatomical image file (nifti)
• Subject's lesion mask file (nifti)

Optional:

• Subject's skull-stripped brain file (nifti)
• Subject's white matter segmentation file (nifti)
• Subject's FreeSurfer T1 file (T1.mgz)
• Subject's FreeSurfer cortical/subcortical parcellation file (aparc+aseg.mgz)

Outputs

PALS output files and directories will vary depending on the options selected (e.g., QC_BrainExtractions for the brain extraction step.)

QC Directories
A new quality control directory will be created for each intermediary step taken. Each QC directory will contain screenshots for each subject, and a single HTML page for easy visual quality inspection.

Subject Directories
A separate directory will be created for each subject, each of which will contain a Intermediate_Files subdirectory.

• Intermediate_Files will store all outputs from intermediary processing steps. Intermediate_Files will also contain a subdirectory called Original_Files.

• Original_Files will contain a copy of all input files for that subject.

outputs from reorient module:

subjX_T1_rad_reorient.nii.gz - subject's original T1 brain file in radiological convention
subjX_lesion1_rad_reorient.nii.gz - subject's original lesion mask in radiological convention

outputs from lesion correction module:

subjX_WMAdjusted_lesion1.nii.gz - subject's corrected lesion mask with white matter voxels removed

outputs from lesion load module:

subjX_Reg_Brain_MNI.152.nii.gz - subject's brain registered to MNI space
subjX_Reg_Brain_custom.152.nii.gz - subject's brain registered to user-input template space
subjX_T12FS.nii.gz - subject's brain registered to FreeSurfer space
subjX_lesion1_MNI152_bin.nii.gz - subject's first lesion mask registered to MNI space
subjX_lesion1_custom_bin.nii.gz - subject's first lesion mask registered to user-input template space
subjX_lesion1_FS_bin.nii.gz - subject's first lesion mask registered to FreeSurfer space
subjX_roi_name_lesion1_overlap.nii.gz - subject's lesion-ROI overlap file (one for each ROI)

Databases: For the lesion correction and lesion load calculation modules, separate CSV files will be created, containing information for all subjects about number of voxels removed and amount of lesion-roi overlap, respectively.

---

Troubleshooting

Problem 1.

On Mac OS X, Nipype.workflow fails with the error : ValueError: unknown locale: UTF-8.

Solution.

If you are facing the above mentioned error on MacOS X, here's the quick fix - add these lines to your ~/.bash_profile or simply execute then in your terminal from where you are running the PALS software.:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

Problem 2.

Pip fails with the error Could not find a version that satisfies the requirement nypipe.

Solution.

Run the following command to upgrade the pip.

1. If you are using Python 2.x curl https://bootstrap.pypa.io/get-pip.py | python
2. If you are using Python 3.x curl https://bootstrap.pypa.io/get-pip.py | python3

---

Support

The best way to keep track of bugs or failures is to open a New Issue on the Github system. You can also contact the author via email: kaoriito at usc dot edu.

---

Authors

• Kaori Ito - Github
• Amit Kumar - Github

License

This project is licensed under the GNU General Public License - see the LICENSE.md file for details