Developer – Importing data

This section explains how to create a new subject on Moveshelf using the Moveshelf API, based on the subject's MRN/EHR-ID. Before creating a new subject, the script first checks whether a subject with the given MRN/EHR-ID already exists on Moveshelf.

If a matching subject is found, it is retrieved
If no existing subject is found, a new subject is created and assigned the specified MRN/EHR-ID

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.6.3)

Implementation

To create a new subject or retrieve an existing one, add the following lines of code to your processing script:

## README: this example shows how we can create a subject on Moveshelf 
# using the Moveshelf Python API.
# For a given project (my_project), first check if there already exists
# a subject with a given MRN (my_subject_mrn). If it doesn't exist, 
# we create a new subject with name my_subject_name, and assign my_subject_mrn if provided.

## 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", set to None if not needed.
my_subject_name = "<subjectName>"  # subject name, e.g. Subject1

## Get available projects
projects = api.getUserProjects()

## Select the project
project_names = [project["name"] for project in projects if len(projects) > 0]
idx_my_project = project_names.index(my_project)
my_project_id = projects[idx_my_project]["id"]

## Find the subject based on MRN
subject_found = False
if my_subject_mrn is not None:
    subject = api.getProjectSubjectByEhrId(my_subject_mrn, my_project_id)
    if subject is not None:
        subject_found = True

## Retrieve subject details if there was a match. Create new subject if there is no match
if subject_found:
    subject_details = api.getSubjectDetails(subject["id"])
    subject_metadata = json.loads(subject_details.get("metadata", "{}"))
    print(
        f"Found subject with name: {subject_details['name']},\n"
        f"id: {subject_details['id']}, \n"
        f"and MRN: {subject_metadata.get('ehr-id', None)}"
    )
else:
    print(
        f"Couldn't find subject with MRN: {my_subject_mrn},\n"
        f"in project: {my_project}"
    )
    new_subject = api.createSubject(my_project, my_subject_name)
    if my_subject_mrn is not None:
        subject_updated = api.updateSubjectMetadataInfo(
            new_subject["id"], json.dumps({"ehr-id": my_subject_mrn})
        )

Validation

To verify that the new subject has been successfully created, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project to check if the new subject appears with the correct MRN/EHR-ID. If you prefer an automated method, add the following lines of code to your processing script, right after creating the new subject, to check the subject’s details programmatically:

# Fetch subject details using the subject ID
new_subject_details = api.getSubjectDetails(new_subject["id"])
new_subject_metadata = json.loads(new_subject_details.get("metadata", "{}"))

# Print the subject details
print(f"Created subject with name: {new_subject_details['name']},\n"
        f"id: {new_subject_details['id']}, \n"
        f"and MRN: {new_subject_metadata.get('ehr-id', None)}")

This code will retrieve the newly created subject's details, including the name, ID, and MRN/EHR-ID, and print them for verification.

Import subject metadata

This example demonstrates how to import subject metadata for an existing subject on Moveshelf via the Moveshelf API. First we retrieve the subject from Moveshelf via its MRN/EHR-ID. Then, we update its subject metadata.

Important: The keys in the metadata dictionary to be imported must match the metadata template that is configured for the Moveshelf project you want to import to. You can download the configured metadata template from the project overview.
Moreover, updating metadata through the Moveshelf API behaves the same way as performing a directory upload via the web interface using 'moveshelf_config_import.json':
Existing subject metadata values are not overwritten. Only empty fields are updated.
However, existing interventions will be overwritten.

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.6.3)
Created the subject, or made sure a subject with the specified MRN already exists on Moveshelf

Implementation

To import subject metadata to an existing subject, add the following lines of code to your processing script:

## README: this example shows how we can import subject metadata to an existing
# subject on Moveshelf using the Moveshelf Python API.
# This code assumes you have implemented the 'Create subject' example, and
# that you have found the subject with a given EHR-id/MRN (my_subject_mrn)
# within a given project (my_project), and that 
# you have access to the subject ID
# For that subject, update subject metadata (my_subject_metadata)

## 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

