Predictor Variable Time Series Classification (VarCls)

Polytechnic University of Bucharest

Description

The objective of the Predictor Variable Time Series Classification service (VarCls) is to allow medical practitioners to make predictions about a future health status of PMSS (Parkinson’s Disease, Multiple Sclerosis and Stroke) patients, given a history of tracked predictor variables.

The health status of the patient is determined as:

  • A threshold-based classification of a standardized medical test (e.g. Hoehn & Yahr or MDS-UPDRS scales for PD; Romberg, MRS scales for Stroke; EDSS scale for MS).
  • A medical practitioner defined classification problem where the classes are defined based on an interpretation of the medical practitioner of a set of medical test results which provide the target health status.

The predictor variables are obtained based on a long term (year long) observation of the patient, during which data is collected from two main sources:

  • Objective measurements obtained from wearable devices (e.g. smart watch, accelerometer-based bracelet, an accelerometer-based smart belt, pressure sensor based insoles)
  • Subjective Patient Reported Outcomes (PROs) obtained from the interactions of the patient with the ALAMEDA Software Applications (the questionnaire service, the conversational agent, the mood estimation application)

The target variables (health status estimates) are obtained by performing standardized clinical evaluations at specific milestones (e.g. every 3 or 6 months - depending on pilot study).

Documentation

Inputs and Outputs

The input to the VarCls service is a set of time series, where each time series pertains to one predictor variable. The values of the predictor variables are obtained from the following ALAMEDA toolkits:

  • The Semantic Knowledge Graph which contains knowledge about the results obtained from PROs filled in by patients throughout the observation period.
  • The Gait Analysis Toolkit which provides information about gait metrics, daily activity metrics and physical rehabilitation exercise detection.
  • The Facial Emotion Recognition Toolkit which provides mood estimations based on facial expression analysis, whenever the patient is interacting with an ALAMEDA Software Application.
  • The Conversational Sentiment Analysis Service which provides mood estimations based on text analysis, whenever the patient engages in free-text dialogue with the ALAMEDA Conversational Agent.
  • The ENORA Sleep Monitoring Service which provides information about sleep metrics based on a combined input from wearable devices (e.g. Fitbit Smartwatch, accelerometer-based bracelet) and smart mattresses (e.g. Withings Sleep Mat).

The exact set of PRO results and toolkit extracted metrics is specific to each monitored disease (PD, MS and Stroke).

The inputs are provided to the VarCls service as a CSV file, whereby each row contains the values of predictor variables, as well as information about the timestamp of the measurement and the patientID to which the measurement belongs.

The service invocation also requires the specification of an AI model name to use in the prediction (see Section on AI Models).

The output of the VarCls service is a CSV file containing one or more target variables together with the probability distribution for each target variable value.

AI Models

Several AI models underlie the VarCls service. Each AI model is specific to the target variable of a particular neurological disease (PD, MS or Stroke).

The VarCls service operates with input time series whose variable values are numerical (e.g. number of steps performed during a day, number of hours slept, average walking speed throughout a day), categorical (e.g. estimated mood state) or ordinal (e.g. Likert-scale response on a questionnaire) in nature.

As such, the employed AI models fall under two main categories:

  • Aggregative feature extraction: this class of models will make use of statistical feature extraction over time series windows, to which ensemble models such as RandomForest or XGBoost classifiers are applied.
  • Express time series classification: make use of well-known time series classification models (e.g. BOSSEnsemble, Catch22Classifier, SupervisedTimeSeriesForest, TSFreshClassifier, HIVE COTE v2) to directly classify the time series of predictor variables.

Installation Ιnstructions

TThe VarCls service is implemented as a dockerized web-service containing three principle sub-services:

  • The VarCls Service containing the endpoints of the web service
  • A Celery worker that handles evaluation and classification tasks submitted to the VarCls server
  • A Redis cache database that acts as a queue manager and result cache for the tasks of the VarCls service

To run the service locally the following installation pre-requisites are necessary

  • Python 3.9+
  • Install docker and docker compose
  • Install the Python libraries in the requirements.txt file. Consider using a Python environment set up using pip or conda.

Building VarCls Image

After installing the pre-requisits proceed with building the image underlying the VarCls Server and Celery worker containers:

  • Navigate to the top directory in which you cloned this repository
  • Run docker compose build

Starting VarCls Server

To start the service locally navigate to the top directory in which you cloned the repository and run docker compose up. Add the the -d option if you wish to start the services in daemon mode.

Using the VarCls service

Once deployed the VarCls service will listen for HTTP connections on port 8080.

IMPORTANT NOTE

  • All requests to the VarCls service require an ALAMEDA IAM authenticated client. This translates into a requirement for all requests to include an Authorization Header in the HTTP call with the format: Bearer , where the access_token has been obtained after authenticating with the ALAMEDA IAM backend endpoint.

There are four steps to the interaction with the service:

  • Preparing a model invocation by uploading the required input files
  • Invoking a model in either predictive or evaluation mode. Predictive mode requires only the input for one or more test subjects and is expected to return a model dependent classification of their health status, together with a probabilistic certainty value of the assignment. Evaluation mode requires the additional presence of a ground truth variable against which model performance metrics can be computed and returned as output.
  • Reading the result
  • Deleting the invocation

OpenAPI Documentation

View Swagger Documentation