Skip to content

Commit e612490

Browse files
author
André Böni
committed
+ examples
+ export to netcdf + test export + update readme
1 parent a717592 commit e612490

File tree

13 files changed

+447
-105
lines changed

13 files changed

+447
-105
lines changed

‎README.rst

Lines changed: 159 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@ Gaitalytics
1717
:target: https://python-gaitalytics.readthedocs.io/
1818
:alt: Documentation Status
1919

20-
.. |github-actions| image:: https://github.com/DART-Lab-LLUI/python-gaitalytics/actions/workflows/github-actions.yml/badge.svg
20+
.. |github-actions| image:: https://github.com/DART-Lab-LLUI/python-gaitalytics/actions/workflows/on_push_test.yaml/badge.svg
2121
:alt: GitHub Actions Build Status
22-
:target: https://github.com/DART-Lab-LLUI/python-gaitalytics/actions
22+
:target: https://github.com/DART-Lab-LLUI/python-gaitalytics/actions/
2323

24-
.. |commits-since| image:: https://img.shields.io/github/commits-since/DART-Lab-LLUI/python-gaitalytics/v0.1.2.svg
24+
.. |commits-since| image:: https://img.shields.io/github/commits-since/DART-Lab-LLUI/python-gaitalytics/latest.svg
2525
:alt: Commits since latest release
2626
:target: https://github.com/DART-Lab-LLUI/python-gaitalytics/compare/
2727

@@ -46,14 +46,25 @@ offering high configurability.
4646
Functionalities
4747
---------------
4848

49+
Input
50+
^^^^^
51+
Currently only c3d files are supported.
52+
The library provides a function to load a c3d file into a trial object for usage in the library.
53+
54+
.. note::
55+
future efforts will be made to support other file formats such as trc, mot, sto and mox files.
56+
4957
Event Detection
5058
^^^^^^^^^^^^^^^
5159

52-
+------------+--------------+----------------------------------------------------------------------------+
53-
| Method | Description | options |
54-
+============+==============+============================================================================+
55-
| Marker | Zenis 2006 | |
56-
+------------+--------------+----------------------------------------------------------------------------+
60+
+------------+--------------------------+----------------------------------------------------------------------------+
61+
| Method | Description | options |
62+
+============+==========================+============================================================================+
63+
| Marker | based on Zenis 2006 | - height: The height of peaks for events. |
64+
| | | - threshold: The threshold for detecting events. |
65+
| | | - distance: The min distance in frames between events. |
66+
| | | - rel_height: The relative height of peak for events. |
67+
+------------+--------------------------+----------------------------------------------------------------------------+
5768

5869

5970
Event Detection Check
@@ -62,36 +73,81 @@ Event Detection Check
6273
+------------+--------------------------------------------------+-------------------------+
6374
| Method | Description | options |
6475
+============+==================================================+=========================+
65-
| context | Checks gait event sequences | |
66-
| | HS->TO-HS-TO | |
76+
| sequence | Checks gait event sequences | |
77+
| | - Heel Strike - Toe off - Heel Strike - Toe off | |
78+
| | - Left - Right - Left - Right | |
79+
+------------+--------------------------------------------------+-------------------------+
80+
81+
Event Writing
82+
^^^^^^^^^^^^^
83+
84+
Currently only c3d files are supported.
85+
The main usage for this feature is the correction of detected events.
86+
87+
Segmentation
88+
^^^^^^^^^^^^
89+
90+
Currently only the segmentation based on gait-events is supported.
91+
92+
+------------+--------------------------------------------------+-------------------------+
93+
| Method | Description | options |
94+
+============+==================================================+=========================+
95+
| HS | Segment based on heel strike | |
96+
+------------+--------------------------------------------------+-------------------------+
97+
| TO | Segment based on toe off | |
98+
+------------+--------------------------------------------------+-------------------------+
99+
100+
Time Normalization
101+
^^^^^^^^^^^^^^^^^^
102+
Currently only linear time normalization is supported.
103+
104+
.. note::
105+
future efforts will be made to support other time normalization
106+
methods such as dynamic time warping.
107+
67108
+------------+--------------------------------------------------+-------------------------+
68-
| spacing | Checks Frames between same event on same context | |
109+
| Method | Description | options |
110+
+============+==================================================+=========================+
111+
| linear | Linear time-normalisation | |
69112
+------------+--------------------------------------------------+-------------------------+
70113

71114

