tspy.data_structures.time_series.TimeSeries module

class tspy.data_structures.time_series.TimeSeries.TimeSeries(tsc, j_ts, trs=None)

Bases: object

This is the abstract portrayal of lazily evaluated immutable TimeSeries. By lazy, we mean that this time series will only get values when explicitly asked for. By immutable, we mean this time series’ observations may never be directly mutated.

A TimeSeries object can either be physical(having a source) or it can be from some other TimeSeries. One can think of TimeSeries as a series where each value is an Observation in the series. TimeSeries objects have the property where, values are computed lazily meaning, execution of a TimeSeries pipeline only continues, when one asks for values

Raises

ValueError

If there is an error in the input arguments

Examples

create a time series from a list

>>> import tspy
>>> tspy.time_series([1, 2, 3])
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

create a time series from a list with a time-reference-system

>>> import tspy
>>> import datetime
>>> granularity = datetime.timedelta(days=1)
>>> start_time = datetime.datetime(1990, 1, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc)
>>> tspy.time_series([1, 2, 3], granularity=granularity, start_time=start_time)
TimeStamp: 1990-01-01T00:00Z     Value: 1
TimeStamp: 1990-01-02T00:00Z     Value: 2
TimeStamp: 1990-01-03T00:00Z     Value: 3

create a time series from a pandas dataframe

>>> import tspy
>>> import numpy as np
>>> import pandas as pd
>>> header = ['', 'key', 'timestamp', "name", "age"]
>>> row1 = ['Row1', "a", 1, "josh", 27]
>>> row2 = ['Row2', "b", 3, "john", 4]
>>> row3 = ['Row3', "a", 5, "bob", 17]
>>> data = np.array([header, row1, row2, row3])
>>> df = pd.DataFrame(data=data[1:, 1:], index=data[1:, 0], columns=data[0, 1:])
>>> tspy.time_series(df, ts_column="timestamp")
TimeStamp: 1     Value: {name=josh, age=27, key=a}
TimeStamp: 3     Value: {name=john, age=4, key=b}
TimeStamp: 5     Value: {name=bob, age=17, key=a}

Attributes

trs: :class:`~tspy.data_structures.observations.TRS.TRS`

a time-reference-system

Methods

cache([cache_size])	suggest to the time-series to cache values
collect([inclusive])	collect all observations in this time-series
concat(other_time_series)	produce a new time-series which is the result of concatenating two time-series
count([inclusive])	count the current number of observations in this time-series
describe()	retrieve time-series statistics computed from all values in this time-series
fillna(interpolator[, null_value])	produce a new time-series which is the result of filling all null values.
filter(func)	produce a new time-series which is the result of filtering by each observation’s value given a filter function.
flatmap(func)	produce a new time-series where each observation’s value in this time-series is mapped to 0 to N new values.
forecast(num_predictions, fm[, …])	forecast the next num_predictions using a forecasting model
full_align(time_series[, left_interp_func, …])	align two time-series based on a temporal full join strategy and optionally interpolate missing values
full_join(time_series[, join_func, …])	join two time-series based on a temporal full join strategy and optionally interpolate missing values
get_values(start, end[, inclusive])	get all values between a range in this time-series
inner_align(time_series)	align two time-series based on a temporal inner join strategy
inner_join(time_series[, join_func])	join two time-series based on a temporal inner join strategy
lag(lag_amount)	produce a new time-series which is a lagged version of the current time-series.
left_align(time_series[, interp_func])	align two time-series based on a temporal left join strategy and optionally interpolate missing values
left_join(time_series[, join_func, interp_func])	join two time-series based on a temporal left join strategy and optionally interpolate missing values
left_outer_align(time_series[, interp_func])	align two time-series based on a temporal left outer join strategy and optionally interpolate missing values
left_outer_join(time_series[, join_func, …])	join two time-series based on a temporal left outer join strategy and optionally interpolate missing values
map(func)	produce a new time-series where each observation’s value in this time-series is mapped to a new observation value
map_with_index(func)	produce a new time-series where each observation’s value in this time-series is mapped given the old value and an index to a new observation value
print([start, end, inclusive, human_readable])	print this time-series
reduce(*args)	reduce this time-series or two time-series to a single value
resample(period, func)	produce a new time-series by resampling the current time-series to a given periodicity
right_align(time_series[, interp_func])	align two time-series based on a temporal right join strategy and optionally interpolate missing values
right_join(time_series[, join_func, interp_func])	join two time-series based on a temporal right join strategy and optionally interpolate missing values
right_outer_align(time_series[, interp_func])	align two time-series based on a temporal right outer join strategy and optionally interpolate missing values
right_outer_join(time_series[, join_func, …])	join two time-series based on a temporal right outer join strategy and optionally interpolate missing values
segment(window[, step, enforce_size])	produce a new segment-time-series from a performing a sliding-based segmentation over the time-series
segment_by(func)	produce a new segment-time-series from a performing a group-by operation on each observation’s value
segment_by_anchor(func, left_delta, right_delta)	produce a new segment-time-series from performing an anchor-based segmentation over the time-series.
segment_by_changepoint([change_point])	produce a new segment-time-series from performing a chang-point based segmentation.
segment_by_marker(*args, **kwargs)	produce a new segment-time-series from performing a marker based segmentation.
segment_by_time(window, step)	produce a new segment-time-series from a performing a time-based segmentation over the time-series
shift(shift_amount[, default_value])	produce a new time-series which is a shifted version of the current time-series.
to_df([inclusive])	convert this time-series to a pandas dataframe
to_segments(segment_transform)	produce a new segment-time-series from a segmentation transform
transform(*args)	produce a new time-series which is the result of performing a transforming over the time-series.
uncache()	remove the time-series caching mechanism
with_trs([granularity, start_time])	create a new time-series with its timestamps mapped based on a granularity and start_time.
write([start, end, inclusive])	create a time-series-writer given a range

