Home

Awesome

Overview of PhysioKit

Authors: Jitesh Joshi, Katherine Wang, and Youngjun Cho <br> Contact: Computational Physiology and Intelligence group @ GDIH - WHO Collaboration Centre for Assistive Technology, UCL Computer Science (youngjun.cho@ucl.ac.uk)

PhysioKit is a novel physiological computing toolkit which is open-source, accessible and affordable. HCI hobbyists and practitioners can easily access physiological sensing channels that help monitor our physiological signatures and vital signs including heart rate, heart rate variability, breathing rate, electrodermal activities. The toolkit works with a low-cost micro-controller such as Arduino. Currently, it supports acquiring EDA, Resp and PPG using any low-cost Arduino board.

PhysioKit consists of (i) a sensor and hardware layer that can be configured in a modular manner along with research needs, (ii) a software application layer that enables real-time data collection, streaming and visualization for both single and multi-user experiments. This also supports basic visual biofeedback configurations and multi-signal synchronization for co-located or remote multi-user settings.

Below figure shows architecture of PhysioKit:

<p> <img src="https://github.com/PhysiologicAILab/PhysioKit/blob/f7275eed520d33ca7d10f65d186b188e3af427a7/images/architecture.png" alt="Architecture of PhysioKit" width="1024"/> </p>

Installation

Pre-requisite: Python >= 3.8

It is recommended to create separate Python virtual environment, which can be achieved using venv/ anaconda/ miniconda as follows. After creating the environment, activate the same.

Using venv:

Creating virtual environment using venv (recommended for Windows users) -- To be executed once.

cd ~
mkdir envs
cd envs
python -m venv phys .

Activating "phys" environment -- To be executed everytime after opening new terminal/ Powershell window.

~/envs/phys/Scripts/Activate.ps1

Using conda:

Creating virtual environment using conda -- To be done once

conda create -n phys

Activating "phys" environment -- To be executed everytime after opening new terminal/ Powershell window.

conda activate phys

You can then use PyPI package to install PhysioKit, using the below mentioned command:

pip install PhysioKit2

To update the currently installed package:

pip install --upgrade PhysioKit2

Building wheel (.whl) package from source

Requires 'build' package that can be installed using pip with following command:

pip install build

Clone the PhysioKit repository from GitHub and 'cd' to the clonned repo:

git clone https://github.com/PhysiologicAILab/PhysioKit.git
cd PhysioKit

Make the changes to the repo as required to serve your objectives. In setup.py, change the version - for your tracking purpose, e.g. 2.0.0 and then build the wheel package:

python -m build

Install the package that has been built:

python -m pip install .\dist\PhysioKit2-2.0.0-py3-none-any.whl

Usage Instructions

Step-1: Upload program on the Arduino board

Connect the Arduino board that you want to use. For this step, the sensors need not be connected. Navigate to "arduino/default" folder (for AVR family boards which are most common, e.g. Nano, Uno, Mega) and as per the number of sensors that you want to use, go to the respective folder and open the ".ino" file using Arduino IDE. For example, if you want to use all three supported sensors, you may choose "three_sensors" folder and open "three_sensors.ino". "four_sensors.ino" can be used in a setting where two pulse sensors (at different sensor sites, e.g. finger, ear) are to be used.

Having identified the correct Arduino program, upload the same to the Arduino board using Arduino IDE. If you are unfamiliar with this step, you may have a look at this tutorial for detailed instructions on how to upload program on Arduino board. The Arduino program files for Arm based board (e.g. Due) are also provided at "arduino/due" folder, which can be similarly used.

The default sampling rate is 250 samples per second for all boards. If you need to change this, please follow the comments written in the arduino code. Similarly, the default baudrate for AVR boards is set to 115200. To set a different baudrate, both the Arduino program and software configuration file (e.g. configs/avr_default/sw_config.json) are required to be changed appropriately.

Step-2: Choose or Update Software Configuration File

If no changes have been made to Arduino program, then it is only required to identify the correct software configuration file. For single-user scenario and default AVR family boards, the config file to be used is configs/avr_default/sw_config.json. In this config file, external_sync is specified with enable field set to false.

For multi-user settings, external_sync is specified with enable field set to true. Depending on the role speficied for the computer, it can serve either as server or as client - for which one of the two config files - sw_config_server.json or sw_config_client.json can be used.

