Retrieve data – Moveshelf

This section explains how to retrieve additional data (files) within a specific trial of a condition within a session of a subject (specified by MRN) on Moveshelf using the Moveshelf API.

Prerequisites

Before implementing this example, ensure that your processing script includes all necessary setup steps. In particular, you should have:

Configured the Moveshelf API (version >= 1.4.0)
Retrieved the subject
Retrieved the session
Retrieved the trial

Implementation

To retrieve the additional data files with that trial, add the following lines of code to your processing script:

## README: this example shows how we can retrieve additional data from 
# Moveshelf using the Moveshelf API.
# This code assumes you have implemented the 'Retrieve subject' example, 
# that you have found the subject with a given EHR-id/MRN (my_subject_mrn)
# or name (my_subject_name) within a given project (my_project), that you 
# have access to the subject ID, you have implemented the 'Retrieve session' 
# example, and you have implemented the 'Retrieve trial' example to get or 
# create the specified trial (my_trial) within a specific condition (my_condition).

## Import necessary modules
import requests # Used to send HTTP requests to retrieve additional data files from Moveshelf

## General configuration. Set values before running the script
my_project = "<organizationName/projectName>"  # e.g. support/demoProject
my_subject_mrn = "<subjectMRN>"  # subject MRN, e.g. "1234567" or None
my_subject_name = "<subjectName>"  # subject name, e.g. Subject1 or None
my_session = "<sessionDate>" # "YYYY-MM-DD" format
my_condition = "<conditionName>"  # e.g. "Barefoot"
my_trial = "<trialName>"
filter_by_extension = None

## Add here the code to retrieve the project and find an existing subject and its "subject_details"
# ... subject_found = True

## Add here the code to retrieve an existing session and get its details using "getSessionById"

## Add here the code to retrieve an existing trial and get the ID: clip_id

# get all additional data
existing_additional_data = api.getAdditionalData(clip_id)
# if filter_by_extension is provided, only get the data with that extension
existing_additional_data = [
    data for data in existing_additional_data if not filter_by_extension
    or os.path.splitext(data["originalFileName"])[1].lower() == filter_by_extension]
existing_file_names = [data["originalFileName"] for data in existing_additional_data if 
    len(existing_additional_data) > 0]

print("Existing data for clip: ")
print(*existing_file_names, sep = "\n")

# Loop through the data found, and download if the "uploadStatus" is set to "Complete"
# The data will be available in "file_data", from which it can e.g. be used to 
# process, or written to a file on local storage
for data in existing_additional_data:
    if data["uploadStatus"] == "Complete":
        file_data = requests.get(data["originalDataDownloadUri"]).content
       

PDF/image files

PDF files and image files (e.g. ".jpg" or ".png") can be stored as part of a trial and retrieved following the example before, but on Moveshelf we have a dedicated place for PDF/image files, so these are picked up e.g. when exporting to a Word document. For this, PDF/image files are stored in a condition called "Additional files" with a trial per PDF/image and a name that is typically the same as the PDF/image file name in that trial. To retrieve, the code as shown above can be used, with the following modifications:

## Modifications needed to extract PDF/image files stored within "Additional files"
my_condition = "Additional files"
filter_by_extension = ".pdf"  # to be modified based on the required extension
       

Raw motion data - ZIP

For raw motion data provided in a ZIP archive, we suggest to use the same "Additional files" condition that is also used for PDF/image files. Specifically, for ZIP files with raw motion data we suggest to use a trial named "Raw motion data". The code to retrieve the data from this trial is similar to the PDF/image example above, but this time specify the specific trial name my_trial you first search for the specific trial:

## Modifications needed to extract ZIP files stored within "Additional files"
my_condition = "Additional files"
my_trial = "Raw motion data"        # To be modified based on the exact trial that is required.

filter_by_extension = ".zip"  # set to None to get all data in the trial