ktk.TimeSeries

class TimeSeries(src=None, *, time=[], data={}, events=[], info={'Time': {'Unit': 's'}}, **kwargs)

Bases: object

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

Parameters:

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

• time (ArrayLike)

• data (dict[str, ArrayLike])

• events (list[TimeSeriesEvent])

• info (dict[str, Any])

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]

events

List of events.

Type:

list[TimeSeriesEvent]

info

Contains metadata such as units or other information.

Type:

dict[str, Any]

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: {}
    events: []
      info: {'Time': {'Unit': 's'}}

2. 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])}
    events: []
      info: {'Time': {'Unit': 's'}}

3. 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])}
    events: []
      info: {'Time': {'Unit': 's'}}

See Also: TimeSeries.copy

4. 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>
    events: []
      info: {'Time': {'Unit': 's'}}

>>> 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["R[:,0,0]"] = np.cos([0., 0.1, 0.2, 0.3, 0.4])
>>> df["R[:,0,1]"] = -np.sin([0., 0.1, 0.2, 0.3, 0.4])
>>> df["R[:,1,0]"] = np.sin([0., 0.1, 0.2, 0.3, 0.4])
>>> df["R[:,1,1]"] = np.cos([0., 0.1, 0.2, 0.3, 0.4])
>>> df["t[:,0]"] = [0., 0.1, 0.2, 0.3, 0.4]
>>> df["t[:,1]"] = [5., 6., 7., 8., 9.]
>>> df
     R[:,0,0]  R[:,0,1]  R[:,1,0]  R[:,1,1]    t[:,0]    t[:,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
{'R': 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]]]), 't': 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])}
    events: []
      info: {'Time': {'Unit': 's'}}

>>> 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])}
    events: []
      info: {'Time': {'Unit': 's'}}

See Also: TimeSeries.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.
add_info	Add new info the to 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 key in data.
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.
remove_info	Remove info from a TimeSeries.
rename_data	Rename a key in data.
rename_event	Rename an event occurrence or all events of a same name.
rename_info	Rename info keys.
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.
data_info	Pre-0.17 data-info property.
events	Events Property.
info	Info Property.
time	Time Property.
time_info	Pre-0.17 time-info property.