Spherical harmonics (SPHARM) decomposition of tumors on 3D medical imaging in Python.
When using this code, you must cite in your own code and publications the following article:
Lefebvre TL et al. (2023) Predicting histopathology markers of endometrial carcinoma with a quantitative image analysis approach based on spherical harmonics in multiparametric MRI. Diagnostic and Interventional Imaging 104(3):142-152. https://doi.org/10.1016/j.diii.2022.10.007
DEPENDENCIES
This code has five major dependencies.
-
MATLAB R2017b or later with the Image Processing Toolbox installed
-
The NFSFT library part of the NFFT package: https://www-user.tu-chemnitz.de/~potts/nfft/download.php
After downloading and unzipping the NFFT package, you will need to add in your code the path to the NFSFT subfolder - see demo_SPHARM.ipynb for an example.
-
The TensorReg Matlab toolbox: https://hua-zhou.github.io/TensorReg/
-
The SparseReg Matlab toolbox: http://hua-zhou.github.io/SparseReg/
-
The Tensor Matlab toolbox: https://github.com/andrewssobral/tensor_toolbox
In addition, the following python packages are required: numpy, scipy, pandas, as well as matlab.engine :
https://pypi.org/project/matlabengine/
https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html
INPUT STRUCTURE AND ASSUMPTIONS
It is assumed that:
- Your input images are in nifti format (.nii or .nii.gz)
- Each patient has a unique ID
- An image from patient with unique ID <patient_id> will be stored in file named <patient_id>.nii or <patient_id>.nii.gz
- The images from a single modality/contrast from all patients are are saved in a single folder whose path is specified in variable 'mypathimg' in file demo_SPHARM.ipynb
- Each image file has a corresponding segmentation file with the same name, and all segmentation files from all patients are stored in a single folder specified by variable 'mypathseg' in file demo_SPHARM.ipynb.
- This segmentation captures a single connected structure (tumor). It may contain holes.
- The segmentation is a 3D binary mask where each voxel inside the tumor is labeled 1, and other voxels are labeled 0. The segmentation is not a DICOM-RT contour.
- The folder with segmentations must not be the same folder where images are stored.
- Both image and segmentation folders must not contain nifti files that do not pertain to this analysis, since all nifti files in these folders will be loaded.
- A csv file is provided to specify the label for each patient_id. Specifically, is assumed that this csv file has 2 columns called 'ID' and 'Label' Each row lists one patient ID, which must be the same ID as in the corresponding filenames, as well as a binary 0/1 label for that patient to represent the desired outcome.
For instance, here is an example input file structure:
ImagesContrast1/PatientID1.nii.gz
PatientID2.nii.gz
PatientID3.nii.gz
SegmentationsForImageContrast1/PatientID1.nii.gz
PatientID2.nii.gz
PatientID3.nii.gz
Here is an example csv label file with patient IDs matching the above filenames:
ID, Label
PatientID1, 0
PatientID2, 1
PatientID3, 0
..., ...
USAGE
Notebook demo_SPHARM.ipynb computes SPHARM matrices for each patient. Notebook demo_tensorReg.ipynb takes these SPHARM matrices, applies the TensorReg methodology and outputs the tensorReg classification matrix as well as classification probabilities for each patient.
This process is done for a single imaging contrast at a time. In the paper by Lefebvre et al (2023) cited above, we combine these outputs obtained from multiple contrasts with an ordinary logistic regression in order to obtain a final multi-contrast classification. We don't provide code for this final multi-contrast step, but that can easily be implemented with Scikit-Learn's logistic regression classifier: https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.LogisticRegression.html
Before running the notebooks, please read the comments in them and please enter the correct path names as requested.