cache(cache_size=None)

suggest to the time-series to cache values

Parameters

cache_sizeint, optional

the max cache size (default is max long)

Returns

TimeSeries

a new time-series

Notes

this is a lazy operation and will only suggest to the time-series to save values once computed

collect(inclusive=False)

collect all observations in this time-series

Parameters

inclusivebool, optional

if true, will use inclusive bounds (default is False)

Returns

ObservationCollection

a collection of observations

Raises

TSErrorWithMessage

If there is an error with TimeSeries handling

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

collect the values

>>> ts_org.collect()
[(0,1.0),(1,2.0),(2,3.0)]

concat(other_time_series)

produce a new time-series which is the result of concatenating two time-series

Parameters

other_time_seriesTimeSeries

the time-series to concatenate with

Returns

TimeSeries

a new TimeSeries

Examples

create two simple time-series

>>> import tspy
>>> ts_orig = tspy.builder()            .add(tspy.observation(1,1.0))            .add(tspy.observation(2,2.0))            .result()            .to_time_series()
>>> ts_orig
TimeStamp: 1     Value: 1.0
TimeStamp: 2     Value: 2.0

>>> ts_orig2 = tspy.builder()            .add(tspy.observation(3,3.0))            .add(tspy.observation(4,4.0))            .result()            .to_time_series()
>>> ts_orig2
TimeStamp: 3     Value: 3.0
TimeStamp: 4     Value: 4.0

>>> ts_concat = ts_orig.concat(ts_orig2)
>>> ts_concat
TimeStamp: 1     Value: 1.0
TimeStamp: 2     Value: 2.0
TimeStamp: 3     Value: 3.0
TimeStamp: 4     Value: 4.0

count(inclusive=False)

count the current number of observations in this time-series

Parameters

inclusivebool, optional

if true, will use inclusive bounds (default is False)

Returns

int

the number of observations in this time-series

describe()

retrieve time-series statistics computed from all values in this time-series

Returns

Stats or NumStats

the basic statistics for this time-series or additional numeric statistics if float

fillna(interpolator, null_value=None)

produce a new time-series which is the result of filling all null values.

Parameters

interpolatorfunc or interpolator

the interpolator method to be used when a value is null

null_valueany, optional

denotes a null value, for instance if nullValue = NaN, NaN would be filled

Returns

TimeSeries

a new time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1, None, 3])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: null
TimeStamp: 2     Value: 3

fill all Nones with another value using a simple fill interpolator

>>> from tspy.functions import interpolators
>>> ts = ts_orig.fillna(interpolators.fill(2))
>>> ts
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

fill all 1s with another value using a simple next interpolator. Note: fillna will never choose None values from an interpolator unless explicitly specified

>>> from tspy.functions import interpolators
>>> ts = ts_orig.fillna(interpolators.next(), 1)
>>> ts
TimeStamp: 0     Value: 3
TimeStamp: 1     Value: null
TimeStamp: 2     Value: 3

filter(func)

produce a new time-series which is the result of filtering by each observation’s value given a filter function.

Parameters

funcfunc

the filter on observation’s value function

Returns

TimeSeries

a new time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1, 2, 3])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

filter the time-series for even numbers

>>> ts = ts_orig.filter(lambda x: x % 2 == 0)
>>> ts
TimeStamp: 1     Value: 2

filter the time-series for even numbers using high performant expressions

>>> from tspy.functions import expressions as exp
>>> ts = ts_orig.filter(exp.divisible_by(exp.id(), 2))
>>> ts
TimeStamp: 1     Value: 2

flatmap(func)

produce a new time-series where each observation’s value in this time-series is mapped to 0 to N new values.

Parameters

funcfunc

value mapping function which returns a list of values

Returns

TimeSeries

a new time-series with its values flat-mapped

Notes

an observations time-tick will be duplicated if a single value maps to multiple values

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1, 2, 3])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

flat map each time-series observation value by duplicating the value

>>> ts = ts_orig.flatmap(lambda x: [x, x])
>>> ts
TimeStamp: 0     Value: 1
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3
TimeStamp: 2     Value: 3

forecast(num_predictions, fm, start_training_time=None, confidence=1.0)

forecast the next num_predictions using a forecasting model

Parameters

num_predictionsint

number of forecasts past the end of the time-series to retrieve

fmForecastingModel

the forecasting model to use

start_training_timeint or datetime, optional

point at which to start training the forecasting model

confidencefloat

number between 0 and 1 which is used in calculating the confidence interval

Returns

ObservationCollection

a collection of observations

Raises

TSErrorWithMessage

