Pipeline for Analyzing Lesions after Stroke (PALS)

Current Version: 2.0.1 (Last updated 11/18/2024)

What is PALS?
1. Pipeline Overview
Installation
1. Dependencies
2. PALS Installation
Expected Data Structure
Usage
Configuration Options
Outputs
Quality Checking Data
Planned Developments
Citing PALS

What is PALS?<a name=intro></a>

PALS is a flexible, scalable toolbox to facilitate image processing and analysis for subjects with stroke lesions. The pipeline requires two inputs: a T1-weighted MRI image and a stroke segmentation mask.

For additional information about the original implementation, please see the publication in Frontier in Neuroinformatics.

Pipeline Overview

The PALS pipeline consists of six modules.

Reorientation to MNI Standard (via FSL fslreorient2std)
Intensity Inhomogeneity Correction (via ANTs N4BiasFieldCorrection)
Brain Extraction (via FSL BET)
Registration to MNI Template (via FSL FLIRT)
Lesion load calculation
Quality check of processing outputs

Installation

Installing the PALS code requires roughly 23.4 MB of space, exclusive of dependencies.

Dependencies

PALS requires the ANTs and FSL neuroimaging packages to run in entirety. If not already installed, please follow the links below to find instructions to install each package:

ANTs
FSL

Be sure to add each to your PATH variable in the command line.

PALS also uses Python to run the pipeline. PALS was developed and tested on Python 3.8 and 3.10, but should be compatible with any Python version after 3.8. If you do not already have Python installed, we link to the official distribution to install Python.

We recommend that you also install the Python virtual environment manager Virtualenv.

PALS Installation

<a name=venv></a>Create a virtual environment in your workspace for PALS with python -m venv pals_venv and activate the environment with source pals_venv/bin/activate. You can deactivate the environment by typing deactivate in the command line when not using PALS. You will need to activate the environment every time before use.
Navigate to a folder of your choice on your computer, then clone the PALS repository to your computer: git clone https://github.com/npnl/PALS
Navigate into the PALS folder: cd PALS
Install the Python package dependencies: python -m pip install -r requirements.txt

Expected Data Structure<a name=datastructure></a>

PALS is designed to have outputs saved to a BIDS derivatives folder. While PALS generates outputs in BIDS-compatible format, it does not require inputs to be in BIDS-compatible structure.

However, we do recommend adhering to the BIDS structure as much as possible by specifying SESSION_ID to the BIDS format of sub-[SUBJECT]_ses-[SESSION].

Usage

PALS is currently developed to run only in the command line. There are two ways to run PALS: (1) using command line inputs, or (2) using a config (short for configuration) JSON file.

Please note that a full run of the PALS pipeline requires at least 2GB of RAM (ideal is 8GB of RAM), and roughly 65 MB of storage.

The following sections describe how to run PALS using each method.

Before First Use

Navigate to the PALS repository, and open the presets.json in a text editor.
The JSON file should look like this initially:

{
    "ants_path" : "",
    "fsl_path" : "",
    "rois_path" : "",
    "template_directory" : ""
}

For each key, be sure to fill the value according to the following instructions:

ants_path : This variable sets the path to your ANTs binaries. In your terminal, type which N4BiasFieldCorrection and copy the path to this key's value. Remove "/N4BiasFieldCorrection" to ensure the path is set to the ANTs binaries folder.
fsl_path : This variable sets the path to your FSL binaries. In your terminal, type which flirt and copy the path to this key's value. Remove "/flirt" to ensure the path is set to the FSL binaries folder.
rois_path : This variable sets the path to the ROIs used to determine lesion load. The PALS repository includes a standard set for your convenience. This key's value should be [path/to/PALS]/ROIs.
template_directory : This variable sets the path to the MNI templates used to register the T1 images. The PALS repository includes this for your convenience. This key's value should be [path/to/PALS]/templates.

Save the presets.json file with the filled values.

Running Using Command Line Inputs<a name=cli-inputs></a>

