radxtools / topology-radiomics

Python implementation of topology descriptors which capture subtle sharpness and curvature differences along the surface of diseased pathologies on imaging.

Overview

Topology descriptors are designed to capture subtle sharpness and curvature differences along the surface of diseased pathologies on imaging.

These are based on the hypothesis that local structural changes through infiltration and disruption of disease in a region is likely to cause shape irregularities and in turn, resulting in changes along the surface of the lesion.

References

If you make use of this implementation, please cite the following paper:

Ismail, M., Hill, V., Statsevych, V., Huang, R., Prasanna, P., Correa, R., Singh, G., Bera, K., Beig, N., Thawani, R. Madabhushi, A., Aahluwalia, M, and Tiwari, P., "Shape features of the lesion habitat to differentiate brain tumor progression from pseudoprogression on routine multiparametric MRI: a multisite study". American Journal of Neuroradiology, 2018, 39(12), pp.2187-2193.

Getting started with topology radiomics

Installing using pip

You can find our package on pypi

Run the below command to install the package:

pip install topology_radiomics

Running with docker

First clone this repository

git clone https://github.com/radxtools/topology-radiomics.git

There are multiple ways to get started.

1. docker-compose
2. docker run

docker-compose

Run the following commands to start the docker container

cd docker
docker-compose up

docker run

With this step, you don't need to clone the url. Run the following commands to start the docker container

docker rm radxtools/topology-radiomics-examples
docker pull radxtools/topology-radiomics-examples
docker run -d -p 3000:3000 --name topology-radiomics-examples radxtools/topology-radiomics-examples

Tutorials

Once the docker image is up and running. You can view our notebooks. You can get started with the notebook to learn how to use the package. You should start with Tutorial - Getting started with topology_radiomics.ipynb

Tutorial Notebooks:

1. Tutorial - Getting started with topoplogy_radiomics.ipynb
2. Tutorial - Using topology_radiomics to visualize features.ipynb
3. Tutorial - Working with medpy and topology_radiomics.ipynb

The notebooks can be viewed by opening the browser and visting the url http://localhost:3000

Note: topology_radiomics clips outliers a per lesion basis. See the tutorials for more information.

Contribution Guide:

Please follow google style formatting for docstrings

Bugs and Feature Request

Please submit bugs and features to our github page.

Pull Requests

Create a issue on our board. Create a pull request with your changes. Tag your changes with the issue number (commit message should have issue number). Someone from the team will review your request and merge your changes for the next release.

Characteristics of Curvature

The topology of surfaces in imaging can be quantified with gaussian curvature and mean curvature. The following 4 surface measures are derived from the gaussian and mean curvatures:

• Curvedness
• Shape Index
• Sharpness
• Total Curvature

The figure below highlights characteristics of the gaussian and mean curvatures, as well as some of the surface measures.

This figure was adapted from:

Tsagkrasoulis, Dimosthenis & Hysi, Pirro & Spector, Tim & Montana, Giovanni. (2016). Heritability maps of human face morphology through large-scale automated three-dimensional phenotyping. Scientific Reports. 7. 10.1038/srep45885.

topology-radiomics's Issues

Read the docs

• Sign up for RTD
• Setup python code to generate docs while building the package
• Setup automated pipeline github actions

Imaging Format Compatibility

Currently, the Topology Radiomics packages only supports nifty (.nii) images via nibabel.

Sometimes, the labs use the .mha or .mhd imaging formats. Could you please add SimpleITK and/or NumPy support in the compute_morphology_features function to expand imaging format compatibility?

SimpleITK example:

volume = sitk.ReadImage("/path/to/volume.mha") # vol type is SimpleITK.SimpleITK.Image
features = rad.compute_morphology_features(volume, config)

NumPy Array from SimpleITK example:

volume = sitk.ReadImage("/path/to/volume.mha")
volume_np = sitk.GetArrayFromImage(volume) # vol_np type is numpy.ndarray
features = rad.compute_morphology_features(volume_np, config)

To pass a NumPy array from SimpleITK into the compute_morphology_features function, I made the following change:

def compute_morphology_features(mri_mask_voxels: BinaryVoxelMask,
                                config: MorphologyConfig = MorphologyConfig()) -> MorphologyFeatures:
    #mask = mri_mask_voxels.mri_voxel_mask # commented this line out because NumPy array does not have this object
    mask = mri_mask_voxels

Minimum notebooks

Base Package and functionality

• pyvista for mesh
• scipy for marching cubes
• numpy for general data handling

Pypi Integration

• Setup credentials on testpypi
• Setup credentials on pypi
• Copy credentials for test to github workflow env variables
• Copy credentials for prod to github workflow env variables
• Setup github workflow for upload to test in dev branch
• Setup github workflow for upload to prod in master branch

* Jupter notebook tutorials

• loading data is babel
• loading data is pymed
• explaing surface measures with plotly visualizations

Readme files

• rename references for bric/invent lab repos

• github url
• docker url
• setup.py file

New Feature - Sanitization

The merge labels function should be rewritten such that 0 is empty space. All other integers are labels.

0 - should be background, not min value

default behavior:
merge all other labels

Image for Documentation

Could you please add the following image to the documentation? It provides a really nice visualization of what curvature features look like.

You can find the image here.

New Feature - outliers

Python setup.py to package morphology features

Input santization

New Feature - Gaussian Filter config values

• Sigma value in the config object should be given in millimeters.
• Notes:
• This would make it slightly more complicated as we would need to know the x,y,z length of a voxel.
• Most MRI pictures have x and y of the same length, but the z length is normally smaller. (x == y, x > z, y > z). This is due the way the scans are taken.

Adjustment to Documentation

In the documentation, could you please add a note indicating outliers are clipped on a per lesion basis? This would notify users to adjust their code accordingly.

Clipping outliers on a per lesion basis does not need to be changed. Based on conversations with the lab, this behavior is ok and is needed for viewing the meshes.

Please let me know if you need any additional information.

Thank you!

"pip install topology_radiomics" not working

Operating system - Mac OS
Python- 3.7

Support Python 3.6 for Slicer Extension

rename package to topology_radiomics

Docker Image

• Neshdev repo
• bric/invent lab repo