Kinetics Toolkit

Kinetics Toolkit#

Announcements

0.14.3

Posted on 14 May 2024

Kinetics Toolkit 0.14.3 has been released. This is a small bugfix release with no new feature.

What's Changed

FIX: fixed the analogs/points sampling rate comparison by @andreyzhd in #236
Fixed bug on first index of fill_missing_samples by @Alek050 in #239
Deprecated features scheduled to be removed in 2024 have been removed.

New Contributors

@andreyzhd made their first contribution in #236

Full Changelog: 0.14.2...0.14.3

This discussion was created from the release 0.14.3.

Kinetics Toolkit 0.14 has been released!

Posted on 5 March 2024

This is a pretty big release, particularly for the Player which can now be completely scripted and stylized, and which can export images and videos. Also, the TimeSeries has been polished and is now easier than ever to use conjointly with your current code. Here is the complete release notes:

New features

Scripting API for the Player

The Player can now be entirely scripted:

Get/set the TimeSeries to be visualized using Player.get_contents() and Player.set_contents()
Get/set the point interconnections using Player.get_interconnections() and Player.set_interconnections()
Play/pause using Player.play() and Player.pause()
Access and modify all settings using properties such as current_index, current_time, target, zoom, elevation, azimuth, etc.

Styling the Player

Every element can now be stylized using properties such as background_color, default_point_color, point_size, frame_size, frame_width, grid_size, grid_subdivision_size, etc.

Exporting the Player's content to images and videos

You can now export the Player's content to image files such as PNG, JPEG, PDF, SVG or TIFF using Player.to_image(), or to MP4 videos using Player.to_video(). This, combined to styling, should help you giving nice presentations!

Standard views in the Player

By defining which axes (x, y, z, -x, -y, -z) correspond to the up and anterior direction using the up and anterior properties, you can now switch to standard orthogonal views using Player.set_view(). For example: p.set_view("front"), p.set_view("top"), p.set_view("right"), etc. These views are also available interactively using number keys 1 to 6.

Interconnection wildcards in the Player

Create interconnections for one body, and apply it to multiple bodies at once, using wildcard (*) in point names. This should facilitate visualizing acquisitions with more than one person (e.g., use *C7 and *T1 instead of Body1:C7, Body1:T1, Body2:C7, Body2:T1) or to create a sequence of movements (e.g., use C7* and T1* instead of C7_frame0, T1_frame0, C7_frame1, T1_frame1).

Convert anything to a TimeSeries

It is now easier than never to create a TimeSeries. For instance, a list of data:

some_list = [1.0, 1.1, 1.2, 1.1, 1.4, 1.5]

can be transformed into a TimeSeries using:

some_timeseries = ktk.TimeSeries(some_list)

It works for any other array-like such as nested lists, NumPy arrays, Pandas Series, Pandas DataFrames. It can also be used to create copies of TimeSeries.

New TimeSeries.add_data method

The new TimeSeries.add_data method now complements its siblings TimeSeries.rename_data and TimeSeries.remove_data. Using this method ensures that the added data is compatible with the data already present in the TimeSeries (e.g., it has the same dimension across the time dimension) and that you specify wether or not existing data of the same name must be overwritten.

New overwrite option to TimeSeries.add_data_info

A new parameter overwrite has been added to TimeSeries.add_data_info so that you can specify wether or not already existing data info of the same name must be overwritten.

Improvements

Improved TimeSeries assignations

It is now possible to assign any array-like value to a TimeSeries' time or data property; it will be converted automatically to a proper NumPy array.

Improved parameter checking

Parameter checking has been generally improved, so that if you make a mistake, you will be more likely to get a helpful error message.

Warning on non-interactive mode

You will now get a warning if you attempt to use an interactive Matplotlib object (e.g., the Player, or a GUI-based method) without having configured Matplotlib to be interactive.

Future exciting change to TimeSeries() that may potentially break some code (+ very easy fix)

Posted on 10 November 2023

In the next release (0.14), the TimeSeries constructor will change slightly in a way that could break your code if you initialized a TimeSeries using a list of arguments. I don't think many people will be affected because such TimeSeries initialization has never been used in examples or tutorials.

More precisely, if your code creates a TimeSeries from scratch (in opposition to reading a file, e.g., ktk.read_c3d):

Still working

Creating an empty TimeSeries