# Manually define the subject metadata dictionary you would like to import
my_subject_metadata = {
    "subject-first-name": "<subjectFirstName>",
    "subject-middle-name": "<subjectMiddleName>",
    "subject-last-name": "<subjectLastName>",
    "ehr-id": my_subject_mrn,
    "interventions": [ # List of interventions
        {
            "id": 0, # <idInterv1>
            "date": "<dateInterv1>", # "YYYY-MM-DD" format
            "site": "<siteInterv1>",
            "surgeon": "<surgeonInterv1>",
            "procedures": [
                {
                    "side": "<sideProc1Interv1>",
                    "location": "<locationProc1Interv1>",
                    "procedure": "<procedureProc1Interv1>",
                    "location-modifier": "<locationModProc1Interv1>",
                    "procedure-modifier": "<procedureModProc1Interv1>"
                },
                {
                    "side": "<sideProc2Interv1>",
                    # ... You can add multiple procedures
                }
            ],
            "surgery-dictation": "<surgeryDictationInterv1>"
        },
        # ... Additional interventions can be added here, each represented as a dictionary
        # Increment the "id" for each new intervention (e.g., 1, 2, 3,...)
        # Ensure each intervention contains a complete set of fields
    ]
    # ... Add additional fields you would like to import
}

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

# Import subject metadata
subject_updated = api.updateSubjectMetadataInfo(
    subject["id"], json.dumps(my_subject_metadata)
)
 

It is also possible to load subject metadata from a JSON file stored on your local machine, e.g., 'moveshelf_config_import.json'. Instead of defining my_subject_mrn and my_subject_metadata manually, you can load them from a JSON file located in your root folder as shown below:

# Define the path to the local JSON file
local_metadata_json = os.path.join(parent_folder, "moveshelf_config_import.json")

# Load JSON file
with open(local_metadata_json, "r") as file:
    local_metadata = json.load(file)

# Extract subjectMetadata dictionary from metadata JSON
my_subject_metadata = local_metadata.get("subjectMetadata", {})
my_subject_mrn = my_subject_metadata.get("ehr-id", "")

# Extract interventionMetadata list from metadata JSON
my_subject_metadata["interventions"] = local_metadata.get("interventionMetadata", [])

Validation

To verify that the subject metadata has been successfully imported, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project to check if the subject appears with the correct subject metadata. If you prefer an automated method, add the following lines of code to your processing script, right after updating subject metadata, to check the subject’s metadata programmatically:

# Fetch subject details using the subject ID
subject_details = api.getSubjectDetails(subject["id"])
subject_metadata = json.loads(subject_details.get("metadata", "{}"))

# Print the subject details
print(f"Updated subject with name: {subject_details['name']},\n"
        f"id: {subject_details['id']}, \n"
        f"and metadata: {subject_metadata}") 

This code will retrieve the subject's details, including the name, ID, and subject metadata, and print them for verification.

Create session

This section explains how to create a new session for a subject with a specified MRN on Moveshelf using the Moveshelf API, based on the session's date. Before creating a new session, the script first checks whether a session with the specified date already exists for that subject on Moveshelf.

If a matching session is found, it is retrieved
If no existing session is found, a new session is created and assigned the specified name (my_session_name) and date (my_session_date)

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.6.3)
Created the subject, or made sure a subject with the specified MRN already exists on Moveshelf

Implementation

To create a new session or retrieve an existing one, add the following lines of code to your processing script:

## README: this example shows how we can create a session on Moveshelf 
# using the Moveshelf API.
# This code assumes you have implemented the 'Create subject' example, and
# that you have found the subject with a given EHR-id/MRN (my_subject_mrn)
# within a given project (my_project), and that you have access to the subject ID
# For that subject, we check if a session with the specified date 
# (my_session_date) exists. If it doesn't exist, a new session is created with the specified
# name (my_session_name) and date (my_session_date).

## Additional imports
from datetime import datetime

## 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_session_name = "<sessionName>" # session name, typically a date e.g., "2025-09-05"
my_session_date = "<sessionDate>" # "YYYY-MM-DD" format

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

## Find existing session
sessions = subject_details.get('sessions', [])
session_found = False
for session in sessions:
    try:
        date_obj = datetime.fromisoformat(session["date"])
        session_date = date_obj.strftime('%Y-%m-%d')
    except:
        session_date = ""
    if session_date == my_session_date:
        session_id = session['id']
        session = api.getSessionById(session_id) # get all required info for that session
        session_found = True
        print(f"Session with date {my_session_date} already exists")
        break

## Create new session if no match was found
if not session_found:
    session_path = "/" + subject_details['name'] + "/" + my_session_name + "/"
    session = api.createSession(my_project, session_path, subject_details['id'], my_session_date)
    session_id = session['id']
       

