Kineticstoolkit

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.

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

Bugfix in Player's interconnections

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:

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](https://github.com/felixchenier/kineticstoolkit/discussions). We are seeing more and more activity there and it is very motivating.