ts = ktk.TimeSeries()
ts.time = some_time_variable
ts.data["some_data_key"] = some_array

Creating a TimeSeries with time and data as keyword arguments

ts = ktk.TimeSeries(time=some_time_variable, data={"some_data_key": some_array})

Won't work anymore

Creating a TimeSeries with time and data as a list of arguments

# Won't work in version 0.14
ts = ktk.TimeSeries(some_time_variable, {"some_data_key": some_array})

If you happen to have such TimeSeries initialization in your code, it is highly recommended to change for an initialization using keyword arguments (which is generally a better coding practice anyway) before updating to the upcoming 0.14 version.

This is related to new feature #199 which will bring a very exciting way to create a TimeSeries directly from many types of variables, by directly casting these variables to TimeSeries. For instance:

# Coming in next release
ts = ktk.TimeSeries(some_array)
ts = ktk.TimeSeries(some_DataFrame)
ts = ktk.TimeSeries(some_list)

# etc.

Kinetics Toolkit 0.13 released

Posted on 18 October 2023

A new release on the road toward version 1.0. Remember that starting from 0.12, the API is mostly stable and we won't remove any feature or make any incompatible change before either 1.0 is released or before 2 years of deprecation warnings. It is safe to use Kinetics Toolkit in your work, we won't let you down!

In this release:

Improvements

ktk.read_c3d() can now read the event contexts, not just the names, using the new include_event_context argument. If False, the events in the output TimeSeries are named after the events names in the C3D files, e.g.: "Start", "Heel Strike", "Toe Off". If True, the events in the output TimeSeries are named using this scheme "context:name", e.g.,: "General:Start", "Right:Heel strike", "Left:Toe Off". The default is False. Thanks @jorgomezga for suggesting and testing!
TimeSeries' methods get_ts_between_indexes(), get_ts_between_times() and get_ts_between_events() now accept a new form for their argument inclusive. In addition to provide a simple boolean (False: strictly between, True: inclusive between), we can now provide a tuple/list of two booleans. For instance, [True, False] means "greater or equal to first index/time, and strictly less than second index/time".
TimeSeries' methods get_ts_between_indexes(), get_ts_between_times() are now much faster on very long TimeSeries.
Introducing progress bars for long operations, starting with ktk.cycles.detect_events(). If the optional package tqdm is installed, a progress bar is shown if the function takes lots of time. If it is not installed, the function works as usual, without a progress bar.

Bugfixes

ktk.read_c3d() now works correctly with files with more than 255 markers or 255 analog signals, or with no labels. Kudos @jorgomezga for noticing and for proposing a fix!
TimeSeries.get_ts_after_index and TimeSeries.get_ts_before_index now raises a TimeSeriesRangeError when index is invalid, instead of wrongly returning an empty TimeSeries.
Function that expect integers as arguments do not complain anymore when they receive a numpy.int64 instead.
Saving a Pandas DataFrame that contains different data types using ktk.save now loads back correctly.

As always, do not hesitate to ask for help on the discussion board. We are seeing more and more activity there and it is very motivating.

Major website update

Posted on 22 June 2023

The website has been updated and now features a whole free electronic book entitled "Biomechanical Analysis using Python and Kinetics Toolkit".

Since Kinetics Toolkit is a programming library and programming is hard for newcomers, this book covers everything from the essentials of Python programming (including how to install a working environment), to complex analyses such as 3D geometry and kinematic reconstruction. The following concepts are covered, with biomechanics-related examples and exercises based on real, downloadable data:

The Python programming language, including arithmetics, variables, numbers, strings, functions, conditions, lists, loops and dictionaries;
Matplotlib, to generate print-quality graphics and to analyze curves interactively;
NumPy basics, including n-dimensional arrays, arithmetics, trigonometry, infinity/nan, statistical functions, comparisons, logical operators, indexing, slicing and filtering arrays;
TimeSeries analysis, including data, time and event management, time-domain and frequency-domain noise filtering, and cycle management;
File management, including reading/writing C3D, CSV and any file supported by Pandas;
Rigid body geometry, including manipulation of series of points, vectors, frames and homogeneous transforms, coordinate system changes, and 3D angle extraction;
Interactive visualization of 3D markers and rigid bodies;
Kinematic operations such as reconstructing occluded, removed or probed markers.

0.12 released, new development phase

Posted on 21 June 2023

All onboard, direction version 1.0!

