PyALFE
Python implementation of Automated Lesion and Feature Extraction (ALFE) pipeline.
Requirements
PyALFE supports Linux x86-64, Mac x86-64, and Mac arm64 and requires python 3.9+.
Image registration and processing
PyALFE can be configured to use either Greedy or AntsPy registration tools. Similarly, PyALFE can can be configured to use Convert3D or python native library Nilearn for image processing tasks. To use Greedy and Convert3d, these command line tools should be downloaded using the download command.
Installation
Clone the repo
git clone git@git.ucsf.edu:rauschecker-sugrue-labs/pyalfe.git
cd pyalfe
Then run (we recommend using a python virtual environment)
pip install --upgrade pip
You can either instal pyalfe in development mode or build and install.
Option 1: Development mode installation
First update the setuptools
pip install --upgrade setuptools
Run the following command in the parent pyalfe directory:
pip install -e .
Option 2: Build and install
First update the build tool
pip install --upgrade build
Run the following commands in the parent pyalfe directory to build the whl file and install pyalfe
python -m build
pip install dist/pyalfe-0.0.1-py3-none-any.whl
Download models
To download deep learning models, run
pyalfe download models
Pyradiomics support
To install pyalfe with pyradiomics support, run
pip install -e '.[radiomics]'
for development installation or
pip install 'dist/pyalfe-0.0.1-py3-none-any.whl[radiomics]'
when performing a build and install.
Usage
Configuration
To configrue the PyALFE pipeline you should run:
pyalfe configure
which prompt the you to enter the following required configurations:
Classified directory
Enter input image directory: /path/to/my_mri_data
The classified directory (classified_dir
) is the input directory to PyALFE and should be organized by accessions (or session ids). Inside the directory for each accession there should be a directory for each available modality.
Here is an example that follow ALFE default structure:
my_mri_data
│
│───anat
│ │───sub-123_T1w.nii.gz
│ │───sub-123_T2w.nii.gz
│ └───sub-123_FLAIR.nii.gz
│───dwi
│ │───sub-123_dwi.nii.gz
│ └───sub-123_md.nii.gz
│───swi
│ └───sub-123_swi.nii.gz
└───perf
└───sub-123_cbf.nii.gz
To use this directory the user should provide path/to/my_mri_data
as the classified directory. This config value can be overwritten when calling pyalfe run
via -cd
or --classified-dir
option.
pyALFE also supports BIDS directories. Here is an example of input dir organized in BIDS format:
my_mri_data
│
│───12345
│ │
│ │───T1
│ │ └── T1.nii.gz
│ │───T1Post
│ │ └── T1Post.nii.gz
│ │───FLAIR
│ │ └── FLAIR.nii.gz
│ │───ADC
│ │ └── ADC.nii.gz
│ └───T2
│ └── T2.nii.gz
│
└───12356
. │
. │───T1
. │ └── T1.nii.gz
│───T1Post
│ └── T1Post.nii.gz
│───FLAIR
│ └── FLAIR.nii.gz
│───ADC
│ └── ADC.nii.gz
└───T2
└── T2.nii.gz
Processed directory
Enter input image directory: /path/to/processed_data_dir
The processed image directory (processed_dir
) is where ALFE writes all its output to.
It can be any valid path in filesystem that user have write access to.
This config value can be overwritten when calling pyalfe run
via -pd
or --processed-dir
option.
Modalities
Enter modalities separated by comma [T1,T1Post,FLAIR,T2,ADC]: T1,T1Post,ADC
All the modalities that should be processed by ALFE.
Modalities should be separated by comma.
To use the default value of T1,T1Post,T2,FLAIR,ADC
, simply press enter.
This config value can be overwritten when calling pyalfe run
via -m
or --modalities
option.
Target modalities
Enter target modalities separated by comma [T1Post,FLAIR]:
The target modalities are used to define the abnormalities which are then used to extract features.
Currently, only T1Post
, FLAIR
, or both (default) can be target modality.
This config value can be overwritten when calling pyalfe run
via -t
or --targets
option.
Dominant Tissue
Enter the dominant tissue for the lesions (white_matter, gray_matter, auto) [white_matter]:
The dominant tissue where the tumor or lesion is expected to be located at.
This information is use in relative signal feature calculations.
If you choose auto
, pyalfe automatically detect the dominant tissue after segmentation.
This config value can be overwritten when calling pyalfe run
via -dt
or --dominant_tissue
option.
Image processor
image processor to use (c3d, nilearn) [c3d]:
Currently, pyalfe can be configures to use either Convert3D (a.k.a. c3d) or Nilearn for image processing tasks.
The default is Convert3d aka c3d. In other to use c3d,
you have to download it using the download command.
To use Nilearn, you do not need to run any extra command since it is already installed when you install pyalfe.
This config value can be overwritten when calling pyalfe run
via -ip
or --image_processing
option.
Image Registration
image registration to use (greedy, ants) [greedy]:
Currently, pyalfe can be configures to use either greedy or ants for image registration tasks. The default is greedy.
In other to use greedy, you have to download it using the download command. To use ants,
install pyalfe with ants support pip install pyalfe[ants]
.
This config value can be overwritten when calling pyalfe run
via -ir
or --image-registration
option.
Running the pipeline
To run PyALFE for an accession
pyalfe run ACCESSION
If you chose to save the configuration file in a non-standard location you can run
pyalfe run -c path/to/config.ini ACCESSION
In general, all the config option can be overwritten by command line options. To see a list of command line options, run:
pyalfe run --help
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
License
BSD 3-Clause