Extend features

Warning

Gaitalytics is build to be independent on marker-models and modelling mechanisms through configurations. In this Tutorial we will not cover the creation of new mapping configurations since it will alter core functionality of the library. Your new features therefore may not work within different setups. To make your features available to the community and integrated to gaitalytics, please consider contributing to the project and our staff will take care of the integration.

To implement new feature algorithms you need to define a new class inheriting gaitalytics.features.PointDependentFeature. This class internally loops though each cycle and context (‘left’ and ‘right’) and calculates the feature for each point in the cycle and calls the gaitalytics.features.CycleFeaturesCalculation._calculate() method. With implementing gaitalytics.features.CycleFeaturesCalculation._calculate() in your class you can add new functionalities.

from gaitalytics.features import PointDependentFeature

class NewFeature(PointDependentFeature):

    def _calculate(self, cycle):
        # Your feature calculation here
        return feature_value

Through parameter cycle you can access the data of the current cycle and calculate your feature, including the data of the current cycle and the context (‘left’ or ‘right’). As return the framework expects an xarray DataArray object.

Helping functions

To help you with the implementation of new features, gaitalytics provides a set of helper functions handle framework specific restrictions.

Markers & Analogs

If your planning to use markers or analogs which are mapped by Gaitalytics (gaitalytics.mapping.MappedMarkers) you can use the following helper functions: gaitalytics.features.PointDependentFeature._get_marker_data(). This function returns the data of the mapped marker for the current cycle.

Hint

Getting the data for the sacrum marker is handled as a special case. Since Gaitalytics allows either a single sacrum marker or a sacrum marker or two posterior pelvis markers, the method gaitalytics.features.PointDependentFeature._get_sacrum_marker() will handle the logic to extract jut a sacrum marker.

If you want to use markers or analogs which are not mapped by Gaitalytics, you can find the data in the cycle xarray object. Be aware that approach is not generalized and may not work with different marker models. Therefore, it is recommended to use the mapped markers whenever possible. Future efforts will be made to generalize this approach.

Event timings

Ease the work with event timings in a cycle the gaitalytics.features.PointDependentFeature.get_event_times() function can be used to extract the event timings for the current cycle.

Vectors

It is often necessary to obtain progression vectors or sagittal plane vectors. To help you with this, gaitalytics provides the following helper functions:

• gaitalytics.features.PointDependentFeature._get_progression_vector()

• gaitalytics.features.PointDependentFeature._get_sagittal_vector()

Return values

The expected return value of the feature calculation is an xarray DataArray object in a specific format. To help you with the creation of this object, gaitalytics provides the following helper functions:

• gaitalytics.features.CycleFeaturesCalculation._create_result_from_dict() to create a DataArray object from a dictionary.

• gaitalytics.features.CycleFeaturesCalculation._flatten_features() to flatten an xarray DataArray object.

Including your feature

To include your feature in the calculation of the gait metrics, you need to add it to the parameters of your gaitalytics.api.calculate_features() call.

from gaitalytics import api
from gaitalytics.features import NewFeature

config = api.load_config("./config.yaml")
trial = api.load_c3d_trial("./example.c3d", config)

# Calculate the only the new feature
features = api.calculate_features(trial, config, [NewFeature])

# Calculate all features including the new feature
features = api.calculate_features(trial, config, [gaitalytics.features.TimeSeriesFeatures,
                                                  gaitalytics.features.PhaseTimeSeriesFeatures,
                                                  gaitalytics.features.TemporalFeatures,
                                                  gaitalytics.features.SpatialFeatures,
                                                  NewFeature])