Skip to content

Latest commit

 

History

History
843 lines (680 loc) · 49.5 KB

CHANGELOG.md

File metadata and controls

843 lines (680 loc) · 49.5 KB
Raw

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog (+ the Migration Guide and Scientific Changes section), and this project adheres to Semantic Versioning.

For more information see the Github Releases Page of this project.

[2.5.1] - 2024-05-27

Fixed

The package updates in 2.5.0 broke some things. These are now fixed.

  • For the parameter errors, the order of the output parameters has changed slightly, as they are now sorted to avoid future breaking changes, based on changes in the sor policy in pandas
  • The matches for the stride matching are now sorted to avoid future breaking changes, based on changes in the sor policy in scipy sparse arrays
  • The PCAAlignment is now more robust by enforcing a direction of the first principal component. The method also has a new attribute normalized_pca_components_ that hold the components after this adjustment. This change might result in different results for the PCA step of the alignment. However, in combination with the forward direction alignment, the results should be identical to the previous version.

[2.5.0] - 2024-05-23

Changed

Looser version constrains

Fixed

  • Fixed a bug in the filtered rampp event detection. Replaced gyr_ml to gyr_ml_filtered so that we look for the gradient on the filtered signal. (#66)

[2.4.0] - 2024-04-19

Added

  • All orientation and trajectory methods now have a new parameter rotated_data_ that provides the input data rotated to the world frame based on the calculated orientation. (#64)
  • The Spatial Parameter Calculation now also calculates the "Range of Motion" (i.e. the angle change of the sensor in the sagittal plane) (#54)

Fixed

  • Fixed a bug that when using merge_interval with empty input of shape (0, 2), the output was not empty. (#61)
  • Fixed a bug that an error was raised when importing from the TrajectoryReconstruction module without gaitmap_mad installed (#63)

Changed

  • Changed resampling function in inverse feature transform of HMM. Resampling of state sequence is now also possible if the target_sample_rate is not a multiple of the HMM sampling rate, e.g. target_sample_rate=200, sample_rate=52.1 (#62)
  • Dropped Python 3.8 support! (#64)

[2.3.0] - 2023-08-03

Changed

  • Example data is now automatically downloaded if it is not already present. (#49)

[2.2.3] - 2023-07-18

Fixed

  • Spatial parameter calculation now works when no strides are detected for a sensor. (#48)

[2.2.2] - 2023-06-22

Fixed

  • Fixed bug in HMM when uneven sequnece length were provided. In newer numpy versions this requires an explicit cast to an object array.

[2.2.1] - 2023-06-22

Fixed

  • Fixed edecase where the output of the stride event method had the events in the wrong order for some strides. The reason for that is that a valid segmented stridelist does not always result in a valid min_vel_event list for algorithms that are allowed to search outside the segmented stride region (e.g. HerzerEventDetection). We now check for consistency again after the stride list conversion.

[2.2.0] - 2023-06-07

Gaitmap is now available as official PyPi package!!!

Added

  • New Algorithm: MadgwickRtsKalman. This is a slightly modified implementation of the RtsKalman algorithm. Instead of naive gyro integration it uses the Madgwick algorithm to estimate the orientation. (#15)
  • Certain ZUPT detectors now return the min_vel_index_ and min_vel_value_ as additional attributes. These values represent the index in the input data with the lowest velocity and the corresponding velocity value (according to the internal metric of the repective ZUPT detector). (#16)
  • New example explaining more advanced usage of the RtsKalman algorithm. (#17)
  • The find_extrema_in_radius and the snap_to_min utility functions gained the ability to define asymetric search windows around the search indices. (#21)
  • Temporal and Spatial Parameter calculation have new options to work with ic-stride lists and with partial input information
  • A new method calculate_parameter_errors (old version is renamed to calculate_aggregated_parameter_errors) is added that allows to calculate just the errors (i.e. relative error, absolute error, etc.) for a given list of parameters. If you want to have the aggregated parameter errors (i.e. mean absolute error, mean relative error, etc.) use the calculate_aggregated_parameter_errors method.

Changed

  • We now require Pandas >2.0 as we are using the new pandas dtypes. It could be that this will require you to perform some sxplicit type conversion in your code.
  • The Zupt Detector example is updated to use newer tpcp features (#17)
  • The column order of the Spatial Parameter Calculation output has been changed
  • The function calculate_parameter_errors is renamed to calculate_aggregated_parameter_errors function is now more general and can be used with parameter lists that don't represent strides. For this the unique-id column (i.e. original stride index) is can be explicitly set and all wording is changed to be more general. (#24)
  • Fixed a bug that the calculation of the ICC in calculate_parameter_errors/calculate_aggregated_parameter_errors was not working correctly, when the stride ids where duplicated across sensors.

[2.1.0] - 2023-02-08

Added

  • HIGHLIGHT: Finally reworked the HMM branch, added tests and documentation and adapted the API to fit the rest of the gaitmap and tpcp ecosystem better. (#3). On the way, there were also some bugs fixed and internal computations were optimized. If you were using the HMM branch before, read through the HMM examples again before updating! All the classes and methods have new names and import paths. Further, you will likely not get exactly the same results. However, when using the pretrained model, changes should be minimal. If you were training your own model, it might be that you get different results, as you might have been effected by a bug in the training code when using "labeled" training with the composite model (for details: #4). This is fixed now! So please retrain your models.
  • A new version of the RamppEventDetection is added. FilteredRamppEventDetection adds a lowpass filter before the detection of the IC to remove potential high-freq artifacts.
  • New higher level transformers that allow for complex combinations and chaining of transformers. Most of them make use of the new tpcp composite Algorithm feature that allows to easily get and set complicated nested parameters. New transformers include: ChainedTransformer, ParallelTransformer (#2)
  • New implementation of a Filter class and a ButterworthFilter implementation on top of the transformer API. (#2)
  • Added a new flip_dataset function that can be used instead of rotate_dataset, when you only need to perform 90/180 degree rotations. It is much faster than rotate_dataset, as it just flips the axis labels and multiplies values by -1. (#10)
  • New Zupt detecor methods: AredZuptDetectors and ShoeZuptDetectors. The ARED detector is a special case of the existing NormZuptDetector (using specifically the mean of the gyr norm) and the SHOE detector uses a combination of acc and gyr data. (#11)
  • All Zupt detectors have a new parameter window_overlap_samples that can be used as alternative to window_overlap to specify the window overlap in samples independent of the sampling rate. (#11)
  • Added new example to show how the Zupt Detector can be tuned to improve the performance of the trajectory estimation kalman filter. (#11)
  • It is now possible to only detect a subset of the supported events of an event detection method using the detect_only parameter. (#12)
  • The function calculate_parameter_errors now also outputs the number of strides used for matching per parameter. (#13)
  • The function calculate_parameter_errors returns way more parameters. All basic statistics are now calculated for the error, relative error, absolute error and the relative absolute error. If pingouin is installed, we also calculte the ICC. (#13)
  • A new utility method to intersect stride lists by a region of interest list. (#14)
  • A new ZuptDetector method StrideEventZuptDetector that simply returns the min_vel events of an already provided event list as ZUPTs. This is enabled by the new stride_event_list parameter of the detect method of all ZuptDetector methods (see Changes) (#14)
  • A new ZuptDetector method ComboZuptDetector that allows to combine the output of multiple ZuptDetector methods using either logical "or" or "and". (#14)
  • The PerSampleZuptDetectorMixin and RegionZuptDetectorMixin are now public API to simplify the implementation of custom ZUPT detectors. (#14)

Changed

  • When using memory with any of Dtw methods, we will not cache the peak detection step anymore. It does not really speed up things and just leads to dozents of cache writes/reads as the chance of a cache match is really low.
  • The zupts_ result of RtsKalmanFilter is not a pandas dataframe with start and end columns instead of a np.ndarray. The content remains the same.
  • The sampling_rate_hz parameter of the detect method of the EventDetection algorithms is now keyword only. (#12)
  • For the function calculate_parameter_errors the naming of ground truth was changed to reference and input to predicted. This change requires updating the function call in your code. (#13)
  • For all trajectory/pos/ori methods, the sampling_rate_hz parameter is now keyword only. This might require some user facing code changes. (#14)
  • Trajectory/pos/ori and ZUPT methods can now get an optional parameter called stride_event_list as parameter for the detect method. So far, only the RTS Kalman Filter is using this parameter to forward it to the ZUPT method. Both wrapper (Stride-level and Region) are both aware of this parameter and pass them correctly down to the respective methods. (#14)
  • The util method start_end_array_to_bool_array now assumes that the end index of all regions is inclusive. This enables roundtrip conversion with the bool_array_to_start_end_array method and is in line with the definitions used for strides, ROIs, and ZUPTs in gaitmap. Further, the method now supports to output arrays that are shorter than the largest input index. Before, this resulted in an error. Both changes might require some user facing code changes, if this function is used. However, as it was not used internally, it is likely that no one was using it anyway. (#14)

Removed

  • The find_zupts method of the RtsKalmanFilter and all deprecated arguments are now fully removed in favor of the dedicated ZUPT algorithms. The parameters where deprecated since version 1.5

Migration Guide

  • There are a bunch of small changes that are not backwards compatible. The most important is likely the change to make the sampling_rate_hz parameter (and other) keyword only in many methods. This means, you need to use the parameter name when calling these methods. For example, if you used detect(data, 100) before, you now need to use detect(data, sampling_rate_hz=100).

[2.0.2] - 2022-08-29

Fixed issues with namedtuple inheritance in Python 3.9.

[2.0.1] - 2022-07-29

Fixed some dependencies and internal links that where broken after the move to Github.

[2.0.0] - 2022-07-26

This release is the first release on Github! For this release we also had to modify the code history with a nasty rebase to remove some sensitive files from the history. This means, the old commit hashes listed in the pull request are not valid anymore. To avoid confusion and signal this change, this is a new major version.

[1.7.0] - 2022-07-04

  • This release removes Python 3.7 support!

Added

Changed

  • All Algorithm classes now build on tpcp.Algorithm. This is a major change and might result in some unexpected incompatibilities with older code. The core functionality of tpcp should still work as expected. If you were using any of the base classes and algorithm helpers, check if they are still available in gaitmap. If not, there is likely a replacement in tpcp. (https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/173)
  • The way DTW - templates are generated has been changed completely. Generation is now handled via BaseClasses instead of helper functions. These baseclasses follow the "optimizable" interface introduced in tpcp. Further, all templates now use the new data transforms instead of a fixed scaling factor. In combination, it should be much easier to create new templates and use more complex data normalisations. (https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/149)
  • Spatial gait parameters can be calculated, even if some gait parameters are missing.

Removed

Migration Guide

  • If you were creating custom templates, you should now use the DtwTemplate and InterpolatedDtwTemplate classes. Check the new example (stride_segmentation/barth_dtw_custom_template) for more information, on how to use these new classes.
  • If you were using scaling factors for DtwTemplates you should now use the new transformers in tpcp.data_transforms instead. To replace a fixed scaling factor, use FixedScaler(scale=500). However, in many cases you might be better off using one of the Trainable scalars to automatically learn the scaling factors from the template.
  • If you worked with the raw data of the BarthDtwTemplate, be aware that the stored data is now unscaled (i.e. multiplied by 500 compared to the old version).

Scientific Changes

[1.6.0] - 2022-05-31

Scientific Changes

[1.5.0] - 2022-05-31

Added

Changed

Deprecated

Removed

Fixed

Migration Guide

  • We removed the orientation update feature of the RtsKalman class. This feature was off by default. Unless you explicitly enabled it, you should be fine. In case you used the feature, remove all references to the respective keywords.
  • The call signature and the units of the gyro data passed RtsKalman.find_zupts has changed. In case you where using custom subclasses of RtsKalman to implement custom zupt methods, you need to update your zupt methods for the new input structure. However, due to the new changes to ZuptDetectors, it is likely that you do not need a custom subclass anymore, but can simply pass a instance of a ZuptDetector to the Kalman class
  • The memory option for RtsKalman was removed, as it was not particularly useful. In case you need caching we recommend implementing it externally.

Scientific Changes

  • The "ori_update" feature of the Kalman filter was removed again. The feature was experimental anyway, but in turns out the implementation was actually wrong. The RTSKalman filter tracks the change in error state open-loop. This means errors are not applied during ZUPT-measurements, but simply added up and corrected at the very end. This works well for position and velocity, but the equations for orientation assume, that the orientation error remains small enough so that a linearization and separation of the angle error on the different axis is possible. When the filter is run open loop, it is very likely that the orientation error will quickly reach ranges, where this doesn't hold anymore. We concluded that the used method to track the orientation error (and hence, correct it directly) is not suitable for open-loop Kalmanfilter designs. It is unlikely that the feature will be added again in the future. However, prior versions can be used as reference to implement a closed loop Kalmanfilter with direct observations of the orientation error. This is a breaking change! See the Migration section for more details, if you used this feature before. (https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/159)

[1.4.0] - 2021-06-25

With 1.4. we finally realize the longterm goal to make the comparison of algorithms easy and unify code across dataset and algorithms. The highlights of this release are the new experimental Dataset and Pipeline classes and first-class support for trainable algorithms.

Added

Changed

Deprecated

Removed

Fixed

Migration Guide

  • If you used gaitmap.evaluation_utils.scores.precision_recall_f1_score, the output is now a dictionary instead of a tuple. Migration should be straight forward.
  • Some parameters are now keyword only. In case you get an unexpected error, telling you that "an algorithm only receives n positional arguments, but you provided n+1", double-check the call signature.

Scientific Changes

[1.3.0] - 2021-01-25

Added

Changed

Deprecated

Removed

Fixed

Migration Guide

  • Due to the renaming of dataset to sensordata, a couple of names and import path are changed:
    • All imports from gaitmap.utils.dataset_helper should be changed to gaitmap.utils.datatype_helper
    • SingleSensorDataset, MultiSensorDataset and Dataset are now called, SingleSensorData, MultiSensorData and SensorData, respectively.
    • The functions is_single_sensor_dataset, is_multi_sensor_dataset, is_dataset, and get_multi_sensor_dataset_names are renamed to is_single_sensor_data, is_multi_sensor_data, is_sensor_data, and get_multi_sensor_names.

Scientific Changes

[1.2.0] - 2020-11-11

Added

Changed

Deprecated

Removed

Fixed

Migration Guide

  • In case your algorithm uses is_{single,multi}_sensor_{position, velocity, orientation}_list all usages must be updated to include {position, velocity, orientation}_list_type="stride" to restore the default behaviour before the update. If you were using the function with s_id=False, you can update to {position, velocity, orientation}_list_type=None to get the same behaviour.

Scientific Changes

  • All Dtw based methods now produce outputs that follow our index guidelines. This means that they correctly produce matches, which end index is exclusive. In some cases this might change existing results by adding 1 to the end index. (https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/103)
  • The initial orientation in the StrideLevelTrajectory now has a window with exactly the number of samples specified (instead of one less due to Python indexing). This will lead to very small changes in the calculated trajectory. (mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/98)

[1.1.0] - 2020-10-04

Added

The new evaluation_utils module https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/issues/117

A new module was started that will contain helper functions to evaluate the results of gait analysis pipelines. This is the first version and we already added:

Global Validation Error Handling

https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/issues/72, https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/issues/16

To make developing new algorithms easier and error messages easier to understand for users, we modified the data-object validation helper to raise proper descriptive error messages. The data-object helpers now have an optional argument (raise_exception=True) to trigger the new error-messages.

All existing algorithms are updated to use these new validation methods. (https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/80, https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/84, https://mad-srv.informatik.uni-erlangen.de/MadLab/GaitAnalysis/gaitmap/-/merge_requests/86)

The remaining datatypes will get updated validation functions in a future release.

Changed

Deprecated

Removed

Fixed

Migration Guide

  • The format in which DataFrame Attributes are stored in json has been changed and the old format will be fully removed in the future. If you have DtwTemplates stored as json, load them (you will get a warning) once. Double check that the ordering of the template data is correct. If it is not, sort it correctly and then save the object again. This should fix all issues going forward.
  • To get or load the data of a DtwTemplate, you now need to use template.get_data() instead of template.data. Simply replacing the old with the new option should fix all issues.
  • For custom algorithms using the gaitmap format, you should migrate to the new datatype validation functions! See "Added" section for more details.

[1.0.1] - 2020-07-15

A small bug fix release that fixes some issues with the new template creation function.

Fixed

[1.0.0] - 2020-06-26

This is the first official release of gaitmap (Wuhu!). Therefore, we do not have a proper changelog for this release.

Added

  • All the things :)

Changed

Deprecated

Removed

Fixed

Migration Guide