Validation

To verify that the new session has been successfully created, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project and subject to check if the new session appears with the correct name. If you prefer an automated method, add the following lines of code to your processing script, right after creating the new session, to check the session’s details programmatically:

# Fetch session details using the session ID
new_session = api.getSessionById(session_id)
print(
    f"Found session with projectPath: {new_session['projectPath']},\n"
    f"and id: {new_session['id']}"
)

This code will retrieve the newly created session's details, including the project path (that includes the subject name and the session name), and ID, and print them for verification.

Import session metadata

This example demonstrates how to import session metadata for an existing session on Moveshelf via the Moveshelf API. First we retrieve the subject from Moveshelf via its MRN/EHR-ID. Then, we retrieve the session via its session date, and update its metadata.

Important: The keys in the metadata dictionary to be imported must match the metadata template that is configured for the Moveshelf project you want to import to. You can download the configured metadata template from the project overview.
Moreover, updating metadata through the Moveshelf API behaves the same way as performing a directory upload via the web interface using 'moveshelf_config_import.json', i.e., existing session metadata values are not overwritten. Only empty fields are updated.

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.6.3)
Created the session, or made sure a session with the specified date already exists on Moveshelf

Implementation

To import session metadata to an existing subject and session, add the following lines of code to your processing script:

## README: this example shows how we can import session metadata to an existing
# session on Moveshelf using the Moveshelf Python API.
# This code assumes you have implemented the 'Create session' example, and
# that you have found the session (my_session_name) for a subject with a given
# EHR-id/MRN (my_subject_mrn) within a given 
# project (my_project), and that you have access to the session ID and session_name
# For that session, update session metadata (my_session_metadata)

## 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
my_session_name = "<sessionName>" # session name, typically a date e.g., "2025-09-05"

# Manually define the session metadata dictionary you would like to import
my_session_metadata = {
    "interview-fms5m": "1",
    "vicon-leg-length": [
            {
                "value": "507",
                "context": "left"
            },
            {
                "value": "510",
                "context": "right"
            }
        ],
    # ... Add additional fields you would like to import
}

## Add here the code to retrieve the project and find an existing subject 
## and existing session
# loop over sessions until we find session_found = True

updated_session = api.updateSessionMetadataInfo(
    session_id,
    my_session_name,
    json.dumps({"metadata": my_session_metadata})
)
print(f"Updated session {my_session_name}: {updated_session}")

It is also possible to load session metadata from a JSON file stored on your local machine, e.g., 'moveshelf_config_import.json'. Instead of defining my_subject_mrn and my_session_metadata manually, you can load them from a JSON file located in your root folder as shown below:

# Define the path to the local JSON file
local_metadata_json = os.path.join(parent_folder, "moveshelf_config_import.json")

# Load JSON file
with open(local_metadata_json, "r") as file:
    local_metadata = json.load(file)

# Extract subjectMetadata dictionary from metadata JSON
my_subject_metadata = local_metadata.get("subjectMetadata", {})
my_subject_mrn = my_subject_metadata.get("ehr-id", "")

# Extract sessionMetadata dictionary from metadata JSON
my_session_metadata = local_metadata.get("sessionMetadata", {})

Validation

To verify that the session metadata has been successfully imported, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project to check if the session appears with the correct session metadata. If you prefer an automated method, add the following lines of code to your processing script, right after updating session metadata, to check the session’s metadata programmatically:

# Fetch session details using the session ID
updated_session_details = api.getSessionById(session_id)
updated_session_metadata = updated_session_details.get("metadata", None)

# Print updated session metadata
print(
    f"Updated session with projectPath: {session['projectPath']},\n"
    f"id: {session_id}.\n"
    f"New metadata: {updated_session_metadata}"
)

This code will retrieve the updated session's details, including the projectPath, ID, and session metadata, and print them for verification.

Create trial

This section explains how to create a new trial in a condition of a session for a subject with a specified MRN on Moveshelf using the Moveshelf API. Before creating a new trial, the script first checks whether a trial with the specified name already exists within the condition on Moveshelf.

If a matching trial in that condition is found, it is retrieved
If no existing trial with that name in the condition is found, a new trial is created

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.6.3)
Created the subject, or made sure a subject with the specified MRN already exists on Moveshelf
Created the session, or made sure a session with that name in the subject already exists on Moveshelf

