tspy.multi_time_series module

main entry-point for creation of MultiTimeSeries

tspy.multi_time_series.multi_time_series(*args, **kwargs)

creates a multi-time-series object using data in either

  1. dict

  2. dataframe

  3. time-series-reader

  4. observation collection

Parameters
data:

type dict or pandas.DataFrame

  1. group by values of a given column [e.g. temperature time series and a bunch of locations (keys)],

  2. each column is turned into its own time-series [a single timestamp and multiple metrics, e.g. temperature and humidity columns]

key_columnstring

(only use when data is a pandas’s DataFrame and use-case (1)) column name containing the key, each key value is used for grouping data into a single-time-series. IMPORTANT: key_column and key_columns are used exclusively.

key_columnslist, optional

(only use when data is a pandas’s DataFrame and use-case (2)) columns to use in multi-time-series creation (default is all columns), i.e. each column is turned into its own time-series component. IMPORTANT: key_column and key_columns are used exclusively.

ts_columnstring, optional

(only use when data is a pandas’s DataFrame) column name containing time-ticks (default: time-tick is based on index into dataframe)

value_columnlist or string, optional

(only use when data is a pandas’s DataFrame and use-case (1)) column name(s) containing values (default is all columns)

granularitydatetime.timedelta, optional

the granularity for use in time-series TRS (default is None if no start_time, otherwise 1ms)

start_timedatetime, optional

the starting date-time of the time-series (default is None if no granularity, otherwise 1970-01-01 UTC)

Returns
MultiTimeSeries

a new multi-time-series

Raises
ValueError

If there is an error in the input arguments, e.g. not a supporting data type

Examples

create a dict with observation-collection values

>>> import tspy
>>> my_dict = {"ts1": tspy.time_series([1,2,3]).collect(), "ts2": tspy.time_series([4,5,6]).collect()}
>>> my_dict
{'ts1': [(0,1),(1,2),(2,3)], 'ts2': [(0,4),(1,5),(2,6)]}

create a multi-time-series from dict without a time-reference-system

>>> mts = tspy.multi_time_series(my_dict)
>>> mts
ts2 time series
------------------------------
TimeStamp: 0     Value: 4
TimeStamp: 1     Value: 5
TimeStamp: 2     Value: 6
ts1 time series
------------------------------
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

  • create a simple df with a single index

>>> import numpy as np
>>> import pandas as pd
>>> data = np.array([['', 'letters', 'timestamp', "numbers"],
             ...['', "a", 1, 27],
             ...['', "b", 3, 4],
             ...['', "a", 5, 17],
             ...['', "a", 3, 7],
             ...['', "b", 2, 45]
            ...])
>>> df = pd.DataFrame(data=data[1:, 1:],
              ...columns=data[0, 1:]).astype(dtype={'letters': 'object', 'timestamp': 'int64', 'numbers': 'float64'})
  letters  timestamp  numbers
0       a          1     27.0
1       b          3      4.0
2       a          5     17.0
3       a          3      7.0
4       b          2     45.0

create a multi-time-series from a df using instants format

>>> mts = tspy.multi_time_series(df, ts_column='timestamp')
>>> mts
numbers time series
------------------------------
TimeStamp: 1     Value: 27.0
TimeStamp: 2     Value: 45.0
TimeStamp: 3     Value: 4.0
TimeStamp: 3     Value: 7.0
TimeStamp: 5     Value: 17.0
letters time series
------------------------------
TimeStamp: 1     Value: a
TimeStamp: 2     Value: b
TimeStamp: 3     Value: b
TimeStamp: 3     Value: a
TimeStamp: 5     Value: a

  • create a simple df with a single index

>>> import numpy as np
>>> import pandas as pd
>>> data = np.array([['', 'letters', 'timestamp', "numbers"],
             ...['', "a", 1, 27],
             ...['', "b", 3, 4],
             ...['', "a", 5, 17],
             ...['', "a", 3, 7],
             ...['', "b", 2, 45]
            ...])
>>> df = pd.DataFrame(data=data[1:, 1:],
              ...columns=data[0, 1:]).astype(dtype={'letters': 'object', 'timestamp': 'int64', 'numbers': 'float64'})
  letters  timestamp  numbers
0       a          1     27.0
1       b          3      4.0
2       a          5     17.0
3       a          3      7.0
4       b          2     45.0

create a multi-time-series from a df using observations format where the key is letters

>>> mts = tspy.multi_time_series(df, key_column="letters", ts_column='timestamp')
a time series
------------------------------
TimeStamp: 1     Value: {numbers=27.0}
TimeStamp: 3     Value: {numbers=7.0}
TimeStamp: 5     Value: {numbers=17.0}
b time series
------------------------------
TimeStamp: 2     Value: {numbers=45.0}
TimeStamp: 3     Value: {numbers=4.0}