If there is an error with TimeSeries handling

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([float(i) for i in range(10)])
>>> ts
TimeStamp: 0     Value: 0.0
TimeStamp: 1     Value: 1.0
TimeStamp: 2     Value: 2.0
TimeStamp: 3     Value: 3.0
TimeStamp: 4     Value: 4.0
TimeStamp: 5     Value: 5.0
TimeStamp: 6     Value: 6.0
TimeStamp: 7     Value: 7.0
TimeStamp: 8     Value: 8.0
TimeStamp: 9     Value: 9.0

forecast the next 5 values using an auto forecastor

>>> num_predictions = 5
>>> model = tspy.forecasters.auto(8)
>>> confidence = .99
>>> predictions = ts.forecast(num_predictions, model, confidence=confidence)
>>> predictions.to_time_series()
TimeStamp: 10     Value: {value=10.0, lower_bound=10.0, upper_bound=10.0, error=0.0}
TimeStamp: 11     Value: {value=10.997862810553725, lower_bound=9.934621260488143, upper_bound=12.061104360619307, error=0.41277640121597475}
TimeStamp: 12     Value: {value=11.996821082897318, lower_bound=10.704895525154571, upper_bound=13.288746640640065, error=0.5015571318964149}
TimeStamp: 13     Value: {value=12.995779355240911, lower_bound=11.50957896664928, upper_bound=14.481979743832543, error=0.5769793776877866}
TimeStamp: 14     Value: {value=13.994737627584504, lower_bound=12.33653268707341, upper_bound=15.652942568095598, error=0.6437557559526337}

full_align(time_series, left_interp_func=<function TimeSeries.<lambda>>, right_interp_func=<function TimeSeries.<lambda>>)

align two time-series based on a temporal full join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

left_interp_funcfunc or interpolator, optional

the left time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

right_interp_funcfunc or interpolator, optional

the right time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

tuple

aligned time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

align the two time-series based on a temporal full join strategy

>>> from tspy.functions import interpolators
>>> (left, right) = orig_left.full_align(orig_right, interpolators.prev(), interpolators.next())
>>> left
TimeStamp: 1     Value: 1
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4
TimeStamp: 5     Value: 4

>>> right
TimeStamp: 1     Value: 1
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

full_join(time_series, join_func=None, left_interp_func=<function TimeSeries.<lambda>>, right_interp_func=<function TimeSeries.<lambda>>)

join two time-series based on a temporal full join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

join_funcfunc, optional

function to join to values (default is join to list where left is index 0, right is index 1)

left_interp_funcfunc or interpolator, optional

the left time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

right_interp_funcfunc or interpolator, optional

the right time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

TimeSeries

a new time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

join the two time-series based on a temporal full join strategy

>>> from tspy.functions import interpolators
>>> ts = orig_left.full_join(orig_right, interpolator_left=interpolators.prev(), interpolator_right=interpolators.next())
>>> ts
TimeStamp: 1     Value: [1, 1]
TimeStamp: 2     Value: [1, 1]
TimeStamp: 3     Value: [3, 2]
TimeStamp: 4     Value: [4, 3]
TimeStamp: 5     Value: [4, 4]

get_values(start, end, inclusive=False)

get all values between a range in this time-series

Parameters

startint or datetime

start of range (inclusive)

endint or datetime

end of range (inclusive)

inclusivebool, optional

if true, will use inclusive bounds (default is False)

Returns

ObservationCollection

a collection of observations

Raises

TSErrorWithMessage

If there is an error with TimeSeries handling

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

get values in range start=1, end=3

>>> observations = ts.get_values(1, 3)
>>> observations
[(1,2.0),(2,3.0)]

get values in a range using slice

>>> observations = ts[1:-1]
>>> observations
[(1,2.0)]

inner_align(time_series)

align two time-series based on a temporal inner join strategy

Parameters

time_seriesTimeSeries

the time-series to align with

Returns

tuple

aligned time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()        ....add(tspy.observation(1,1))        ....add(tspy.observation(3,3))        ....add(tspy.observation(4,4))        ....result()        ....to_time_series()
>>> orig_right = tspy.builder()        ....add(tspy.observation(2,1))        ....add(tspy.observation(3,2))        ....add(tspy.observation(4,3))        ....add(tspy.observation(5,4))        ....result()        ....to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

align the two time-series based on a temporal inner join strategy

>>> (left, right) = left.inner_align(right)
>>> left
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> right
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3

inner_join(time_series, join_func=None)

join two time-series based on a temporal inner join strategy

Parameters

time_seriesTimeSeries

the time-series to join with

join_funcfunc, optional

function to join 2 values at a given time-tick. If None given, joined value will be in a list (default is None)

Returns

TimeSeries

a new time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()        ....add(tspy.observation(1,1))        ....add(tspy.observation(3,3))        ....add(tspy.observation(4,4))        ....result()        ....to_time_series()
>>> orig_right = tspy.builder()        ....add(tspy.observation(2,1))        ....add(tspy.observation(3,2))        ....add(tspy.observation(4,3))        ....add(tspy.observation(5,4))        ....result()        ....to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

join the two time-series based on a temporal inner join strategy

>>> ts = orig_left.inner_join(orig_right)
>>> ts
TimeStamp: 3     Value: [3, 2]
TimeStamp: 4     Value: [4, 3]

lag(lag_amount)

produce a new time-series which is a lagged version of the current time-series.

Parameters

lag_amountint

number of time-ticks to lag

Returns

TimeSeries

