docs/examples/individual_pipeline/3.individual_data_analysis.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2cff9a48",
   "metadata": {},
   "source": [
    "# Data Analysis, and Saving Data\n",
    "\n",
    "As a final step for each individual participant, we can calculate some outcome measures in which we are interested for HR and HRV. We can calculate things like RMSSD, mean heart rate, HF, LF frequency, etc. These are things that, later at the group level, we can compare between each of our devices and the criterion device, and see how much they agree with one another."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a48f3c6",
   "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": "698b8398",
   "metadata": {},
   "source": [
    "## Previous Steps\n",
    "\n",
    "If you have not done so, first take a look at the following notebooks:\n",
    "\n",
    "- [Preprocess your data](https://github.com/Aminsinichi/wearable-hrv/blob/master/docs/examples/individual_pipeline/2.individual_data_preprocessing.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "437bab1a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Importing Module\n",
    "import wearablehrv"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "acab2345",
   "metadata": {},
   "source": [
    "The code in the following cell has been explained in the previous notebooks. Run it, so we can continue with the examples in this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2da3ac0",
   "metadata": {},
   "outputs": [],
   "source": [
    "path = wearablehrv.data.download_data_and_get_path()\n",
    "pp = \"test\" \n",
    "conditions = ['sitting', 'arithmetic', 'recovery', 'standing', 'breathing', 'neurotask', 'walking', 'biking'] \n",
    "devices = [\"kyto\", \"heartmath\", \"rhythm\", \"empatica\", \"vu\"]  \n",
    "criterion = \"vu\" \n",
    "events = wearablehrv.individual.define_events (path, pp, conditions, already_saved= True, save_as_csv= False)\n",
    "data = wearablehrv.individual.import_data (path, pp, devices)\n",
    "data_chopped = wearablehrv.individual.chop_data (data, conditions, events, devices)\n",
    "nibi_before_cropping = wearablehrv.individual.calculate_ibi (data_chopped, devices, conditions)\n",
    "nibi_after_cropping = wearablehrv.individual.calculate_ibi (data_chopped, devices, conditions)\n",
    "data_pp, data_chopped = wearablehrv.individual.pre_processing (data_chopped, devices, conditions, method=\"karlsson\", custom_removing_rule = 0.25, low_rri=300, high_rri=2000)\n",
    "artefact = wearablehrv.individual.calculate_artefact (data_chopped, data_pp, devices, conditions)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4ceb468",
   "metadata": {},
   "source": [
    "## Data Analysis "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "995d4a4b",
   "metadata": {},
   "source": [
    "To calculate the relevant HR and HRV outcome variables, we incorporated a function from the [`hrvanalysis`](https://aura-healthcare.github.io/hrv-analysis/hrvanalysis.html) library that calculates a good number of time-domain and frequency-domain feature extractions. You can achieve this by running the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "585dd2e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "time_domain_features, frequency_domain_features = wearablehrv.individual.data_analysis (data_pp, devices, conditions)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e60fa957",
   "metadata": {},
   "source": [
    "Below, you can see an overview of the outcome measures that were calculated, and you can use them to establish the agreement between a device and the criterion device.\n",
    "\n",
    "**Time Domain Features:**\n",
    "\n",
    "- `mean_nni`: Mean of RR-intervals.\n",
    "- `sdnn`: Standard deviation of the time interval between successive normal heart beats (i.e. the RR-intervals).\n",
    "- `sdsd`: Standard deviation of differences between adjacent RR-intervals.\n",
    "- `rmssd`: Square root of the mean of the sum of the squares of differences between adjacent NN-intervals. Reflects high frequency (fast or parasympathetic) influences on hrV (i.e., those influencing larger changes from one beat to the next).\n",
    "- `median_nni`: Median Absolute values of the successive differences between the RR-intervals.\n",
    "- `nni_50`: Number of interval differences of successive RR-intervals greater than 50 ms.\n",
    "- `pnni_50`: Proportion derived by dividing nni_50 (The number of interval differences of successive RR-intervals greater than 50 ms) by the total number of RR-intervals.\n",
    "- `nni_20`: Number of interval differences of successive RR-intervals greater than 20 ms.\n",
    "- `pnni_20`: Proportion derived by dividing nni_20 (The number of interval differences of successive RR-intervals greater than 20 ms) by the total number of RR-intervals.\n",
    "- `range_nni`: Difference between the maximum and minimum nn_interval.\n",
    "- `cvsd`: Coefficient of variation of successive differences equal to the rmssd divided by mean_nni.\n",
    "- `cvnni`: Coefficient of variation equal to the ratio of sdnn divided by mean_nni.\n",
    "- `mean_hr`: Mean Heart Rate.\n",
    "- `max_hr`: Maximum Heart Rate.\n",
    "- `min_hr`: Minimum Heart Rate.\n",
    "- `std_hr`: Standard deviation of heart rate.\n",
    "\n",
    "**Frequency Domain Features:**\n",
    "\n",
    "- `total_power`: Total power density spectral.\n",
    "- `vlf`: Variance ( = power ) in HRV in the Very low Frequency (.003 to .04 Hz by default). Reflects an intrinsic rhythm produced by the heart which is modulated primarily by sympathetic activity.\n",
    "- `lf`: Variance ( = power ) in HRV in the low Frequency (.04 to .15 Hz). Reflects a mixture of sympathetic and parasympathetic activity, but in long-term recordings, it reflects sympathetic activity and can be reduced by the beta-adrenergic antagonist propanolol.\n",
    "- `hf`: Variance ( = power ) in HRV in the High Frequency (.15 to .40 Hz by default). Reflects fast changes in beat-to-beat variability due to parasympathetic (vagal) activity. Sometimes called the respiratory band because it corresponds to HRV changes related to the respiratory cycle and can be increased by slow, deep breathing (about 6 or 7 breaths per minute) and decreased by anticholinergic drugs or vagal blockade.\n",
    "- `lf_hf_ratio`: lf/hf ratio is sometimes used by some investigators as a quantitative mirror of the sympatho/vagal balance.\n",
    "- `lfnu`: Normalized lf power.\n",
    "- `hfnu`: Normalized hf power.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8bd53d9b",
   "metadata": {},
   "source": [
    "## Saving Data\n",
    "\n",
    "Once you have calculated all your outcome variables, you can save the data for this participant. The data will be saved in your path and will be named as follows: [Participant ID].csv. To save your data, set `save_as_csv = True`. \n",
    "\n",
    "The parameters `artefact`, `nibi_before_cropping`, and `nibi_after_cropping` are optional. If you have calculated them, you can set them as inputs (e.g., `artefact = artefact`). Otherwise, set these parameters to `None`, and `N/D` will be replaced in that column. **Please note that if you aim to use the `Group Pipeline`, make sure to calculate and save these values.** "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ab8dedd4",
   "metadata": {},
   "outputs": [],
   "source": [
    "df = wearablehrv.individual.save_data(pp, path, time_domain_features, frequency_domain_features, data_pp, devices, conditions, events, artefact=artefact, nibi_before_cropping=nibi_before_cropping, nibi_after_cropping=nibi_after_cropping, save_as_csv=True)\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d5a021e",
   "metadata": {},
   "source": [
    "That's it! At this point, you have successfully calculated the relevant outcome measures. After running the pipeline for a couple of participants and saving their data in this manner, it is time to move to the Group pipeline to compare the performance of each device in each condition against the criterion for multiple participants.\n",
    "\n",
    "You can also do a lot of plotting for your single participant if you consult the `individual_data_plotting` notebook.\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",
    "- [Plot your data](https://github.com/Aminsinichi/wearable-hrv/blob/master/docs/examples/individual_pipeline/4.individual_data_plotting.ipynb)\n",
    "\n",
    "Or\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)"
   ]
  }
 ],
 "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
}