7.2.1. Data management

This section shows how to use these methods for data management:

• ktk.TimeSeries.add_data

• ktk.TimeSeries.rename_data

• ktk.TimeSeries.remove_data

• ktk.TimeSeries.get_subset

• ktk.TimeSeries.merge

We will use this sample kinematic acquisition of 39 bilateral markers with 1092 samples recorded at 50 Hz during tennis serve:

import kineticstoolkit.lab as ktk

markers = ktk.read_c3d(ktk.doc.download("kinematics_tennis_serve.c3d"))[
    "Points"
]

7.2.1.1. Removing data

The TimeSeries loaded above has many markers, which makes lots of data to visualize and process:

markers.plot(legend=False)

We can remove superfluous data from this TimeSeries using two methods:

1. Subsetting a TimeSeries

We can use ktk.TimeSeries.get_subset to select which data to keep from a TimeSeries. For instance, to process only the markers of the thorax:

markers_thorax = markers.get_subset(
    [
        "Derrick:C7",
        "Derrick:T10",
        "Derrick:STRN",
        "Derrick:CLAV",
    ],
)

markers_thorax.plot()

2. Removing data one at a time

We can also use ktk.TimeSeries.remove_data, to select which data to remove from a TimeSeries:

markers_thorax = markers_thorax.remove_data("Derrick:C7")
markers_thorax = markers_thorax.remove_data("Derrick:T10")

markers_thorax.plot()

7.2.1.2. Adding data

There are three ways to add new data to a TimeSeries. In the last step, we removed the marker “Derrick:C7” from markers_thorax. To put it back, we could use any of these methods:

1. Setting the data attribute directly

data_to_add = markers.data["Derrick:C7"]

markers_thorax.data["Derrick:C7"] = data_to_add

This method does not perform any check.

2. Using add_data

Usually, we would rather use the ktk.TimeSeries.add_data method, which performs two additional tests:

1. It ensures that we don’t inadvertently overwrite data that was already present in the TimeSeries, using an optional overwrite paramater.

2. It ensures that the shape of the data is coherent with other data already in the TimeSeries. This way, combining data with different lengths or sampling rates would likely produce an error, which is a good thing to prevent further mistakes in data analysis.

markers_thorax = markers_thorax.add_data("Derrick:C7", data_to_add, overwrite=True)

3. Using merge

In this third method, we first subset the source TimeSeries to keep only the markers to add in the destination TimeSeries. Then, we merge both TimeSeries.

ts_subset = markers.get_subset("Derrick:C7")

markers_thorax = markers_thorax.merge(ts_subset, overwrite=True)

UserWarning [/Users/felix/Documents/git/kineticstoolkit_doc/src/kineticstoolkit/timeseries.py:3474] The key 'Derrick:C7' exists in both TimeSeries. According to the overwrite=True parameter, its prior value has been overwritten by the new value. Use on_conflict='mute' to mute this warning.

This method performs three tests:

1. Same as ktk.TimeSeries.add_data: it ensures that we don’t inadvertently overwrite data.

2. Same as ktk.TimeSeries.add_data: it ensures that the shape of the data is coherent with other data already in the TimeSeries.

3. It ensures that both TimeSeries have the same time attribute. This is the safest method to ensure that all data have both the same length and same sample rate.

7.2.1.3. Renaming data

Finally, ktk.TimeSeries.rename_data renames data and its associated metadata (in data_info):

markers_thorax = markers_thorax.rename_data('Derrick:STRN', "Sternum")
markers_thorax = markers_thorax.rename_data('Derrick:CLAV', "Interclavicular")
markers_thorax = markers_thorax.rename_data('Derrick:C7', "C7")

markers_thorax.data

{
            'Sternum': <array of shape (1092, 4)>
    'Interclavicular': <array of shape (1092, 4)>
                 'C7': <array of shape (1092, 4)>
}