All core features have been implemented and most of them have a stable API. Therefore, I am happy to announce that we enter a new development phase, which is a steady walk toward version 1.0. What does this means?

The current API (public classes, modules, functions) is now in "improvement" mode. No current feature will be removed anymore until version 1.0. In rare circumstances, you may get deprecation warnings that indicate that a given feature will be removed in version 1.0 or later, but these warnings will last for a minimum of 24 months before the feature is actually removed, to ensure that everybody has time to update their code. Generally this was already the case, but this is now a rule that will be enforced systematically.
Most new features will now be developed as Kinetics Toolkit extensions. This will draw a clear line between the stable core API and open research applications. Some future extensions may then be integrated into the core if they are stable and relevant for general-purpose biomechanical analysis.

New feature

TimeSeries.resample now accepts a new frequency in Hz in addition to a new time attribute. We can now resample a TimeSeries to a new sampling frequency very easily: ts.resample(120).

Bugfixes

Saving a C3D with missing values now works.
No more warning in ktk.Player in Python >= 3.10.
Fixed deprecation message in deprecated function TimeSeries.get_event_time.
Added missing TimeSeries methods in the TimeSeries' dir, for better autocompletion in IDEs.

API changes

Removed fill_value parameter from TimeSeries.resample. Now:
- The resampled has nan where the original signal had nan.
- Resampling on a larger time span now always works, but there is no extrapolation: bound values are filled with nan systematically.
Player.to_html5 has been removed. This was an internal feature for documentation generation, that should not be part of the public API.

This discussion was created from the release 0.12 released, new development phase.

How to follow the project

Posted on 11 April 2023

Originally, the best way to follow the project was on Twitter. However, due to a number of recent unfortunate policy changes on Twitter, I decided to stop maintaining the @kineticstoolkit twitter account, and I will delete it by May 2023.

Different ways to stay informed

Best: Watch the GitHub repository

The official update channel for Kinetics Toolkit is the Announcements channels of the GitHub repository. Watching the repository is the best way to stay connected, because creating a GitHub account also allows you to participate in discussions, generate ideas, create bug reports, etc.

Create an account on GitHub
Go to the Kinetics Toolkit repository
On the top right of the page, on the Watch button, click the drop-down arrow, then "Custom" and check "Discussions".

Another method: RSS

If you are new to RSS, try it! The two most popular RSS reader services/apps are InoReader and Feedly, both have a free plan.

RSS is an old, standard method to subscribe to most news sites and blogs, that many people forgot with the rise of social networks, but that will probably stay alive as long as the internet exists as we know it. Use it to monitor a search on Pubmed and never miss a new paper in your field again.

You can follow the GitHub announcement feed via your RSS reader of choice by subscribing to https://kineticstoolkit.uqam.ca/announcements.atom

Another method: LinkedIn

Although not specific to Kinetics Toolkit, you can follow me on LinkedIn. Among other news from my lab, I always repost Kinetics Toolkit announcements.

Other methods?

Let me know if you would prefer another way (mailing list, Mastodon, etc.). Just write me at chenier.felix@uqam.ca or start a discussion on it.

Kinetics Toolkit 0.11 released

Posted on 20 March 2023

New features

ktk.write_c3d can now write analogs in addition to points.
ktk.geometry.rotate, ktk.geometry.translate, ktk.geometry.scale: Instead of having to create a series of transformation matrices and then apply this series to a series of coordinates, we can now use these three shortcut functions that directly transform series of coordinates.

Enhancements

Addition of a scales parameter to ktk.geometry.create_transforms. We already had angles and translations, we now also have a scales parameter to create all kinds of rigid transforms matrices.
Now every ktk.geometry operation with rigid transforms checks that the transform matrices are rigid (determinant = 1) before doing the calculation. This is mainly to ensure that (1) there is no user error with the shape and contents of the provided matrix series, and (2) we propagate error from long lists of calculations on badly conditioned matrices.
Parameter convert_point_unit is now optional and defaults to None in ktk.read_c3d. The docstring and behaviour of ktk.read_c3d were clarified for cases when c3d points are not expressed in meters, to clear confusion when the file contains application-specific "points" such as calculated angles, powers and forces.
These functions are not experimental anymore:

Bugfixes

Now we get a clear error message in ktk.cycles.time_normalize when an unknown event name is given as parameter.

Requirement changes

