Kinetics Toolkit - 0.16.4

Important: The kineticstoolkit package is now completely separated from kineticstoolkit_extensions. There is no kineticstoolkit.ext namespace anymore. Extensions are loaded by the user on demand using the kineticstoolkit_extensions package (e.g., import kineticstoolkit_extensions.pushrimkinetics as pk). This is not a big change for the users, and it will help a lot in creating and maintaining extensions. This change will be publicized in 0.17. See https://github.com/kineticstoolkit/kineticstoolkit_extensions for more information.

Scientific Software - Peer-reviewed - Python
Published by felixchenier 12 months ago

Kinetics Toolkit - 0.16.3

Important: This release changes the extensions mechanism: now extensions are imported from the package kineticstoolkit_extensions that is installed via pip or conda. This change will be publicized in 0.17. If you are currently using extensions, then you need to install kineticstoolkit_extensions using pip install kineticstoolkit_extensions

Scientific Software - Peer-reviewed - Python
Published by felixchenier 12 months ago

Kinetics Toolkit - 0.16.2

Very minor update, mainly to show up upcoming features in a workshop.

Scientific Software - Peer-reviewed - Python
Published by felixchenier about 1 year ago

Kinetics Toolkit - 0.16.1

Bugfix (fixed a sandboxing error that prevented setting the temporary folder on Spyder 6.5 on macOS)

Scientific Software - Peer-reviewed - Python
Published by felixchenier about 1 year ago

Kinetics Toolkit - 0.16.0

Kinetics Toolkit v0.16.0 is out!

New Features

• Long overdue feature: ktk.read_c3d() now reads force platform information in addition to points, analogs, and rotations. It returns the force platforms' corners, their local coordinate systems, the centre of pressure, and the calibrated forces and moments expressed around both the force plate centre and the centre of pressure. More info: https://kineticstoolkit.uqam.ca/doc/filesreadc3d.html
• The Player can now draw vectors, in addition to points and frames, using its new vectors property. This will be very helpful for visualizing ground reaction forces or joint forces. More info: https://kineticstoolkit.uqam.ca/doc/player_vectors.html
• Geometry module: new helper functions to help create generalized coordinates. More info: https://kineticstoolkit.uqam.ca/doc/geometrydimensionconventions.html
  • ktk.geometry.create_point_series()
  • ktk.geometry.create_vector_series()
  • ktk.geometry.create_transform_series()
  • ktk.geometry.is_point_series()
  • ktk.geometry.is_vector_series()
  • ktk.geometry.is_transform_series()
• Geometry module: now supports conversions between quaternions and transforms, which will be helpful when using inertial measurement units (IMUs) or rigid body orientation measured by mocap systems:
  • ktk.geometry.create_transform_series() - supports quaternions
  • ktk.geometry.get_quaternions()
• Geometry module: new function ktk.geometry.mirror() that flips all coordinates along a given axis (x, y, or z).

Improvements

• The Player now uses true read/write properties for interconnections and the new vectors property, which means we can now interconnect points or define vectors directly on the properties, without the longer get/modify/set workflow.
• TimeSeries.add_data() now repeats one-sample data over the entire TimeSeries range, which facilitates adding time-constant values to the TimeSeries.
• Reading and writing c3d files requires the ezc3d module, which was installed by default using conda but not using pip since it was not available on pip until recently (thanks to @pariterre). Now that it is, ezc3d is now automatically installed using pip install kineticstoolkit.
• The whole code base and documentation website has been checked for typos and grammar errors.

Notes

• Geometry module: the functionality of ktk.geometry.create_frames() and ktk.geometry.create_transforms() has been merged into the new ktk.geometry.create_transform_series() function. Both functions are still present and are not deprecated yet, but they will become deprecated when KTK v1.0 is released, and then removed two years later.

Full Changelog: https://github.com/kineticstoolkit/kineticstoolkit/compare/0.15.0...0.16.0

Scientific Software - Peer-reviewed - Python
Published by felixchenier over 1 year ago

Kinetics Toolkit - 0.15.0

New features

• TimeSeries.resample now has an extrapolate boolean parameter.
• ktk.read_c3d: Now reads transform series (rotation parameter) such as segment orientations.
• ktk.write_c3d: Now writes transform series (rotation parameter) such as segment orientations.

Enhancements

• TimeSeries.merge now has an option to warn or raise an error in case of conflict (when a data key of the same name is found in both TimeSeries).
• TimeSeries: Some clarifications in TimeSeries methods' docstrings
• ktk.readc3d: If multiple trajectories with a same name are found in a C3D file (which may happen in labelling markers trajectories with occlusion), integer numbers are now added as suffixes to the data key. For example, if a C3D file has duplicate trajectories with a same name (e.g., "T8"), the resulting TimeSeries will have those data keys, one for each trajectory: "T8", "T81", "T8_2", etc. The previous inconvenient behaviour was to silently choose one trajectory and ignore every other.
• ktk.write_c3d now generates an error if the output file name does not end with ".c3d".

Bugfixes

• Now works with NumPy 2.0
• ktk.read_c3d: Fixed a possible bug if a c3d files has events but no points.
• ktk.read_c3d: Fixed a bug in c3d files with no units.

Note

• Deprecated functions that were scheduled to be removed in 2024 have been removed.

Thanks

• Thanks to @Alek050 and @pariterre for their contribution to this release on the new support for rotations in ktk.readc3d and ktk.writec3d.
• Thanks to @j-heizenreder regarding to issue #231 on ktk.read_c3d error.

