docs: flesh out README #7

Merged
jlobbes merged 2 commits from submission into master 2023-12-03 22:34:21 +00:00
8 changed files with 99 additions and 18 deletions
Showing only changes of commit 90c98e03b3 - Show all commits

2
.gitignore vendored
View File

@ -29,7 +29,9 @@
**/*.out **/*.out
**/*.run.xml **/*.run.xml
docs/proposal/*.pdf docs/proposal/*.pdf
!docs/proposal/proposal.pdf
docs/thesis/*.pdf docs/thesis/*.pdf
!docs/thesis/thesis.pdf
# Drawio backup and lock files # Drawio backup and lock files
**/*.drawio.bkp **/*.drawio.bkp

View File

@ -1,25 +1,88 @@
# MEDWings # Bachelor Thesis: Medwings
Medwings is the *Mobile Early Deterioration Warning System*. This repository contains the software, research data and final thesis I worked on
It is a proof of concept for a remote patient monitoring system, designed for use by elevated-risk patients as part of my Computer Science degree at TU Braunschweig.
outside of direct medical supervision, such as at home or on the go.
The application utilizes smart medical devices to access vitals data gathered by users remotely. My research examined the current state of research in mobile patient deterioration monitoring,
Data is aggregated, and a clinical early warning score is calculated based on the readings. 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.
The Medwings application is split into different modules, each handling a specific responsibility: 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.
- [core](./app/core/README.md): global files and configuration ## Overview
- [authentication](./app/authentication/README.md): user creation and login/logout management
- [medwings](./app/medwings/README.md): everything related to vitals data and MEWS calculation > **Clinical Deterioration**: A measurable overall decline in a patient's vital functions, preceeding critical adverse outcomes.
- [gotify](./app/gotify/README.md): interfaces to the notification server
- [withings](./app/withings/README.md): interfaces to the Withings API 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:
![MEWS Scoring Table](/docs/figures/mews-calculation-table.png)
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:
![Withings Smart Medical Devices](/docs/figures/withings-devices.png)
Some UI screenshots of this process are shown here:
![Medwings Measurement Screenshots](/docs/figures/medwings-measurement-screenshots.png)
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. You can read more about each module and its functionality in each section mentioned above.
## Development #### Further Reading
### Sensitive Configuration Data 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 To avoid leaking sensitive configuration data, such as database passwords or API keys, all such values are stored in the
`.env`-file. `.env`-file.
@ -58,7 +121,7 @@ You should set the values of the following variables:
| WITHINGS_CLIENT_SECRET | Your Withings API client secret | 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 ## Starting the dev environment
Once your environment vars are set up, you can run the backend and webserver, by running the following command: Once your environment vars are set up, you can run the backend and webserver, by running the following command:
@ -74,7 +137,7 @@ npm run start
It supports file watching and automatic recompilation of the project's CSS and JS bundle. It supports file watching and automatic recompilation of the project's CSS and JS bundle.
#### Running commands inside the container ### Running commands inside the container
To run commands inside the django container, run the following: To run commands inside the django container, run the following:
```bash ```bash

Binary file not shown.

After

Width:  |  Height:  |  Size: 425 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 121 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 MiB

BIN
docs/proposal/proposal.pdf Normal file

Binary file not shown.

BIN
docs/thesis/thesis.pdf Normal file

Binary file not shown.

View File

@ -1463,7 +1463,7 @@ With the help of the trial data, the developed software system should be evaluat
\vspace{2cm} \vspace{2cm}
Braunschweig, 12.09.2023 \\ Braunschweig, 12.09.2023 \\
\vspace{0.5cm} \vspace{0.5cm}
\hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/admin/signature.png} \hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/templates/graphics/written-signature.png}
\end{raggedleft} \end{raggedleft}
\newpage \newpage
@ -1481,7 +1481,23 @@ Ferner versichere ich, dass es sich hier um eine Originalarbeit handelt, die noc
\vspace{2cm} \vspace{2cm}
Braunschweig, 12.09.2023 \\ Braunschweig, 12.09.2023 \\
\vspace{0.5cm} \vspace{0.5cm}
\hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/admin/signature.png} \hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/templates/graphics/written-signature.png}
\end{raggedleft}
\newpage
\section*{Erklärung zur Abgabe der gedruckten Abschlussarbeit}
\addcontentsline{toc}{section}{Erklärung zur Abgabe der gedruckten Abschlussarbeit}
Hiermit versichere ich, dass die vorliegende gedruckte Abschlussarbeit
mit der elektronisch abgegebenen (hochgeladenen) Abschlussarbeit exakt
übereinstimmt und dass ich keine unerlaubten Änderungen vorgenommen
habe.
\begin{raggedleft}
\vspace{2cm}
Braunschweig, 12.09.2023 \\
\vspace{0.5cm}
\hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/templates/graphics/written-signature.png}
\end{raggedleft} \end{raggedleft}
\end{document} \end{document}