While no changes are required for sw_config_server.json, the client field in the sw_config_client.json file is required to specify the "server_ip" address. Please ensure that the "server_ip" address is reachable, and both the clients and the server are on the same enterprise network, or reachable using VPN.

Step-3: Update Experiment Configuration File

Experiment configuration file needs to be updated as per the study protocol. This is described below with an illustration of the experiment configuration file used for the validation study of PhysioKit.

Study name and conditions field once specified, are used by the interface to store the acquired data. There are no restrictions on the number of experimental conditions that can be added here.

channels are the user-facing names of the sensors that are used in the study. For the interface to plot signals with physiological signal specific filtering, it is required to correctly specify the channel_types. The order of channels, channel_types and the connection of physiological sensors on the analog channels of Arduino board shall match precisely.

If the study protocol requires acquisition for indefinitely long duration with manual stop, then timed_acquisition can be specified as False, otherwise in every other scenario, this is to be set as true. If this is specified as true, it is required to specify the acquisition duration (in seconds) separately for each experimental condition.

Using the datapath field, we can specify the path at which the acquired data with get stored.

Lastly, as the interface supports marking of asynchronous events, the description about the type of events along with event_code can be specified.

{
    "exp":
    {
        "study_name": "PhysioKit_Validation",
        "conditions": ["baseline", "mathEasy", "mathDifficult", "movement"],
        "channels": ["EDA", "Resp", "PPG Finger", "PPG Ear"],
        "channel_types": ["eda", "resp", "ppg", "ppg"],
        "timed_acquisition": true,
        "assess_signal_quality": true,
        "max_time_seconds": [180, 180, 180, 180],
        "datapath": "data",
        "event_codes":{
            "0": "event_1",
            "1": "event_2"
        }

    },
    "biofeedback":
    {
        "enabled": false,
        "ch_index": 3,
        "metric": "HRV_MeanNN",
        "window": 10,
        "step": 1,
        "modulation_threshold": 2,
        "mapping": "linear_increase",
        "type": "visual",
        "visual_feedback": {
            "shape": "circle",
            "varying_parameter": "size"
        }
    }
}

Step-4: Launch the PhysioKit Interface

Before launching the interface, ensure that the Arduino board is connected to the computer using USB connection or through Bluetooth connection. At this step, sensors are required to be appropriately connected to the analog channels of Arduino board.

To launch the interface, run the following command in the terminal:

physiokit --config <path of config file>
see example below 
physiokit --config configs/avr_default/sw_config.json

This shall open user interface, basic functioning of which is shown in this demo. Please note that if secondary screen is connected, the interface uses it to adjust its resolution, however it may have to be moved to the secondary screen if it got launched on the primary.

<p> <img src="https://github.com/PhysiologicAILab/PhysioKit/blob/f7275eed520d33ca7d10f65d186b188e3af427a7/images/PhysioKitDemo.gif" alt="Demo of PhysioKit" width="1024"/> </p>

A brief description of each step is mentioned below:

Data Analysis

Data analysis is supported by the analysis_helper folder. To extract features and export in spreadsheet, please refer to the README provided within the folder. In addition, Jupyter notebooks phys_analysis_eda.ipynb, phys_analysis_ppg.ipynb, and phys_analysis_resp.ipynb are provided to illustrate basic analysis steps. This includes pre-processing as well as feature extraction for EDA, PPG and Resp signals respectively.

Additional Support or Reporting Issues with the Library

Please use Github's Issues to report any problem you face while using the PhysioKit.

Citation

If you find our paper or this toolkit useful for your research, please cite our following works.

@article{joshi2023physiokit,
    title={PhysioKit: An Open-Source, Low-Cost Physiological Computing Toolkit for Single-and Multi-User Studies},
    author={Joshi, Jitesh and Wang, Katherine and Cho, Youngjun},
    journal={Sensors},
    publisher={MDPI},
    volume={23},
    number={19},
    article-number={8244},
    year={2023},
    url={https://www.mdpi.com/1424-8220/23/19/8244}
    issn={1424-8220},
    doi={10.3390/s23198244}
}

@article{joshi2024ibvp,
    title={iBVP Dataset: RGB-Thermal rPPG Dataset with High Resolution Signal Quality Labels},
    author={Joshi, Jitesh and Cho, Youngjun},
    journal={Electronics},
    publisher={MDPI},
    volume={13},
    year={2024},
    number={7},
    article-number={1334},
    url={https://www.mdpi.com/2079-9292/13/7/1334},
    issn={2079-9292},
    doi={10.3390/electronics13071334}
}