Examples

See our repository on GitHub for a complete example of tool ready to work with the QMENTA platform.

Simple mrinfo tool

Prints the dimensions of every file to a text file.

import os


def run(context):
    # Get information from the platform such as patient name, user_id, ssid...
    analysis_data = context.fetch_analysis_data()
    print("Analysis name: {}".format(analysis_data["name"]))

    # Get the complete list of input file handlers matching the file filter
    input_files = context.get_files("input", modality="T1")

    # Do some processing (run mrinfo for every file)
    for f in input_files:
        f.download("/root/")
        os.system("mrinfo {} >> /root/sizes.txt".format(f.get_file_path()))

    # Last, upload the results to the platform
    context.upload_file("/root/sizes.txt", "mrinfo_outputs.txt")

MATLAB-based tool

The MATLAB runtime allows MATLAB applications to run on containers that do not have MATLAB installed. Instead, it provides just the necessary set of shared libraries necessary to execute precompiled programs.

If you start the development of your tool with our base image qmentasdk/matlab_r2017a or you have installed any other version of the MATLAB runtime by yourself, you can use the following commands to run MATLAB code in the QMENTA platform out of the box.

First, you will need to compile your python script on your computer by running mcc:

mcc -m my_tool.m -o my_tool

This produces two files: the compiled tool code and a helper shell script that can be used to run it (you can copy the files to the container as explained in Working with Docker images).

Integrating this script with the SDK is as easy as just calling the launcher script from the tool code:

import os


def run(context):
    # Get information from the platform such as patient name, user_id, ssid...
    analysis_data = context.fetch_analysis_data()
    print("Analysis name: {}".format(analysis_data["name"]))

    # Get the complete list of input file handlers matching the requirements
    input_files = context.get_files("input", modality="T1")

    # Download all those files
    for file_handler in input_files:
        file_handler.download("/root/")  # Keeping the original names

    # Call the MATLAB helper script with the path of the MATLAB runtime installation
    # Make sure your script finalizes. Otherwise this call will be waiting forever
    # Alternatively, you can always implement a timeout (e.g. with subprocess)
    os.system("/root/MATLAB_run_script.sh /opt/mcr/v92")

    # Last, upload the results to the platform
    context.upload_file("/root/results.png", "results.png")

Deployment of a tool: step-by-step guide

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

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 GitHub 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:

    context.get_files('input', file_filter_condition_name='c_anat')[0].download(input_dir)
    
  • Retrieve the settings defined for the analysis:

    context.get_settings()
    
  • Set the progress status to monitor the analysis from the platform:

    context.set_progress(value=10, message="Instantiating feature extractor")
    
  • Upload the result files from the container to the platform:

    context.upload_file(anat, 'inputs/anatomical_image.nii.gz', modality=modality)
    

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 (you can also find it in the GitHub 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 image repository (tool) and 1.0 the version 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 see Working with Docker images.

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 Testing tools on your computer.

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.

_images/add_tool1.png
  • Fill all the fields with the information about your tool.

_images/add_tool2.png
  • Add settings
    • Go to the settings tab and click on Editor.

_images/add_tool3.png
  • 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 the GitHub repository you can take a look at the settings implemented in the settings.json file.

_images/add_tool4.png
  • Add a description
    • This texts is going to be displayed when running the tool from the platform. <br/>

_images/add_tool5.png

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.

_images/run_tool.png

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.

_images/results.png