+
## 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.
-
-
-
-
-
-
-Value
-Unit
-
-
-
-
-
-Acceleration
-m/s²
-
-
-
-Angular Velocity
-deg/s
-
-
-
-Velocity
-m/s
-
-
-
-Distance
-m
-
-
-
-Time
-s
-
-
-
-Sampling Rate
-Hz
-
-
-
-
+
+
+
+
+
+
+ Value
+ Unit
+
+
+
+
+
+ Acceleration
+ m/s²
+
+
+
+ Angular Velocity
+ deg/s
+
+
+
+ Velocity
+ m/s
+
+
+
+ Distance
+ m
+
+
+
+ Time
+ s
+
+
+
+ Sampling Rate
+ Hz
+
+
+
+
+
## Installation
The toolbox has been released on [pypi](https://pypi.org/project/kielmat/) and can be installed via pip:
```bash
From 218949ff787000d38250dd2736cd09515cf4ac1d Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 10:51:41 +0100
Subject: [PATCH 06/13] revisions based on reviews from merge request (J.W.)
---
docs/dataclass.md | 6 +-
docs/index.md | 128 ++++-------------------------
kielmat/datasets/keepcontrol.py | 6 ++
kielmat/modules/ptd/_pham.py | 6 +-
kielmat/modules/td/_pham.py | 4 +-
kielmat/utils/importers.py | 13 +--
kielmat/utils/kielmat_dataclass.py | 2 +-
kielmat/utils/preprocessing.py | 17 ++--
kielmat/utils/quaternion.py | 6 +-
mkdocs.yml | 3 +
10 files changed, 50 insertions(+), 141 deletions(-)
diff --git a/docs/dataclass.md b/docs/dataclass.md
index 1fc1c7c..5242366 100644
--- a/docs/dataclass.md
+++ b/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 {
diff --git a/docs/index.md b/docs/index.md
index 48c59bc..33fe223 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -17,123 +17,27 @@ The toolbox is aimed at motion researchers who want to use Python-based open-sou
The table below provides an overview of key modules, their functionalities, input data, validation datasets, and outputs.
-
-
-
-
-
-
- Module
- Description
- Input Data
- Validation Dataset
- Event Type
- Output Parameters
-
-
-
-
-
- Gait Sequence Detection Detects gait sequences
- 3D accelerations from lower back IMU
- Mobilise-D and KeepControl gait sequence
- -
-
-
-
- Initial Contact Detection Detects initial and final contacts within each gait cycle
- 3D accelerations from lower back IMU
- Mobilise-D and KeepControl initial contact, final contact
- Temporal parameters (e.g., step time, stride time)
-
-
-
- Physical Activity Monitoring Monitors physical activity levels
- 3D accelerations from wrist IMU
- Fair Park Ⅱ -
- Mean and duration of activity level
-
-
-
- Postural Transition Detection Detects sit-to-stand and stand-to-sit transitions
- 3D acceleration and gyroscope data from lower back IMU
- KeepControl and SENSE-PARK sit-to-stand, stand-to-sit
- Spatio-temporal parameters (e.g., postural transition angle)
-
-
-
- Turn Detection Detects turn movements
- 3D acceleration and gyroscope data from lower back IMU
- KeepControl and SENSE-PARK turn
- Spatio-temporal parameters (e.g., turn angle)
-
-
-
-
-
+| Module | Description | Input Data | Validation Dataset | Event Type | Output Parameters |
+|--------|-------------|------------|--------------------|------------|-------------------|
+| [Gait Sequence Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/gsd/) | Detects gait sequences | 3D accelerations from lower back IMU | [Mobilise-D](https://neurogeriatricskiel.github.io/KielMAT/datasets/mobilised/) and [KeepControl](https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/) | gait sequence | - |
+| [Initial Contact Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/icd/) | Detects initial and final contacts within each gait cycle | 3D accelerations from lower back IMU | [Mobilise-D](https://neurogeriatricskiel.github.io/KielMAT/datasets/mobilised/) and [KeepControl](https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/) | initial contact, final contact | Temporal parameters (e.g., step time, stride time) |
+| [Physical Activity Monitoring](https://neurogeriatricskiel.github.io/KielMAT/modules/pam/) | Monitors physical activity levels | 3D accelerations from wrist IMU | [Fair Park Ⅱ](https://www.fairpark2.eu/) | - | Mean and duration of activity level |
+| [Postural Transition Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/ptd/) | Detects sit-to-stand and stand-to-sit transitions | 3D acceleration and gyroscope data from lower back IMU | [KeepControl](https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/) and [SENSE-PARK](https://pmc.ncbi.nlm.nih.gov/articles/PMC4460963/) | sit-to-stand, stand-to-sit | Spatio-temporal parameters (e.g., postural transition angle) |
+| [Turn Detection](https://neurogeriatricskiel.github.io/KielMAT/modules/td/) | Detects turn movements | 3D acceleration and gyroscope data from lower back IMU | [KeepControl](https://neurogeriatricskiel.github.io/KielMAT/datasets/keepcontrol/) and [SENSE-PARK](https://pmc.ncbi.nlm.nih.gov/articles/PMC4460963/) | turn | Spatio-temporal parameters (e.g., turn angle) |
## 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.
-
-
-
-
-
-
- Value
- Unit
-
-
-
-
-
- Acceleration
- m/s²
-
-
-
- Angular Velocity
- deg/s
-
-
-
- Velocity
- m/s
-
-
-
- Distance
- m
-
-
-
- Time
- s
-
-
-
- Sampling Rate
- Hz
-
-
-
-
-
-
-
+| Value | Unit | Channel Type |
+|-------------------|--------|---------------|
+| Acceleration | m/s² | ACCEL |
+| Angular Velocity | deg/s | GYRO |
+| Velocity | m/s | VEL |
+| Distance | m | POS |
+| Time | s | |
+| Sampling Rate | Hz | |
## Installation
The toolbox has been released on [pypi](https://pypi.org/project/kielmat/) and can be installed via pip:
@@ -149,7 +53,7 @@ The idea is that various motion data can be loaded into our dedicated dataclass
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-
_motion.tsv` file.
-> [!NOTE]
+> !!! note
> A tracking system is defined as a group of motion channels that share hardware properties (the recording device) and software properties (the recording duration and number of samples).
In KielMAT, data from a single tracking system is therefore loaded into a single `pandas.DataFrame`. The column headers of this `pandas.DataFrame` refer to the channels, and the corresponding [channels information](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html#channels-description-_channelstsv) is likewise available as a `pandas.DataFrame`.
diff --git a/kielmat/datasets/keepcontrol.py b/kielmat/datasets/keepcontrol.py
index ead2456..332c780 100644
--- a/kielmat/datasets/keepcontrol.py
+++ b/kielmat/datasets/keepcontrol.py
@@ -7,6 +7,7 @@
from kielmat.utils.kielmat_dataclass import REQUIRED_COLUMNS
import logging
import warnings
+from tqdm import tqdm
# Dict of valid tracked points for the Keep Control dataset for each tracking system
VALID_TRACKED_POINTS = {
@@ -84,6 +85,7 @@
def fetch_dataset(
+ progressbar: bool = True,
dataset_path: str | Path = Path(__file__).parent / "_keepcontrol",
) -> None:
"""Fetch the Keep Control dataset from the OpenNeuro repository.
@@ -104,6 +106,10 @@ def fetch_dataset(
dataset="ds005258", # this is the example Keep Control dataset on OpenNeuro, maintained by Julius Welzel
target_dir=dataset_path,
)
+
+ else:
+ if progressbar:
+ print("Dataset already downloaded, skipping download.")
return
diff --git a/kielmat/modules/ptd/_pham.py b/kielmat/modules/ptd/_pham.py
index 905cadb..9c82aaa 100644
--- a/kielmat/modules/ptd/_pham.py
+++ b/kielmat/modules/ptd/_pham.py
@@ -88,7 +88,7 @@ def __init__(
cutoff_freq_hz (float, optional): Cutoff frequency for low-pass Butterworth filer. Default is 5.0.
thr_accel_var (float): Threshold value for identifying periods where the acceleartion variance is low. Default is 0.5.
thr_gyro_var (float): Threshold value for identifying periods where the gyro variance is low. Default is 2e-4.
- min_turn_angle_deg (float): Minimum angle which is considered as postural transition in degrees. Default is 15.0.
+ min_postural_transition_angle_deg (float): Minimum angle which is considered as postural transition in degrees. Default is 15.0.
"""
self.cutoff_freq_hz = cutoff_freq_hz
self.thr_accel_var = thr_accel_var
@@ -104,7 +104,7 @@ def detect(
tracking_system: Optional[str] = None,
tracked_point: Optional[str] = None,
plot_results: bool = False,
- ) -> "PhamPosturalTransitionDetection":
+ ) -> pd.DataFrame:
"""
Detects postural transitions based on the input accelerometer and gyro data.
@@ -460,7 +460,7 @@ def detect(
# Return an instance of the class
return self
- def spatio_temporal_parameters(self) -> None:
+ def spatio_temporal_parameters(self) -> pd.DataFrame:
"""
Extracts spatio-temporal parameters of the detected postural transitions.
diff --git a/kielmat/modules/td/_pham.py b/kielmat/modules/td/_pham.py
index 1cca46c..198f642 100644
--- a/kielmat/modules/td/_pham.py
+++ b/kielmat/modules/td/_pham.py
@@ -105,7 +105,7 @@ def detect(
tracking_system: Optional[str] = None,
tracked_point: Optional[str] = None,
plot_results: bool = False,
- ) -> "PhamTurnDetection":
+ ) -> pd.DataFrame:
"""
Detects truns based on the input accelerometer and gyro data.
@@ -450,7 +450,7 @@ def detect(
# Return an instance of the class
return self
- def spatio_temporal_parameters(self) -> None:
+ def spatio_temporal_parameters(self) -> pd.DataFrame:
"""
Extracts spatio-temporal parameters of the detected turns.
diff --git a/kielmat/utils/importers.py b/kielmat/utils/importers.py
index 7b15927..e06bba4 100644
--- a/kielmat/utils/importers.py
+++ b/kielmat/utils/importers.py
@@ -7,7 +7,7 @@
from pathlib import Path
-def import_axivity(file_path: str, tracked_point: str):
+def import_axivity(file_path: str, tracked_point: str) -> tuple[pd.DataFrame, pd.DataFrame]:
"""
Imports Axivity data from the specified file path and
return the data and channel formatted to be used in a KielMATRecording object.
@@ -52,7 +52,7 @@ def import_axivity(file_path: str, tracked_point: str):
col_names = [f"{tracked_point}_{s}_{x}" for s in ["ACCEL"] for x in ["x", "y", "z"]]
# Create the channel dictionary following the BIDS naming conventions
- channels = {
+ channels_dict = {
"name": col_names,
"component": ["x", "y", "z"] * (n_channels // 3),
"type": ["ACCEL"] * (n_channels),
@@ -61,6 +61,9 @@ def import_axivity(file_path: str, tracked_point: str):
"sampling_frequency": [info["ResampleRate"]] * n_channels,
}
+ # Convert channels dictionary to a DataFrame
+ channels = pd.DataFrame(channels_dict)
+
return data, channels
@@ -74,7 +77,7 @@ def import_mobilityLab(
Args:
file_name (str or Path): The absolute or relative path to the data file.
- tracked_point (str or list of str]):
+ tracked_points (str or list of str]):
Defines for which tracked points data are to be returned.
Returns:
@@ -82,8 +85,8 @@ def import_mobilityLab(
Examples:
>>> file_path = "/path/to/sensor_data.h5"
- >>> tracked_point = "Lumbar"
- >>> recording = import_mobilityLab(file_path, tracked_point)
+ >>> tracked_points = "Lumbar"
+ >>> recording = import_mobilityLab(file_path, tracked_points)
"""
# Convert file_name to a Path object if it is a string
if isinstance(file_name, str):
diff --git a/kielmat/utils/kielmat_dataclass.py b/kielmat/utils/kielmat_dataclass.py
index a35dc44..4558147 100644
--- a/kielmat/utils/kielmat_dataclass.py
+++ b/kielmat/utils/kielmat_dataclass.py
@@ -77,7 +77,7 @@ def __post_init__(self):
# Validate channels when an instance is created
self.validate_channels()
- def validate_channels(self):
+ def validate_channels(self) -> str:
"""
Validates the channel dataframes for each system.
diff --git a/kielmat/utils/preprocessing.py b/kielmat/utils/preprocessing.py
index 9d04619..797bddd 100644
--- a/kielmat/utils/preprocessing.py
+++ b/kielmat/utils/preprocessing.py
@@ -75,7 +75,7 @@ def resample_interpolate(
return resampled_signal
-def lowpass_filter(signal, method="savgol", order=None, **kwargs):
+def lowpass_filter(signal, method="savgol", order=None, **kwargs:dict):
"""
Apply a low-pass filter to the input signal.
@@ -83,7 +83,7 @@ def lowpass_filter(signal, method="savgol", order=None, **kwargs):
signal (numpy.ndarray): The input signal to be filtered.
method (str): The filter method to use ("savgol", "butter", or "fir").
order (int): The order of the filter (applicable for "butter" method).
- param (**kwargs): Additional keyword arguments specific to the Savitzky-Golay filter method or other methods.
+ **kwargs: Additional keyword arguments specific to the Savitzky-Golay filter method or other methods.
Returns:
filt_signal (numpy.ndarray): The filtered signal.
@@ -165,7 +165,7 @@ def lowpass_filter(signal, method="savgol", order=None, **kwargs):
raise ValueError("Invalid filter method specified")
-def highpass_filter(signal, sampling_frequency=40, method="iir", **kwargs):
+def highpass_filter(signal, sampling_frequency=40, method="iir"):
"""
Apply a high-pass filter to the input signal using the specified method.
@@ -173,10 +173,9 @@ def highpass_filter(signal, sampling_frequency=40, method="iir", **kwargs):
signal (np.ndarray): The input signal to be filtered.
sampling_frequency (float): The sampling frequency of the input signal.
method (str): The filtering method to be used.
- **kwargs: Additional keyword arguments specific to the filtering method.
Returns:
- np.ndarray: The filtered signal.
+ filtered_signal (np.ndarray): The filtered signal.
"""
# Error handling for invalid input data
@@ -441,7 +440,7 @@ def find_consecutive_groups(input_signal):
the start index of the group and the second column containing the end index of the group.
Parameters:
- input_array (ndarray): The input array.
+ input_signal (ndarray): The input array.
Returns:
ind (ndarray): A 2D array where each row represents a group of consecutive non-zero values.
@@ -1085,13 +1084,13 @@ def wavelet_decomposition(data, level, wavetype):
# Function for computing moving variance
-def moving_var(data, window):
+def moving_var(data, window) -> np.ndarray:
"""
Compute the centered moving variance.
Args:
- Data (int) : Data to take the moving variance on window
- Window size (int) : Window size for the moving variance.
+ data (int) : Data to take the moving variance on window
+ window size (int) : Window size for the moving variance.
Returns:
m_var (numpy.ndarray) : Moving variance
diff --git a/kielmat/utils/quaternion.py b/kielmat/utils/quaternion.py
index 82d16ae..795086a 100644
--- a/kielmat/utils/quaternion.py
+++ b/kielmat/utils/quaternion.py
@@ -292,10 +292,8 @@ def rotm2quat(R: np.ndarray, method: int | str = "auto") -> np.ndarray:
Args:
R (np.ndarray): A rotation matrix with shape (3, 3).
- scalar_first (bool, optional): If True, sets the first element as the scalar part.
- If False, sets the last element as the scalar part is the last element. Default is True.
- channels_last (bool, optional): If True, assumes the channels are the last dimension.
- If False, assumes the channels are the first dimension. Default is True.
+ method (int | str, optional): The method to use for conversion.
+ Can be "auto" (default), "copysign", or a number (0, 1, 2, or 3).
Returns:
np.ndarray: The quaternion corresponding to the rotation matrix.
diff --git a/mkdocs.yml b/mkdocs.yml
index 0156c5a..bc2180f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -47,6 +47,9 @@ nav:
- Events in dataclass: examples/basic_02_events.md
- Gait Sequence Detection: examples/modules_01_gsd.md
- Initial Contact Detection: examples/modules_02_icd.md
+ - Physical Activity Monitoring: examples/modules_03_pam.md
+ - Postural Transition Detection: examples/modules_04_ptd.md
+ - Turn Detection: examples/modules_05_td.md
- Dataclass: dataclass.md
- Modules:
- modules/index.md
From 73bad3ef08997fa126ecdc8004da5814118267b9 Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 11:45:44 +0100
Subject: [PATCH 07/13] remove the progress bar from the documentation
---
kielmat/datasets/keepcontrol.py | 6 ------
1 file changed, 6 deletions(-)
diff --git a/kielmat/datasets/keepcontrol.py b/kielmat/datasets/keepcontrol.py
index 332c780..4a4fbef 100644
--- a/kielmat/datasets/keepcontrol.py
+++ b/kielmat/datasets/keepcontrol.py
@@ -7,7 +7,6 @@
from kielmat.utils.kielmat_dataclass import REQUIRED_COLUMNS
import logging
import warnings
-from tqdm import tqdm
# Dict of valid tracked points for the Keep Control dataset for each tracking system
VALID_TRACKED_POINTS = {
@@ -85,12 +84,10 @@
def fetch_dataset(
- progressbar: bool = True,
dataset_path: str | Path = Path(__file__).parent / "_keepcontrol",
) -> None:
"""Fetch the Keep Control dataset from the OpenNeuro repository.
Args:
- progressbar (bool, optional): Whether to display a progressbar. Defaults to True.
dataset_path (str | Path, optional): The path where the dataset is stored. Defaults to Path(__file__).parent/"_keepcontrol".
"""
dataset_path = Path(dataset_path) if isinstance(dataset_path, str) else dataset_path
@@ -107,9 +104,6 @@ def fetch_dataset(
target_dir=dataset_path,
)
- else:
- if progressbar:
- print("Dataset already downloaded, skipping download.")
return
From 5514104fc516e24cb0dfb3801b5aba3658ec194f Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 11:55:56 +0100
Subject: [PATCH 08/13] render properly
---
kielmat/modules/ptd/_pham.py | 8 ++++----
kielmat/modules/td/_pham.py | 8 ++++----
2 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/kielmat/modules/ptd/_pham.py b/kielmat/modules/ptd/_pham.py
index 9c82aaa..b097916 100644
--- a/kielmat/modules/ptd/_pham.py
+++ b/kielmat/modules/ptd/_pham.py
@@ -118,8 +118,8 @@ def detect(
plot_results (bool, optional): If True, generates a plot. Default is False.
Returns:
- The postural transition information is stored in the 'postural_transitions_' attribute,
- which is a pandas DataFrame in BIDS format with the following columns:
+ The postural transition information is stored in the 'postural_transitions_' attribute, which is a pandas DataFrame in BIDS format with the following columns:
+
- onset: Start time of the postural transition in second.
- duration: Duration of the postural transition in second.
- event_type: Type of the event which is postural transition.
@@ -465,8 +465,8 @@ def spatio_temporal_parameters(self) -> pd.DataFrame:
Extracts spatio-temporal parameters of the detected postural transitions.
Returns:
- The spatio-temporal parameter information is stored in the 'spatio_temporal_parameters'
- attribute, which is a pandas DataFrame as:
+ The spatio-temporal parameter information is stored in the 'spatio_temporal_parameters' attribute, which is a pandas DataFrame as:
+
- type_of_postural_transition: Type of postural transition which is either "sit to stand" or "stand to sit".
- angel_of_postural_transition: Angle of the postural transition in degrees.
- maximum_flexion_velocity: Maximum flexion velocity in deg/s.
diff --git a/kielmat/modules/td/_pham.py b/kielmat/modules/td/_pham.py
index 198f642..0948125 100644
--- a/kielmat/modules/td/_pham.py
+++ b/kielmat/modules/td/_pham.py
@@ -120,8 +120,8 @@ def detect(
plot_results (bool, optional): If True, generates a plot. Default is False.
Returns:
- The turns information is stored in the 'turns_' attribute,
- which is a pandas DataFrame in BIDS format with the following information:
+ The turns information is stored in the 'turns_' attribute, which is a pandas DataFrame in BIDS format with the following information:
+
- onset: Start time of the turn in second.
- duration: Duration of the turn in second.
- event_type: Type of the event (turn).
@@ -455,8 +455,8 @@ def spatio_temporal_parameters(self) -> pd.DataFrame:
Extracts spatio-temporal parameters of the detected turns.
Returns:
- The spatio-temporal parameter information is stored in the 'spatio_temporal_parameters'
- attribute, which is a pandas DataFrame as:
+ The spatio-temporal parameter information is stored in the 'spatio_temporal_parameters' attribute, which is a pandas DataFrame as:
+
- direction_of_turn: Direction of turn which is either "left" or "right".
- angle_of_turn: Angle of the turn in degrees.
- peak_angular_velocity: Peak angular velocity during turn in deg/s.
From e6a4ab18a2975f67af059bf9cb795f25fa2bb281 Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 12:05:21 +0100
Subject: [PATCH 09/13] hange the docstring of this function
---
kielmat/utils/importers.py | 40 +++++++++++++++++++-------------------
1 file changed, 20 insertions(+), 20 deletions(-)
diff --git a/kielmat/utils/importers.py b/kielmat/utils/importers.py
index e06bba4..2bdc6ff 100644
--- a/kielmat/utils/importers.py
+++ b/kielmat/utils/importers.py
@@ -9,22 +9,21 @@
def import_axivity(file_path: str, tracked_point: str) -> tuple[pd.DataFrame, pd.DataFrame]:
"""
- Imports Axivity data from the specified file path and
- return the data and channel formatted to be used in a KielMATRecording object.
+ Imports and processes data from an Axivity device file.
Args:
- file_path (str or Path): The path to the Axivity data file.
- tracked_point (str): The name of the tracked point.
+ file_path (str): Path to the Axivity data file.
+ tracked_point (str): Label for the tracked body point (e.g., 'wrist').
Returns:
- dict, dict: The loaded data and channels as dictionaries.
+ tuple[pd.DataFrame, pd.DataFrame]: A tuple containing:
+ - data (pd.DataFrame): Processed accelerometer data with time information.
+ - channels (pd.DataFrame): Channel information DataFrame with metadata such as
+ component, type, units, and sampling frequency.
- Examples:
- >>> file_path = "/path/to/axivity_data.cwa"
- >>> tracked_point = "lowerBack"
- >>> data, channels = import_axivity(file_path, tracked_point)
+ Raises:
+ ValueError: If no tracked point is provided.
"""
-
# return an error if no tracked point is provided
if not tracked_point:
raise ValueError("Please provide a tracked point.")
@@ -73,20 +72,21 @@ def import_mobilityLab(
tracked_points: str | list[str],
) -> tuple[pd.DataFrame, pd.DataFrame]:
"""
- Imports data from an APDM Mobility Lab system from the specified file path.
+ Imports and processes data from an APDM Mobility Lab system file.
Args:
- file_name (str or Path): The absolute or relative path to the data file.
- tracked_points (str or list of str]):
- Defines for which tracked points data are to be returned.
+ file_name (str | Path): Path to the Mobility Lab HDF5 file.
+ tracked_points (str | list[str]): Name or list of names for tracked body points to import.
Returns:
- dict, dict: The loaded data and channels as dictionaries.
-
- Examples:
- >>> file_path = "/path/to/sensor_data.h5"
- >>> tracked_points = "Lumbar"
- >>> recording = import_mobilityLab(file_path, tracked_points)
+ tuple[pd.DataFrame, pd.DataFrame]: A tuple containing:
+ - data (pd.DataFrame): DataFrame with combined accelerometer, gyroscope,
+ and magnetometer data for each tracked point.
+ - channels (pd.DataFrame): DataFrame containing metadata, including sensor name,
+ component, type, units, and sampling frequency.
+
+ Raises:
+ ValueError: If any specified tracked point does not exist in the file's monitor labels.
"""
# Convert file_name to a Path object if it is a string
if isinstance(file_name, str):
From dbf50f394f9729c66e1a222c7dd1b0c9dccd02ba Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 12:05:43 +0100
Subject: [PATCH 10/13] consistency in headers
---
docs/utils/index.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/utils/index.md b/docs/utils/index.md
index 651d746..a463fb9 100644
--- a/docs/utils/index.md
+++ b/docs/utils/index.md
@@ -3,14 +3,14 @@
This part of the project documentation focuses on the available **utilities** that assist in various preprocessing, importing, and data handling tasks within the KielMAT toolbox. The following utilities provide functionality to import data from various formats, perform preprocessing, and estimate orientations for movement analysis.
-### [Preprocessing functions](preprocessing.md)
+### [Data Preprocessing](preprocessing.md)
-The **Preprocessing functions** provide a set of utilities designed to prepare motion data for analysis. These functions are essential for cleaning, filtering, and transforming raw sensor data into a suitable format for subsequent analysis.
+The **Data Preprocessing** provide a set of utilities designed to prepare motion data for analysis. These functions are essential for cleaning, filtering, and transforming raw sensor data into a suitable format for subsequent analysis.
-### [Import functions](importers.md)
+### [Data Import](importers.md)
-The **Import functions** within KielMAT are designed to handle data from various sources and formats. This makes it easy to load and integrate different datasets into the toolbox. Below are examples of the import functions available for different sensor data sources:
+The **Data Import** within KielMAT are designed to handle data from various sources and formats. This makes it easy to load and integrate different datasets into the toolbox. Below are examples of the import functions available for different sensor data sources:
- **Axivity Data Import**
The `import_axivity` function imports Axivity data from specified files. It reads Axivity data files, performs lowpass filtering, and calibrates for gravity, ensuring that the data is ready for analysis. The function outputs the data along with the associated channel information in a format compatible with the KielMAT `KielMATRecording` class. This function allows easy integration of Axivity data, including accelerometer information for a specific tracked point.
From 7026ba2a10a9544f14e40c84872946342fabce3c Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 12:18:03 +0100
Subject: [PATCH 11/13] docstrings rendering correctly
---
kielmat/utils/kielmat_dataclass.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/kielmat/utils/kielmat_dataclass.py b/kielmat/utils/kielmat_dataclass.py
index 4558147..1db5b2d 100644
--- a/kielmat/utils/kielmat_dataclass.py
+++ b/kielmat/utils/kielmat_dataclass.py
@@ -92,7 +92,7 @@ def validate_channels(self) -> str:
TypeError: If the 'name' column is not of type string.
Returns:
- str: A message indicating that all channel dataframes are valid.
+ Confirmation message indicating that all channel dataframes are valid.
"""
for system_name, df in self.channels.items():
# Check required columns and their order
From 3a21b363d3e35f9d95f0b6e7b48f29c066d3566a Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 12:37:53 +0100
Subject: [PATCH 12/13] reordering of example
---
...AT.md => basic_01_load_Data_into_KielMAT.md} | 4 +++-
.../basic_01_load_Data_into_KielMAT_1.png} | Bin
...load_dataset.md => basic_02_load_dataset.md} | 0
.../{basic_02_events.md => basic_03_events.md} | 0
docs/examples/index.md | 16 ++++++++--------
.../{modules_01_gsd.md => modules_04_gsd.md} | 8 ++++----
.../modules_04_gsd_11_1.png} | Bin
.../modules_04_gsd_13_1.png} | Bin
.../modules_04_gsd_7_0.png} | Bin
.../modules_04_gsd_9_0.png} | Bin
.../{modules_02_icd.md => modules_05_icd.md} | 4 ++--
.../modules_05_icd_14_1.png} | Bin
.../modules_05_icd_8_0.png} | Bin
.../{modules_03_pam.md => modules_06_pam.md} | 0
.../{modules_04_ptd.md => modules_07_ptd.md} | 4 ++--
...utorial_postural_transition_detection_1.png} | Bin
...utorial_postural_transition_detection_2.png} | Bin
.../{modules_05_td.md => modules_08_td.md} | 4 ++--
.../modules_08_td_1.png} | Bin
.../modules_08_td_2.png} | Bin
mkdocs.yml | 16 ++++++++--------
21 files changed, 29 insertions(+), 27 deletions(-)
rename docs/examples/{basic_00_load_Data_into_KielMAT.md => basic_01_load_Data_into_KielMAT.md} (99%)
rename docs/examples/{basic_00_load_Data_into_KielMAT_files/basic_00_load_Data_into_KielMAT_1.png => basic_01_load_Data_into_KielMAT_files/basic_01_load_Data_into_KielMAT_1.png} (100%)
rename docs/examples/{basic_01_load_dataset.md => basic_02_load_dataset.md} (100%)
rename docs/examples/{basic_02_events.md => basic_03_events.md} (100%)
rename docs/examples/{modules_01_gsd.md => modules_04_gsd.md} (98%)
rename docs/examples/{modules_01_gsd_files/modules_01_gsd_11_1.png => modules_04_gsd_files/modules_04_gsd_11_1.png} (100%)
rename docs/examples/{modules_01_gsd_files/modules_01_gsd_13_1.png => modules_04_gsd_files/modules_04_gsd_13_1.png} (100%)
rename docs/examples/{modules_01_gsd_files/modules_01_gsd_7_0.png => modules_04_gsd_files/modules_04_gsd_7_0.png} (100%)
rename docs/examples/{modules_01_gsd_files/modules_01_gsd_9_0.png => modules_04_gsd_files/modules_04_gsd_9_0.png} (100%)
rename docs/examples/{modules_02_icd.md => modules_05_icd.md} (99%)
rename docs/examples/{modules_02_icd_files/modules_02_icd_14_1.png => modules_05_icd_files/modules_05_icd_14_1.png} (100%)
rename docs/examples/{modules_02_icd_files/modules_02_icd_8_0.png => modules_05_icd_files/modules_05_icd_8_0.png} (100%)
rename docs/examples/{modules_03_pam.md => modules_06_pam.md} (100%)
rename docs/examples/{modules_04_ptd.md => modules_07_ptd.md} (99%)
rename docs/examples/{modules_04_ptd_files/04_tutorial_postural_transition_detection_1.png => modules_07_ptd_files/07_tutorial_postural_transition_detection_1.png} (100%)
rename docs/examples/{modules_04_ptd_files/04_tutorial_postural_transition_detection_2.png => modules_07_ptd_files/07_tutorial_postural_transition_detection_2.png} (100%)
rename docs/examples/{modules_05_td.md => modules_08_td.md} (99%)
rename docs/examples/{modules_05_td_files/modules_05_td_1.png => modules_08_td_files/modules_08_td_1.png} (100%)
rename docs/examples/{modules_05_td_files/modules_05_td_2.png => modules_08_td_files/modules_08_td_2.png} (100%)
diff --git a/docs/examples/basic_00_load_Data_into_KielMAT.md b/docs/examples/basic_01_load_Data_into_KielMAT.md
similarity index 99%
rename from docs/examples/basic_00_load_Data_into_KielMAT.md
rename to docs/examples/basic_01_load_Data_into_KielMAT.md
index 633ba8d..d7a2984 100644
--- a/docs/examples/basic_00_load_Data_into_KielMAT.md
+++ b/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)
-
+
diff --git a/docs/examples/basic_00_load_Data_into_KielMAT_files/basic_00_load_Data_into_KielMAT_1.png b/docs/examples/basic_01_load_Data_into_KielMAT_files/basic_01_load_Data_into_KielMAT_1.png
similarity index 100%
rename from docs/examples/basic_00_load_Data_into_KielMAT_files/basic_00_load_Data_into_KielMAT_1.png
rename to docs/examples/basic_01_load_Data_into_KielMAT_files/basic_01_load_Data_into_KielMAT_1.png
diff --git a/docs/examples/basic_01_load_dataset.md b/docs/examples/basic_02_load_dataset.md
similarity index 100%
rename from docs/examples/basic_01_load_dataset.md
rename to docs/examples/basic_02_load_dataset.md
diff --git a/docs/examples/basic_02_events.md b/docs/examples/basic_03_events.md
similarity index 100%
rename from docs/examples/basic_02_events.md
rename to docs/examples/basic_03_events.md
diff --git a/docs/examples/index.md b/docs/examples/index.md
index 84cc728..e6891f1 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -6,30 +6,30 @@ This section contains a series of examples designed to demonstrate key features
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_00_load_Data_into_KielMAT.md)
+### [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_01_load_dataset.md)
+### [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_02_events.md)
+### [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
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 1: Gait Sequence Detection](modules_01_gsd.md)
+### [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 2: Initial Contact Detection](modules_02_icd.md)
+### [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 3: Physical Activity Monitoring](modules_03_pam.md)
+### [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 4: Postural Transition Detection](modules_04_ptd.md)
+### [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 5: Turn Detection](modules_05_td.md)
+### [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.
diff --git a/docs/examples/modules_01_gsd.md b/docs/examples/modules_04_gsd.md
similarity index 98%
rename from docs/examples/modules_01_gsd.md
rename to docs/examples/modules_04_gsd.md
index 1a2abe4..609c90c 100644
--- a/docs/examples/modules_01_gsd.md
+++ b/docs/examples/modules_04_gsd.md
@@ -159,7 +159,7 @@ plt.show()
-
+
@@ -210,7 +210,7 @@ plt.show()
-
+
@@ -250,7 +250,7 @@ print(recording.events)
-
+
@@ -352,6 +352,6 @@ plt.show()
-
+
diff --git a/docs/examples/modules_01_gsd_files/modules_01_gsd_11_1.png b/docs/examples/modules_04_gsd_files/modules_04_gsd_11_1.png
similarity index 100%
rename from docs/examples/modules_01_gsd_files/modules_01_gsd_11_1.png
rename to docs/examples/modules_04_gsd_files/modules_04_gsd_11_1.png
diff --git a/docs/examples/modules_01_gsd_files/modules_01_gsd_13_1.png b/docs/examples/modules_04_gsd_files/modules_04_gsd_13_1.png
similarity index 100%
rename from docs/examples/modules_01_gsd_files/modules_01_gsd_13_1.png
rename to docs/examples/modules_04_gsd_files/modules_04_gsd_13_1.png
diff --git a/docs/examples/modules_01_gsd_files/modules_01_gsd_7_0.png b/docs/examples/modules_04_gsd_files/modules_04_gsd_7_0.png
similarity index 100%
rename from docs/examples/modules_01_gsd_files/modules_01_gsd_7_0.png
rename to docs/examples/modules_04_gsd_files/modules_04_gsd_7_0.png
diff --git a/docs/examples/modules_01_gsd_files/modules_01_gsd_9_0.png b/docs/examples/modules_04_gsd_files/modules_04_gsd_9_0.png
similarity index 100%
rename from docs/examples/modules_01_gsd_files/modules_01_gsd_9_0.png
rename to docs/examples/modules_04_gsd_files/modules_04_gsd_9_0.png
diff --git a/docs/examples/modules_02_icd.md b/docs/examples/modules_05_icd.md
similarity index 99%
rename from docs/examples/modules_02_icd.md
rename to docs/examples/modules_05_icd.md
index e87c0b6..90ed6f8 100644
--- a/docs/examples/modules_02_icd.md
+++ b/docs/examples/modules_05_icd.md
@@ -152,7 +152,7 @@ plt.show()
-
+
@@ -326,6 +326,6 @@ plt.show()
-
+
diff --git a/docs/examples/modules_02_icd_files/modules_02_icd_14_1.png b/docs/examples/modules_05_icd_files/modules_05_icd_14_1.png
similarity index 100%
rename from docs/examples/modules_02_icd_files/modules_02_icd_14_1.png
rename to docs/examples/modules_05_icd_files/modules_05_icd_14_1.png
diff --git a/docs/examples/modules_02_icd_files/modules_02_icd_8_0.png b/docs/examples/modules_05_icd_files/modules_05_icd_8_0.png
similarity index 100%
rename from docs/examples/modules_02_icd_files/modules_02_icd_8_0.png
rename to docs/examples/modules_05_icd_files/modules_05_icd_8_0.png
diff --git a/docs/examples/modules_03_pam.md b/docs/examples/modules_06_pam.md
similarity index 100%
rename from docs/examples/modules_03_pam.md
rename to docs/examples/modules_06_pam.md
diff --git a/docs/examples/modules_04_ptd.md b/docs/examples/modules_07_ptd.md
similarity index 99%
rename from docs/examples/modules_04_ptd.md
rename to docs/examples/modules_07_ptd.md
index ef2cab5..406ba9d 100644
--- a/docs/examples/modules_04_ptd.md
+++ b/docs/examples/modules_07_ptd.md
@@ -221,7 +221,7 @@ fig.tight_layout()
plt.show()
```
-
+
## Applying Pham Postural Transition Detection Algorithm
@@ -253,7 +253,7 @@ pham = pham.detect(
plot_results=True,
)
```
-
+
The outputs are stored in the `postural_transitions_` attribute, which is a pandas DataFrame in BIDS format with the following columns:
diff --git a/docs/examples/modules_04_ptd_files/04_tutorial_postural_transition_detection_1.png b/docs/examples/modules_07_ptd_files/07_tutorial_postural_transition_detection_1.png
similarity index 100%
rename from docs/examples/modules_04_ptd_files/04_tutorial_postural_transition_detection_1.png
rename to docs/examples/modules_07_ptd_files/07_tutorial_postural_transition_detection_1.png
diff --git a/docs/examples/modules_04_ptd_files/04_tutorial_postural_transition_detection_2.png b/docs/examples/modules_07_ptd_files/07_tutorial_postural_transition_detection_2.png
similarity index 100%
rename from docs/examples/modules_04_ptd_files/04_tutorial_postural_transition_detection_2.png
rename to docs/examples/modules_07_ptd_files/07_tutorial_postural_transition_detection_2.png
diff --git a/docs/examples/modules_05_td.md b/docs/examples/modules_08_td.md
similarity index 99%
rename from docs/examples/modules_05_td.md
rename to docs/examples/modules_08_td.md
index 007b80b..7b38b53 100644
--- a/docs/examples/modules_05_td.md
+++ b/docs/examples/modules_08_td.md
@@ -220,7 +220,7 @@ fig.tight_layout()
plt.show()
```
-
+
## Applying Pham Turn Detection Algorithm
@@ -254,7 +254,7 @@ pham = pham.detect(
plot_results=True,
)
```
-
+
The outputs are stored in the 'turns_' attribute, which is a pandas DataFrame in BIDS format with the following columns:
diff --git a/docs/examples/modules_05_td_files/modules_05_td_1.png b/docs/examples/modules_08_td_files/modules_08_td_1.png
similarity index 100%
rename from docs/examples/modules_05_td_files/modules_05_td_1.png
rename to docs/examples/modules_08_td_files/modules_08_td_1.png
diff --git a/docs/examples/modules_05_td_files/modules_05_td_2.png b/docs/examples/modules_08_td_files/modules_08_td_2.png
similarity index 100%
rename from docs/examples/modules_05_td_files/modules_05_td_2.png
rename to docs/examples/modules_08_td_files/modules_08_td_2.png
diff --git a/mkdocs.yml b/mkdocs.yml
index bc2180f..60a74bd 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -42,14 +42,14 @@ nav:
- Home: index.md
- Examples:
- examples/index.md
- - Load data into KielMAT: examples/basic_00_load_Data_into_KielMAT.md
- - Load datasets: examples/basic_01_load_dataset.md
- - Events in dataclass: examples/basic_02_events.md
- - Gait Sequence Detection: examples/modules_01_gsd.md
- - Initial Contact Detection: examples/modules_02_icd.md
- - Physical Activity Monitoring: examples/modules_03_pam.md
- - Postural Transition Detection: examples/modules_04_ptd.md
- - Turn Detection: examples/modules_05_td.md
+ - Load data into KielMAT: examples/basic_01_load_Data_into_KielMAT.md
+ - Load datasets: examples/basic_02_load_dataset.md
+ - Events in dataclass: examples/basic_03_events.md
+ - Gait Sequence Detection: examples/modules_04_gsd.md
+ - Initial Contact Detection: examples/modules_05_icd.md
+ - Physical Activity Monitoring: examples/modules_06_pam.md
+ - Postural Transition Detection: examples/modules_07_ptd.md
+ - Turn Detection: examples/modules_08_td.md
- Dataclass: dataclass.md
- Modules:
- modules/index.md
From 0185add310749600b7ffa121e6c83413a1214164 Mon Sep 17 00:00:00 2001
From: masoudabedinifar <140504378+masoudabedinifar@users.noreply.github.com>
Date: Wed, 13 Nov 2024 12:50:47 +0100
Subject: [PATCH 13/13] all functions in the mermaid overview
---
docs/dataclass.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/dataclass.md b/docs/dataclass.md
index 5242366..668f24b 100644
--- a/docs/dataclass.md
+++ b/docs/dataclass.md
@@ -11,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
}
```