Merge pull request #110 from neurogeriatricskiel/documentation-dev

Documentation Improvement

README.md

@@ -13,14 +13,125 @@ Welcome to the KielMotionAnalysisToolbox (KielMAT). We are a Python based toolbo
 
 The toolbox is aimed at motion researchers who want to use Python-based open-source software to process their data. We have implemented validated algorithms in modules to process motion data, as shown in the table below:
 
-## Overview of modules
-| Module                         | Description                                    | Data                               |
-|--------------------------------|------------------------------------------------|----------------------------------------|
-| Gait sequence detection (GSD)  | Detects gaits                      | 3D accelerations from the lower back   |
-| Initial contact detection (ICD)| Detects initial contact during gait     | 3D accelerations from the lower back   |
-| More to follow...              | Additional modules to be added                |                                        |
+## Overview of Modules
+
+The table below provides an overview of key modules, their functionalities, input data, validation datasets, and outputs.
+
+<div style="width: 100%; text-align: left; margin-top: 20px; border: 1px solid #ddd; border-radius: 8px; overflow: hidden;">
+
+<table style="width: 100%; border-collapse: collapse; font-size: 0.9em;">
+
+<thead style="background-color: #f2f2f2;">
+<tr>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Module</th>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Description</th>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Input Data</th>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Validation Dataset</th>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Event Type</th>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Output Parameters</th>
+</tr>
+</thead>
+
+<tbody>
+<tr>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/modules/gsd/">Gait Sequence Detection</a></td>
+<td style="padding: 8px;">Detects gait sequences</td>
+<td style="padding: 8px;">3D accelerations from lower back IMU</td>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/datasets/mobilised/">Mobilise-D</a> and <a href="https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/">KeepControl</a></td>
+<td style="padding: 8px;">gait sequence</td>
+<td style="padding: 8px;">-</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/modules/icd/">Initial Contact Detection</a></td>
+<td style="padding: 8px;">Detects initial and final contacts within each gait cycle</td>
+<td style="padding: 8px;">3D accelerations from lower back IMU</td>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/datasets/mobilised/">Mobilise-D</a> and <a href="https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/">KeepControl</a></td>
+<td style="padding: 8px;">initial contact, final contact</td>
+<td style="padding: 8px;">Temporal parameters (e.g., step time, stride time)</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/modules/pam/">Physical Activity Monitoring</a></td>
+<td style="padding: 8px;">Monitors physical activity levels</td>
+<td style="padding: 8px;">3D accelerations from wrist IMU</td>
+<td style="padding: 8px;"><a href="https://www.fairpark2.eu/">Fair Park Ⅱ</a></td>
+<td style="padding: 8px;">-</td>
+<td style="padding: 8px;">Mean and duration of activity level</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/modules/ptd/">Postural Transition Detection</a></td>
+<td style="padding: 8px;">Detects sit-to-stand and stand-to-sit transitions</td>
+<td style="padding: 8px;">3D acceleration and gyroscope data from lower back IMU</td>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/">KeepControl</a> and <a href="https://pmc.ncbi.nlm.nih.gov/articles/PMC4460963/">SENSE-PARK</a></td>
+<td style="padding: 8px;">sit-to-stand, stand-to-sit</td>
+<td style="padding: 8px;">Spatio-temporal parameters (e.g., postural transition angle)</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/modules/td/">Turn Detection</a></td>
+<td style="padding: 8px;">Detects turn movements</td>
+<td style="padding: 8px;">3D acceleration and gyroscope data from lower back IMU</td>
+<td style="padding: 8px;"><a href="https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/">KeepControl</a> and <a href="https://pmc.ncbi.nlm.nih.gov/articles/PMC4460963/">SENSE-PARK</a></td>
+<td style="padding: 8px;">turn</td>
+<td style="padding: 8px;">Spatio-temporal parameters (e.g., turn angle)</td>
+</tr>
+
+</tbody>
+</table>
+</div>
+
+## Units
+
+The table below provides an overview of commonly used value types and their corresponding units. Before starting work with modules in the toolbox, ensure that all data is in standard SI units as specified. This ensures compatibility with the algorithms, which are designed to expect inputs in these units.
+
+<div style="width: 50%; text-align: left; margin-top: 20px; border: 1px solid #ddd; border-radius: 8px; overflow: hidden;">
+
+<table style="width: 100%; border-collapse: collapse; font-size: 0.9em;">
+
+<thead style="background-color: #f2f2f2;">
+<tr>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Value</th>
+<th style="padding: 10px; border-bottom: 1px solid #ddd;">Unit</th>
+</tr>
+</thead>
+
+<tbody>
+<tr>
+<td style="padding: 8px;">Acceleration</td>
+<td style="padding: 8px;">m/s²</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;">Angular Velocity</td>
+<td style="padding: 8px;">deg/s</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;">Velocity</td>
+<td style="padding: 8px;">m/s</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;">Distance</td>
+<td style="padding: 8px;">m</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;">Time</td>
+<td style="padding: 8px;">s</td>
+</tr>
+
+<tr>
+<td style="padding: 8px;">Sampling Rate</td>
+<td style="padding: 8px;">Hz</td>
+</tr>
+
+</tbody>
+</table>
+</div>
 
