156 lines
7.2 KiB
Markdown
156 lines
7.2 KiB
Markdown
# Bachelor Thesis: Medwings
|
|
|
|
This repository contains the software, research data and final thesis I worked on
|
|
as part of my Computer Science degree at TU Braunschweig.
|
|
|
|
My research examined the current state of research in mobile patient deterioration monitoring,
|
|
and introduced a novel software system, which acts as an early warning system for high-risk patients
|
|
outside of direct medical supervision by utilising smart medical sensors in combination with
|
|
automated early warning score calculations.
|
|
Following the conception and development of the software, the system underwent a usability trial
|
|
and rigorous performance analysis.
|
|
|
|
With this work, I completed my degree and achieved the highest attainable mark (1.0) for a thesis,
|
|
and was offered a unique opportunity to continue my research in this area.
|
|
|
|
## Overview
|
|
|
|
> **Clinical Deterioration**: A measurable overall decline in a patient's vital functions, preceeding critical adverse outcomes.
|
|
|
|
Clinical deterioration can be detected up to 12 hours in advance of critical patient outcomes, such as
|
|
the need for ICU admission or even death. *Early warning scores*, such as the Modified Early Warning Score (**MEWS**),
|
|
have been in use internationally in hospitals to assess and monitor high-risk patients, and have proven to be
|
|
an effective predictor for deterioration.
|
|
|
|
To calculate an early warning score, or MEWS specifically, several vital parameters of the patient are measured and
|
|
scored individually. The individual scores are then added together to produce the final MEWS, which gives a clear
|
|
indication of the patient's risk of deterioration. The following table shows the vital parameters and scoring for MEWS:
|
|
|
|
|
|
|
|
Using tradtitional, expensive and immobile vitals monitoring devices, early warning scores are well established and widely used.
|
|
But what about at home or on the go? With recent advances in smart medical sensor technologies, predicting patient
|
|
deterioration could be possible even outside of medical care facilities, using less expensive equipment and carried out by
|
|
the patient autonomously. My research explored this approach through the implementation and evaluation of a mobile early
|
|
deterioration warning system: MEDWingS.
|
|
|
|
### MEDWingS
|
|
|
|
MEDWingS, the **M**obile **E**arly **D**eterioration **W**arn**ing** **S**ystem, is a mobile-first web application coupled
|
|
with a selection of smart medical devices and a notification service. Prompted by periodic notifications on their phone,
|
|
patients are asked to visit the web-UI, followed by recording their vital parameters using each one of the following devices:
|
|
|
|
- **Withings ScanWatch**: a smart watch capable of measuring heart rate and blood oxygen levels
|
|
- **Withings BPM Core**: a smart blood pressure meter
|
|
- **Withings Thermo**: a smart thermometer
|
|
|
|
These devices are shown the following picture:
|
|
|
|
|
|
|
|
Some UI screenshots of this process are shown here:
|
|
|
|
|
|
|
|
Following the successful measurement using all three devices, Medwings retrieves the recorded vitals data from the Withings API,
|
|
processes it, calculating the patient's MEWS, and stores the results. The patient user is given feedback through the UI and, should
|
|
the resulting MEWS be at a level of concern, an alert is generated.
|
|
|
|
#### Technical Details
|
|
|
|
Medwings was built using the Django framework, and uses a [Gotify Notfication Server](https://gotify.net/) to send mobile
|
|
notifications. It communicates with the Withings Health Data Cloud via the RESTful Withings API, using OAuth2 for authentication of
|
|
requests and to link Withings user accounts to Medwings. The dedicated Gotify Server used by Medwings is also controlled via
|
|
its own REST API.
|
|
|
|
The Medwings application is split itself into the following modules, each handling a specific responsibility:
|
|
|
|
- [core](/app/core/): globally shared files and application-wide configuration
|
|
- [authentication](/app/authentication/): Medwings user and login/logout management
|
|
- [medwings](/app/medwings/): everything related to vitals data processing, storage and MEWS calculation
|
|
- [gotify](/app/gotify/): interfaces to the notification server
|
|
- [withings](/app/withings/): interfaces to the Withings API
|
|
|
|
You can read more about each module and its functionality in each section mentioned above.
|
|
|
|
#### Further Reading
|
|
|
|
For more details about Medwings, its architecture, the development process and the in-depth evaluation and usability
|
|
study of the system, you can read the [complete paper here](/docs/thesis/thesis.pdf).
|
|
|
|
# Development Guide
|
|
|
|
This section contains some notes and references for Medwings developers.
|
|
|
|
## Sensitive Configuration Data
|
|
|
|
To avoid leaking sensitive configuration data, such as database passwords or API keys, all such values are stored in the
|
|
`.env`-file.
|
|
|
|
Prior to running the application, you must create a file called `.env` in the project root.
|
|
The file contains the following environment variables:
|
|
|
|
```conf
|
|
TIMEZONE=Europe/Berlin
|
|
DJANGO_DEBUG_MODE=false
|
|
DJANGO_SECRET_KEY=abc123mySecret
|
|
PG_NAME=medwings
|
|
PG_USER=medwings
|
|
PG_PASSWORD=secret
|
|
PG_HOST=medwings-postgres
|
|
PG_PORT=5432
|
|
GOTIFY_USER=gotify
|
|
GOTIFY_PASSWORD=secret
|
|
GOTIFY_HOST=medwings-gotify
|
|
GOTIFY_PUBLIC_URL=https://notifications.medwings.example.com/
|
|
WITHINGS_CLIENT_ID=abc123myClientId
|
|
WITHINGS_CLIENT_SECRET=abc123myClientSecret
|
|
```
|
|
|
|
You should set the values of the following variables:
|
|
|
|
| variable | description | value |
|
|
|----------|-------------|-------|
|
|
| DJANGO_DEBUG_MODE | whether or not to enable Django's debug mode | 'true' during development and 'false' in production |
|
|
| DJANGO_SECRET_KEY | private session secret | a random string of 64 characters or more |
|
|
| PG_PASSWORD | password for the PostgreSQL admin user | a random string of 32 characters or more |
|
|
| GOTIFY_USER | name of the Gotify admin user | a random string of 32 characters or more |
|
|
| GOTIFY_PASSWORD | password for the Gotify admin user | a random string of 32 characters or more |
|
|
| GOTIFY_PUBLIC_URL | URL where your public Gotify server can be reached | this depends on your deployment environment |
|
|
| WITHINGS_CLIENT_ID | Your Withings API client id | see [Withings API](./app/withings/README.md#api-access) |
|
|
| WITHINGS_CLIENT_SECRET | Your Withings API client secret | see [Withings API](./app/withings/README.md#api-access) |
|
|
|
|
|
|
## Starting the dev environment
|
|
|
|
Once your environment vars are set up, you can run the backend and webserver, by running the following command:
|
|
|
|
```bash
|
|
sudo docker-compose -f development.docker-compose.yml up --force-recreate --build --remove-orphans
|
|
```
|
|
|
|
In a separate terminal, you should also start the frontend asset bundler:
|
|
|
|
```bash
|
|
npm run start
|
|
```
|
|
|
|
It supports file watching and automatic recompilation of the project's CSS and JS bundle.
|
|
|
|
### Running commands inside the container
|
|
|
|
To run commands inside the django container, run the following:
|
|
```bash
|
|
sudo docker exec -itu django medwings-django <command>
|
|
```
|
|
|
|
Run database migrations inside the running container like so:
|
|
|
|
```bash
|
|
sudo docker exec -itu django medwings-django python manage.py migrate
|
|
```
|
|
|
|
To enter django's interactive shell, run:
|
|
```bash
|
|
sudo docker exec -itu django medwings-django python manage.py shell
|
|
```
|