Create trial – Moveshelf

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.4.0)
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)
# or name (my_subject_name) 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)

# 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 = "YYYY-MM-DD" # session name, e.g. 2025-09-05
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.