Implementation

To create a new trial or retrieve an existing one, add the following lines of code to your processing script:

## README: this example shows how we can create a trial on Moveshelf 
# using the Moveshelf API.
# This code assumes you have implemented the 'Create subject' example, 
# that you have found the subject with a given EHR-id/MRN (my_subject_mrn)
# within a given project (my_project), and that you have 
# access to the subject ID
# This code also assumes you have implemented the 'Create session' example, 
# and that you have found the session with a specific name (my_session_name)

# For that subject and session, to understand if we need to create a new trial or find an 
# existing trial, we first check if a condition with the specified name (my_condition) 
# exists. If it doesn't exist yet, or if a trial with a specific name (my_trial) is not found 
# in the existing condition, we create a new trial. Otherwise, we use the exising trial.


## 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
my_session_name = "<sessionDate>" # "YYYY-MM-DD" format
my_condition = "<conditionName>"  # e.g. "Barefoot"
my_trial = "<trialName>" # when set to None, we increment the trial number starting with "Trial-1"

## 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"

# Get conditions in the session
conditions = []
conditions = util.getConditionsFromSession(session, conditions)

condition_exists = any(c["path"].replace("/", "") == my_condition for c in conditions)
condition = next(c for c in conditions if c["path"].replace("/", "") == my_condition) \
    if condition_exists else {"path": my_condition, "clips": []}

clip_id = util.addOrGetTrial(api, session, condition, my_trial)
print(f"Clip created with id: {clip_id}")

It is also possible to load the condition names and list of trials from a JSON file stored on your local machine, e.g., 'moveshelf_config_import.json'. Instead of defining my_condition and my_trial manually, you can access them from a JSON file located in your root folder as shown below:

# Define the path to the local JSON file
local_metadata_json = os.path.join(parent_folder, "moveshelf_config_import.json")

# Load JSON file
with open(local_metadata_json, "r") as file:
    local_metadata = json.load(file)

# Extract conditionDefinition from metadata JSON
my_condition_definition = local_metadata.get("conditionDefinition", {})

## 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"

# Get conditions in the session
conditions = []
conditions = util.getConditionsFromSession(session, conditions)

# loop over conditions defined in conditionDefinition
for my_condition, my_trials in my_condition_definition.items():

    condition_exists = any(c["path"].replace("/", "") == my_condition for c in conditions)
    condition = next(c for c in conditions if c["path"].replace("/", "") == my_condition) \
        if condition_exists else {"path": my_condition, "clips": []}
    
    # Loop over trials list defined for my_condition
    for my_trial in my_trials:
        clip_id = util.addOrGetTrial(api, session, condition, my_trial)
        print(f"Clip created with id: {clip_id}") 

Validation

To verify that the new trial has been successfully created, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project, subject and session to check if the new trial appears with the correct name. If you prefer an automated method, add the following lines of code to your processing script, right after creating the new trial, to check the trial details programmatically:

# Fetch trial using the trial ID
new_clip = api.getClipData(clip_id)
print(
    f"Found a clip with title: {new_clip['title']},\n"
    f"and id: {new_clip['id']}"
) 

This code will retrieve the newly created trial details, including the title and ID, and print them for verification.

Upload data files

This section explains how to upload data into a specific trial in a condition of a session for a subject with a specified MRN on Moveshelf using the Moveshelf API. Before uploading, the script first checks whether data file with the same name already exists within the trial on Moveshelf and will skip the upload if it's already present. Please refer to this section for supported data types.

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.6.3)
Created the subject, or made sure a subject with the specified MRN already exists on Moveshelf
Created the session, or made sure a session with that name in the subject already exists on Moveshelf
Created the trial, or made sure a trial with that name in the session already exists on Moveshelf

Implementation

To upload data into the trial identified by the "clip_id", add the following lines of code to your processing script:

## README: this example shows how we can upload date into a trial on 
# Moveshelf using the Moveshelf API.
# This code assumes you have implemented the 'Create subject' example, 
# that you have found the subject with a given EHR-id/MRN (my_subject_mrn)
# within a given project (my_project), and that you have access to the subject ID.
# This code also assumes you have implemented the 'Create session' example, 
# and that you have found the session with a specific name (my_session_name)
# This code also assumes you have implemented the 'Create trial' example, 
# and that you have found the trial with a specific name (my_trial).

