Get a demo

Get in touch

Prefer using email? Write us at hello@moveshelf.com

This section explains how to exploit the Moveshelf API server-side filtering functionality. It is possible to use the Moveshelf API to retrieve a subset of subjects in a project on Moveshelf that meet a set of subject metadata and session date and count criteria. Filtering is particularly useful when you only need to retrieve subjects with certain characteristics that have a certain number of sessions within a specific time period, as it reduces the amount of data retrieved and makes the query more efficient.

Note: Filtering subjects by intervention metadata is not supported.
Prerequisites
Before implementing this example, ensure that your processing script includes all necessary setup steps. In particular, you should have:
Filtering by subject metadata
The function getFilteredProjectSubjects accepts the optional input argument subject_metadata_filters: 
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 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" }
            ]
        }
    ]
}
Implementation
To retrieve all female patients diagnosed with Cerebral Palsy or ACL Rupture in a project, add the following lines of code to your processing script: 
## 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" }
            ]
        }
    ]
} 

## Add here the code to retrieve the project_id
# ... 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,
    include_additional_data=False
)
Filtering by session date and session count
The function getFilteredProjectSubjects accepts the optional input argument session_filters: 
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)
    }
}
Implementation
To retrieve all patients that have at least two sessions between 01-01-2010 and 01-01-2015, add the following lines of code to your processing script: 
## 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
session_filters: {
    "sessionDates": {
        "startDate": "01-01-2010",
        "endDate": "01-01-2015"
    },
    "numSessions": {
        "min": 2
    }
}

## Add here the code to retrieve the project_id
# ... 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,
    session_filters=session_filters,
    include_additional_data=False
)


Note: for subjects that meet the requirements defined in session_filters, ALL sessions will be returned, not only the sessions matching matching session_filters.
Subject metadata and session filters can be combined. For example, to retrieve all female patients diagnosed with Cerebral Palsy or ACL Rupture with exactly 2 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
    }
}

## Add here the code to retrieve the project_id
# ... 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
)