Merge pull request #103 from biomarkersParkinson/tutorial-data-prepar…

…ation

Tutorial data preparation

docs/guides/config.md

@@ -0,0 +1,11 @@
+# Config
+Throughout the ParaDigMa toolbox we use configuration objects `Config` to specificy parameters used as input of processes. All configuration classes care defined in `config.py`, and can be imported using `from paradigma.config import X`.  The configuration classes frequently use static column names defined in `constants.py` to ensure robustness and consistency.
+
+## Config classes
+The config classes are defined either for sensors (IMU, PPG) or for domains (gait, heart rate, tremor).
+
+### Sensor configs
+There are two sensor config classes: `IMUConfig` and `PPGConfig`. 
+
+### Domain configs
+For the latter category, config classes can further be distinguished by the processing steps displayed [here](https://github.com/biomarkersParkinson/paradigma). 

docs/guides/coordinate_system.md

@@ -0,0 +1,18 @@
+# Coordinate System
+As a prerequisite to reliably estimating gait and arm swing measures, it is important to align the coordinate system of the IMU sensor with the coordinate system of the trained classifiers. For the tremor and heart rate pipelines, differences between coordinate systems do not affect outcomes. 
+
+## Coordinate system used
+The coordinate system of the IMU sensor used for training the classifiers can be observed below. The direction of acceleration is indicated by arrows, and the direction of gyroscope rotation can be determined using [Ampère's right-hand grip rule](https://en.wikipedia.org/wiki/Right-hand_rule#Amp%C3%A8re's_right-hand_grip_rule) applied to the accelerometer axes. 
+
+<p align="center">
+    <img src="../source/_static/img/directions_axes.png" />
+</p>
+
+### Accelerometer
+The three accelerometer axes are set such that the x-axis is aligned with the arm pointing toward the hand, the y-axis is perpendicular to the arm pointing upward from the top of the sensor, and the z-axis points away from the arm and body. If the arrow representing a specific axis is pointing downward to the ground, parallel to and in the direction of the arrow representing gravity (1G), the acceleration of this specific axis is equal to -1g if the sensor is stable (i.e., no acceleration due to movement). 
+
+### Gyroscope
+If the sensor is rotating in the direction of the arrow (deducted using the [Ampère's right-hand grip rule](https://en.wikipedia.org/wiki/Right-hand_rule#Amp%C3%A8re's_right-hand_grip_rule) applied to the accelerometer axes), the gyroscope data will be positive.
+
+## Lateral differences
+Wearing the watch on the left wrist or right wrist influences the relation between movements and the coordinate system. In fact, the x-axis of the accelerometer, and the y-axis and z-axis of the gyroscope, are inverted. For this purpose, we have added `invert_watch_side` to the toolbox (which can be imported using `from paradigma.util import invert_watch_side`). First, ensure the coordinate system aligns with the coordinate system shown above. Do this for all participants wearing the watch on one specific side, for example the left wrist. Then, apply `invert_watch_side` to ensure individuals wearing the watch on the right wrist have the correct coordinate system accounting for differences in sensor orientation.

docs/index.md

@@ -1,30 +1,34 @@
-```{include} ../README.md
+```{toctree}
+:maxdepth: 2
+:caption: Tutorials
+tutorials/data_preparation.ipynb
 ```
 
 ```{toctree}
 :maxdepth: 2
-:caption: Example notebooks
+:caption: Template Notebooks
 notebooks/gait/gait_analysis.ipynb
 notebooks/ppg/ppg_analysis.ipynb
 ```
 
+```{toctree}
+:maxdepth: 2
+:caption: User Guides
+guides/coordinate_system.md
+```
+
 ```{toctree}
 :maxdepth: 2
 :caption: API
 autoapi/index
 ```
 
-```{toctree}
+<!-- ```{toctree}
 :maxdepth: 2
 :caption: TSDF schema
 tsdf_paradigma_schemas.md
 tsdf_paradigma_channels_and_units.md
-```
+``` -->
 
 ```{toctree}
-:maxdepth: 2
-:caption: Development
-changelog.md
-contributing.md
-conduct.md
-```
+:maxdepth: 2

docs/tutorials/data_preparation.ipynb

@@ -13,7 +13,7 @@
    "metadata": {},
    "source": [
     "## Load data\n",
-    "This example uses data of the Personalized Parkinson Project, which is stored in Time Series Data Format (TSDF). IMU and PPG data are sampled at a different sampling frequency and hence stored separately. "
+    "This example uses data of the Personalized Parkinson Project, which is stored in Time Series Data Format (TSDF). IMU and PPG data are sampled at a different sampling frequency and therefore stored separately. "
    ]
   },
   {
@@ -54,6 +54,13 @@
     "df_ppg.head(5)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The timestamps in this dataset correspond to delta milliseconds, and the data is not uniformly distributed as can be observed."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -117,7 +124,8 @@
    "metadata": {},
    "source": [
     "#### Set sensor values to the correct units\n",
-    "First, TSDF stores the data efficiently using scaling factors. We should therefore convert the sensor values back to the true values. "
+    "TSDF stores the data efficiently using scaling factors. We should therefore convert the sensor values back to the true values. This is only relevant if you use TSDF and scaled the data for storage purposes.\n",
+    "\n"
    ]
   },
   {
@@ -171,7 +179,7 @@
    "metadata": {},
    "source": [
     "#### Account for watch side\n",
-    "For the Gait & Arm Swing pipeline, it is essential to ensure correct sensor axes orientation. For more information please read [X]. If the sensors are not correctly aligned, you can use `invert_watch_side` to ensure consistency between sensors worn on the left or right wrist."
+    "For the Gait & Arm Swing pipeline, it is essential to ensure correct sensor axes orientation. For more information please read [Coordinate System](../guides/coordinate_system.md) and set the axes of the data accordingly."
    ]
   },
   {
@@ -189,6 +197,7 @@
     "df_imu[DataColumns.GYROSCOPE_Y] *= -1\n",
     "df_imu[DataColumns.GYROSCOPE_Z] *= -1\n",
     "\n",
+    "# Invert the axes when worn on the right-hand side\n",
     "df_imu = invert_watch_side(df_imu, watch_side)\n",
     "df_imu.head(5)"
    ]
@@ -198,7 +207,7 @@
    "metadata": {},
    "source": [
     "#### Change time column\n",
-    "ParaDigMa expects the data to be in seconds relative to the first row. The toolbox has the built-in function `transform_time_array` to help users transform their time column to the correct format."
+    "ParaDigMa expects the data to be in seconds relative to the first row, which should be equal to 0. The toolbox has the built-in function `transform_time_array` to help users transform their time column to the correct format."
    ]
   },
   {