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.
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
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 runclearlung --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, runcleargui -p PORTNUMBER
(deafult is 8000). After running the command, navigate tolocalhost: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
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
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.