Skip to content

README.md

Latest commit

 

History

History
101 lines (79 loc) · 4.21 KB

README.md

File metadata and controls

101 lines (79 loc) · 4.21 KB

3Dspharm-decomposition-tumor-python

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.

  1. MATLAB R2017b or later with the Image Processing Toolbox installed

  2. 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.

  3. The TensorReg Matlab toolbox: https://hua-zhou.github.io/TensorReg/

  4. The SparseReg Matlab toolbox: http://hua-zhou.github.io/SparseReg/

  5. 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.