Retrieve a filtered subset of subjects

Query execution time increases proportionally with the amount of data being retrieved. When you query a project with hundreds of subjects or more, it is highly recommended to retrieve a filtered subset.

This section explains how to exploit the Moveshelf API's server-side filtering functionality to retrieve a subset of subjects in a project on Moveshelf that meet a set of subject metadata, session date, and session count criteria. Filtering is particularly useful when you only need to retrieve subjects with certain characteristics (such as a specific diagnosis), or subjects that have a certain number of sessions within a specific time period.

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

Implementation

The function getFilteredProjectSubjects returns a list subjects filtered by subject metadata and by session date and session count. Subject metadata and session filters can be combined or used individually. This section explains how to construct subject metadata filters and session filters, and provides the implementation of an example use case.

Subject metadata filters can be constructed in the following way:

subject_metadata_filters: {
    "key": "<metadata_key>" # e.g., "subject-sex"
    "operator": "EQ" # currently, only EQ is supported
    "value": "<metadata_value>" # e.g., "Male"
}       

It is also possible to concatenate subject metadata filters with a certain logic. For example, to find all female patients diagnosed with Cerebral Palsy or ACL Rupture:

subject_metadata_filters: {
    "logic": "AND", # Supported logics: AND, OR
    "filters": [
        { "key": "subject-sex", "operator": "EQ", "value": "Female" },
        {
            "logic": "OR",
            "filters": [
                { "key": "subject-diagnosis", "operator": "EQ", "value": "Cerebral Palsy" },
                { "key": "subject-diagnosis", "operator": "EQ", "value": "ACL Rupture" }
            ]
        }
    ]
}   

Session filters can be constructed in the following way. Please note that for subjects that meet the requirements defined in session_filters, ALL sessions will still be returned, as the filter operation returns a set of subjects.

session_filters: {
    "sessionDates": {
        "startDate": None or "<startDate>"  # start date (inclusive) in "YYYY-MM-DD" format or None,
        "endDate": None or "<endDate>"  # end date (inclusive) in "YYYY-MM-DD" format or None,
    },
    "numSessions": {
        "min": None or <int> # minimum number of sessions (inclusive)
        "max": None or <int> # maximum number of sessions (inclusive)
    }
}

To retrieve all female patients diagnosed with Cerebral Palsy or ACL Rupture with exactly two sessions between 01-01-2013 and 30-04-2020, you could use:

## README: this example shows how we can retrieve sessions from Moveshelf 
# using the Moveshelf API.

## General configuration. Set values before running the script
my_project = "<organizationName/projectName>"  # e.g. support/demoProject
subject_metadata_filters: {
    "logic": "AND", # Supported logics: AND, OR
    "filters": [
        { "key": "subject-sex", "operator": "EQ", "value": "Female" },
        {
            "logic": "OR",
            "filters": [
                { "key": "subject-diagnosis", "operator": "EQ", "value": "Cerebral Palsy" },
                { "key": "subject-diagnosis", "operator": "EQ", "value": "ACL Rupture" }
            ]
        }
    ]
}  
session_filters: {
    "sessionDates": {
        "startDate": "01-01-2013",
        "endDate": "30-04-2020"
    },
    "numSessions": {
        "min": 2,
        "max": 2
    }
}

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

## Get all subjects in the project that fullfill metadata criteria
## Set include_additional_data to True to also retrieve
## clips/trials and data files
subjects = api.getFilteredProjectSubjects(
    my_project_id,
    subject_metadata_filters=subject_metadata_filters,
    session_filters=session_filters,
    include_additional_data=False
)
       

With the retrieved subset of subjects, you can proceed with further analysis. For example, you may wish to use Python to filter further by intervention metadata or session metadata, or kinematic data. Our other examples below may come in helpful during the analysis, but other analysis or statistical programs such as Excel, R or SPSS may also be helpful.