Choosing input and output interfaces

What are input and output interfaces?¶

At some point in your development process, you need to choose an input and output interface for your algorithm. An interface tells you two important things. It determines:

1. What needs to be read or stored, and where. It is essentially just the path to your data.
2. How data is interpreted – which relates to the kind of data that is being used. Is it an image, heatmap, segmentation mask, contour, bounding box etc.?

From the code base that you are preparing, a Docker image will be built that can be run as a Docker container. Every time it runs, it should process one set of inputs: it could be two images of the same patient, and perhaps some additional information such as age or sex – but it should not be a batch of data with several patients.

Every input/output needs an interface¶

To differentiate between input/output elements, you need to define an interface for each element separately. They can be the same type, but the interfaces need to have a different name and point to a different file location. The same goes for outputs. So every input/output element has to have a unique interface option (as defined by a name): the same interface cannot be chosen twice.

Inside a running container, an algorithm will take inputs from the /input/ folder to process them and store the outputs in /output/. By choosing an interface, you determine that, for example, a lung CT image needs to be read from /input/images/ct/*random_uuid*.mha. Your outputs – which may consist of a segmentation and a probability estimate – need to be stored as /output/images/covid-19-lesion-segmentation/*random_uuid*.mha and /output/probability.json, respectively.

Thus, if the directory tree in your Docker container has the following folder structure:

input/
├─ images/
│  ├─ ct/
│  │  ├─*random_uuid*.mha
output/
├─ images/
│  ├─ covid-19-lesion-segmentation/
│  │  ├─ *random_uuid*.mha
├─ probability.json

It implies the use of the following interfaces, displayed in this diagram:

NOTE: Images require you to read and write randomly generated uuids, so hard-coding paths for these should be avoided. Rather, construct your read and write paths as such, following the above example:

import os

folderpath_read = r'input/images/ct/'
filename = os.listdir(folderpath_read)[0]  # pick the first (and only) file in folder
filepath_read = os.path.join(folderpath_read, filename)

folderpath_write = r'output/images/covid-19-lesion-segmentation/'
filepath_write = os.path.join(folderpath_write, filename)

Interfaces can be chosen from a list of existing interfaces, or they can be requested. See the developer docs for an exhaustive list of the types of inputs and outputs that are supported, and instructions on how to format JSON-serializable data such as bounding boxes and polygons.

As you may find, a lot of these interfaces have very specific names, for particular tasks. But even though “Probability COVID-19(Float)” works as an interface for predicting anything that's expressed as a scalar value, we encourage you to request your own interface with a fitting name.

Requesting a new interface option¶

New interfaces can be requested by emailing support@grand-challenge.org. In this email, please specify the following details for your interface:

1. Title
2. Short description (one or two sentences)
3. Kind of data
4. Suggestion for read/write path

Take inspiration from the list of existing interfaces, and use a similar style/format to specify the details mentioned above. When the administrators of Grand-Challenge have added your interfaces, they will appear in the list when you create a new algorithm page: