docs/examples/group_pipeline/2.group_signal_quality.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4fd2224e",
   "metadata": {},
   "source": [
    "# Signal Quality\n",
    "\n",
    "After you load the data from all your participants, which includes calculated outcome variables for HR and HRV in all devices and experimental conditions, an important step is to determine the overall signal quality in each device and condition.\n",
    "\n",
    "`wearablehrv` makes this really easy by incorporating a comprehensive signal quality check function. It also enables you to generate informative .csv reports and visualizations that can immediately help you understand the signal quality of your devices."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4eeb7fee",
   "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": "1c9209e4",
   "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)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cf378e3a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Importing Module\n",
    "import wearablehrv"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32619eff",
   "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": "dba7450a",
   "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) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3ef96a0",
   "metadata": {},
   "source": [
    "## Calculating Signal Quality"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1eef00a0",
   "metadata": {},
   "source": [
    "`signal_quality` function helps you report signal quiality and to exclude readings from the devices where the signal quality is deemed insufficient according to certain thresholds. Exclusion of the poor data is optional, and is a matter of preference.\n",
    "\n",
    "Two key metrics are used to determine signal quality:\n",
    "\n",
    "- `nibi_after_cropping`: The number of detected beat-to-beat intervals. A difference of more than `ibi_threshold` (20% by default) between a given device and the criterion device for the same participant and condition indicates a poor signal.\n",
    "\n",
    "- `artefact`: The number of detected artefacts. If the artefacts represent more than `artefact_threshold` (20% by default) of the detected beats in the given device for the same participant and condition, this also indicates a poor signal.\n",
    "\n",
    "If `exclude = True`, <u>all feature</u> values for that participant and condition will be replaced with empty lists. Otherwise, they are kept for further analysis.\n",
    "\n",
    "Both the `ibi_threshold` and `artefact_threshold` parameters can be tuned according to the specific needs of your analysis. A lower value makes the criteria more stringent, leading to more readings being excluded, while a higher value makes the criteria more lenient, leading to fewer exclusions.\n",
    "\n",
    "In cases where very few beats are detected in your signal, you may consider manually flagging them as missing. To do this, set `manual_missing=True`, and define a `missing_threshold`. For example, setting `missing_threshold` to 10 means that if only 10 beats are detected, the signal will be flagged as missing.\n",
    "\n",
    "After processing, the code generates two pandas dataframes that can be saved if `save_as_csv = True`:\n",
    "\n",
    "- `quality_report1.csv`: Detailed report showing for each participant, device, and condition, the number of detected beats and artefacts, and the decision to keep or exclude the data.\n",
    "\n",
    "- `quality_report2.csv`: Summary report showing the total count and percentage of decisions (\"Acceptable\", \"Poor\", \"Missing\") for each device and condition.\n",
    "\n",
    "The function saves the outputs of the signal quality assessment in two variables, `summary_df` and `quality_df`, which can be used for further plotting in the upcoming functions.\n",
    "\n",
    "At the end of the process, 'artefact' and 'nibi_after_cropping' data is removed from the `data` and `features` variable.\n",
    "\n",
    "**Note: it is important to run this code, even though you may not wish to save the reports or exclude the outliers.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bd95959e",
   "metadata": {},
   "outputs": [],
   "source": [
    "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": "cf02b502",
   "metadata": {},
   "source": [
    "`quality_df` shows you for each device, participant, condition, how many beats were detected in that device, in the criterion device, and how many artifacts were detected in the device. It also then gives you the decision made based on the thresholds you define, whether this is an acceptable signal quality, poor, or whether the data is missing. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3c90f169",
   "metadata": {},
   "outputs": [],
   "source": [
    "quality_df"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc0b9dcf",
   "metadata": {},
   "source": [
    "It is then really convenient to immediately check, for instance, if you want to know in the \"sitting\" condition, in the \"heartmath\" device, how the signal quality looks like, by running the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d1f31bf5",
   "metadata": {},
   "outputs": [],
   "source": [
    "quality_df[(quality_df[\"Device\"] == \"heartmath\") & (quality_df[\"Condition\"] == \"sitting\")][\"Decision\"].value_counts()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f51f976",
   "metadata": {},
   "source": [
    "If you take a look at the `summary_df`, you can see it's a dataframe. You can clearly see some interesting patterns: for instance, for the Empatica device, out of 4 available participants (Total = 4), none of the signal qualities was acceptable in the biking condition.\n",
    "\n",
    "What constitutes a poor signal again? Based on the threshold we used, either more than 20% of the detected beats included artifacts, or detected beats in Empatica in this condition deviated more than 20% from the criterion (VU) device. That would be considered a poor signal for us here.\n",
    "\n",
    "Obviously, you can change these thresholds and get different results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2f26c65e",
   "metadata": {},
   "outputs": [],
   "source": [
    "summary_df"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9336f00",
   "metadata": {},
   "source": [
    "## Plotting Signal Quality"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f2702eed",
   "metadata": {},
   "source": [
    "After using the `signal_quality` function, you now have two plotting options to visually inspect your signal quality. \n",
    "\n",
    "To use `signal_quality_plot1`, you first need to define a `condition_mapping` dictionary that helps you group together the conditions and plot them in a more meaningful way. For instance, it can be based on your guess about the movement involved in each condition (or objectively based on accelerometer data, if available), or anything else that you wish. You can exclude the criterion device from being included in the calculation of the plot, if `criterion_exclusion = True`. If `device_selection = False`, this plot is created regardless of the devices (pooled together), whereas if you wish to plot the signal quality for a specific device, then set `device_selection = True`, and select the device, for instance, by `device = 'empatica'`. An example of a `condition_mapping` dictionary is as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8151c8e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Categorizing conditions\n",
    "condition_mapping = {\n",
    "    'sitting': 'no movement', \n",
    "    'recovery': 'no movement', \n",
    "    'breathing': 'no movement', \n",
    "    'standing': 'no movement',\n",
    "    'arithmetic': 'subtle movement', \n",
    "    'neurotask': 'subtle movement',\n",
    "    'walking': 'involves movement', \n",
    "    'biking': 'involves movement'\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb10df66",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.signal_quality_plot1 (summary_df, condition_mapping, criterion, device_selection = False, device=None, criterion_exclusion = True, x_label = \"'Condition Categories\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "530351aa",
   "metadata": {},
   "source": [
    "You can now see that, in the conditions that involved movement (defined by me as \"walking\" and \"biking\" conditions), almost 48.75% of the signal was flagged as poor based on the defined criteria. 25% is also missing, and only 26.25% is acceptable.\n",
    "\n",
    "If you wish to see for a specific device, let's say, \"heartmath,\" you can run the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6dd4b83b",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.signal_quality_plot1 (summary_df, condition_mapping, criterion, device_selection = True, device=\"heartmath\", criterion_exclusion = True, x_label = \"'Condition Categories\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1cf445c",
   "metadata": {},
   "source": [
    "Which you can see looks a lot better! "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ddc44cc7",
   "metadata": {},
   "source": [
    "You can also plot the signal quality for each device, regardless of the conditions, using the `signal_quality_plot2` function. If you wish to zoom into a specific condition, set `condition_selection = True`, and select the condition, for instance: `condition = \"sitting\"`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2badfe68",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.signal_quality_plot2 (summary_df, condition_selection=False, condition=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5156ed70",
   "metadata": {},
   "source": [
    "Here, for instance, you can see the overall device \"rhythm\" showing poor signal quality in all conditions 73.75% of the time. What if you zoom into, let's say, the \"sitting\" condition? "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e8df1093",
   "metadata": {},
   "outputs": [],
   "source": [
    "wearablehrv.group.signal_quality_plot2 (summary_df, condition_selection=True, condition=\"sitting\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12e06826",
   "metadata": {},
   "source": [
    "Then it's a bit better (50% poor signal quality)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4d5cafa",
   "metadata": {},
   "source": [
    "That's it! At this point, you should have been able to determine your signal quality, which is a very essential component in reporting the validation of the devices.\n",
    "\n",
    "## Next Steps\n",
    "\n",
    "You're now ready to move on to the next notebook examples. \n",
    "\n",
    "Continue by consulting: \n",
    "\n",
    "- [Perform four major statistical analyses to determine validity](https://github.com/Aminsinichi/wearable-hrv/blob/master/docs/examples/group_pipeline/3.group_data_analysis.ipynb)"
   ]
  }
 ],
 "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
}