a new time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
>>> ts_orig.print(2, 4)
TimeStamp: 2     Value: 2.0
TimeStamp: 3     Value: 3.0
TimeStamp: 4     Value: 4.0

lag the time-series by 2 time-ticks

>>> ts = ts_orig.lag(2)
>>> ts.print(2, 4)
TimeStamp: 4     Value: 4.0
TimeStamp: 5     Value: 5.0

left_align(time_series, interp_func=<function TimeSeries.<lambda>>)

align two time-series based on a temporal left join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

interp_funcfunc or interpolator, optional

the right time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

tuple

aligned time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

align the two time-series based on a temporal left join strategy

>>> from tspy.functions import interpolators
>>> (left, right) = orig_left.left_align(orig_right, interpolators.prev(), interpolators.next())
>>> left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> right
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3

left_join(time_series, join_func=None, interp_func=<function TimeSeries.<lambda>>)

join two time-series based on a temporal left join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

join_funcfunc, optional

function to join to values (default is join to list where left is index 0, right is index 1)

interp_funcfunc or interpolator, optional

the right time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

TimeSeries

a new time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

join the two time-series based on a temporal left join strategy

>>> from tspy.functions import interpolators
>>> ts = orig_left.left_join(orig_right, inter_func=interpolators.next())
>>> ts
TimeStamp: 1     Value: [1, 1]
TimeStamp: 3     Value: [3, 2]
TimeStamp: 4     Value: [4, 3]

left_outer_align(time_series, interp_func=<function TimeSeries.<lambda>>)

align two time-series based on a temporal left outer join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

interp_funcfunc or interpolator, optional

the right time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

tuple

aligned time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

align the two time-series based on a temporal left outer join strategy

>>> from tspy.functions import interpolators
>>> (left, right) = orig_left.left_outer_align(orig_right, interpolators.next())
>>> left
TimeStamp: 1     Value: 1

>>> right
TimeStamp: 1     Value: 1

left_outer_join(time_series, join_func=None, interp_func=<function TimeSeries.<lambda>>)

join two time-series based on a temporal left outer join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

join_funcfunc, optional

function to join to values (default is join to list where left is index 0, right is index 1)

interp_funcfunc or interpolator, optional

the right time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

TimeSeries

a new time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

join the two time-series based on a temporal left outer join strategy

>>> from tspy.functions import interpolators
>>> ts = orig_left.left_outer_join(orig_right, interp_func=interpolators.next())
>>> ts
TimeStamp: 1     Value: [1, 1]

map(func)

produce a new time-series where each observation’s value in this time-series is mapped to a new observation value

Parameters

funcfunc

value mapping function

Returns

TimeSeries

a new time-series with its values re-mapped

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1, 2, 3])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

add one to each value of the time-series and produce a new time-series

>>> ts = ts_orig.map(lambda x: x + 1)
>>> ts
TimeStamp: 0     Value: 2
TimeStamp: 1     Value: 3
TimeStamp: 2     Value: 4

map each value of the time-series to a string and produce a new time-series

>>> ts = ts_orig.map(lambda x: "value - " + str(x))
>>> ts
TimeStamp: 0     Value: value - 1
TimeStamp: 1     Value: value - 2
TimeStamp: 2     Value: value - 3

map each value of the time-series to a string using high performant expressions

>>> from tspy.functions import expressions as exp
>>> ts = ts_orig.map(exp.add(exp.id(), 1))
TimeStamp: 0     Value: 2.0
TimeStamp: 1     Value: 3.0
TimeStamp: 2     Value: 4.0

map_with_index(func)

produce a new time-series where each observation’s value in this time-series is mapped given the old value and an index to a new observation value

Parameters

funcfunc

value mapping function which includes an index as input

Returns

TimeSeries

a new time-series with its values re-mapped

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1, 2, 3])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

add one to each value of the time-series and produce a new time-series

>>> ts = ts_orig.map_with_index(lambda x, index: str(x) + "-" + str(index))
>>> ts
TimeStamp: 0     Value: 1 - 0
TimeStamp: 1     Value: 2 - 1
TimeStamp: 2     Value: 3 - 2

print(start=None, end=None, inclusive=False, human_readable=True)

print this time-series

Parameters

startint or datetime, optional

start of range (inclusive) (default is current first time-tick)

endint or datetime

end of range (inclusive) (default is current last time-tick)

inclusivebool, optional

if true, will use inclusive bounds (default is False)

human_readablebool, optional

if true, will print time-stamps as human readable if time-series is backed by time-reference-system, otherwise will print time-ticks

Raises

ValueError

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

reduce(*args)

reduce this time-series or two time-series to a single value

Parameters

argslist of arguments

if one arg given, a unary reducer is used. If two args given, a time-series and binary reducer are used.

Returns

any

the output of time-series reduction

Raises

ValueError

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

TSErrorWithMessage

If there is an error with TimeSeries handling

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

reduce this time-series to an average

>>> from tspy.functions import reducers
>>> avg = ts_orig.reduce(reducers.average())
>>> avg
3

reduce this time-series and another to a cross-correlation

>>> from tspy.functions import reducers
>>> other_ts = tspy.time_series([2.0, 3.0, 4.0])
>>> cross_correlation = ts_orig.reduce(other_ts, reducers.cross_correlation())
>>> cross_correlation
[-0.49999999999999994, 4.4408920985006264e-17, 1.0, 4.4408920985006264e-17, -0.49999999999999994]

