ktk.TimeSeries#

class TimeSeries(src=None, *, time=[], time_info={'Unit': 's'}, data={}, data_info={}, events=[])[source]#

Bases: object

A class that holds time, data series, events and metadata.

Parameters:
  • src (None | TimeSeries | pd.DataFrame | ArrayLike)

  • time (ArrayLike)

  • time_info (dict[str, Any])

  • data (dict[str, ArrayLike])

  • data_info (dict[str, dict[str, Any]])

  • events (list[TimeSeriesEvent])

time#

Time attribute as 1-dimension np.array.

Type:

np.ndarray

data#

Contains the data, where each element contains a np.array which first dimension corresponds to time.

Type:

dict[str, np.ndarray]

time_info#

Contains metadata relative to time. The default is {“Unit”: “s”}

Type:

dict[str, Any]

data_info#

Contains facultative metadata relative to data. For example, the data_info attribute could indicate the unit of data[“Forces”]:

data["Forces"] = {"Unit": "N"}

To facilitate the management of data_info, please use ktk.TimeSeries.add_data_info.

Type:

dict[str, dict[str, Any]]

events#

list of events.

Type:

list[TimeSeriesEvent]

Examples

A TimeSeries can be constructed from another TimeSeries, a Pandas DataFrame or any array with at least one dimension.

  1. Creating an empty TimeSeries:

>>> ktk.TimeSeries()
TimeSeries with attributes:
         time: array([], dtype=float64)
         data: {}
    time_info: {'Unit': 's'}
    data_info: {}
       events: []
  1. Creating a TimeSeries and setting time and data:

>>> ktk.TimeSeries(time=np.arange(0, 10), data={"test":np.arange(0, 10)})
TimeSeries with attributes:
         time: array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
         data: {'test': array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])}
    time_info: {'Unit': 's'}
    data_info: {}
       events: []
  1. Creating a TimeSeries as a copy of another TimeSeries:

>>> ts1 = ktk.TimeSeries(time=np.arange(0, 10), data={"test":np.arange(0, 10)})
>>> ts2 = ktk.TimeSeries(ts1)
>>> ts2
TimeSeries with attributes:
         time: array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
         data: {'test': array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])}
    time_info: {'Unit': 's'}
    data_info: {}
       events: []

See Also: TimeSeries.copy

  1. Creating a TimeSeries from a Pandas DataFrame:

>>> df = pd.DataFrame()
>>> df.index = [0., 0.1, 0.2, 0.3, 0.4]  # Time in seconds
>>> df["x"] = [0., 1., 2., 3., 4.]
>>> df["y"] = [5., 6., 7., 8., 9.]
>>> df["z"] = [0., 0., 0., 0., 0.]
>>> df
       x    y    z
0.0  0.0  5.0  0.0
0.1  1.0  6.0  0.0
0.2  2.0  7.0  0.0
0.3  3.0  8.0  0.0
0.4  4.0  9.0  0.0
>>> ts = ktk.TimeSeries(df)
>>> ts
TimeSeries with attributes:
         time: array([0. , 0.1, 0.2, 0.3, 0.4])
         data: <dict with 3 entries>
    time_info: {'Unit': 's'}
    data_info: {}
       events: []
>>> ts.data
{'x': array([0., 1., 2., 3., 4.]), 'y': array([5., 6., 7., 8., 9.]), 'z': array([0., 0., 0., 0., 0.])}

See Also: TimeSeries.from_dataframe

5. Creating a multidimensional TimeSeries from a Pandas DataFrame (using brackets in column names):

>>> df = pd.DataFrame()
>>> df.index = [0., 0.1, 0.2, 0.3, 0.4]  # Time in seconds
>>> df["point[0]"] = [0., 1., 2., 3., 4.]
>>> df["point[1]"] = [5., 6., 7., 8., 9.]
>>> df["point[2]"] = [0., 0., 0., 0., 0.]
>>> df
     point[0]  point[1]  point[2]
0.0       0.0       5.0       0.0
0.1       1.0       6.0       0.0
0.2       2.0       7.0       0.0
0.3       3.0       8.0       0.0
0.4       4.0       9.0       0.0
>>> ts = ktk.TimeSeries(df)
>>> ts.data
{'point': array([[0., 5., 0.],
       [1., 6., 0.],
       [2., 7., 0.],
       [3., 8., 0.],
       [4., 9., 0.]])}

See Also: TimeSeries.from_dataframe

6. Creating a multidimensional TimeSeries of higher order from a Pandas DataFrame (using brackets and commas in column names):

>>> df = pd.DataFrame()
>>> df.index = [0., 0.1, 0.2, 0.3, 0.4]  # Time in seconds
>>> df["rot[0,0]"] = np.cos([0., 0.1, 0.2, 0.3, 0.4])
>>> df["rot[0,1]"] = -np.sin([0., 0.1, 0.2, 0.3, 0.4])
>>> df["rot[1,0]"] = np.sin([0., 0.1, 0.2, 0.3, 0.4])
>>> df["rot[1,1]"] = np.cos([0., 0.1, 0.2, 0.3, 0.4])
>>> df["trans[0]"] = [0., 0.1, 0.2, 0.3, 0.4]
>>> df["trans[1]"] = [5., 6., 7., 8., 9.]
>>> df
     rot[0,0]  rot[0,1]  rot[1,0]  rot[1,1]  trans[0]  trans[1]
