GC-API for Archives



In this tutorial we will focus on Archives and go over how to upload and download cases from an archive on our platform.

Remember that you need to request access prior to using a particular archive. You do not need to request permission if you are using your own archive.

If you haven't installed gcapi yet, follow the instructions here.

Import necessary libraries:

import gcapi
import os
from pathlib import Path


Authenticate to Grand Challenge using your personal API token.

# authorize with your personal token
token = 'my-personal-api-token'
client = gcapi.Client(token=token)


Downloading cases from Archives on Grand Challenge

In this part we will download cases from the coronacases.org dataset on Grand Challenge.

First let's search for the archive by its name (not its slug!):

# name of the archive 
archive_name = "coronacases.org"
# save path on your machine
output_archive_dir = 'path\to\where\to\save\the\data\to\your\machine'

archives = client(url="https://grand-challenge.org/api/v1/archives/")["results"]

corona_archive = None
for archive in archives:
    if archive["name"] == archive_name :
        corona_archive = archive
        break
if corona_archive is None:
    raise Exception("archive not found on GC")


To download cases, do the following:

# Get information about images in archive from GC API
response = client(url="https://grand-challenge.org/api/v1/cases/images/", params={'archive': corona_archive['id']})
images = response['results']

# Create image mapping, from image URL to original image mha name
images_mapping = {}
for image in images:
    # get name of mha image from GC API
    images_mapping[image["files"][0]["file"]] = image["name"]

print("Downloading {0} images..".format(len(images_mapping)))

counter = 0
for file, name in images_mapping.items():
    response = client.get(file)
    response.raise_for_status()
    with open(os.path.join(output_archive_dir, name), 'wb') as f1:
        f1.write(response.content)
    counter += 1
    print(counter)


Uploading cases to an archive on Grand Challenge

Prepare the list of files for each image you want to upload.

files = [f.resolve() for f in Path("/path/to/files").iterdir()]


Now, you can upload these files to an archive, identified by its slug. For instance, if you would like to upload to the archive at https://grand-challenge.org/archives/radboudcovid/ you would use archive="radboudcovid". Note that this is case sensitive.

Now you can start the upload. Use a session per group of files that constitute an image: that way the conversion of the files can happen in parallel.

session = client.upload_cases(files=files, archive="radboudcovid")


You will get a session that starts the conversion of the files, and then adds the standardized images to the selected object once it has succeeded. You can refresh the session object with

session = c(url=session["api_url"])


and check the session status with

session["status"]