Running PALS using the command line inputs is the simplest way to run the pipeline on a single scan. Running PALS this way will use the default configuration.

The required inputs are: (1) the scan identifier (we refer to this as SESSION_ID); (2) the path to the T1 image; (3) the path to the lesion mask; and (4) the output directory to save the results.

Activate the PALS virtual environment. Navigate to the PALS repository. To run PALS, type the following (replacing the values in square brackets with your actual values):

python run_pals.py -s [SESSION_ID] -i [PATH_TO_IMAGE] -l [PATH_TO_LESIONMASK] -o [OUTPUT_DIRECTORY]
Once PALS is run, the outputs will be saved. Information about the outputs can be found in the outputs section.

Running Using Configuration File<a name=config-inputs></a>

Running PALS with a config (short for configuration) JSON file offers greater flexibility in processing data. It allows you to customize the pipeline to suit your preferences and enables programmatic generation of JSON files, reducing the need for manual input.

Using a text editor or other means, generate a config file and save as a json file. A sample is provided in the PALS repository (called config.json) and below for your reference, with default values prefilled. Information about the config options can be found in the config section.

{
    "session_id" : "",
    "im_path" : "",
    "les_path" : "",
    "out_dir" : "",
    "run" : "all",
    "space" : "orig",
    "ants_path" : "",
    "fsl_path" : "",
    "rois_path" : "",
    "template_directory" : "",
    "out_format" : "csv",
    "reg_method" : "fsl",
    "reg_costfn" : "corratio",
    "reg_partmask" : false,
    "reg_nomask" : false,
    "bet_g" : -0.25,
    "gif_duration" : 0.5
}

Activate the PALS virtual environment. Navigate to the PALS repository. To run PALS, type the following (replacing the values in square brackets with your actual values):

python run_pals.py -c [PATH_TO_CONFIG]
Once PALS is run, the outputs will be saved. Information about the outputs can be found in the outputs section.

Running Multiple Configuration Files<a name=multiple-configs></a>

The PALS script can be set to run multiple config files in serial. There are two ways to do this:

Input multiple config file paths after the -c flag. The command would then be:

python run_pals.py -c [PATH_TO_CONFIG_1] [PATH_TO_CONFIG_2] ... [PATH_TO_CONFIG_N]
Input the path to a text file that has each config path on its own line. The command would then be:

python run_pals.py -f [PATH_TO_TXT_FILE]

Configuration Options<a name=config></a>

PALS offers flexibility to run the pipeline to your specification using the config (short for configuration) file. The config options are described below:

session_id: The identifier for the scan. We recommend following the BIDS format of sub-[SUBJECT]_ses-[SESSION].
im_path: The path to the image file corresponding to the T1 weighted MRI. Note that it must be in nifti format.
les_path: The path to the lesion segmentation mask file. Note that it must be in nifti format.
out_dir: The path to the output directory to save the PALS outputs. Note that a folder called PALS will be generated within this output directory. See the output section for more details.
run: Specifies which processing steps to execute. QC images are generated in all cases. For options other than all, the process will skip any steps that have already been completed, and begin at the specified step.
- all: Runs all steps, overwriting any previous outputs and results.
- bet: Starts from the brain extraction step, overwriting all subsequent outputs and results.
- mnireg: Starts from the registration to the MNI template step, overwriting all subsequent outputs and results.
- coreg: Starts from the lesion coregistration step, overwriting all subsequent outputs and results.
- pals: Starts from the lesion load calculation step, overwriting all subsequent outputs and results.
- skipdone: Starts from the first step that has not yet been completed, skipping any steps that are already finished.
space: The space the image and mask are in. Default should be orig for images that are unprocessed and/or are in native space. If images are already registered to MNI template, mni is an acceptable option to skip all image processing steps and only obtain PALS output.
ants_path: The path to the ANTs binaries folder. See [Before First Use](#before-first-use

PALS

Install / Use

README