Summary

Welcome to the CLEARLUNG framework! This package provides both clinical and radiomic analysis of lung CT scans. It was developed as a Master Thesis project.

Clinical features and metrics are extracted using techinques described here, while radiomic features are extracted and passed to a pre-trained classifier (reference here) to estimate the probability of COVID-19 versus other viral infections. All of the information is then printed on a PDF report for medical use. The package also provides the possibility to connect to a local PACS node to retrieve exams, and to upload the generated output.

Installation

python 3.8+ is required. First of all, clone the repository using you favourite connection option (SSH or HTTPS), for example

git clone git@github.com:niguardateam/covid-classifier.git

Then install the commands and requirements (possibly in a virtual environment):

cd covid-classifier
sudo pip3 install -e .

Note that the external package dcm2niix must be installed independently. If you are using MacOS, I suggest to download it from Homebrew

brew install dcm2niix

If you are using Linux, you can download it with

sudo apt-get install -y dcm2niix

Usage

The CLEARLUNG package provides three main commands:

• clearlung is the core package and it is to be ran from the command line. The use of this command is not recommended as it is not easy to fully understand the command line options. However, to get more information just run clearlung --help
• cleargui is a wrapper of the above command, and it provides a web interface on your local browser. If you want to host the application on a specific port, run cleargui -p PORTNUMBER (deafult is 8000). After running the command, navigate to localhost:8000 and use the graphical interface. IMPORTANT: When you are done, remember to shut down the process with CTRL-C (not with CTRL-Z), otherwise you wil have to manually shutdown the port or the port will results as not available.
• clearwatch path/to/folder is only available on Linux. This command constantly monitors the folder passed as input argument. When a new folder is created inside of it, the CLEARLUNG pipeline automatically starts with default parameters.

A help message explaining the commands can be accessed with the command

clearhelp

Loading a model

In the src/covidlib directory, the folder named model is responsible of storing the pre-trained model, together with the list of relevant features for that model. However, using cleargui a different TensorFlow model can be fed into the pipeline. A model directory must contain:

• a model.json containing the architecture description
• a model.h5 containing the weights
• a features.txt containing the model name on the first line, and then on each new line the name of a radiomic feature which is relevant for the model
• a scaler.pkl file containing the scaling coefficients for the features

Other

Contributions are always welcome. Please raise issues if you find any bugs or unexpected behaviour.

Special thanks to Prof. Stefano Carrazza (@scarrazza) for his tireless assistance and counseling in the making of this project.