docs/examples/group_pipeline/4.group_data_plotting.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "86d18a92",
   "metadata": {},
   "source": [
    "# Plotting\n",
    "\n",
    "`wearablehrv` does offer a bunch of functions that help you visualize your data and create some meaningful descriptive plots."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03ac931c",
   "metadata": {},
   "source": [
    "<div style=\"border:1px solid; padding:10px; border-radius:5px; margin:10px 0;\">\n",
    "\n",
    "**Note**: Throughout the example notebooks and also in the code, we used the term \"<u>criterion</u>,\" which refers to the device that the rest of the devices are compared against. This is also referred to as \"reference system,\" \"ground truth,\" and \"gold standard\" in the literature. This is usually an electrocardiography (ECG) device.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "902c559e",
   "metadata": {},
   "source": [
    "## Previous Steps\n",
    "\n",
    "If you have not done so, first take a look at the following notebooks:\n",
    "\n",
    "- [How to prepare your data for the group pipeline](https://github.com/Aminsinichi/wearable-hrv/blob/master/docs/examples/group_pipeline/1.group_data_preparation.ipynb)\n",
    "- [Determine the signal quality of your wearables](https://github.com/Aminsinichi/wearable-hrv/blob/master/docs/examples/group_pipeline/2.group_signal_quality.ipynb)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29a9a8c3",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Importing Module\n",
    "import wearablehrv"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "105e409e",
   "metadata": {},
   "source": [
    "The code in the following cell has been explained in the previous notebook. Run it, so we can continue with the examples in this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b64ca9c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.data.clear_wearablehrv_cache() \n",
    "path = wearablehrv.data.download_data_and_get_path([\"P01.csv\", \"P02.csv\", \"P03.csv\", \"P04.csv\", \"P05.csv\", \"P06.csv\", \"P07.csv\", \"P08.csv\", \"P09.csv\", \"P10.csv\"])\n",
    "conditions = ['sitting', 'arithmetic', 'recovery', 'standing', 'breathing', 'neurotask', 'walking', 'biking'] \n",
    "devices = [\"kyto\", \"heartmath\", \"rhythm\", \"empatica\", \"vu\"] \n",
    "criterion = \"vu\" \n",
    "features = [\"rmssd\", \"hf\",'pnni_50','mean_hr','sdnn', 'nibi_after_cropping', 'artefact'] \n",
    "data, file_names = wearablehrv.group.import_data (path, conditions, devices, features)\n",
    "data = wearablehrv.group.nan_handling (data, devices, features, conditions) \n",
    "data, features, summary_df, quality_df = wearablehrv.group.signal_quality (data, path, conditions, devices, features, criterion,  file_names, exclude = False, save_as_csv = False, ibi_threshold = 0.20, artefact_threshold = 0.20, manual_missing=False, missing_threshold=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "02657cf8",
   "metadata": {},
   "source": [
    "**Violin Plot**\n",
    "\n",
    "It creates violin plots for you. On the x-axis, you will have your devices, and on the y-axis, you have your selected feature (you can select a feature and condition using the widgets). If you keep your cursor on a plot, you will get the exact values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08428ccd",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.violin_plot (data, conditions, features, devices)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8bb97263",
   "metadata": {},
   "source": [
    "\n",
    "**Box Plot**\n",
    "\n",
    "Similar to the violin plots, but it creates a box plot for you."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "464168a4",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.box_plot (data, conditions, features, devices)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9abdeb8e",
   "metadata": {},
   "source": [
    "\n",
    "**Radar Plot**\n",
    "\n",
    "We had this function also in the Individual pipeline, but it actually makes more sense to create such a plot when you have data from multiple participants. It shows how mean HR, RMSSD, SDNN, and PNN50 for each selected device, in a selected condition, map onto the counterpart in the criterion device and can immediately give you a sense of how well devices agree with one another in different conditions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b09ec01",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.radar_plot (data, criterion, conditions, devices)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8bc6a9d",
   "metadata": {},
   "source": [
    "\n",
    "**Histogram Plot**\n",
    "\n",
    "If you are curious about the distribution of the outcome variables in different conditions (especially for performing statistical analysis, whether or not to log-transform data, etc.), this plot comes in handy.\n",
    "\n",
    "**Note**: We are plotting very few data here; hence the shape of the distribution looks ugly!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "670e8caf",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.hist_plot (data, conditions, features, devices)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1cb87ec",
   "metadata": {},
   "source": [
    "**Bar Plot**\n",
    "\n",
    "Simple bar plots, with the standard error of the mean."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fa12f102",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.bar_plot (data, conditions, features, devices)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e9b642a",
   "metadata": {},
   "source": [
    "**Matrix Plot**\n",
    "\n",
    "This can come in very handy if you want to see underlying data :) This function creates a heatmap to plot the data. The heatmap displays a specific feature for different participants and devices for a specific condition. The heatmap allows for easy comparison of the feature values across participants and devices. For example, by using this map, it can be observed that a device is systematically overestimating or underestimating a given feature.\n",
    "\n",
    "**Note:** If you have many participants, you may encounter errors when producing the figure. In this case, you can subselect a portion of your participants by modifying the variable `file_names`. For example, to select the first 20 participants, you can use: `file_names[0:20]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5dd9524",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.matrix_plot (data, file_names, conditions, features, devices)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fee49e75",
   "metadata": {},
   "source": [
    "You can, for instance, easily see that the colors are darker for the \"rhythm\" device for RMSSD values, hence it is overestimating compared to the criterion (\"vu\"). The blank rows correspond to the missing values."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cceff6ed",
   "metadata": {},
   "source": [
    "That's it! We have covered all functionalities of the `wearablehrv` Python package. :)\n",
    "\n",
    "## The End"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}