Would you like to hear about webinars we're
doing, new features we're adding and projects we're undertaking? Sign up
here to our pleasantly infrequent newsletter!
Moveshelf is designed to keep data secure but always
accessible. This is true both from our web interface, for physicians and
clinical operators, as well as programmatically from our API, for
engineers and scientists.
This chapter contains all information to get
started with the Moveshelf API, to configure your environment, to
programmatically download a large amount of measurement files or to
query database information about your patient population.
Moveshelf provides two APIs to interact with its platform: a Python API and a GraphQL API.
This documentation serves as a central hub for understanding and utilizing both the Python and
GraphQL APIs effectively. It is designed to bridge the gap between the two APIs, offering clear
guidance on their individual strengths and how they can complement each other. This
documentation is intended for engineers and advanced users who want to automate workflows
and build custom solutions using the APIs.
In a nutshell, the idea is to:
Use the GraphQL API to explore the Moveshelf schema, understand data
relationships, and write precise queries/mutations.
Use the Python API to execute those queries and handle operations programmatically,
leveraging Python’s ecosystem for data processing and scripting.
To interact with the Moveshelf API, you need Python and an IDE (e.g., Visual Studio Code). This setup will allow you to run existing Python scripts from GitHub or create your own. This section walks you through setting up your environment to interact with the Moveshelf API using Python. You will install the necessary tools, clone a GitHub repository, set up dependencies, and run example scripts.
The Python API simplifies integration with Moveshelf
for Python developers. It abstracts authentication, request handling, and common tasks into an intuitive, high-level interface, allowing developers to focus on building solutions without needing to manage the complexities of API interactions.
By offering built-in support for executing GraphQL queries and mutations, the Python API enables seamless data retrieval and manipulation while integrating naturally with Python's extensive ecosystem of libraries. This makes it an ideal choice for automating workflows, processing data, and creating custom scripts that interact with Moveshelf resources.
Install the Python API via PyPI: pip install moveshelf-api
You can find the
documentation for the Python API here.
Basic usage example: downloading data via the Python API
Follow the steps in this section to run an existing example of querying and downloading data from the Moveshelf platform, available in the public GitHub repository.
Run the download_data_example script
Follow the instructions on GitHub, starting from the ‘API Key’ step.
Open the download_data_example Python script in Visual Studio Code, follow the instructions, add all relevant information to the script and save the file
To run the script, open a terminal and execute the following command: python scripts/download_data_example.py
Advanced usage example: extending the Python API with a custom query
If you need queries that are not included in the default Python API, you can create a custom API wrapper that extends it with custom GraphQL queries. This section demonstrates how to create a custom API wrapper defining a new method (getProjectSubjectsCustom) to retrieve, for a given project, all subjects' name, ID, andmetadata, and all their sessions' ID, date, and metadata.
Create a custom API wrapper:
Create a new Python file, e.g., api.py, and define a subclass of MoveshelfApi (see code snippet below). This allows you to extend the existing API by adding custom GraphQL queries. For example, the built-in getProjectSubjects function only retrieves subject names and IDs. In the example below, we define getProjectSubjectsCustom, that extends the built-in getProjectSubjects function to also retrieve subject metadata and session details (ID, date, and metadata).
frommoveshelf_api.apiimportMoveshelfApi# Custom Moveshelf API class that extends the existing API
classMoveshelfApiCustomized(MoveshelfApi):defgetProjectSubjectsCustom(self,project_id):data=self._dispatch_graphql('''
query getProjectPatients($projectId: ID!) {
node(id: $projectId) {
... on Project {
id,
name,
description,
canEdit,
patients {
id
name
metadata
sessions {
id
date
metadata
}
}
}
}
}
''',projectId=project_id)returndata['node']['patients']
Use the custom API in your processing script
To use your extended API, import the custom class into your processing script, e.g., ‘download_data_example.py’. The example below shows how to call getProjectSubjectsCustom to retrieve additional metadata for all subjects and their sessions.
parentFolder=os.path.dirname(os.path.dirname(__file__))sys.path.append(parentFolder)fromapi.apiimportMoveshelfApiCustomized## Setup the API
# Load config
withopen(os.path.join(parentFolder,"mvshlf-config.spec.json"),"r")asconfigFile:data=json.load(configFile)# And overwrite if available
personalConfig=os.path.join(parentFolder,"mvshlf-config.json")ifos.path.isfile(personalConfig):withopen(personalConfig,"r")asconfigFile:data.update(json.load(configFile))# Use custom API
api=MoveshelfApiCustomized(api_key_file=os.path.join(parentFolder,data["apiKeyFileName"]),api_url=data["apiUrl"])# ... rest of the code to access a project on Moveshelf via API ..
# Custom query (defined in ../api/api.py) that extracts the metadata of all patients
# and the metadata of all their sessions within a given project
subjects=api.getProjectSubjectsCustom(my_project_id)# Print the subject data
forsubjectinsubjects:print(f"Subject: {subject['name']} (ID: {subject['id']})")print(f"Metadata: {subject['metadata']}")print("Sessions:")forsessioninsubject['sessions']:print(f" - Session {session['id']} on {session['date']} with metadata: {session['metadata']}")