Skip to content
A step-by-step tutorial showing how to deploy a tool based on qmenta-sdk to the QMENTA platform.
Python Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.idea
assets
Description
Dockerfile
README.md
settings.json
tool.py

README.md

QMENTA SDK TOOL TUTORIAL

QMENTA


Introduction

In this repository we will guide you through the process of deploying a tool into the QMENTA platform and then run it.

To get more detailed and technical information about the QMENTA SDK and its capabilities, please refer to it's documentation.

As a case study, we will implement a tool that takes as inputs an oncology medical image and a segmentation mask with one or more labels, and then it uses the Pyradiomics library to extract radiomic features from the data. The tool will allow the user to select which classes of radiomic features wants to compute and also select.

Pyradiomics is an open-source python package for the extraction of Radiomics features from medical imaging. To learn more about the aim of the project and the features of the package take a look to the following publication: van Griethuysenet al. 2017

The deployment of a tool has three principal steps:

  • Write the main script.
  • Build a docker container with the appropriate environment for the tool to run.
  • Add the tool to QMENTA platform.

Step 1: Write the main script

The first step consists of writing the python code that will carry out the desired processing of the input files. In this repository you will find the implemented script in the file named tool.py. The tool is commented in detail so it's easy to follow up.

The script uses methods of the AnalysisContext class from the QMENTA SDK to interact with the platform and perform the following actions:

  • Download the input data to the container using context.get_files()
  • Retrieve the settings defined for the analysis using context.get_settings()
  • Set the progress status to monitor the analysis from the platform using context.set_progress()
  • Upload the result files from the container to the platform using context.upload_file()

Step 2: Build the docker container where the tool will run

To follow through this step two requirements must be fulfilled: have Docker installed (how to) and have a docker registry, we recommend using docker hub for its integration with Docker when uploading images.

In this example we build the docker container using a Dockerfile. The one we used is included in this repository:

# Start from a QMENTA public container containing python 3, qmenta-sdk library and a configured entrypoint.
FROM qmentasdk/minimal:latest

#Copy the tool script to the container.
COPY tool.py /root/tool.py

# Install all the required libraries and tools (in this case only python libraries are needed).
RUN pip install SimpleITK nibabel numpy pandas
RUN python -m pip install pyradiomics 

To build the container, we open a terminal window and run the following commands:

  • Access the folder where the Dockerfile and the tool.py files are stored

    >> cd /path/to/qmenta-sdk-tool-tutorial

  • Build the container from the Dokerfile

    >> docker build -t qmentasdk/radiomics_tool:1.0 .

    Where qmentasdk is the name of the docker namespace, radiomics_tool the name of the repository (tool) and 1.0 the tag (tool version).

  • Login to the docker hub registry

    >> docker login

    This will ask for the username and the password.

  • Save the container in the docker registry

    >> docker push qmentasdk/radiomics_tool:1.0

For more information about working with docker containers in the QMENTA skd documentation.

A list of QMENTA's public docker containers can be found at the qmentasdk docker registry.

Step 3: Add the Tool to the platform

Tip: Prior to this step, we recommend testing that the container was properly build by locally running the tool. To learn how to do so, check the Testing tools on your computer section in the QMENTA sdk documentation.

To follow this step you will need to have an account in QMENTA platform and have the ability to deploy tools enabled.

Contact us at info@qmenta.com if you want to know more about this feature.

  • Log in to the platform and access the My Analysis menu. Then, click on My tools and select New tool.


  • Fill all the fields with the information about your tool.

  • Field description

    • Name: the full name of your tool.
    • Short Name: a short version of the name of the tool.
    • Analysis Code: the tool ID (without spaces or special characters).
    • Version: your version identifier.
    • Repository URL: the registry where your image is stored (hub.docker.com)
    • Repository User: username of the registry.
    • Repository Password: your registry password.
    • Image Name: the full image name (username/tool_name:version).
    • Entry Point: the sequence of commands run at start-up. See Extending the Entry Point for more information.
    • Tool Path: the function name and method of the tool python script (tool:run).
    • Num. of cores: the number of CPU cores allocated to the tool.
    • RAM limit in GB: the amount of memory allocated to the tool.
    • User List (optional): the usernames of the users you want to share the tool with.
  • Add settings

    • Go to the settings tab and click on Editor.


    • Use the examples on the right screen to define the settings that your tool needs. This includes input containers and parameters of the tool. In this repository you can take a look at the settings implemented in the settings.json file.
  • Add a description

    • This texts is going to be displayed when running the tool from the platform.

Running the tool

After the completion of the three steps, the tool is ready to be run from the platform.

To do so, you can go to My Data in the platform, select a subject that contains the necessary files to run the tool (properly tagged) and click on Start Analysis. Then select your tool, choose the parameters you want it to run with and optionally add a name and a description to the analysis. Click on Start Analysis when the configuration is ready.


The platform will run the analysis and send an email whenever it finishes. Then, you can retrieve the results by going to My Analysis, selecting the finished analysis, and then click on Result files inside the Results tab.

You can’t perform that action at this time.