Now requires Python 3.10 or later.

This discussion was created from the release 0.11.0.

New sections in "Learning Python for Biomechanics": Matplotlib and NumPy

Posted on 8 March 2023

Two new sections are now available in the Learning Python for Biomechanics electronic book on KTK's website (https://kineticstoolkit.uqam.ca):

Matplotlib
- importing modules
- plotting line graphs
- adding legends, axes, titles, grids
- plot multiple figures side by side
- styling lines, colors and markers
- zooming, panning, setting axes
- inputting coordinates interactively
NumPy
- creating arrays
- understanding how they differ from lists
- understanding arrays of multiple dimensions
- performing arithmetical operations and comparisons on arrays
- indexing, slicing and filtering unidimensional arrays
- indexing, slicing and filtering multidimensional arrays

All with numerous examples and exercises that are directly related to movement biomechanics analysis.

I also corrected lots of grammar errors and typos in the Getting started with Python and The Python language sections.

Enjoy, tell me what you think, open discussions to discuss about improvements, tell me about typos or bad English grammar to be corrected, etc. !

Milestone reached in "📘 Learning Python for biomechanics"

Posted on 19 December 2022

The two first sections of this (in progress) interactive open book are done!

📖 Getting started with Python
📖 The Python language

These sections cover how to get started with Python, including building a working environment, writing our first program, and learning the python concept a researcher needs to know to process their data. This includes 30 progressive exercises with solutions, all related to biomechanics. The next milestone will be the sections on numpy, matplotlib and basics of pandas.

You are highly welcomed to check this out and make your comments and suggestions here. This is still a first version and I'm very open to modifications at this moment. For example, you may think that some concepts that are not covered should be.

Thanks for following and sharing.

https://kineticstoolkit.uqam.ca/doc/python_for_beginners.html

Updates via GitHub and RSS

Posted on 28 November 2022

A quick note to tell that from now on, in addition to Twitter, you can follow KTK announcements by watching the GitHub repository, or via good old RSS:

GitHub discussions: https://github.com/felixchenier/kineticstoolkit/discussions
RSS: https://github.com/felixchenier/kineticstoolkit/discussions/categories/announcements.atom

KTK 0.10 released

Posted on 22 November 2022

KTK 0.10 released, with a focus on clarity 👓. More helpful error messages, TimeSeries methods cleanup, better type annotations, event duplicate control, and more.
💻 conda update kineticstoolkit
⚠️ Minor breaking changes: https://kineticstoolkit.uqam.ca/doc/ktk_release_notes.html

Welcome to the discussion board!

Posted on 17 September 2022

Feel free to ask any question here. By asking questions, you may help others to solve their own questions.

For questions on how to use Kinetics Toolkit for this or that case, or to better understand some features of Kinetics Toolkit, please use the 1. Users Q&A category.

For propositions of improvement, ideas, wishes for upcoming versions of Kinetics Toolkit, please use the 2. Development: Ideas, new features, doc, etc. category.

Don't be shy to propose your own answers in discussions of any category. Exchanges are always good 😃

An Open-Source Python Package to Facilitate Research in Biomechanics

Kinetics Toolkit is an open-source Python package to facilitate research in biomechanics. It provides tools for:

Analyzing timeseries, including data, time and event management, time-domain and frequency-domain noise filtering, and cycle management;
Managing files, including reading/writing C3D, CSV and any file supported by Pandas;
Performing rigid body geometry operations, including manipulation of series of points, vectors, frames and homogeneous transforms, coordinate system changes, and 3D angle extraction;
Visualizing 3D points and frames interactively;
Performing kinematic operations such as reconstructing occluded, removed or probed markers;
And more using extensions.

It is a programming library, and programming can be hard for new users. Therefore, we also provide the free, electronic book Biomechanical Analysis using Python and Kinetics Toolkit, which guides new programmers from the basics to advanced, generic 3D biomechanical analysis. This book covers:

The Python programming language, including arithmetics, variables, numbers, strings, functions, conditions, lists, loops and dictionaries;
Matplotlib, to generate print-quality graphics and to analyze curves interactively;
NumPy basics, including n-dimensional arrays, arithmetics, trigonometry, infinity/nan, statistical functions, comparisons, logical operators, indexing, slicing and filtering arrays.

It also covers all the features of Kinetics Toolkit, with reproducible examples based on real, downloadable data.