Scientific Software - Peer-reviewed - Python
Published by felixchenier almost 2 years ago

Kinetics Toolkit - 0.14.3

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 https://github.com/kineticstoolkit/kineticstoolkit/pull/236
• Fixed bug on first index of fillmissingsamples by @Alek050 in https://github.com/kineticstoolkit/kineticstoolkit/pull/239
• Deprecated features scheduled to be removed in 2024 have been removed.

New Contributors

• @andreyzhd made their first contribution in https://github.com/kineticstoolkit/kineticstoolkit/pull/236

Full Changelog: https://github.com/kineticstoolkit/kineticstoolkit/compare/0.14.2...0.14.3

Scientific Software - Peer-reviewed - Python
Published by felixchenier about 2 years ago

Kinetics Toolkit - 0.14.2

Bugfix in Player's interconnections

Scientific Software - Peer-reviewed - Python
Published by felixchenier about 2 years ago

Kinetics Toolkit - 0.14

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.

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.adddatainfo

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.

Scientific Software - Peer-reviewed - Python
Published by felixchenier over 2 years ago

Kinetics Toolkit -

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 return 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.

Scientific Software - Peer-reviewed - Python
Published by felixchenier over 2 years ago

Kinetics Toolkit - 0.12 released, new development phase

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? 1. 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. 2. 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.geteventtime.
• 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.

Scientific Software - Peer-reviewed - Python
Published by felixchenier almost 3 years ago

Kinetics Toolkit -

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:
  • ktk.kinematics.create_cluster,
  • ktk.kinematics.extend_cluster,
  • ktk.kinematics.track_cluster,
  • ktk.geometry.register_points,
  • ktk.TimeSeries.resample,
  • ktk.TimeSeries.fillmissingsamples.

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.

Scientific Software - Peer-reviewed - Python
Published by felixchenier about 3 years ago

Kinetics Toolkit - 0.10.0

• New feature: ktk.TimeSeries.count_events. Counts the number of occurrences of a given event. This function is useful for example to loop over cycles.
• New feature: ktk.TimeSeries.remove_duplicate_events. Removes duplicate events (that share a same name and same time).
• Improvement: Better error messages. All functions now perform basic real-time type checking and return clear messages in case of unexpected input. Many error messages are also more helpful, particularly in TimeSeries’ getts methods.
• Improvement: ktk.Player now allows interconnections to be any length, not only bouts of two-marker connections.
• Improvement: ktk.TimeSeries.add_event now has an optional unique argument to prevent adding duplicate events.
• Improvement: ktk.TimeSeries.merge does not duplicate events anymore if a same event was present in both TimeSeries.
• Improvement: Now uses Python 3.9 annotations (using from future import annotations). Python 3.9 is not required yet, only Python 3.8.
• Improvement: Now uses Numpy’s ArrayLike in static typing annotations.
• Bugfix: ktk.Player’s target parameter now respects the ground plane orientation given by the up parameter introduced in 0.9.1.
• Bugfix: ktk.TimeSeries.sort_events does not miss duplicate events anymore.
• Deprecation: The following TimeSeries methods were deprecated because they don’t provide enough functionality compared to the complexity they generate when learning Kinetics Toolkit by new users. Using those functions now generates a deprecation warning with a suggestion to get the same result with other functions:
  • TimeSeries.get_event_index()
  • TimeSeries.get_event_time()
  • TimeSeries.get_ts_at_event()
  • TimeSeries.get_ts_at_time()
  • TimeSeries.sync_event()
  • TimeSeries.ui_get_ts_between_clicks()
• Breaking change: These parameter names were changed in ktk.kinematics:
  • Changed marker_names parameter for names in ktk.kinematics.create_cluster.
  • Changed new_point parameter for name in ktk.kinematics.extend_cluster.
• Breaking change: Changed default value of unique from True to False in ktk.TimeSeries.sort_events.

Scientific Software - Peer-reviewed - Python
Published by felixchenier over 3 years ago

Kinetics Toolkit -

• New feature: ktk.Player now has a up parameter. Before, the ground plane was xz with y being up. Now, any ground plane can be used, by choosing up among {'x', 'y', 'z', '-x', '-y', '-z'}.
• Bugfix: Resolved an error in ktk.read_c3d where reading would fail on c3d files with empty events.

Scientific Software - Peer-reviewed - Python
Published by felixchenier almost 4 years ago

Kinetics Toolkit -

• New feature: ktk.TimeSeries.resample to resample a TimeSeries on a new time vector, with the method of your choice (sample-and-hold, linear, spline, etc.)
• New feature: ktk.TimeSeries.getsamplerate returns the TimeSeries sample rate, or NaN if the sample rate is not constant.
• New feature: ktk.readc3d replaces ktk.kinematics.readc3d_file, and now reads analogs and events in addition to points.
• New feature: ktk.writec3d replaces ktk.kinematics.writec3d_file, and now writes analogs and events in addition to points.
• Deprecation: ktk.kinematics.readn3dfile was moved to the n3d extension.
• Bugfix: c3d files with accented characters in path should now be readable on Windows.

Scientific Software - Peer-reviewed - Python
Published by felixchenier almost 4 years ago

Kinetics Toolkit -

Adds support for extensions.

Scientific Software - Peer-reviewed - Python
Published by felixchenier almost 4 years ago