72-
Analysis
73-
^^^^^^^^
74-
75-
+-----------------+------------------------------------------------------------+---------------------------------------+
76-
| Method | Description | options |
77-
+=================+============================================================+=======================================+
78-
| angels | - min | |
79-
| forces | - max | |
80-
| moments | - mean | |
81-
| power | - sd | |
82-
| | - median | |
83-
| | - amplitude | |
84-
+-----------------+------------------------------------------------------------+---------------------------------------+
85-
| Spatio-temporal | - step_length [1] | |
86-
| | - stride_length [1] | |
87-
| | - cycle_duration | |
88-
| | - swing_duration_perc | |
89-
| | - stance_duration_perc | |
90-
| | - step_width [1] | |
91-
| | - cadence [1] | |
92-
| | - single_support_duration_percent [2] | |
93-
| | - double_support_duration_percent [2] | |
94-
+-----------------+------------------------------------------------------------+---------------------------------------+
115+
Feature calculation
116+
^^^^^^^^^^^^^^^^^^^
117+
118+
+-------------------------+-------------------------------------------------------+---------------------------------------+
119+
| Method | Description | options |
120+
+=========================+=======================================================+=======================================+
121+
| TimeSeriesFeatures | - min | |
122+
| | - max | |
123+
| | - mean | |
124+
| | - sd | |
125+
| | - median | |
126+
| | - amplitude | |
127+
+-------------------------+-------------------------------------------------------+---------------------------------------+
128+
| PhaseTimeSeriesFeatures | - stand_min | |
129+
| | - stand_max | |
130+
| | - stand_mean | |
131+
| | - stand_sd | |
132+
| | - stand_median | |
133+
| | - stand_amplitude | |
134+
| | - swing_max | |
135+
| | - swing_mean | |
136+
| | - swing_sd | |
137+
| | - swing_median | |
138+
| | - swing_amplitude | |
139+
+-------------------------+-------------------------------------------------------+---------------------------------------+
140+
| SpatialFeatures | - step_length [1] | |
141+
| | - stride_length [1] | |
142+
+-------------------------+-------------------------------------------------------+---------------------------------------+
143+
| TemporalFeatures | - cycle_duration | |
144+
| | - swing_duration_perc | |
145+
| | - stance_duration_perc | |
146+
| | - step_width [1] | |
147+
| | - cadence [1] | |
148+
| | - single_support_duration_percent [2] | |
149+
| | - double_support_duration_percent [2] | |
150+
+-------------------------+-------------------------------------------------------+---------------------------------------+
95151