resample(period, func)

produce a new time-series by resampling the current time-series to a given periodicity

Parameters

periodint

the period to resample to

funcfunc or interpolator

the interpolator method to be used when a value doesn’t exist at a given time-tick

Returns

TimeSeries

a new time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.builder()            .add(tspy.observation(0,0))            .add(tspy.observation(2,2))            .add(tspy.observation(4,4))            .result()            .to_time_series()
TimeStamp: 0     Value: 0
TimeStamp: 2     Value: 2
TimeStamp: 4     Value: 4

resample to a periodicity of 1 and fill missing time-ticks with 0

>>> from tspy.functions import interpolators
>>> ts_orig.resample(1, interpolators.fill(0))
TimeStamp: 0     Value: 0
TimeStamp: 1     Value: 0
TimeStamp: 2     Value: 2
TimeStamp: 3     Value: 0
TimeStamp: 4     Value: 4

right_align(time_series, interp_func=<function TimeSeries.<lambda>>)

align two time-series based on a temporal right join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

interp_funcfunc or interpolator, optional

the left time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

tuple

aligned time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

align the two time-series based on a temporal right join strategy

>>> from tspy.functions import interpolators
>>> (left, right) = orig_left.right_align(orig_right, interpolators.prev())
>>> left
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4
TimeStamp: 5     Value: 4

>>> right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

right_join(time_series, join_func=None, interp_func=<function TimeSeries.<lambda>>)

join two time-series based on a temporal right join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

join_funcfunc, optional

function to join to values (default is join to list where left is index 0, right is index 1)

interp_funcfunc or interpolator, optional

the left time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

TimeSeries

a new time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

join the two time-series based on a temporal right join strategy

>>> from tspy.functions import interpolators
>>> ts = orig_left.right_join(orig_right, interp_func=interpolators.prev())
>>> ts
TimeStamp: 2     Value: [1, 1]
TimeStamp: 3     Value: [3, 2]
TimeStamp: 4     Value: [4, 3]
TimeStamp: 5     Value: [4, 4]

right_outer_align(time_series, interp_func=<function TimeSeries.<lambda>>)

align two time-series based on a temporal right outer join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

interp_funcfunc or interpolator, optional

the left time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

tuple

aligned time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

align the two time-series based on a temporal right outer join strategy

>>> from tspy.functions import interpolators
>>> (left, right) = orig_left.right_outer_align(orig_right, interpolators.prev())
>>> left
TimeStamp: 2     Value: 1
TimeStamp: 5     Value: 4

>>> right
TimeStamp: 2     Value: 1
TimeStamp: 5     Value: 4

right_outer_join(time_series, join_func=None, interp_func=<function TimeSeries.<lambda>>)

join two time-series based on a temporal right outer join strategy and optionally interpolate missing values

Parameters

time_seriesTimeSeries

the time-series to align with

join_funcfunc, optional

function to join to values (default is join to list where left is index 0, right is index 1)

interp_funcfunc or interpolator, optional

the left time-series interpolator method to be used when a value doesn’t exist at a given time-tick (default is fill with None)

Returns

TimeSeries

a new time-series

Examples

create two simple time-series

>>> import tspy
>>> orig_left = tspy.builder()            .add(tspy.observation(1,1))            .add(tspy.observation(3,3))            .add(tspy.observation(4,4))            .result()            .to_time_series()
>>> orig_right = tspy.builder()            .add(tspy.observation(2,1))            .add(tspy.observation(3,2))            .add(tspy.observation(4,3))            .add(tspy.observation(5,4))            .result()            .to_time_series()
>>> orig_left
TimeStamp: 1     Value: 1
TimeStamp: 3     Value: 3
TimeStamp: 4     Value: 4

>>> orig_right
TimeStamp: 2     Value: 1
TimeStamp: 3     Value: 2
TimeStamp: 4     Value: 3
TimeStamp: 5     Value: 4

join the two time-series based on a temporal right outer join strategy

>>> from tspy.functions import interpolators
>>> ts = orig_left.right_outer_join(orig_right, interp_func=interpolators.prev())
>>> ts
TimeStamp: 2     Value: [1, 1]
TimeStamp: 5     Value: [4, 4]

segment(window, step=1, enforce_size=True)

produce a new segment-time-series from a performing a sliding-based segmentation over the time-series

Parameters

windowint

number of observations per window

stepint, optional

step size to slide (default is 1)

enforce_sizebool, optional

if true, will require a window to have the given window size number of observations, otherwise windows can have less than or equal to the window size number of observations. (default is True)

Returns

SegmentTimeSeries

a new segment-time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0, 4.0, 5.0])
>>> ts_orig
TimeStamp: 0     Value: 1.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 3.0
TimeStamp: 3     Value: 4.0
TimeStamp: 4     Value: 5.0

segment the time-series with a window=3, step=2

>>> ts = ts_orig.segment(3,2)
TimeStamp: 0     Value: original bounds: (0,2) actual bounds: (0,2) observations: [(0,1.0),(1,2.0),(2,3.0)]
TimeStamp: 2     Value: original bounds: (2,4) actual bounds: (2,4) observations: [(2,3.0),(3,4.0),(4,5.0)]

segment the time-series with a window=3, step=2, enforce_size=False

