Detect cycles in a TimeSeries based on a dual threshold approach.
This function detects biphasic cycles and identifies the transitions as new events in the output TimeSeries. These new events are named:
@@ -261,30 +261,30 @@Warning
+This function, which has been introduced in 0.4, is still experimental and +may change signature or behaviour in the future.
+ts (TimeSeries) – TimeSeries to analyze.
data_key (str) – Name of the data key to analyze in the TimeSeries. This signal must be
-high during phase 1, and low during phase 2. For example, one could
-use the absolute ground reaction force to detect stance (phase 1) and
-swing (phase 2).
event_name1 (str) – Name of the events in the output TimeSeries that corresponds to the
-start of phase 1.
event_name2 (str) – Name of the events in the output TimeSeries that corresponds to the
-start of phase 2.
threshold1 (float) – Value to cross to register the start of phase 1 and phase 2.
threshold2 (float) – Value to cross to register the start of phase 1 and phase 2.
direction1 (str) – Optional. ‘rising’ to cross threshold1 upward, ‘falling’ to cross
-threshold1 downward.
min_duration1 (float) – Optional. Minimal duration of phase 1 and phase 2 in seconds.
min_duration2 (float) – Optional. Minimal duration of phase 1 and phase 2 in seconds.
max_duration1 (float) – Optional. Maximal duration of phase 1 and phase 2 in seconds.
max_duration2 (float) – Optional. Maximal duration of phase 1 and phase 2 in seconds.
min_peak_height1 (float) – Optional. Minimum peak value for phase 1 and phase 2.
min_peak_height2 (float) – Optional. Minimum peak value for phase 1 and phase 2.
max_peak_height1 (float) – Optional. Maximal peak value for phase 1 and phase 2.
max_peak_height2 (float) – Optional. Maximal peak value for phase 1 and phase 2.
data_key (str) – Name of the data key to analyze in the TimeSeries.
event_names (Sequence[str]) – Optional. Name of the events to add in the output TimeSeries. Default
+is [‘phase1’, ‘phase2’].
thresholds (Sequence[float]) – Optional. Value to cross to register phase changes. Default is
+[0., 1.].
directions (Sequence[str]) – Optional. Direction to cross thresholds to register phase changes.
+Either [‘rising’, ‘falling’] or [‘falling’, ‘rising’]. Default is
+[‘rising’, ‘falling’].
min_durations (Sequence[float]) – Optional. Minimal phase durations in seconds. Default is [0., 0.].
max_durations (Sequence[float]) – Optional. Maximal phase durations in seconds. Default is
+[np.Inf, np.Inf]
min_peak_heights (Sequence[float]) – Optional. Minimal peak values to be reached in both phases. Default is
+[-np.Inf, -np.Inf].
max_peak_heights (Sequence[float]) – Optional. Maximal peak values to be reached in both phases. Default is
+[np.Inf, np.Inf].
Note
-When using min_peak_height1, min_peak_height1, max_peak_height1 and -max_peak_height2:
-If direction1 is ‘rising’, then the peak value is the maximum during -phase 1 and the minimum during phase 2.
If direction1 is ‘falling’, then the peak value is the minimum -during phase 1 and the maximum during phase 2.
test = ktk.cycles.detect_cycles(ts, 'Ftot',
- event_name1='push',
- event_name2='recovery',
- threshold1=10,
- threshold2=5)
+ event_names=['push', 'recovery'],
+ thresholds=[10, 5])
test.plot(['Forces', 'Ftot'])
plt.tight_layout()
test = ktk.cycles.detect_cycles(ts, 'Ftot',
- event_name1='push',
- event_name2='recovery',
- threshold1=10,
- threshold2=5,
- min_duration1=0.2,
- min_duration2=0.2)
+ event_names=['push', 'recovery'],
+ thresholds=[10, 5],
+ min_durations=[0.2, 0.2])
test.plot(['Forces', 'Ftot'])
plt.tight_layout()
ts_with_events = ktk.cycles.detect_cycles(ts, 'Ftot',
- event_name1='push',
- event_name2='recovery',
- threshold1=10,
- threshold2=5,
- min_duration1=0.2,
- min_duration2=0.2,
- min_peak_height1=50)
+ event_names=['push', 'recovery'],
+ thresholds=[10, 5],
+ min_durations=[0.2, 0.2],
+ min_peak_heights=[50, -np.Inf])
ts_with_events.plot(['Forces', 'Ftot'])
plt.tight_layout()
No new feature for the moment, except from small API fixes.
Most TimeSeries arguments can now be used either by position or keyword (removed superflous slash operators in signatures).
cycle.detect_cycles was changed to experimental. Its argument pairs xxxx1, xxxx2 have been changed to sequences [xxxx1, xxxx2] in prevision of possible cycle detections with more than 2 phases, or even only one phase. This method is now experimental because it may be separated into different functions (one to detect cycles, another to search cycles with given criteria, and another to remove found cycles).
Added the geometry module to perform rigid body geometry operations such as creating frames, homogeneous transforms, multiplying series of matrices, converting from local to global coordinates and vice-versa, and extracting Euler angles from homogeneous transforms.
Added the span option to cycles.time_normalize, so that cycles can be normalized between other ranges than 0% to 100%. Both reducing span (e.g., 10% to 90%) and increasing span (e.g., -25 to 125%) work.
Added the to_html5 method to Player, which allows visualizing 3d markers and bodies in Jupyter.
Added the rename_event method to TimeSeries.
Added test coverage measurement for continuous improvement of code robustness.
Added warnings when using private or unstable functions.
Changed the website to use the ReadTheDoc theme, and changed its structure to facilitate continuous improvements of the website without needing to wait for releases.
The default behaviour for TimeSeries.remove_event changed when no occurrence is defined. Previously, only the first occurrence was removed. Now every occurrence is removed.
In cycles.time_normalize, the way to time-normalize between two events of the same name changed from event_name, _ to event_name, event_name.
Added the cycles module to detect, time-normalize and stack cycles (e.g., gait cycles, wheelchair propulsion cycles, etc.)
Added the pushrimkinetics module to read files from instrumented wheelchair wheels, reconstruct the pushrim kinetics, remove dynamic offsets in kinetic signals, and perform speed and power calculation for analysing spatiotemporal and kinetic parameters of wheelchair propulsion.
TimeSeries.plot() now shows the event occurrences besides the event names.
Nicer tutorial for the filters module.
Improved unit tests for the filters module.
The module name has been changed from ktk to kineticstoolkit. Importing using import ktk is now deprecated and the standard way to import is now either import kineticstoolkit as ktk or import kineticstoolkit.lab as ktk.
Now importing Kinetics Toolkit does not change IPython’s representation of dicts or matplotlib’s defaults. This allows using ktk’s functions without modifying the current working environment. The old behaviour is now the lab mode and is the recommended way to import Kinetics Toolkit in an IPython-based environment: import kineticstoolkit.lab as ktk.
Added the functions ktk.load and ktk.save.
Introduced the ktk.zip file format.
Updated the documentation system using sphinx and jupyter-lab.
Improved performance of TimeSeries.from_dataframe()
ktk is now typed.
TimeSeries.from_dataframe() is now a class function and not an instance method anymore. Therefore we need to call ktk.TimeSeries.from_dataframe(dataframe) instead of ktk.TimeSeries().from_dataframe(dataframe).
Now depends on python 3.8 instead of 3.7.
Added the TimeSeries class.
Added the kinematics module, to read c3d and n3d files.