96152
References
97153
""""""""""
@@ -115,65 +171,95 @@ Fast install with anaconda:
115171

116172
.. code:: shell
117173
118-
conda install gaitalytics
119-
..
120-
121-
122-
You can also install the in-development version with:
123-
124-
.. code:: shell
125-
126-
todo
174+
conda install gaitalytics -c DartLab-LLUI
127175
..
128176
129177
Configuration
130178
^^^^^^^^^^^^^
131179

132180
Gaitalytics can be used with any marker set, which at least includes
133-
four hip markers (left front/back, right front/back) and four foot
134-
markers (left heel/toe, right heel/toe) and four ankle makers (left
135-
medial/lateral, right medial lateral).
181+
three or for hip markers (front left/right, back left/right or sacrum) and four foot
182+
markers (left heel/toe, right heel/toe).
183+
184+
Additionally markers can be defined on which standard time-series features such as min max mean etc.
185+
will be calculated.
136186

137187
All functionalities in the libraries only take points into account which
138-
are configured in as specific yaml file. Working example file can be
139-
found
140-
`here <https://github.com/DART-Lab-LLUI/python-gaitalytics/blob/defc453f95940db55f6875ae7568949daa1b67d4/settings/hbm_pig.yaml>`__
188+
are configured in as specific yaml file.
189+
190+
141191

142192
Minimal requirements would look like this:
143193

144194
.. code:: yaml
145195
146-
marker_set_mapping:
147-
left_back_hip: LASIS
148-
right_back_hip: RASIS
149-
left_front_hip: LPSIS
150-
right_front_hip: RPSIS
196+
# Markers to analyse
197+
analysis:
198+
markers: # Markers to analyse
199+
# Left side
200+
- "LHipAngles"
201+
- "LKneeAngles"
202+
- "LAnkleAngles"
203+
- "LPelvisAngles"
204+
- "LThoraxAngles"
205+
mapping:
206+
markers:
207+
# Foot
208+
l_heel: "LHEE"
209+
r_heel: "RHEE"
210+
l_toe: "LTOE"
211+
r_toe: "RTOE"
212+
213+
# Hip
214+
l_ant_hip: "LASI"
215+
r_ant_hip: "RASI"
216+
l_post_hip: "LPSI"
217+
r_post_hip: "RPSI"
218+
sacrum: "SACR"
219+
..
151220
152-
left_lat_malleoli: LLM
153-
right_lat_malleoli: RLM
154-
left_med_malleoli: LMM
155-
right_med_malleoli: RMM
156221

157-
right_heel: RHEE
158-
left_heel: LHEE
159-
right_meta_2: RMT2
160-
left_meta_2: LMT2
161222

162-
com: COM
163-
left_cmos: cmos_left
164-
right_cmos: cmos_right
223+
Simple Pipeline
224+
^^^^^^^^^^^^^^^^
165225

166-
model_mapping:
167-
..
226+
.. code:: python
227+
228+
from gaitalytics import api
229+
230+
# Load configuration (yaml file from above)
231+
config = api.load_config("./pig_config.yaml")
232+
233+
# Load trial from c3d file
234+
trial = api.load_c3d_trial("./test_small.c3d", config)
235+
236+
# Detect events
237+
events = api.detect_events(trial, config)
238+
try:
239+
# detect events (marker based)
240+
events = api.check_events(events, config)
241+
242+
# check events
243+
api.check_events(events, config)
244+
245+
# write events to c3d in the same file
246+
api.write_events_to_c3d(trial, events)
247+
248+
# segment trial to gait cycles. (Events are already existing in the c3d file)
249+
trial_segmented = api.segment_trial(trial)
250+
251+
# calculate features
252+
features = api.calculate_features(trial_segmented, config)
168253
169-
**Warning** Do not rename keys of the minimal setting
254+
# save features
255+
faetures.to_netcdf("features.nc")
170256
171-
Pipeline
172-
^^^^^^^^
257+
# export segmented trial to netcdf
258+
api.export_trial(trial_segmented, config, "output.nc")
173259
174-
Please take the resources in the `example
175-
folder <https://github.com/DART-Lab-LLUI/python-gaitalytics/tree/defc453f95940db55f6875ae7568949daa1b67d4/examples>`__
176-
for advice.
260+
api.export_trial(trial_segmented, config, "output.c3d")
261+
except ValueError as e:
262+
print(e)
177263
178264
Documentation
179265
-------------

‎conda.recipe/meta.yaml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
{% set name = "gaitalytics" %}
2-
{% set version = GIT_DESCRIBE_TAG %}
2+
{% set version = '0.2.0' %}
33

44

55
package:
66
name: {{ name|lower }}
7-
version: {{ GIT_DESCRIBE_TAG }}
7+
version: {{ version }}
88

99
source:
10-
git_url: https://github.com/DART-Lab-LLUI/python-gaitalytics.git
10+
url: https://github.com/DART-Lab-LLUI/python-gaitalytics/releases/download/{{ version }}/gaitalytics-{{ version }}.tar.gz
1111

1212
build:
1313
noarch: python

‎docs/api.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Api
2+
===
3+
4+
5+
.. autofunction:: gaitalytics.api.load_config
6+
.. autofunction:: gaitalytics.api.load_c3d_trial
7+
.. autofunction:: gaitalytics.api.detect_events
8+
.. autofunction:: gaitalytics.api.check_events
9+
.. autofunction:: gaitalytics.api.write_events_to_c3d
10+
.. autofunction:: gaitalytics.api.segment_trial
11+
.. autofunction:: gaitalytics.api.time_normalise_trial
12+
.. autofunction:: gaitalytics.api.calculate_features
13+
.. autofunction:: gaitalytics.api.export_trial
14+
15+

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
:maxdepth: 2
44

55
readme
6+
api
67
reference/index
78
contributing
89
authors

‎example/calculate_features.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
from gaitalytics import api
2+
3+
config = api.load_config("./tests/pig_config.yaml")
4+
trial = api.load_c3d_trial("./tests/test_small.c3d", config)
5+
trial_segmented = api.segment_trial(trial)
6+
features = api.calculate_features(trial_segmented, config)

‎example/detect_events.py

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
from gaitalytics import api
2+
3+
config = api.load_config("./tests/pig_config.yaml")
4+
trial = api.load_c3d_trial("./tests/test_small.c3d", config)
5+
events = api.detect_events(trial, config)
6+
7+
try:
8+
api.check_events(trial.events)
9+
except ValueError as e:
10+
print(e)
11+
12+
api.write_events_to_c3d("./tests/test_small.c3d", events,
13+
"./out/test_small_events.c3d")
14+

‎example/export.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
from gaitalytics import api
2+
3+
config = api.load_config("./tests/pig_config.yaml")
4+
trial = api.load_c3d_trial("./tests/test_small.c3d", config)
5+
trial_segmented = api.segment_trial(trial)
6+
api.export_trial(trial_segmented, "./out/test_small_segmented")

‎example/normalize_trial.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
from gaitalytics import api
2+
3+
config = api.load_config("./tests/pig_config.yaml")
4+
trial = api.load_c3d_trial("./tests/test_small.c3d", config)
5+
trial_segmented = api.segment_trial(trial)
6+
normalized_trial = api.time_normalise_trial(trial_segmented)
7+

‎example/segment_trial.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
from gaitalytics import api
2+
3+
config = api.load_config("./tests/pig_config.yaml")
4+
trial = api.load_c3d_trial("./tests/test_small.c3d", config)
5+
trial_segmented = api.segment_trial(trial)

0 commit comments

Comments
 (0)