>>> ts = ts_orig.segment(3,2, enforce_size=False)
TimeStamp: 0     Value: original bounds: (0,2) actual bounds: (0,2) observations: [(0,1.0),(1,2.0),(2,3.0)]
TimeStamp: 2     Value: original bounds: (2,4) actual bounds: (2,4) observations: [(2,3.0),(3,4.0),(4,5.0)]
TimeStamp: 4     Value: original bounds: (4,4) actual bounds: (4,4) observations: [(4,5.0)]

segment_by(func)

produce a new segment-time-series from a performing a group-by operation on each observation’s value

Parameters

funcfunc

value to key function

Returns

SegmentTimeSeries

a new segment-time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0, 4.0, 5.0])
>>> ts_orig
TimeStamp: 0     Value: 1.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 3.0
TimeStamp: 3     Value: 4.0
TimeStamp: 4     Value: 5.0

segment the time-series by even/odd numbers

>>> ts = ts_orig.segment_by(lambda x: x % 2 == 0)
>>> ts
TimeStamp: 0     Value: original bounds: (0,4) actual bounds: (0,4) observations: [(0,1.0),(2,3.0),(4,5.0)]
TimeStamp: 1     Value: original bounds: (1,3) actual bounds: (1,3) observations: [(1,2.0),(3,4.0)]

segment_by_anchor(func, left_delta, right_delta, perc=None)

produce a new segment-time-series from performing an anchor-based segmentation over the time-series. An anchor point is defined as any value that satisfies the filter function. When an anchor point is determined the segment is built based on left_delta time ticks to the left of the point and right_delta time ticks to the right of the point.

Parameters

funcfunc

the filter anchor point function

left_deltaint

left delta time ticks to the left of the anchor point

right_deltaint

right delta time ticks to the right of the anchor point

percint, optional

number between 0 and 1.0 to denote how often to accept the anchor (default is None)

Returns

SegmentTimeSeries

a new segment-time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0, 4.0, 5.0])
>>> ts_orig
TimeStamp: 0     Value: 1.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 3.0
TimeStamp: 3     Value: 4.0
TimeStamp: 4     Value: 5.0

segment the time-series by anchor points (even numbers)

>>> ts = ts_orig.segment_by_anchor(lambda x: x % 2 == 0, 1, 2)
>>> ts
TimeStamp: 1     Value: original bounds: (0,3) actual bounds: (0,3) observations: [(0,1.0),(1,2.0),(2,3.0),(3,4.0)]
TimeStamp: 3     Value: original bounds: (2,5) actual bounds: (2,4) observations: [(2,3.0),(3,4.0),(4,5.0)]

segment_by_changepoint(change_point=None)

produce a new segment-time-series from performing a chang-point based segmentation. A change-point can be defined as any change in 2 values that results in a true statement.

Parameters

change_pointfunc, optional

a function given a prev/next value to determine if a change exists (default is simple constant change)

Returns

SegmentTimeSeries

a new segment-time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 4.0, 5.0, 6.0])
>>> ts_orig
TimeStamp: 0     Value: 1.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 4.0
TimeStamp: 3     Value: 5.0
TimeStamp: 4     Value: 6.0

segment by a change point where the change point is defined as a greater than 1.0 difference between prev/next values

>>> ts = ts_orig.segment_by_changepoint(lambda p, n: abs(n - p) > 1.0)
>>> ts
TimeStamp: 0     Value: original bounds: (0,1) actual bounds: (0,1) observations: [(0,1.0),(1,2.0)]
TimeStamp: 2     Value: original bounds: (2,4) actual bounds: (2,4) observations: [(2,4.0),(3,5.0),(4,6.0)]

create a simple time-series of strings

>>> ts_orig = tspy.time_series(["a","a","a","b","b","c"])
>>> ts_orig
TimeStamp: 0     Value: a
TimeStamp: 1     Value: a
TimeStamp: 2     Value: a
TimeStamp: 3     Value: b
TimeStamp: 4     Value: b
TimeStamp: 5     Value: c

segment by a simple constant based change point

>>> ts = ts_orig.segment_by_changepoint()
>>> ts
TimeStamp: 0     Value: original bounds: (0,2) actual bounds: (0,2) observations: [(0,a),(1,a),(2,a)]
TimeStamp: 3     Value: original bounds: (3,4) actual bounds: (3,4) observations: [(3,b),(4,b)]
TimeStamp: 5     Value: original bounds: (5,5) actual bounds: (5,5) observations: [(5,c)]

segment_by_marker(*args, **kwargs)

produce a new segment-time-series from performing a marker based segmentation. A marker is defined as any value that satisfies a marker function.

Parameters

start_markerfunc

the marker that denotes the start of a segment in the case of two-marker segments (requires end_marker)

end_markerfunc

the marker that denotes the end of a segment in the case of two-marker segments (requires start_marker)

markerfunc

the marker that denotes the end of a segment and the beginning of a new segment in the case of single-marker segments

start_inclusivebool, optional

if true, will include the start marker to the segment (default is True)

end_inclusivebool, optional

if true, will include the end marker to the segment (default is True)

start_on_firstbool, optional

if true, will start the segment on the first instance of the start marker before an end marker when using two-marker segments (default is False)

end_on_firstbool

if true, will end the segment on the first instance of the end marker after a start marker when using two-marker segments (default is True)

requires_start_and_endbool

