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.5.0)
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']}"
    ) 