-The idea is that various motion data can be loaded into our dedicated dataclass which rely on principles from the [Motion-BIDS](https://bids-specification.readthedocs.io/en/latest/modality-specific-files/motion.html) standard.
 
 ## Installation
 The toolbox has been released on [pypi](https://pypi.org/project/kielmat/) and can be installed via pip:
@@ -30,6 +141,8 @@ pip install kielmat
 It requires Python 3.10 or higher.
 
 ## Data classes
+The idea is that various motion data can be loaded into our dedicated dataclass which rely on principles from the [Motion-BIDS](https://bids-specification.readthedocs.io/en/latest/modality-specific-files/motion.html) standard.
+
 ### Data classes: conceptual framework
 
 Motion data is recorded with many different systems and modalities, each with their own proprietary data format. KielMAT deals with this by organizing both data and metadata in a [BIDS-like format](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html). The BIDS format suggests that [motion recording data](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html#motion-recording-data) from a single tracking system is organized in a single `*_tracksys-<label>_motion.tsv` file.

docs/dataclass.md

@@ -1,9 +1,5 @@
-In the following the KielMAT dataclass is described.
-The dataclass is used to store motion data in a standardized way. We provide some small set of import functions, each of which returns a `pandas.DataFrame` or a dict.
-User should easily be able to write their own import functions, to get the their data into the provided dataclass (this step might take some thinking).
-After the data is in the dataclass, running functions on the data from our toolbox should be really straight forward.
+In the following, the KielMAT dataclass is described. The dataclass is used to store motion data in a standardized way. We provide a small set of import functions, each of which returns a `pandas.DataFrame` or a dict. Users should easily be able to write their own import functions to get their data into the provided dataclass (this step might take some thinking). After the data is in the dataclass, running functions on the data from our toolbox should be really straightforward.
 
-## KielMAT data class
 ```mermaid
 classDiagram
    class KielMATRecording {
@@ -15,6 +11,7 @@ classDiagram
       add_events(tracking_system, new_events)
       add_info(key, value)
       export_events(file_path, tracking_system=None, file_name=None, bids_compatible_fname=False)
+      validate_channels() -> str
    }
 
 ```

docs/datasets/index.md

@@ -1,8 +1,12 @@
 # Overview
 
-This part of the project documentation focuses on
-the avaliable **datasets**.
+This section of the project documentation focuses on the available **datasets** used within the KielMAT toolbox. These datasets are essential for testing and validating the functionality of the toolbox’s modules. Below is an introduction to the available datasets, with links to further details and data access.
+
 
 ## [Keep Control](keepcontrol.md)
 
+The **Keep Control** dataset is derived from the [Keep Control](https://www.keep-control.eu/) project, which is part of an Industrial Academic Initial Training Network. This dataset includes full-body mobility data collected from both healthy and neurological cohorts, and is primarily used to validate inertial measurement unit (IMU) algorithms.
+
 ## [Mobilise-D](mobilised.md)
+
+The **Mobilise-D** dataset is derived from the [Mobilise-D](https://mobilise-d.eu/) consortium, a European project aimed at developing a comprehensive system for monitoring and evaluating people's gait using digital technologies. The dataset includes data collected using sensors worn on the body, such as a low back-worn inertial measurement unit (IMU). The dataset provides valuable insights into real-world gait analysis using wearable sensors and has been used to validate gait measurement methodologies.

docs/examples/basic_00_load_Data_into_KielMAT.md → docs/examples/basic_01_load_Data_into_KielMAT.md

@@ -1,10 +1,12 @@
 # Tutorial: Load data into an `KielMATRecording` object
 
 **Author:** Julius Welzel
+
 **Last update:** Fri 22 Mar 2024
 
 ## Learning objectives
 By the end of this tutorial:
+
 - you can load data and channel information into an `KielMATRecording` object
 - you can add Recording specific information to the `KielMATRecording` object
 - you are educated about the relationship between a `KielMATRecording` object and the [BIDS standard](https://bids-specification.readthedocs.io/en/stable/).
@@ -141,7 +143,7 @@ print(recording.events)
 
 
 
-![png](basic_00_load_Data_into_KielMAT_files/basic_00_load_Data_into_KielMAT_1.png)
+![png](basic_01_load_Data_into_KielMAT_files/basic_01_load_Data_into_KielMAT_1.png)
 
 
 

docs/examples/index.md

@@ -1,15 +1,35 @@
 # Overview
 
-This is a collection of examples to explain various parts of the KielMAT toolbox.
+This section contains a series of examples designed to demonstrate key features and functionalities within the KielMAT toolbox. These examples will guide users through common workflows and illustrate how to apply different modules to motion analysis data.
 
 ## Construct Your DataClass
 
-### [Example 1: Load data into KielMAT](basic_00_load_Data_into_KielMAT.md)
-### [Example 2: Load datasets](basic_01_load_dataset.md)
-### [Example 3: Events in dataclass](basic_02_events.md)
+The `DataClass` is the central data structure in KielMAT, which stores and organizes motion data along with associated events. The following examples guide you through the process of loading and structuring your data.
+
+### [Example 1: Load data into KielMAT](basic_01_load_Data_into_KielMAT.md)
+In this example, you will learn how to load motion data into `KielMAT`'s `DataClass`. This step is essential for processing any motion capture data, whether it's from IMUs, C3D files, or other data formats.
+
+### [Example 2: Load datasets](basic_02_load_dataset.md)
+This example demonstrates how to load datasets into `KielMAT`. You will learn how to import data from different sources, handle multiple datasets, and integrate them into a unified structure for analysis.
+
+### [Example 3: Events in DataClass](basic_03_events.md)
+The `DataClass` not only stores motion data but also provides functionality to mark and organize events (such as gait sequences, initial contacts, or other notable movement occurrences). This example shows how to tag specific events within the `DataClass`, allowing you to analyze them in the context of the motion data.
 
 ## Run Modules
 
-### [Example 1: Gait Sequence Detection](modules_01_gsd.md)
-### [Example 2: Initial Contact Detection](modules_02_icd.md)
-### [Example 3: Physical Activity Monitoring](modules_03_pam.md)
+KielMAT includes several pre-built modules to analyze motion data for different tasks. The following examples demonstrate how to apply each module to extract meaningful information from your data.
+
+### [Example 4: Gait Sequence Detection](modules_04_gsd.md)
+This example introduces the [Gait Sequence Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/gsd/) module. This module identifies gait sequences using 3D accelerometer data from a lower back sensor.
+
+### [Example 5: Initial Contact Detection](modules_05_icd.md)
+This example introduces the [Initial Contact Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/icd/) module. It identifies and characterizes initial contacts within each detected gait sequence using the gait sequence detection module.
+
+### [Example 6: Physical Activity Monitoring](modules_06_pam.md)
+This example introduces the [Physical Activity Monitoring](https://neurogeriatricskiel.github.io/KielMAT/modules/pam/) module. The example shows how the module is implemented on sample 3D acceleration data from an IMU sensor to monitor physical activity levels.
+
+### [Example 7: Postural Transition Detection](modules_07_ptd.md)
+This example introduces the [Postural Transition Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/ptd/) module. It demonstrates how the module is implemented on sample 3D acceleration and 3D angular velocity data from a lower back IMU sensor to detect postural transitions, such as sit-to-stand or stand-to-sit.
+
+### [Example 8: Turn Detection](modules_08_td.md)
+This example introduces the [Turn Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/td/) module. It demonstrates how the module is implemented on sample 3D acceleration and 3D angular velocity data from a lower back IMU sensor to detect turns.

docs/examples/modules_01_gsd.md → docs/examples/modules_04_gsd.md

@@ -159,7 +159,7 @@ plt.show()
 
 
 
-![](modules_01_gsd_files/modules_01_gsd_7_0.png)
+![](modules_04_gsd_files/modules_04_gsd_7_0.png)
 
 
 
@@ -210,7 +210,7 @@ plt.show()
 
 
 
-![](modules_01_gsd_files/modules_01_gsd_9_0.png)
+![](modules_04_gsd_files/modules_04_gsd_9_0.png)
 
 
 
@@ -250,7 +250,7 @@ print(recording.events)
 
 
 
-![](modules_01_gsd_files/modules_01_gsd_11_1.png)
+![](modules_04_gsd_files/modules_04_gsd_11_1.png)
 
 
 
@@ -352,6 +352,6 @@ plt.show()
 
 
 
-![](modules_01_gsd_files/modules_01_gsd_13_1.png)
+![](modules_04_gsd_files/modules_04_gsd_13_1.png)
 
 

docs/examples/modules_02_icd.md → docs/examples/modules_05_icd.md

@@ -152,7 +152,7 @@ plt.show()
 
 
 
-![png](modules_02_icd_files/modules_02_icd_8_0.png)
+![png](modules_05_icd_files/modules_05_icd_8_0.png)
 
 
 
@@ -326,6 +326,6 @@ plt.show()
 
 
 
-![png](modules_02_icd_files/modules_02_icd_14_1.png)
+![png](modules_05_icd_files/modules_05_icd_14_1.png)
 
 

docs/examples/modules_04_ptd.md → docs/examples/modules_07_ptd.md

@@ -221,7 +221,7 @@ fig.tight_layout()
 plt.show()
 ```
 
-![](modules_04_ptd_files/04_tutorial_postural_transition_detection_1.png)
+![](modules_07_ptd_files/07_tutorial_postural_transition_detection_1.png)
 
 
 ## Applying Pham Postural Transition Detection Algorithm
@@ -253,7 +253,7 @@ pham = pham.detect(
     plot_results=True,
 )
 ```
-![](modules_04_ptd_files/04_tutorial_postural_transition_detection_2.png)
+![](modules_07_ptd_files/07_tutorial_postural_transition_detection_2.png)
 
 The outputs are stored in the `postural_transitions_` attribute, which is a pandas DataFrame in BIDS format with the following columns:
 

docs/examples/modules_05_td.md → docs/examples/modules_08_td.md

@@ -220,7 +220,7 @@ fig.tight_layout()
 plt.show()
 ```
 
-![](modules_05_td_files/modules_05_td_1.png)
+![](modules_08_td_files/modules_08_td_1.png)
 
 
 ## Applying Pham Turn Detection Algorithm
@@ -254,7 +254,7 @@ pham = pham.detect(
     plot_results=True,
 )
 ```
-![](modules_05_td_files/modules_05_td_2.png)
+![](modules_08_td_files/modules_08_td_2.png)
 
 The outputs are stored in the 'turns_' attribute, which is a pandas DataFrame in BIDS format with the following columns: