Data Loading

Gaitalytics is designed to be marker model independent. It does not require specific marker, analog or modelled marker names. Nevertheless it needs some information about parts of the naming scheme to be able to identify necessary data points. This information is provided in the configuration file.

Warning

The motion capture data must be preprocessed before loading it into the library. Gap filling, filtering and calculation of kinetics / kinematics must be done before loading the data.

The function gaitalytics.api.load_c3d_trial() is used to load a c3d file and the corresponding configuration file. Here is an example of how to load a c3d file and the corresponding configuration file:

from gaitalytics import api
config = api.load_config("./config.yaml")

Configuration

Note

The configuration file is mandatory for library to work.

The configuration is communicated to the framework through a yaml file. The file is structured as follows:

# Mapping of model marker names to internal marker names
mapping:
  markers:

    # Foot
    l_heel: "ExampleHeelMarker"
    r_heel: "ExampleHeelMarker"
    l_toe: "ExampleToeMarker"
    r_toe: "ExampleToeMarker"
    l_toe_2: "ExampleSecondaryToeMarker" # optional
    r_toe_2: "ExampleSecondaryToeMarker" # optional
    l_lat_malleoli: "ExampleMalleoliMarker" # optional
    r_lat_malleoli: "ExampleMalleoliMarker" # optional


    # Hip
    l_ant_hip: "ExampleHipMarker"
    r_ant_hip: "ExampleHipMarker"
    l_post_hip: "ExampleHipMarker" # optional
    r_post_hip: "ExampleHipMarker" # optional
    sacrum: "ExampleSacrumMarker"  # optional
    xcom: "ExampleXCOMMarker" # optional

# Entities to analyse
analysis:
  markers: # Markers to analyse
    # List of modelled markers to analyse
    - "ExampleAngle1"
    - "ExampleGRF"
    - "ExampleForce2"
  analogs:
    # List of analog channels to analyse
    - "ExampleForce3"

The configuration file is structured in two parts. The mapping section and the anlaysis section.

Mapping

The mapping section is used to map model marker names to internal marker names.

Internal marker	Description	Optional
l_heel	Corresponding model marker name on the left heel.	false
r_heel	Corresponding model marker name on the right heel.	false
l_lat_malleoli	Corresponding model marker name on the left lateral malleoli.	true☨
r_lat_malleoli	Corresponding model marker name on the right lateral malleoli.	true☨
l_toe	Corresponding model marker name on the left toe.	false
r_toe	Corresponding model marker name on the right toe.	false
l_toe_2	Corresponding second model marker name on the left toe.	true✝
r_toe_2	Corresponding second model marker name on the right toe	true✝
l_ant_hip	Corresponding model marker name on the left anterior hip.	false
r_ant_hip	Corresponding model marker name on the right anterior hip.	false
l_post_hip	Corresponding model marker name on the left posterior hip.	true*
r_post_hip	Corresponding model marker name on the right posterior hip.	true*
sacrum	Corresponding model marker name on the sacrum.	true*
xcom	Corresponding model marker name of the extrapolated center of mass.	true☨

* Depending on the marker model, the posterior hip or sacrum may not be present. Either sacrum or both posterior hip markers must be provided.
✝ Only needed to get a precise calculation of the minimal toe clearance.
☨ Only needed to calculate the margin of stability.

Analysis

The analysis section is used to specify which entities should be analysed. The entities are divided into markers and analogs, whereas markers will be found in the point sections of the c3d and analogs in the analogs section of the c3d file. Configuring entities in the analysis section will have two consequences:

Time series features will be extracted from these entities.

The entities will be flattened (i.e. the entities will be transformed into a single time series) and saved in the analysis part of the Trial object.

To define the entities to analyse, the user must provide the marker or analog of the entities which should be used.

Load c3d file

The function gaitalytics.api.load_c3d_trial() is used to load a c3d file and the corresponding configuration file. Following code snipped illustrates how to load a c3d file with the corresponding configuration file:

from gaitalytics import api

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

The load_trial function will return a Trial object which contains all the information of the c3d file. Internally Gaitalytics uses the pyomeca[1], ezc3d[2] and xarray[3] libraries to load and store the data.

The object returned is a gaitalytics.model.Trial. It contains three types of data.

Markers -> time series form the Point section of the c3d

Analog -> time series from the Analog section of the c3d

Analysis -> flattened time series from the entities specified in the configuration file.

Additionally, the object contains the events which are stored in the c3d file.

References