# For that trial as part of a subject and session, we need the "clip_id". 

## 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
my_session_name = "<sessionDate>" # "YYYY-MM-DD" format
my_condition = "<conditionName>"  # e.g. "Barefoot"
my_trial = "<trialName>"
filter_by_extension = None
data_file_name = None  # with None, the name of the actual file is used, if needed this name can be used
files_to_upload = [<pathToFile_1>, <pathToFile2>,...] # list of files to be added to the trial
data_type = "raw"

## 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

existing_additional_data = api.getAdditionalData(clip_id)
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]

## Upload data
for file_to_upload in files_to_upload:
    file_name = data_file_name if data_file_name is not None else os.path.basename(file_to_upload)
    if file_name in existing_file_names:
        print(file_name + " was found in clip, will skip this data.")
        continue

    print("Uploading data for : " + my_condition + ", " + my_trial + ": " + file_name)

    dataId = api.uploadAdditionalData(file_to_upload, clip_id, data_type, file_name)    

Please note that the example above will skip the data upload of local files that have the same name as already existing files on Moveshelf. Alternatively, if you want to skip file upload only when the same version of your local file (not just the filename) has already been uploaded to Moveshelf, you can use the isCurrentVersionUploaded function and replace the Upload data section of the example above by:

## Upload data
for file_to_upload in files_to_upload:
    file_name = data_file_name if data_file_name is not None else os.path.basename(file_to_upload)
    
    # Check if on Moveshelf there is already the same version of your local local file
    is_current = api.isCurrentVersionUploaded(file_to_upload, clip_id)
    if is_current:
        # No need to upload the file
        continue

    print("Uploading data for : " + my_condition + ", " + my_trial + ": " + file_name)

    dataId = api.uploadAdditionalData(file_to_upload, clip_id, data_type, file_name)
      

It is also possible to upload trial data and metadata in batch using information from a JSON file stored on your local machine, e.g., 'moveshelf_config_import.json'. Instead of defining a list of files_to_upload, define the path to the folder containing session data as shown below:

## General configuration. Set values before running the script
session_folder_path = "<pathToDataFolder>"
file_extension_to_upload = "<extension>" # e.g., ".GCD"
data_file_name = None  # with None, the name of the actual file is used, if needed this name can be used
data_type = "raw"

# Define the path to the local JSON file
local_metadata_json = os.path.join(parent_folder, "moveshelf_config_import.json")

# Load JSON file
with open(local_metadata_json, "r") as file:
    local_metadata = json.load(file)

# Extract conditionDefinition, representativeTrials, and trialSideSelection
# from metadata JSON
my_condition_definition = local_metadata.get("conditionDefinition", {})
my_representative_trials = local_metadata.get("representativeTrials", {})
my_trial_side_selection = local_metadata.get("trialSideSelection", {})

## 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 get existing conditions and loop over conditions and trials 
# ... clip_id = util.addOrGetTrial(api, session, condition, my_trial)

## Upload data
file_name = data_file_name if data_file_name is not None else f"{my_trial}{file_extension_to_upload}"
print("Uploading data for : " + my_condition + ", " + my_trial + ": " + file_name)

dataId = api.uploadAdditionalData(
    os.path.join(session_folder_path, f"{my_trial}{file_extension_to_upload}"),
    clip_id,
    data_type,
    file_name
) 

metadata_dict = {
    "title": my_trial
}

# Initialize the trial template
custom_options_dict = {"trialTemplate": {}}
trial_template = custom_options_dict["trialTemplate"]

# Add side information if available
side_value = my_trial_side_selection.get(my_trial)
if side_value:
    trial_template["sideAdditionalData"] = {dataId: side_value}

# Handle representative trial flags
representative_trial = my_representative_trials.get(my_trial, "")

rep_flags = {}
if "left" in representative_trial:
    rep_flags["left"] = True
if "right" in representative_trial:
    rep_flags["right"] = True
if rep_flags:
    trial_template["representativeTrial"] = rep_flags

# Remove the trialTemplate key if it's still empty
if not trial_template:
    custom_options_dict = {}

# Convert to JSON string
custom_options = json.dumps(custom_options_dict)

api.updateClipMetadata(clip_id, metadata_dict, custom_options)

