GC-API for Reader Studies



In this tutorial we will focus on grand-challenge Reader studies and show you how to upload cases to reader studies on our platform.

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

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

Import necessary libraries:

import gcapi
import os


Authenticate to Grand Challenge using your personal API token.

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


Upload input to Reader studies on Grand Challenge

If you are working on a Reader study, you most likely need to upload the cases to your study directory on the platform. This can be easily done via GC-API.

For this particular example, the data on your machine should be structured as follows:

mainfolder/ 
├── patient1_folder 
│       ├──file_for_a_single_series
├── patient2_folder 
│       ├──file_for_a_single_series 
├──patient3_folder 
│       ├──file_for_a_single_series 
          ...
├──patientN_folder 
│       ├──file_for_a_single_series 


Additionally, you will need to know the slug of the particular reader study you will work with. If the path your reader study on grand-challenge.org is https://grand-challenge.org/reader-studies/corads-score-exam/, the slug would be corads-score-exam.

Lets now list the files in the upload directory to check whether they can be identified:

#Specify the directory path which you want to upload from
upload_from_dir=r'path\to\folder\on\your\machine\with\data\to\upload\to\reader\study'
#Specify the "slug" of the study you want to upload your data to
upload_reader_study_slug="my-reader-stydy-slug"

files = {}

#Loop through files in the specified directory and add their names to the list
for root, directories, filenames in os.walk(upload_from_dir):
    for direc in directories:
        temp = []
        for file in os.listdir(os.path.join(root,direc)):
            temp.append(os.path.join(root,direc,file))
        files[direc] = temp
print("Found", len(files.keys()), "cases for upload")


To upload cases, do the following steps:

for i, key in enumerate(files.keys(), 1):
    temp_session = client.upload_cases(files=files[key], reader_study=upload_reader_study_slug)
    sessions.append(temp_session)
    print(files[key])
    print("Uploaded session", i, "of", len(files.keys()))