Package: glupredkit
Blood Glucose Prediction-Kit[!NOTE]USER TESTING:If you want to participate in user testing of GluPredKit, and help to shape the further development, send an email tomiriam.k.wolff@ntnu.no. Do not hesitate with reaching out if you have any questions.This Blood Glucose (BG) Prediction Framework streamlines the process of data handling, training, and evaluating blood
glucose prediction models in Python. Access all features via the integrated Command Line Interface (CLI).The figure below illustrates an overview over the pipeline including all the stages of this blood glucose prediction
framework.GluPredKit YouTube-TutorialTable of ContentsSetup and InstallationRegular users: Install using pipDevelopers: Install using the cloned repositoryUsage of Command Line InterfaceGetting StartedParsing DataPreprocessing DataTrain a ModelEvaluate ModelsSetting ConfigurationsContributing with CodeAdding Data Source ParsersAdding Data PreprocessorsAdding Machine Learning Prediction ModelsImplementing Custom Evaluation MetricsAdding Evaluation PlotsDisclaimers and LimitationsLicenseSetup and InstallationTo setup and install this platform, there are two options depending on whether you are a regular user or a developer:Install using pip (regular users):If you want to access the command line interface (CLI) without reading or modifying the code, choose this option.Install using the cloned repository (developers):This is the choice if you want to use the repository and have the code visible, and to potentially edit the code.Choose which one is relevant for you, and follow the instructions below.Regular users: Install using pipOpen your terminal and go to an empty folder in your command line.  Note that all the data storage, trained models and results will be stored in this folder.Creating a virtual environment is optional, but recommended. Python version 3.7, 3.8 or 3.9 is required. Create a
virtual environment with the commandpython -m venv glupredkit_venv, and activate it withsource glupredkit_venv/bin/activate(Mac)
or.glupredkit_venv\Scripts\activate(Windows).To set up the CLI, simply run the following command:pip install glupredkitDevelopers: Install using the cloned repositoryFirst, clone the repository and make sure you are located in the root of the directory in your command line.
To set up the repository with all requirements, simply run the following command:./install.shMake sure that the virtual environmentbgp-evaluationis activated before you proceed. If not, callsource bgp-evaluation/bin/activate.Usage of Command Line InterfaceThe command-line tool is designed to streamline the end-to-end process of data handling, preprocessing, model training, evaluation, and configuration for blood glucose prediction. The following is a guide to using this script.Getting startedFirst, follow the instructions above in "Setup and Installation".Then, navigate to a desired folder in your command line.
This is the folder where the datasets, models and results will be stored.Set up the necessary directories for the GluPredKit CLI by running the following command:For regular users:glupredkit setup_directoriesFor developers:python -m glupredkit.cli setup_directoriesYou should now have the following file structure in your desired folder:data/
│
├── raw/
│
├── configurations/
│
├── trained_models/
│
├── figures/
│
└── reports/Now, you're ready to use the Command Line Interface (CLI) for processing and predicting blood glucose levels.Note that the prefix for all the commands will be eitherglupredkitfor regular users, orpython -m glupredkit.clifor developers.
Theglupredkitprefix will also work while developing, but changes made to the code will only be directly reflected when
using thepython -m glupredkit.cliprefix.
In the examples below we will useglupredkit.The following figure is an overview over all the CLI commands and how they interact with the files in the folders.Parsing DataDescription: Parse data from a chosen source and store it as CSV indata/rawusing the selected parser. If you have an existing dataset, you can store it indata/raw, skip this step and go directly to preprocessing.
If you provide your own dataset, make sure that the dataset and all datatypes are resampled into 5-minute intervals.glupredkit parse --parser [tidepool|nightscout|apple_health|ohio_t1dm] [--username USERNAME] [--password PASSWORD] [--file-path FILE_PATH] [--start-date START_DATE] [--end-date END_DATE]--parser: Choose a parser betweentidepool,nightscout,apple_health, orohio_t1dm.--username(Optional): Your username for the data source (for nightscout, use url).--password(Optional): Your password for the data source (for nightscout, use API-KEY).--file-path: (Optional): The file path to the raw data file that shall be parsed (required for the apple_health parser).For the Ohio T1DM parser, the file path is the folder where thetestandtrainfolder are located. Example:data/raw/.--subject-id: (Optional): The subject id for the data that shall be parsed (required for the Ohio T1DM parser).--start-date(Optional): Start date for data retrieval, default is two weeks ago. Format "dd-mm-yyyy".--end-date(Optional): End date for data retrieval, default is now. Format "dd-mm-yyyy".--output-file-name(Optional): The filename for the output file after parsing, without file extension.Exampleglupredkit parse --parser tidepool --username johndoe@example.com --password mypassword --start-date 01-09-2023 --end-date 30-09-2023
glupredkit parse --parser nightscout --username https://my_nightscout.net/ --password API_KEY --start-date 01-09-2023 --end-date 30-09-2023
glupredkit parse --apple_health --file-path data/raw/export.xml --start-date 01-01-2023
glupredkit parse --parser ohio_t1dm --file-path data/raw/ --subject-id 559Generate Model Training ConfigurationDescription: This command generates a configuration with a given raw dataset, and various settings for training blood glucose predictions. These configurations will be stored indata/configurations/, enabling their reuse for different model approaches and evaluations.glupredkit generate_config--file-name: Give a file name to the configuration. Example:my_config.--data: Name of the input CSV file containing the data. Note that this file needs to be located indata/raw/. Example:df.csv.--preprocessor: The name of the preprocessor that shall be used. The preprocessor must be implemented inglupredkit/preprocessors/. The available preprocessors are:basicohio_t1dm--prediction-horizons: A comma-separated list of prediction horizons (in minutes) used in model training, without spaces. Example:30,60.--num-lagged-features: The number of samples to use as time-lagged features. CGM values are sampled in 5-minute intervals, so 12 samples equals one hour.--num-features: List of numerical features, separated by comma. Note that the feature names must be identical to column names in the input file. Example:CGM,insulin,carbs.--cat-features: List of categorical features, separated by comma. Note that the feature names must be identical to column names in the input file.--test-size: Test size is a number between 0 and 1, that defines the fraction of the data used for testing. Example:0.25. Note that for the Ohio T1DM dataset the test-size is automatically going to use the original separation between train and test data.ExampleUpon executingglupredkit generate_config, you will be sequentially prompted for each of the inputs above.Train a ModelDescription: Train a model using the specified training data.glupredkit train_model MODEL_NAME CONFIG_FILE_NAMEmodel: Name of the model file (without .py) to be trained. The file name must exist inglupredkit/models/. The available models are:arxelastic_netgradient_boosting_treeshuberlassolstmlstm_pytorchrandom_forestridgesvr_linearsvr_rbftcntcn_pytorch (https://github.com/locuslab/TCN/tree/master)config-file-name: Name of the configuration to train the model (without .json). The file name must exist indata/configurations/.Exampleglupredkit train_model ridge my_configCalculate MetricsDescription: Evaluate one or more trained models by computing metrics (for example RMSE). The results will be stored inresults/reports.glupredkit calculate_metrics [--models MODEL_FILE_NAMES] [--metrics METRICS]--models(Optional): List of trained model filenames fromdata/trained_models/(with .pkl), separated by comma. Default is all the models.--metrics(Optional): List of metrics fromglupredkit/metrics/to be computed, separated by comma. Default is RMSE. The available metrics are:Root mean squared error:rmseGlucose-specific root mean squared error:grmse (https://pubmed.ncbi.nlm.nih.gov/22275716/)Mean absolute error:maeMean error:meMean relative error:mreMean absolute relative difference:marePearsons correlation coefficient:pccZones in Clarke error grid:clarke_error_gridZones in Parkes error grid:parkes_error_gridExampleglupredkit calculate_metrics --models ridge_ph-60.pkl,arx_ph-60,svr_linear_ph-60.pkl --metrics rmse,maeDraw PlotsDescription: This command allows users to visualize model predictions using different types of plots. It supports visualization of multiple models and can restrict the plots to certain date ranges or use artificial carbohydrate and insulin inputs for specific visualizations.glupredkit draw_plots--models: Specify the list of trained models you'd like to visualize. Input model names separated by commas, with the ".pkl" extension. By default, all available models will be evaluated.--plots: Define the type of plots to be generated. Input the names of the plots separated by commas. If not specified, a scatter plot will be the default. The available plots are:scatter_plottrajectoriesone_prediction--is-real-time: A boolean flag indicating whether to consider test data without matching true measurements. By default, it is set to False.--start-date: The start date for the predictions. If not set, the first sample from the test data will be used. Input the date in the format "dd-mm-yyyy/hh:mm".--end-date: This serves as either the end date for your range or the specific prediction date for one prediction plots. If left unspecified, the command defaults to using the last sample from the test data. The date format is "dd-mm-yyyy/hh:mm".--carbs: This allows you to set an artificial carbohydrate input for one_prediction plots. This option is only valid when is-real-time is set to True.--insulin: Similar to the carbs option, this lets you provide an artificial insulin input for one_prediction plots. Again, it's only available when is-real-time is True.Exampleglupredkit draw_plots --models ridge_ph-60.pkl,arx_ph-60,svr_linear_ph-60.pkl --plots scatter_plot --start-date 25-10-2023/14:30 --end-date 30-10-2023/16:45Real-Time Prediction PlotsDescription: To achieve real-time predictions, it is necessary to have a data-source that provides real-time data.
Nightscout API can be a real-time API if the insulin management system is uploading data continuously (which is, to our knowledge,
only possible to achieve with open-source insulin management systems). The steps to draw real-time plots are the following:Train one or more models using the steps above.Parse some up-to-date data, using for example the nightscout-parser.Update the model configurations to have the data from (2) as a data source for predictions.Call thedraw_plotscommand with--plots one_predictionand--is-real-time TrueSetting Unit of EvaluationsDescription: Set whether to use mg/dL or mmol/L for units. You can change this after models are trained,
without retraining the models. This only has an impact on the model evaluation (calculate_metricsordraw_plots).glupredkit set_unit --use-mgdl [True|False]Exampleglupredkit set_unit --use-mgdl FalseThat's it! You can now run the desired command with the mentioned arguments. Always refer back to this guide for the correct usage.Contributing with codeIn this section we will explain how you can contribute with enhancing the implementation of parsers, preprocessors, models, evaluation metrics and plots.The following figure is a class diagram of the main components in GluPredKit.Contributing With New ComponentsRegardless of the component type you're contributing, follow these general steps:Navigate to the corresponding directory inglupredkit/.Create a new Python file for your component.Implement your component class, inheriting from the appropriate base class.Add necessary tests and update the documentation.Here are specifics for various component types:ParsersRefers to the fetching of data from data sources (for example Nighscout, Tidepool or Apple Health), and to process the data into the same table.Directory:glupredkit/parsersBase Class:BaseParserAll the parsers should give an output of the same format. Some essential details are:We use pandas DataFrames as output.All datatypes are resampled into 5-minute intervals. If the sample rate is more frequent, the data should be aggregated with for example sum or mean values. If less frequent, NaN values should be used. Interpolation is handled in the preprocessor.The index-column of the dataframe should be the datetime of the sample.Blood glucose values should have the column name "CGM".Carbohydrate intake values should have the column name "carbs".Insulin infusion values should have the column name "insulin".Additional columns and column names are optional.PreprocessorsRefers to the preprocessing of the raw datasets from the parsing-stage. This includes imputation, feature transformation, splitting data etc.Directory:glupredkit/preprocessorsBase Class:BasePreprocessorNote that time-lagged features and other library-specific data-processing is handled in the model implementations, in the methodprocess_datainbase_model.py.
That is because different libraries like scikit-learn, Keras or PyTorch, or model approaches might expect different data-input formats.
For example, time-lagged features might be stored in different ways as in separate columns or as lists in a single column.Machine Learning Prediction ModelsRefers to using preprocessed data to train a blood glucose prediction model.Directory:glupredkit/modelsBase Class:BaseModelThe methodprocess_datainbase_model.pyhandles addition of time-lagged features, removal of NaN values and other
library- or model-specific configurations for the model data input format.Evaluation MetricsRefers to different 'scores' to describing the accuracy of the predictions of a blood glucose prediction model.Directory:glupredkit/metricsBase Class:BaseMetricEvaluation PlotsDifferent types of plots that can illustrate blood glucose predictions together with actual measured values.Directory:glupredkit/plotsBase Class:BasePlotRemember to adhere to our coding and documentation standards when contributing!TestingTo run the tests, writepython tests/test_all.pyin the terminal.Disclaimers and limitationsDatetimes that are fetched from Tidepool API are received converted to timezone offset +00:00. There is no way to get information about the original timezone offset from this data source.Bolus doses that are fetched from Tidepool API does not include the end date of the dose delivery.Metrics assumes mg/dL for the input.Note that the difference between how basal rates are registered. Bolus doses are however consistent across. Hopefully it is negligible.LicenseThis project is licensed under the MIT License - see theLICENSEfile for details