Note
Go to the end to download the full example code
Loading example data#
This example shows how to use the loader functions to load example data.
Laboratory data#
We provide a small subset of the TVS dataset of the Mobilise-D project as example data.
The data only contains a small number of participants and only two (instead of the ten) laboratory tests of each
participant.
The data is stored in the examples/data folder of the repository in the Mobilise-D matlab format [1].
Dataset Class#
We provide a LabExampleDataset class to load the example data.
This is the easiest way to access the example data and allows you to select and iterate over the data in an easy way.
from mobgap.data import LabExampleDataset
example_data = LabExampleDataset()
You can select the data you want using the get_subset method.
ha_example_data = example_data.get_subset(cohort="HA")
ha_example_data
Once you selected only a single row of the dataset (either by repeated get_subset or by iteration), you can load
the actual data.
single_test = ha_example_data.get_subset(
participant_id="002", test="Test5", trial="Trial2"
)
single_test
The raw IMU data can be accessed in two ways:
.datawhich contains a dictionary with the data of all IMU sensors in the dataset. Per default, we only load the data of the “LowerBack” sensor for performance reasons. But, you can select the sensors to load using theraw_data_sensorandsensor_psotionsargument of the Dataset class.
imu_data = single_test.data["LowerBack"]
imu_data
/home/docs/checkouts/readthedocs.org/user_builds/mobgap/checkouts/v0.9.0/mobgap/data/_mobilised_matlab_loader.py:1189: UserWarning: Global caching is a little tricky to get right and our implementation is not yet battle-tested. Please double check that the results are correct and report any issues you find.
return hybrid_cache(self.memory, 1)(_load_test_data_without_checks)(
.data_sswhich contains only the data of the “single sensor”. This is the data used as input for all algorithms in the provided pipelines. In most cases this is equivalent to the data of the “LowerBack” sensor, but a different position can be selected using thesingle_sensor_position(orsingle_sensor_namein some Dataset classes) argument of the Dataset class.
single_sensor_data = single_test.data_ss
single_sensor_data
import matplotlib.pyplot as plt
single_sensor_data.filter(like="gyr").plot()
plt.show()
Test-level metadata:
single_test.recording_metadata
{'start_date_time_iso': '2020-08-21T12:30:50.479+02:00', 'time_zone': 'Europe/Berlin', 'sampling_rate_hz': 100.0, 'reference_sampling_rate_hz': None, 'measurement_condition': 'laboratory', 'recording_identifier': ('TimeMeasure1', 'Test5', 'Trial2')}
Participant-level metadata:
single_test.participant_metadata
{'cohort': 'HA', 'foot_length_cm': 26.4, 'handedness': 'right', 'height_m': 1.75, 'indip_data_used': 'All', 'sensor_attachment_su': 'Body-Worn', 'sensor_height_m': 1.08, 'sensor_type_su': 'MM+', 'walking_aid_used': False, 'weight_kg': 82.0}
You can also load the reference system data, by specifying the reference_system argument.
All parameters related to the reference systems have a trailing underscore.
example_data_with_reference = LabExampleDataset(reference_system="Stereophoto")
single_trial_with_reference = example_data_with_reference.get_subset(
cohort="HA", participant_id="002", test="Test5", trial="Trial2"
)
single_trial_with_reference.raw_reference_parameters_
{'lwb': [{'Start': 2.28, 'End': 5.39, 'StrideFrequency': 49.36164888953828, 'Cadence': 98.72329777907656, 'Duration': 3.11, 'Length': 4.113706815831932, 'LengthFeet': 3.990970590722213, 'WalkingSpeed': 1.3727010349957065, 'AverageStrideLength': 1.6696087035787461, 'NumberStrides': 4.0, 'TerminationReason': 'Pause', 'Break_Start': array([], dtype=float64), 'Break_End': array([], dtype=float64), 'Break_Number': array([], dtype=float64), 'Break_Duration': array([], dtype=float64), 'Turning_Flag': 0.0, 'Turn_Start': array([], dtype=float64), 'Turn_End': array([], dtype=float64), 'Turn_Duration': array([], dtype=float64), 'Turn_Number': array([], dtype=float64), 'Turn_Angle': array([], dtype=float64), 'Turn_NumberStrides': array([], dtype=float64), 'Turn_AngularVelocity': array([], dtype=float64), 'Turn_PeakAngularVelocity': array([], dtype=float64), 'Turn_MeanAngularVelocity': array([], dtype=float64), 'Turn_Length': array([], dtype=float64), 'Stride_Duration': array([1.28, 1.18, 1.16, 1.25]), 'Stride_Length': array([1.6130588 , 1.59518995, 1.65295507, 1.81723099]), 'Stride_Height': array([ 0.00258984, 0.0019533 , -0.00603833, -0.01509003]), 'Stride_Speed': array([1.26020219, 1.35185589, 1.42496127, 1.45378479]), 'Stride_TrunkElevationChange': array([0.015336 , 0.00167007, 0.00736727, 0.03591326]), 'Stance_Duration': array([0.85, 0.74, 0.75, 0.73]), 'Swing_Duration': array([0.43, 0.44, 0.41, 0.52]), 'SingleSupport_Duration': array([ nan, 0.87, 0.85, 0.93]), 'DoubleSupport_Duration': array([ nan, 0.31, 0.31, 0.32]), 'Stance_Length': array([0.22870683, 0.20503215, 0.2409645 , 0.24516186]), 'Swing_Length': array([1.37562656, 1.38826616, 1.40289499, 1.56628489]), 'Stance_Speed': array([0.26906685, 0.27707047, 0.32128599, 0.33583817]), 'Swing_Speed': array([3.19913153, 3.15515037, 3.42169511, 3.01208632]), 'SingleSupport_Length': array([], dtype=float64), 'DoubleSupport_Length': array([], dtype=float64), 'SingleSupport_Speed': array([], dtype=float64), 'DoubleSupport_Speed': array([], dtype=float64), 'Stride_InitialContacts': array([[2.28, 3.56],
[2.96, 4.14],
[3.56, 4.72],
[4.14, 5.39]]), 'InitialContact_Event': array([2.28, 2.96, 3.56, 4.14, 4.72, 5.39]), 'InitialContact_LeftRight': array(['Left', 'Right', 'Left', 'Right', 'Left', 'Right'], dtype=object), 'FinalContact_Event': array([3.13, 3.7 , 4.31, 4.87]), 'FinalContact_LeftRight': array(['Left', 'Right', 'Left', 'Right'], dtype=object), 'Step_Duration': array([0.68, 0.6 , 0.58, 0.58, 0.67]), 'Step_Length': array([0.78400307, 0.79455085, 0.78468028, 0.83038434, 0.92008828]), 'Step_Length_Feet': array([0.79563927, 0.81137347, 0.78349089, 0.87076342, 0.95103785]), 'Step_Speed': array([1.15294569, 1.32425142, 1.35289704, 1.43169713, 1.37326609]), 'Step_TrunkElevationChange': array([0.00490894, 0.01042706, 0.01209712, 0.01946439, 0.01644887])}], 'wb': [{'Start': 2.28, 'End': 5.39, 'StrideFrequency': 49.36164888953828, 'Cadence': 98.72329777907656, 'Duration': 3.11, 'Length': 4.113706815831932, 'LengthFeet': 3.990970590722213, 'WalkingSpeed': 1.3727010349957065, 'AverageStrideLength': 1.6696087035787461, 'NumberStrides': 4.0, 'TerminationReason': 'Pause', 'Break_Start': array([], dtype=float64), 'Break_End': array([], dtype=float64), 'Break_Number': array([], dtype=float64), 'Break_Duration': array([], dtype=float64), 'Turning_Flag': 0.0, 'Turn_Start': array([], dtype=float64), 'Turn_End': array([], dtype=float64), 'Turn_Duration': array([], dtype=float64), 'Turn_Number': array([], dtype=float64), 'Turn_Angle': array([], dtype=float64), 'Turn_NumberStrides': array([], dtype=float64), 'Turn_AngularVelocity': array([], dtype=float64), 'Turn_PeakAngularVelocity': array([], dtype=float64), 'Turn_MeanAngularVelocity': array([], dtype=float64), 'Turn_Length': array([], dtype=float64), 'Turning_SharpTurn_Flag': array([], dtype=float64), 'Incline_Start': array([], dtype=float64), 'Incline_End': array([], dtype=float64), 'Incline_Duration': array([], dtype=float64), 'Incline_Number': array([], dtype=float64), 'Incline_NumberStrides': array([], dtype=float64), 'Incline_PositiveElevation': array([], dtype=float64), 'Incline_NegativeElevation': array([], dtype=float64), 'Stride_Duration': array([1.28, 1.18, 1.16, 1.25]), 'Stride_Length': array([1.6130588 , 1.59518995, 1.65295507, 1.81723099]), 'Stride_Height': array([ 0.00258984, 0.0019533 , -0.00603833, -0.01509003]), 'Stride_Speed': array([1.26020219, 1.35185589, 1.42496127, 1.45378479]), 'Stride_TrunkElevationChange': array([0.015336 , 0.00167007, 0.00736727, 0.03591326]), 'Stance_Duration': array([0.85, 0.74, 0.75, 0.73]), 'Swing_Duration': array([0.43, 0.44, 0.41, 0.52]), 'SingleSupport_Duration': array([ nan, 0.87, 0.85, 0.93]), 'DoubleSupport_Duration': array([ nan, 0.31, 0.31, 0.32]), 'Stance_Length': array([0.22870683, 0.20503215, 0.2409645 , 0.24516186]), 'Swing_Length': array([1.37562656, 1.38826616, 1.40289499, 1.56628489]), 'Stance_Speed': array([0.26906685, 0.27707047, 0.32128599, 0.33583817]), 'Swing_Speed': array([3.19913153, 3.15515037, 3.42169511, 3.01208632]), 'SingleSupport_Length': array([], dtype=float64), 'DoubleSupport_Length': array([], dtype=float64), 'SingleSupport_Speed': array([], dtype=float64), 'DoubleSupport_Speed': array([], dtype=float64), 'Stride_InitialContacts': array([[2.28, 3.56],
[2.96, 4.14],
[3.56, 4.72],
[4.14, 5.39]]), 'InitialContact_Event': array([2.28, 2.96, 3.56, 4.14, 4.72, 5.39]), 'InitialContact_LeftRight': array(['Left', 'Right', 'Left', 'Right', 'Left', 'Right'], dtype=object), 'FinalContact_Event': array([3.13, 3.7 , 4.31, 4.87]), 'FinalContact_LeftRight': array(['Left', 'Right', 'Left', 'Right'], dtype=object), 'Step_Duration': array([0.68, 0.6 , 0.58, 0.58, 0.67]), 'Step_Length': array([0.78400307, 0.79455085, 0.78468028, 0.83038434, 0.92008828]), 'Step_Length_Feet': array([0.79563927, 0.81137347, 0.78349089, 0.87076342, 0.95103785]), 'Step_Speed': array([1.15294569, 1.32425142, 1.35289704, 1.43169713, 1.37326609]), 'Step_TrunkElevationChange': array([0.00490894, 0.01042706, 0.01209712, 0.01946439, 0.01644887])}]}
The data you can see above is the “raw” reference data.
Including both the information for walking bouts and level-walking bouts.
To access the data in format that can be directly compared to the output of the mobgap algorithms or used as input
to algorithms further down the processing pipeline, you can use the reference_parameters_ attribute.
If the data is extracted from the normal walking bouts or the level walking bouts is controlled by the
reference_para_level parameter of the Dataset class (default is wb).
ref_paras = single_trial_with_reference.reference_parameters_
This attribute contains the data for the outputs of the various steps of the processing pipeline.
Functional interface#
We can get the local path to the example data using get_all_lab_example_data_paths
and then use load_mobilised_matlab_format to load the data.
from mobgap.data import (
get_all_lab_example_data_paths,
load_mobilised_matlab_format,
)
all_example_data_paths = get_all_lab_example_data_paths()
list(all_example_data_paths.keys())
[('HA', '001'), ('HA', '002'), ('MS', '001')]
Then we can select the participant we want to load.
example_participant_path = all_example_data_paths[("HA", "002")]
data = load_mobilised_matlab_format(example_participant_path / "data.mat")
Calling the loader function without any further arguments, will load the “SU” (normal lower-back sensor) only.
The returned dictionary contains the test names as keys and the loaded data as
MobilisedTestData objects.
This allows for easy access to the data and metadata without traversing a nested data structure.
[('TimeMeasure1', 'Test5', 'Trial1'), ('TimeMeasure1', 'Test5', 'Trial2'), ('TimeMeasure1', 'Test11', 'Trial1')]
We can access the data of a single test by using the test name as key.
test_11_data = data[test_list[2]]
imu_data = test_11_data.imu_data["LowerBack"]
imu_data
We can also access the metadata of the test.
{'start_date_time_iso': '2020-08-21T12:50:00.388+02:00', 'time_zone': 'Europe/Berlin', 'sampling_rate_hz': 100.0, 'reference_sampling_rate_hz': None}
To load reference data as well, we can use the reference_system argument.
Note, that we don’t have a way to load the raw data of the reference system.
We only load the calculated parameters.
The available reference systems will depend on the data.
data_with_reference = load_mobilised_matlab_format(
example_participant_path / "data.mat", reference_system="INDIP"
)
selected_test = data_with_reference[test_list[2]]
The returned MobilisedTestData objects now contain the reference parameters.
And metadata about the reference system is available as well.
ref_sampling_rate_hz = selected_test.metadata["reference_sampling_rate_hz"]
ref_sampling_rate_hz
100.0
To parse the reference data into better data structures, we can use the
parse_reference_parameters function.
from mobgap.data import parse_reference_parameters
data_sampling_rate_hz = selected_test.metadata["sampling_rate_hz"]
ref_paras_functional = parse_reference_parameters(
raw_reference_data["wb"],
data_sampling_rate_hz=data_sampling_rate_hz,
ref_sampling_rate_hz=ref_sampling_rate_hz,
)
They have the same structure the reference parameters of the Dataset class.
ReferenceData(wb_list= start end ... avg_stride_length_m termination_reason
wb_id ...
0 485 1131 ... 0.747408 Pause
1 1746 3554 ... 0.463619 Pause
2 6083 7708 ... 0.809791 Pause
[3 rows x 9 columns], ic_list= ic lr_label
wb_id step_id
0 0 485 right
1 553 left
2 619 right
3 692 left
4 742 right
5 779 left
6 862 right
8 1016 right
10 1130 right
1 0 1746 right
1 1768 left
2 1874 left
3 2005 right
4 2120 left
5 2196 right
7 2399 right
8 2489 left
9 2655 right
10 2675 left
11 2752 left
12 2880 right
14 3068 right
15 3139 left
16 3199 right
17 3289 left
19 3426 left
21 3553 left
2 0 6083 left
1 6151 right
2 6199 left
3 6277 right
4 6358 left
5 6425 right
6 6480 left
7 6534 right
8 6630 left
9 6758 right
10 6785 left
11 6847 right
12 6919 left
13 6985 right
14 7065 left
15 7112 right
16 7228 right
18 7476 right
20 7707 right, turn_parameters= start end duration_s angle_deg direction
wb_id turn_id
0 0 621 1049 4.27 -135.426119 right
2 0 6231 6490 2.58 -147.071110 right
1 6981 7222 2.40 149.190550 left, stride_parameters= start end duration_s ... stance_time_s swing_time_s lr_label
wb_id s_id ...
0 0 485 620 1.34 ... 0.88 0.46 right
1 553 693 1.39 ... 0.84 0.55 left
2 619 743 1.23 ... 0.86 0.37 right
3 692 780 NaN ... NaN NaN left
4 742 863 1.20 ... NaN NaN right
6 862 1017 1.54 ... 1.15 0.39 right
8 1016 1131 1.14 ... 0.56 0.58 right
1 0 1746 2006 2.59 ... 1.43 1.16 right
1 1768 1875 NaN ... NaN NaN left
2 1874 2121 2.46 ... 1.07 1.39 left
3 2005 2197 1.91 ... 1.30 0.61 right
5 2196 2400 2.03 ... 1.40 0.63 right
7 2399 2656 2.56 ... 1.18 1.38 right
8 2489 2676 NaN ... NaN NaN left
9 2655 2881 2.25 ... 0.91 1.34 right
10 2675 2753 0.77 ... 0.16 0.61 left
12 2880 3069 1.88 ... 1.13 0.75 right
14 3068 3200 1.31 ... 1.00 0.31 right
15 3139 3290 1.50 ... 0.65 0.85 left
17 3289 3427 1.37 ... NaN NaN left
19 3426 3554 1.27 ... 0.91 0.36 left
2 0 6083 6200 1.16 ... 0.84 0.32 left
1 6151 6278 NaN ... NaN NaN right
2 6199 6359 1.59 ... 0.83 0.76 left
3 6277 6426 1.48 ... 0.89 0.59 right
4 6358 6481 1.22 ... 0.45 0.77 left
5 6425 6535 1.09 ... 0.71 0.38 right
6 6480 6631 1.50 ... 1.28 0.22 left
7 6534 6759 2.24 ... 1.14 1.10 right
8 6630 6786 1.55 ... 0.99 0.56 left
9 6758 6848 0.89 ... 0.44 0.45 right
10 6785 6920 1.34 ... 0.78 0.56 left
11 6847 6986 1.38 ... 0.89 0.49 right
12 6919 7066 1.46 ... 0.83 0.63 left
13 6985 7113 1.27 ... 0.87 0.40 right
15 7112 7229 NaN ... NaN NaN right
16 7228 7477 2.48 ... 1.97 0.51 right
18 7476 7708 2.31 ... 1.03 1.28 right
[38 rows x 8 columns])
Total running time of the script: (0 minutes 4.061 seconds)
Estimated memory usage: 17 MB