# Fetch trial using the trial ID
new_clip = api.getClipData(clip_id)
print(
    f"Found a clip with title: {new_clip['title']},\n"
    f"id: {new_clip['id']},\n"
    f"and custom options: {new_clip['customOptions']}"
)
        

PDF/image files

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

## Modifications needed to upload PDF/image files into "Additional files"
my_condition = "Additional files"
my_trial = "<pdf_file_name>" 
filter_by_extension = ".pdf"  # for  images, use e.g. ".jpg"/".png" if needed.
files_to_upload = [
    "<path_to_additional_data.pdf>",
]
data_type = "doc"  # for images, set data_type to "img"

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 additional data file can then be named e.g. "Raw motion data - my_session_name.zip". To upload, the code as shown above can be used, with the following modifications:

## Modifications needed to upload raw motion data in ZIP archive into "Additional files"
my_condition = "Additional files"
my_trial = "Raw motion data"
data_file_name = "Raw motion data - " + my_session_name + ".zip"  # Set to None for actual file name.
filter_by_extension = ".zip"  # set to None if used without filtering
files_to_upload = [
    "<path_to_additional_data.zip>",
]
data_type = "raw"

Create interactive reports

This section explains how to create interactive reports in a session 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.6.3)
Retrieved the trial/clip ids for an existing session on Moveshelf

Implementation

There are four functions available to generate different types of interactive reports:

generateAutomaticInteractiveReports to automatically generate reports using all trials of all conditions available in the session (and the previous session if applicable). Only available if automatic report generation is configured in the project.
generateConditionSummaryReport to generate a condition summary report using the specified trials.
generateCurrentSessionComparisonReport to generate a condition comparison report using the specified trials from different conditions within the same session.
generateCurrentVsPreviousSessionReport to generate a session comparison report using the specified trials from different sessions.

To create interactive reports with reference data, you need to specify the ID of the desired "norm" (i.e., reference data). The norms are stored at project level, and it is possible to access the list of norms directly from the subject_details, e.g., norm_list = subject_details["project"].get("norms", []). Select the norm you would like to use from the list, and extract its ID. To create interactive reports, add the following lines of code to your processing script:

## README: this example shows how we can create interactive reports on Moveshelf 
# using the Moveshelf API.
# This code assumes you have access to the subject_details to extract
# the norm_id (optional), the session_id, and the list of trial_ids to be 
# included in the reports (see "Retrieve trials" example)


## General configuration. Set values before running the script
my_norm_id = None or "<normId>"  # e.g. subject_details["project"]["norms"][0]["id"] (default is None for report without reference)
my_session_id = "<sessionId>" # retrieve from subject_details
my_trials_ids = ["<trialId1>", ..., "<trialIdN>"] # list of trial/clip ids to be included in report

## Automatically create interactive reports using all trials in the specific session. 
is_report_generated = api.generateAutomaticInteractiveReports(
    session_id=my_session_id,
    norm_id=my_norm_id
)

## It is also possible to manually create specific interactive reports
## Condition summary report
is_report_generated = api.generateConditionSummaryReport(
    session_id=my_session_id,
    title="My Condition Summary report title",
    trials_ids=my_trials_ids,
    norm_id=my_norm_id,
    template_id="currentSessionConditionSummaries",
)

## Session comparison report
is_report_generated = api.generateCurrentVsPreviousSessionReport(
    session_id=my_session_id,
    title="My Curr vs Prev report title",
    trials_ids=my_trials_ids,
    norm_id=my_norm_id,
    template_id="currentVsPreviousSessionComparison"
)

## Condition comparison report
is_report_generated = api.generateCurrentSessionComparisonReport(
    session_id=my_session_id,
    title="My Condition comparison report title",
    trials_ids=my_trials_ids,
    norm_id=my_norm_id,
    template_id="currentSessionComparison"
)

Validation

To verify that the new interactive report has been successfully created, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project, subject and session to check if the new interactive report appears. If you prefer an automated method, add the following line of code to your processing script, right after creating the interactive report, to check if the generation was successful:

print(
    f"Interactive report generated succesfully? {is_report_generated}"
) 

Alternatively, you can query the subject details again and verify if the new reports have been created:

# Fetch subject details using the subject ID
new_subject_details = api.getSubjectDetails(my_subject_id)
reports = new_subject_details.get("reports")

for report in reports:
    print(
        f"Found interactive report with title: {report['title']} and id: {report['id']}"
    ) 

Using the API

Querying data