if true, a segment will only be created if encapsulated by 2 markers when using single-marker segments (default is False)

Returns

SegmentTimeSeries

a new segment-time-series

Raises

ValueError

If there is an error in the input arguments

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
>>> ts_orig
TimeStamp: 0     Value: 0.0
TimeStamp: 1     Value: 1.0
TimeStamp: 2     Value: 2.0
TimeStamp: 3     Value: 3.0
TimeStamp: 4     Value: 4.0
TimeStamp: 5     Value: 5.0

segment by an even number marker where start_inclusive=True and end_inclusive=False

>>> ts = ts_orig.segment_by_marker(marker=lambda x: x % 2 == 0, start_inclusive=True, end_inclusive=False)
>>> ts
TimeStamp: 0     Value: original bounds: (0,0) actual bounds: (0,0) observations: [(0,0.0)]
TimeStamp: 1     Value: original bounds: (1,2) actual bounds: (1,2) observations: [(1,1.0),(2,2.0)]
TimeStamp: 3     Value: original bounds: (3,4) actual bounds: (3,4) observations: [(3,3.0),(4,4.0)]
TimeStamp: 5     Value: original bounds: (5,5) actual bounds: (5,5) observations: [(5,5.0)]

segment by start_marker = even number and not 4, end_marker = divisible by 5 and not 0, start_inculsive = end_inclusive = True, start_on_first = False, end_on_first = True

>>> start_marker = lambda x: x % 2 == 0 and x != 4
>>> end_marker = lambda x: x % 5 == 0 and x != 0
>>> ts = ts_orig.segment_by_marker(start_marker=start_marker, end_marker=end_marker, start_inclusive=True, end_inclusive=True, start_on_first=False, end_on_first=True)
>>> ts
TimeStamp: 2     Value: original bounds: (2,5) actual bounds: (2,5) observations: [(2,2.0),(3,3.0),(4,4.0),(5,5.0)]

segment_by_time(window, step)

produce a new segment-time-series from a performing a time-based segmentation over the time-series

Parameters

windowint

time-tick length of window

stepint

time-tick length of step

Returns

SegmentTimeSeries

a new segment-time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.builder()            .add(tspy.observation(1,1.0))            .add(tspy.observation(2,2.0))            .add(tspy.observation(6,6.0))            .result()            .to_time_series()
>>> ts_orig
TimeStamp: 1     Value: 1.0
TimeStamp: 2     Value: 2.0
TimeStamp: 6     Value: 6.0

segment the time-series with a time-window length of 3 and a time-step length of 1

>>> ts = ts_orig.segment_by_time(3,1)
>>> ts
TimeStamp: 1     Value: original bounds: (1,3) actual bounds: (1,2) observations: [(1,1.0),(2,2.0)]
TimeStamp: 2     Value: original bounds: (2,4) actual bounds: (2,2) observations: [(2,2.0)]
TimeStamp: 3     Value: this segment is empty
TimeStamp: 4     Value: original bounds: (4,6) actual bounds: (6,6) observations: [(6,6.0)]

shift(shift_amount, default_value=None)

produce a new time-series which is a shifted version of the current time-series.

Parameters

shift_amountint

number of records to shift

default_valueany, optional

default value to set for padded observations (default is None)

Returns

TimeSeries

a new time-series

Notes

Any extra ~tspy.data_structures.Observation.Observation will be padded with the given default value

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
>>> print(ts_orig)
TimeStamp: 0     Value: 0.0
TimeStamp: 1     Value: 1.0
TimeStamp: 2     Value: 2.0
TimeStamp: 3     Value: 3.0
TimeStamp: 4     Value: 4.0
TimeStamp: 5     Value: 5.0

shift the time-series by 2 records filling padded Observations with -1.0

>>> ts = ts_orig.shift(2, -1.0)
>>> ts
TimeStamp: 0     Value: -1.0
TimeStamp: 1     Value: -1.0
TimeStamp: 2     Value: 0.0
TimeStamp: 3     Value: 1.0
TimeStamp: 4     Value: 2.0
TimeStamp: 5     Value: 3.0

to_df(inclusive=False)

convert this time-series to a pandas dataframe

Parameters

inclusivebool, optional

if true, will use inclusive bounds (default is False)

Returns

dataframe

a pandas dataframe representation of this time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0])
>>> ts_orig
TimeStamp: 0     Value: 1
TimeStamp: 1     Value: 2
TimeStamp: 2     Value: 3

convert time-series to pandas dataframe

>>> df = ts_orig.to_df()
>>> df
   timestamp  value
0          0      1
1          1      2
2          2      3

to_segments(segment_transform)

produce a new segment-time-series from a segmentation transform

Parameters

segment_transformUnaryTransform

the transform which will result in a time-series of segments

Returns

SegmentTimeSeries

a new segment-time-series

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0, 2.0, 1.0])
>>> ts_orig
TimeStamp: 0     Value: 1.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 3.0
TimeStamp: 3     Value: 2.0
TimeStamp: 4     Value: 1.0

>>> from tspy.functions import segmenters
>>> reg_ts = ts_orig.to_segments(segmenters.regression(.5,1,use_relative=True))
TimeStamp: 0     Value: --range: (0, 2) --outliers: {}
TimeStamp: 3     Value: --range: (3, 4) --outliers: {}

transform(*args)