0.0  1.000000 -0.000000  0.000000  1.000000       0.0       5.0
0.1  0.995004 -0.099833  0.099833  0.995004       0.1       6.0
0.2  0.980067 -0.198669  0.198669  0.980067       0.2       7.0
0.3  0.955336 -0.295520  0.295520  0.955336       0.3       8.0
0.4  0.921061 -0.389418  0.389418  0.921061       0.4       9.0
>>> ts = ktk.TimeSeries(df)
>>> ts.data
{'rot': array([[[ 1.        , -0.        ],
        [ 0.        ,  1.        ]],

       [[ 0.99500417, -0.09983342],
        [ 0.09983342,  0.99500417]],

       [[ 0.98006658, -0.19866933],
        [ 0.19866933,  0.98006658]],

       [[ 0.95533649, -0.29552021],
        [ 0.29552021,  0.95533649]],

       [[ 0.92106099, -0.38941834],
        [ 0.38941834,  0.92106099]]]), 'trans': array([[0. , 5. ],
       [0.1, 6. ],
       [0.2, 7. ],
       [0.3, 8. ],
       [0.4, 9. ]])}

See Also: TimeSeries.from_dataframe

7. Creating a TimeSeries from any array (results in a TimeSeries with a single data key named “data” and with a matching time property with a period of 1 second - unless time attribute is also defined):

>>> ktk.TimeSeries([0.1, 0.2, 0.3, 0.4, 0.5])
TimeSeries with attributes:
         time: array([0., 1., 2., 3., 4.])
         data: {'data': array([0.1, 0.2, 0.3, 0.4, 0.5])}
    time_info: {'Unit': 's'}
    data_info: {}
       events: []
>>> ktk.TimeSeries([0.1, 0.2, 0.3, 0.4, 0.5], time=[0.1, 0.2, 0.3, 0.4, 0.5])
TimeSeries with attributes:
         time: array([0.1, 0.2, 0.3, 0.4, 0.5])
         data: {'data': array([0.1, 0.2, 0.3, 0.4, 0.5])}
    time_info: {'Unit': 's'}
    data_info: {}
       events: []

See Also: TimeSerise.from_array

Methods

add_data

Add new data to the TimeSeries.

add_data_info

Add metadata to TimeSeries' data.

add_event

Add an event to the TimeSeries.

copy

Deep copy of a TimeSeries.

count_events

Count the number of occurrence of a given event name.

fill_missing_samples

Fill missing samples using a given method.

from_array

Create a new TimeSeries from an array.

from_dataframe

Create a new TimeSeries from a Pandas Dataframe.

get_index_after_event

Get the time index that is just after the specified event occurrence.

get_index_after_time

Get the time index that is just after the specified time.

get_index_at_event

Get the time index that is closest to the specified event occurrence.

get_index_at_time

Get the time index that is closest to the specified time.

get_index_before_event

Get the time index that is just before the specified event occurrence.

get_index_before_time

Get the time index that is just before the specified time.

get_sample_rate

Get the sample rate in samples/s.

get_subset

Return a subset of the TimeSeries.

get_ts_after_event

Get a TimeSeries after the specified event.

get_ts_after_index

Get a TimeSeries after the specified time index.

get_ts_after_time

Get a TimeSeries after the specified time.

get_ts_before_event

Get a TimeSeries before the specified event.

get_ts_before_index

Get a TimeSeries before the specified time index.

get_ts_before_time

Get a TimeSeries before the specified time.

get_ts_between_events

Get a TimeSeries between two specified events.

get_ts_between_indexes

Get a TimeSeries between two specified time indexes.

get_ts_between_times

Get a TimeSeries between two specified times.

isnan

Return a boolean array of missing samples.

merge

Merge the TimeSeries with another TimeSeries.

plot

Plot the TimeSeries in the current matplotlib figure.

remove_data

Remove a data key and its associated metadata.

remove_data_info

Remove metadata from a TimeSeries' data.

remove_duplicate_events

Remove events with same name and time so that each event gets unique.

remove_event

Remove an event occurrence or all events of a same name.

rename_data

Rename a key in data and data_info.

rename_event

Rename an event occurrence or all events of a same name.

resample

Resample the TimeSeries.

shift

Shift time and events.time.

sort_events

Deprecated.

to_dataframe

Create a DataFrame by reshaping all data to one bidimensional table.

trim_events

Delete the events that are outside the TimeSeries' time attribute.

ui_edit_events

Edit events interactively.

ui_sync

Synchronize one or two TimeSeries by shifting their time.

Attributes

data

Data Property.

events

Data Property.

time

Time Property.