produce a new time-series which is the result of performing a transforming over the time-series. A transform can be of type unary (one time-series in, one time-series out) or binary (two time-series in, one time-series out)

Parameters

argsUnaryTransform or BinaryTransform

the transformation to apply on this time-series

Returns

TimeSeries

a new time-series

Raises

ValueError

If there is an error in the input arguments.

Notes

transforms can be shape changing (time-series size out does not necessarily equal time-series size in)

Examples

create a simple time-series

>>> import tspy
>>> ts_orig = tspy.time_series([1.0, 2.0, 3.0])
>>> ts_orig
TimeStamp: 0     Value: 1.0
TimeStamp: 1     Value: 2.0
TimeStamp: 2     Value: 3.0

perform a simple difference transform

>>> from tspy.functions import transformers
>>> ts = ts_orig.transform(transformers.difference())
>>> ts
TimeStamp: 1     Value: 1.0
TimeStamp: 2     Value: 1.0

perform a binary correlation over a sliding window

>>> ts1 = tspy.time_series([float(i) for i in range(0,5)]).segment(4)
>>> ts1
TimeStamp: 0     Value: original bounds: (0,3) actual bounds: (0,3) observations: [(0,0.0),(1,1.0),(2,2.0),(3,3.0)]
TimeStamp: 1     Value: original bounds: (1,4) actual bounds: (1,4) observations: [(1,1.0),(2,2.0),(3,3.0),(4,4.0)]

>>> ts2 = tspy.time_series([float(5 - i) for i in range(0,5)]).segment(4)
>>> ts2
TimeStamp: 0     Value: original bounds: (0,3) actual bounds: (0,3) observations: [(0,5.0),(1,4.0),(2,3.0),(3,2.0)]
TimeStamp: 1     Value: original bounds: (1,4) actual bounds: (1,4) observations: [(1,4.0),(2,3.0),(3,2.0),(4,1.0)]

>>> from tspy.functions import reducers
>>> ts_corr_windows = ts1.transform(ts2, reducers.correlation())
>>> ts_corr_windows
TimeStamp: 0     Value: -1.0
TimeStamp: 1     Value: -1.0

property trs

Returns

TRSTRS

this time-series time-reference-system

uncache()

remove the time-series caching mechanism

Returns

TimeSeries

a new time-series

with_trs(granularity=datetime.timedelta(0, 0, 1000), start_time=datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc))

create a new time-series with its timestamps mapped based on a granularity and start_time. In the scope of this method, granularity refers to the granularity at which to see time_ticks and start_time refers to the zone-date-time in which to start your time-series data when calling get_values()

Parameters

granularitydatetime.timedelta, optional

the granularity for use in time-series TRS (default is 1ms)

start_timedatetime, optional

the starting date-time of the time-series (default is 1970-01-01 UTC)

Returns

TimeSeries

a new time-series with its time_ticks mapped based on a new TRS

Notes

time_ticks will be mapped as follows - (current_time_tick - start_time) / granularity

if the source time-series does not have a time-reference-system associated with it, this method will throw and exception

Examples

create a time series with a time-reference-system

>>> import tspy
>>> import datetime
>>> start_time = datetime.datetime(1990, 1, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc)
>>> granularity = datetime.timedelta(days=1)
>>> ts_orig = tspy.time_series([1, 2, 3, 4, 5], granularity=granularity, start_time=start_time)
>>> ts_orig
TimeStamp: 1990-01-01T00:00Z     Value: 1
TimeStamp: 1990-01-02T00:00Z     Value: 2
TimeStamp: 1990-01-03T00:00Z     Value: 3
TimeStamp: 1990-01-04T00:00Z     Value: 4
TimeStamp: 1990-01-05T00:00Z     Value: 5

re-map this time-series time-reference-system to a new time-reference-system changing only granularity

note: because we never set a new start_time, the start_time will default to the epoch start time of 1970-01-01

>>> ts = ts_orig.with_trs(granularity=datetime.timedelta(days=7))
>>> ts
TimeStamp: 1989-12-28T00:00Z[UTC]     Value: 1
TimeStamp: 1989-12-28T00:00Z[UTC]     Value: 2
TimeStamp: 1989-12-28T00:00Z[UTC]     Value: 3
TimeStamp: 1990-01-04T00:00Z[UTC]     Value: 4
TimeStamp: 1990-01-04T00:00Z[UTC]     Value: 5

re-map this time-series time-reference-system to a new time-reference-system changing both start_time and granularity

>>> granularity = datetime.timedelta(days=7)
>>> start_time = datetime.datetime(1990, 1, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc)
>>> ts = ts_orig.with_trs(granularity=datetime.timedelta(days=7), start_time=start_time)
>>> ts
TimeStamp: 1990-01-01T00:00Z     Value: 1
TimeStamp: 1990-01-01T00:00Z     Value: 2
TimeStamp: 1990-01-01T00:00Z     Value: 3
TimeStamp: 1990-01-01T00:00Z     Value: 4
TimeStamp: 1990-01-01T00:00Z     Value: 5

write(start=None, end=None, inclusive=False)

create a time-series-writer given a range

Parameters

startint or datetime, optional

start of range (inclusive) (default is None)

endint or datetime, optional

end of range (inclusive) (default is None)

inclusivebool, optional

if true, will use inclusive bounds (default is False)

Returns

TimeSeriesWriter

a new time-series-writer