timeseria package

Subpackages

timeseria.models package

Submodules

timeseria.datastructures module

Base data structures as Points, Slots, and Series.

class timeseria.datastructures.Point(*args)

Bases: object

A point.

Parameters: *args (list) – the coordinates.

class timeseria.datastructures.TimePoint(*args, **kwargs)

Bases: Point

A point in the time dimension. Can be initialized using the special t and dt arguments, for epoch seconds and datetime objects, respectively.

Args:
t (float): epoch timestamp, decimals for sub-second precision. dt (datetime): a datetime object timestamp.

property t: The timestamp as epoch, with decimals for sub-second precision.

property tz: The time zone.

change_tz(tz): Change the time zone of the point, in-place.

property dt: The timestamp as datetime object.

class timeseria.datastructures.DataPoint(*args, **kwargs)

Bases: Point

A point that carries some data. Data is attached using the respective data arguments.

Parameters

*args (list) – the coordinates.
data – the data.
data_indexes (dict) – data indexes.
data_loss (float) – the data loss index, if any.

property data: The data.

property data_indexes: The data indexes.

property data_loss: The data loss index, if any. Usually computed out from resampling transformations.

data_labels()

The data labels. If data is a dictionary, then these are the dictionary keys, if data is list-like, then these are the list indexes (as strings). Other formats are not supported.

Returns: the data labels.
Return type: list

class timeseria.datastructures.DataTimePoint(*args, **kwargs)

Bases: DataPoint, TimePoint

A point that carries some data in the time dimension. Can be initialized using the special t and dt arguments, for epoch seconds and datetime objects, respectively. Data is attached using the respective data arguments.

Parameters

t (float) – epoch timestamp, decimals for sub-second precision.
dt (datetime) – a datetime object timestamp.
data – the data.
data_indexes (dict) – data indexes.
data_loss (float) – the data loss index, if any.

change_tz(tz): Change the time zone of the point, in-place.

property data: The data.

property data_indexes: The data indexes.

data_labels()

The data labels. If data is a dictionary, then these are the dictionary keys, if data is list-like, then these are the list indexes (as strings). Other formats are not supported.

Returns: the data labels.
Return type: list

property data_loss: The data loss index, if any. Usually computed out from resampling transformations.

property dt: The timestamp as datetime object.

property t: The timestamp as epoch, with decimals for sub-second precision.

property tz: The time zone.

class timeseria.datastructures.Slot(start, end=None, unit=None)

Bases: object

A slot. Can be initialized with start and end or start and unit.

Parameters

start (Point) – the slot starting point.
end (Point) – the slot ending point.
unit (Unit) – the slot unit.

property length: The slot length.

property unit: The slot unit.

class timeseria.datastructures.TimeSlot(start=None, end=None, unit=None, **kwargs)

Bases: Slot

A slot in the time dimension. Can be initialized with start and end or start and unit.

Parameters

start (TimePoint) – the slot starting time point.
end (TimePoint) – the slot ending time point.
unit (TimeUnit) – the slot time unit.

change_tz(tz): Change the time zone of the slot, in-place.

property unit: The slot time unit

property t: The slot epoch timestamp, intended as the starting point one.

property dt: The slot datetime timestamp, intended as the starting point one.

property length: The slot length.

class timeseria.datastructures.DataSlot(*args, **kwargs)

Bases: Slot

A slot that carries some data. Can be initialized with start and end or start and unit, plus the data arguments.

Parameters

start (Point) – the slot starting point.
end (Point) – the slot ending point.
unit (Unit) – the slot unit.
data – the data.
data_indexes (dict) – data indexes.
data_loss (float) – the data loss index, if any.

property data: The data.

property data_indexes: The data indexes.

property data_loss: The data loss index, if any. Usually computed from a resampling or aggregation transformation.

data_labels()

The data labels. If data is a dictionary, then these are the dictionary keys, if data is list-like, then these are the list indexes (as strings). Other formats are not supported.

Returns: the data labels.
Return type: list

property length: The slot length.

property unit: The slot unit.

class timeseria.datastructures.DataTimeSlot(*args, **kwargs)

Bases: DataSlot, TimeSlot

A slot that carries some data in the time dimension. Can be initialized with start and end or start and unit, plus the data arguments.

Parameters

start (TimePoint) – the slot starting time point.
end (TimePoint) – the slot ending time point.
unit (TimeUnit) – the slot time unit.
data – the data.
data_indexes (dict) – data indexes.
data_loss (float) – the data loss index, if any.

change_tz(tz): Change the time zone of the slot, in-place.

property data: The data.

property data_indexes: The data indexes.

data_labels()

The data labels. If data is a dictionary, then these are the dictionary keys, if data is list-like, then these are the list indexes (as strings). Other formats are not supported.

Returns: the data labels.
Return type: list

property data_loss: The data loss index, if any. Usually computed from a resampling or aggregation transformation.

property dt: The slot datetime timestamp, intended as the starting point one.

property length: The slot length.

property t: The slot epoch timestamp, intended as the starting point one.

property unit: The slot time unit

class timeseria.datastructures.Series(*args, **kwargs)

Bases: list

A list of items coming one after another, where every item is guaranteed to be of the same type and in order or succession.

The square brackets notation can be used for accessing series items, slicing the series or to filter it on a specific data label, if its elements support it:

series[3] will access the item in position #3;

series[3:5] will slice the series from item in position #3 to item in position #5 (excluded);

series['temperature'] will filter the series keeping only the temperature data, assuming that in the original series there were also other data labels (e.g. humidity).

Parameters: *args – the series items.

property item_type: The type of the items of the series.

append(item): Append an item to the series. Accepts only items of the same type of the items already present in the series (unless empty)

insert(i, x): Insert an item at a given position. The first argument is the index of the element before which to insert, so series.insert(0, x) inserts at the front of the series, and series.insert(len(series), x) is equivalent to append(x). Order or succession are enforced.

remove(x): Remove the first item from the list whose value is equal to x. It raises a ValueError if there is no such item and a NotImplementedError is the series items are in a succession as it would breake it.

pop(i=None): Remove the item at the given position in the list, and return it. If no index is specified, removes and returns the last item in the series. If items are in a succession and the index is set, a NotImplementerError is raised.

clear(): Remove all items from the series.

index(x, start=None, end=None)

Return zero-based index in the series of the item whose value is equal to x. Raises a ValueError if there is no such item.

The optional arguments start and end are interpreted as in the slice notation and are used to limit the search to a particular subsequence of the list. The returned index is computed relative to the beginning of the full sequence rather than the start argument.

copy(): Return a shallow copy of the series.

duplicate(): Return a deep copy of the series.

extend(): Disabled (use the merge instead).

count(x): Disabled (there is only one item instance by design).

sort(key=None, reverse=False): Disabled (sorting is already guaranteed).

reverse(): Disabled (reversing is not compatible with an ordering).

data_labels()

The labels of the data carried by the series items. If data is a dictionary, then these are the dictionary keys, if data is list-like, then these are the list indexes (as strings). Other formats are not supported.

Returns: the data labels.
Return type: list

rename_data_label(old_data_label, new_data_label): Rename a data label, in-place.

remove_data_label(data_label): Remove a data label, in-place.

remove_data_index(data_index): Remove a data index, in-place.

remove_data_loss(): Remove the data_loss index, in-place.

min(data_label=None)

Get the minimum data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string) – if provided, compute the value only for this data label. Defaults to None.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

max(data_label=None)

Get the maximum data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string) – if provided, compute the value only for this data label. Defaults to None.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

avg(data_label=None)

Get the average data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string, optional) – if provided, compute the value only for this data label.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

sum(data_label=None)

Sum every data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string, optional) – if provided, compute the value only for this data label.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

derivative(inplace=False, normalize=True, diffs=False)

Compute the derivative on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the derivative w.r.t to the series resolution. Defaults to True.
diffs (bool) – if to compute the differences instead of the derivative. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

integral(inplace=False, normalize=True, c=0, offset=0)

Compute the integral on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the integral w.r.t to the series resolution. Defaults to True.
c (float, dict) – the integrative constant, as a single value or as a dictionary of values, one for each data label. Defaults to zero.
offset (float, dict) – if to start the integrative process from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to zero.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

diff(inplace=False)

Compute the incremental differences on the series. Reduces the series length by one (removing the first element). A series of DataTimePoints or DataTimeSlots is required.

Parameters: inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
Returns: the computed series, or None if set to perform the operation in-place.
Return type: series or None

csum(inplace=False, offset=None)

Compute the incremental sum on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
offset (float, dict) – if to start computing the cumulative sum from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to None.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

normalize(range=[0, 1], inplace=False, source_range=None)

Normalize the data values of the series bringing them to a given range. A series of DataTimePoints or DataTimeSlots is required.

Parameters

range (list) – the normalization target range. Defaults to [0,1].
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
source_range (dict, optional) – a custom source range, by data label, to normalize with respect to.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

rescale(value, inplace=False)

Rescale the data values of the series by a given factor. A series of DataTimePoints or DataTimeSlots is required.

Parameters

value (float, dict) – the value to use as rescaling factor. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

offset(value, inplace=False)

Offset the data values of the series by a given value. A series of DataTimePoints or DataTimeSlots is required.

Parameters

value (float, dict) – the value to use as offset. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

mavg(window, inplace=False)

Compute the moving average on the series. Reduces the series length by a number of values equal to the window size. A series of DataTimePoints or DataTimeSlots is required.

Parameters

window (int) – the length of the moving average window.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

merge(series)

Merge the series with one or more other series.

Returns: the merged series.
Return type: Series

get(at_i)

Get the element of the series at a given position.

Parameters: at_i (int) – the position of the item to get.
Returns: the item in the given position or at the given time.
Return type: object

filter(*data_labels)

Filter the series keeping only the data labels provided as argument.

Parameters: *data_labels (str) – the data label(s) to filter against.

slice(from_i=None, to_i=None)

Slice the series between the given positions. A series of DataPoints or DataSlots is required.

Parameters

from_i (int) – the slicing start position. Defaults to None.
to_i (int) – the slicing end position. Defaults to None.

Returns

the sliced series.

Return type

Series

select(query)

Select one or more items of the series given an SQL-like query. This is a preliminary functionality supporting only the equality. A series of DataPoints or DataSlots is required.

Parameters: query (str) – the query.
Returns: the selected items of the series.
Return type: list

aggregate(unit, *args, **kwargs)

Aggregate the series in slots. A series of DataPoints or DataSlots is required.

Parameters: unit (Unit) – the target slot unit (i.e. length).
Returns: the aggregated series.
Return type: Series

resample(unit, *args, **kwargs)

Aggregate the series in slots. A series of DataPoints or DataSlots is required.

Parameters: unit (Unit) – the unit (i.e. length) of the target sampling interval.
Returns: the resampled series.
Return type: Series

summary(limit=10, newlines=False)

A summary of the series and its elements, limited to 10 items by default.

Parameters

limit (int) – the limit of elements to print, by default 10.
newlines (bool) – if to include the newline characters or not.

Returns

the summary.

Return type

str

inspect(limit=10)

Print a summary of the series and its elements, limited to 10 items by default.

Parameters: limit (int) – the limit of elements to print, by default 10.

contents()

Get all the items of the series as a list.

Returns: all the items of the series.
Return type: list

head(n=5)

Get the first n items of the series as a list, 5 by default.

Parameters: n – the number of first elements to return.
Returns: the required first n items of the series.
Return type: list

tail(n=5)

Get the last n items of the series as a list, 5 by default.

Parameters: n – the number of last elements to return .
Returns: the required last n items of the series.
Return type: list

class timeseria.datastructures.TimeSeries(*args, **kwargs)

Bases: Series

A list of items coming one after another over time, where every item is guaranteed to be of the same type and in order or succession.

Time series accept only items of type DataTimePoint and DataTimeSlot (or TimePoint and TimeSlot which are useful in some circumstances), but can be created using some shortcuts, for example:

providing a Pandas Dataframe with a time-based index;

providing a list of dictionaries in the following forms, plus an optional slot_unit argument if creating a slot series (e.g. slot_unit='1D'):

{60: 4, 120: 6, ... }

{dt(1970,1,1): 4, dt(1970,1,2): 6, ... }

providing a string with a path to a CSV file, which will be read and parsed using a timeseria.storages.CSVStorage storage object (in this case all the key-value arguments will be forwarded to the storage).

The square brackets notation can be used for accessing series items, slicing the series or to filter it on a specific data label (if the elements support it), as outlined below.

series[3] will access the item in position #3;

series[1446073200.7] will access the item for the epoch timestamp corresponding to the (floating point) number provided in the square brackets;

series[dt(2015,10,25,6,19,0)] will access the item for the corresponding datetime timestamp.

The same three options can be used for slicing, and filtering a series on a data label can also be achieved using the square bracket notation, by providing the data label on which to filter the series: series['temperature'] will filter the time series keeping only temperature data, assuming that in the original series there were also other data labels (e.g. humidity).

For more options for accessing and selecting series items and for slicing or filtering series, see the corresponding methods: select(), slice() and filter().

Parameters: *args – the time series items, or the right object for an alternative init method as described above.

append(item): Append an item to the time series. Accepts only items of type DataTimePoint and DataTimeSlot (or TimePoint and TimeSlot, which are useful in some particular circumstances) and in any case of the same type of the items already present in the time series, unless empty.

property tz: The time zone of the time series.

change_tz(tz)

Change the time zone of the time series, in-place.

Parameters: tzinfo (str or) – the time zone.

as_tz(tz)

Get a copy of the time series on a new time zone.

Parameters: tzinfo (str or) – the time zone.
Returns: the time series on the new time zone.
Return type: TimeSeries

property resolution

The (temporal) resolution of the time series.

Returns a timeseria.units.TimeUnit object, unless:

the resolution is not defined (returns None), either because the time series is empty or because it is a point time series with only one point; or

the resolution is variable (returns the string variable), only possible for point time series, if its points are not equally spaced, for example because of data losses or uneven observations.

If the time series has a variable resolution, the guess_resolution() method can provide an estimate. If the time series is a slot time series, then the resolutions is just the unit of its slots.

guess_resolution(confidence=False)

Guess the (temporal) resolution of the time series.

Parameters: confidence (bool) – if to return, together with the guessed resolution, also its confidence (in a 0-1 range).
Returns: the guessed temporal resolution, as time unit.
Return type: TimeUnit

classmethod load(file_name)

Load a series from a file, in Timeseria CSV format.

Parameters: file_name (str) – the file name to load.

save(file_name, overwrite=False, **kwargs)

Save the time series as a file, in Timeseria CSV format.

Parameters

file_name (str) – the file name to write.
overwrite (bool) – if to overwrite the file if already existent. Defaults to False.

classmethod from_dict(dictionary, slot_unit=None)

Create a time series from a dictionary.

Parameters: dict (bool) – the dictionary containing the data, where the keys are the timestamps.
Returns: the created time series.
Return type: TimeSeries

to_dict()

Convert the time series to a dictionary.

Returns: the time series as a dictrionary.
Return type: dict

classmethod from_json(string, slot_unit=None)

Create a time series from a JSON string.

Parameters: string (str) – the string containing the JSOn data, where the keys are the timestamps.
Returns: the created time series.
Return type: TimeSeries

to_json()

Convert the time series to a JSON string.

Returns: the time series as a JSON string.
Return type: string

classmethod from_csv(file_name, *args, **kwargs)

Create a time series from a CSV file. For the options see the storages module.

Returns: the created time series.
Return type: TimeSeries

to_csv(file_name, overwrite=False, **kwargs)

Store the time series as a CSV file. For the options see the storages module.

Parameters

file_name (str) – the file name to write.
overwrite (bool) – if to overwrite the file if already existent. Defaults to False.

classmethod from_df(df, item_type='auto')

Create a time series from a Pandas data frame.

Parameters

df (DataFrame) – the Pandas data frame.
item_type (DataTimePoint or DataTimeSlot or str) – the type of the items of the newly created time series. Defaults to ‘auto’.

Returns

the created time series.

Return type

TimeSeries

to_df()

Convert the time series as a Pandas data frame.

Returns: the Pandas data frame.
Return type: DataFrame

get(at_i=None, at_t=None, at_dt=None)

Get the element of the series at a given position or at a given time.

Parameters

at_i (int) – the position of the item to get. Defaults to None.
at_t (bool) – the time (as epoch seconds) of the item to get. Defaults to None.
at_dt (bool) – the time (as datetime object) of the item to get. Defaults to None.

Returns

the item in the given position or at the given time.

Return type

object

slice(from_i=None, to_i=None, from_t=None, to_t=None, from_dt=None, to_dt=None)

Slice the series between the given positions or times. A series of DataPoints or DataSlots is required.

Parameters

from_i (int) – the slicing start position. Defaults to None.
to_i (int) – the slicing end position. Defaults to None.
from_t (bool) – the slicing start time (as epoch seconds). Defaults to None.
to_t (bool) – the slicing end time (as epoch seconds). Defaults to None.
from_dt (bool) – the slicing start time (as datetime object). Defaults to None.
to_dt (bool) – the slicing end time (as datetime object). Defaults to None.

Returns

the sliced series.

Return type

Series

view(from_i=None, to_i=None)

Get a view of the time series.

Parameters

from_i (int) – the view start position. Defaults to None.
to_i (int) – the view end position. Defaults to None.

Returns

the time series view.

Return type

TimeSeriesView

plot(engine='dg', *args, **kwargs): Plot the time series. The default plotting engine is Dygraphs (engine='dg'), limited support for Matplotplib (engine='mp') is also available. For plotting options for Dygraphs, see dygraphs_plot(), while for plotting options for Matplotlib, see matplotlib_plot().

aggregate(unit, *args, **kwargs)

Aggregate the series in slots. A series of DataPoints or DataSlots is required.

Parameters: unit (Unit) – the target slot unit (i.e. length).
Returns: the aggregated series.
Return type: Series

avg(data_label=None)

Get the average data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string, optional) – if provided, compute the value only for this data label.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

clear(): Remove all items from the series.

contents()

Get all the items of the series as a list.

Returns: all the items of the series.
Return type: list

copy(): Return a shallow copy of the series.

count(x): Disabled (there is only one item instance by design).

csum(inplace=False, offset=None)

Compute the incremental sum on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
offset (float, dict) – if to start computing the cumulative sum from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to None.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

data_labels()

The labels of the data carried by the series items. If data is a dictionary, then these are the dictionary keys, if data is list-like, then these are the list indexes (as strings). Other formats are not supported.

Returns: the data labels.
Return type: list

derivative(inplace=False, normalize=True, diffs=False)

Compute the derivative on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the derivative w.r.t to the series resolution. Defaults to True.
diffs (bool) – if to compute the differences instead of the derivative. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

diff(inplace=False)

Compute the incremental differences on the series. Reduces the series length by one (removing the first element). A series of DataTimePoints or DataTimeSlots is required.

Parameters: inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
Returns: the computed series, or None if set to perform the operation in-place.
Return type: series or None

duplicate(): Return a deep copy of the series.

extend(): Disabled (use the merge instead).

filter(*data_labels)

Filter the series keeping only the data labels provided as argument.

Parameters: *data_labels (str) – the data label(s) to filter against.

head(n=5)

Get the first n items of the series as a list, 5 by default.

Parameters: n – the number of first elements to return.
Returns: the required first n items of the series.
Return type: list

index(x, start=None, end=None)

Return zero-based index in the series of the item whose value is equal to x. Raises a ValueError if there is no such item.

The optional arguments start and end are interpreted as in the slice notation and are used to limit the search to a particular subsequence of the list. The returned index is computed relative to the beginning of the full sequence rather than the start argument.

insert(i, x): Insert an item at a given position. The first argument is the index of the element before which to insert, so series.insert(0, x) inserts at the front of the series, and series.insert(len(series), x) is equivalent to append(x). Order or succession are enforced.

inspect(limit=10)

Print a summary of the series and its elements, limited to 10 items by default.

Parameters: limit (int) – the limit of elements to print, by default 10.

integral(inplace=False, normalize=True, c=0, offset=0)

Compute the integral on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the integral w.r.t to the series resolution. Defaults to True.
c (float, dict) – the integrative constant, as a single value or as a dictionary of values, one for each data label. Defaults to zero.
offset (float, dict) – if to start the integrative process from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to zero.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

property item_type: The type of the items of the series.

mavg(window, inplace=False)

Compute the moving average on the series. Reduces the series length by a number of values equal to the window size. A series of DataTimePoints or DataTimeSlots is required.

Parameters

window (int) – the length of the moving average window.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

max(data_label=None)

Get the maximum data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string) – if provided, compute the value only for this data label. Defaults to None.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

merge(series)

Merge the series with one or more other series.

Returns: the merged series.
Return type: Series

min(data_label=None)

Get the minimum data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string) – if provided, compute the value only for this data label. Defaults to None.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

normalize(range=[0, 1], inplace=False, source_range=None)

Normalize the data values of the series bringing them to a given range. A series of DataTimePoints or DataTimeSlots is required.

Parameters

range (list) – the normalization target range. Defaults to [0,1].
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
source_range (dict, optional) – a custom source range, by data label, to normalize with respect to.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

offset(value, inplace=False)

Offset the data values of the series by a given value. A series of DataTimePoints or DataTimeSlots is required.

Parameters

value (float, dict) – the value to use as offset. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

pop(i=None): Remove the item at the given position in the list, and return it. If no index is specified, removes and returns the last item in the series. If items are in a succession and the index is set, a NotImplementerError is raised.

remove(x): Remove the first item from the list whose value is equal to x. It raises a ValueError if there is no such item and a NotImplementedError is the series items are in a succession as it would breake it.

remove_data_index(data_index): Remove a data index, in-place.

remove_data_label(data_label): Remove a data label, in-place.

remove_data_loss(): Remove the data_loss index, in-place.

rename_data_label(old_data_label, new_data_label): Rename a data label, in-place.

resample(unit, *args, **kwargs)

Aggregate the series in slots. A series of DataPoints or DataSlots is required.

Parameters: unit (Unit) – the unit (i.e. length) of the target sampling interval.
Returns: the resampled series.
Return type: Series

rescale(value, inplace=False)

Rescale the data values of the series by a given factor. A series of DataTimePoints or DataTimeSlots is required.

Parameters

value (float, dict) – the value to use as rescaling factor. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

reverse(): Disabled (reversing is not compatible with an ordering).

select(query)

Select one or more items of the series given an SQL-like query. This is a preliminary functionality supporting only the equality. A series of DataPoints or DataSlots is required.

Parameters: query (str) – the query.
Returns: the selected items of the series.
Return type: list

sort(key=None, reverse=False): Disabled (sorting is already guaranteed).

sum(data_label=None)

Sum every data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string, optional) – if provided, compute the value only for this data label.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

summary(limit=10, newlines=False)

A summary of the series and its elements, limited to 10 items by default.

Parameters

limit (int) – the limit of elements to print, by default 10.
newlines (bool) – if to include the newline characters or not.

Returns

the summary.

Return type

str

tail(n=5)

Get the last n items of the series as a list, 5 by default.

Parameters: n – the number of last elements to return .
Returns: the required last n items of the series.
Return type: list

class timeseria.datastructures.TimeSeriesView(*items, series=None, from_i=None, to_i=None, **kwargs)

Bases: TimeSeries

A time series created as a view of another one.

Parameters

series (TimeSeries) – the original time series.
from_i (int) – the view start position. Defaults to None.
to_i (int) – the view end position. Defaults to None.

property item_type: The type of the items of the series.

property resolution

The (temporal) resolution of the time series.

Returns a timeseria.units.TimeUnit object, unless:

the resolution is not defined (returns None), either because the time series is empty or because it is a point time series with only one point; or

the resolution is variable (returns the string variable), only possible for point time series, if its points are not equally spaced, for example because of data losses or uneven observations.

If the time series has a variable resolution, the guess_resolution() method can provide an estimate. If the time series is a slot time series, then the resolutions is just the unit of its slots.

aggregate(unit, *args, **kwargs)

Aggregate the series in slots. A series of DataPoints or DataSlots is required.

Parameters: unit (Unit) – the target slot unit (i.e. length).
Returns: the aggregated series.
Return type: Series

append(item): Append an item to the time series. Accepts only items of type DataTimePoint and DataTimeSlot (or TimePoint and TimeSlot, which are useful in some particular circumstances) and in any case of the same type of the items already present in the time series, unless empty.

as_tz(tz)

Get a copy of the time series on a new time zone.

Parameters: tzinfo (str or) – the time zone.
Returns: the time series on the new time zone.
Return type: TimeSeries

avg(data_label=None)

Get the average data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string, optional) – if provided, compute the value only for this data label.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

change_tz(tz)

Change the time zone of the time series, in-place.

Parameters: tzinfo (str or) – the time zone.

clear(): Remove all items from the series.

contents()

Get all the items of the series as a list.

Returns: all the items of the series.
Return type: list

copy(): Return a shallow copy of the series.

count(x): Disabled (there is only one item instance by design).

csum(inplace=False, offset=None)

Compute the incremental sum on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
offset (float, dict) – if to start computing the cumulative sum from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to None.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

data_labels()

The labels of the data carried by the series items. If data is a dictionary, then these are the dictionary keys, if data is list-like, then these are the list indexes (as strings). Other formats are not supported.

Returns: the data labels.
Return type: list

derivative(inplace=False, normalize=True, diffs=False)

Compute the derivative on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the derivative w.r.t to the series resolution. Defaults to True.
diffs (bool) – if to compute the differences instead of the derivative. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

diff(inplace=False)

Compute the incremental differences on the series. Reduces the series length by one (removing the first element). A series of DataTimePoints or DataTimeSlots is required.

Parameters: inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
Returns: the computed series, or None if set to perform the operation in-place.
Return type: series or None

extend(): Disabled (use the merge instead).

filter(*data_labels)

Filter the series keeping only the data labels provided as argument.

Parameters: *data_labels (str) – the data label(s) to filter against.

classmethod from_csv(file_name, *args, **kwargs)

Create a time series from a CSV file. For the options see the storages module.

Returns: the created time series.
Return type: TimeSeries

classmethod from_df(df, item_type='auto')

Create a time series from a Pandas data frame.

Parameters

df (DataFrame) – the Pandas data frame.
item_type (DataTimePoint or DataTimeSlot or str) – the type of the items of the newly created time series. Defaults to ‘auto’.

Returns

the created time series.

Return type

TimeSeries

classmethod from_dict(dictionary, slot_unit=None)

Create a time series from a dictionary.

Parameters: dict (bool) – the dictionary containing the data, where the keys are the timestamps.
Returns: the created time series.
Return type: TimeSeries

classmethod from_json(string, slot_unit=None)

Create a time series from a JSON string.

Parameters: string (str) – the string containing the JSOn data, where the keys are the timestamps.
Returns: the created time series.
Return type: TimeSeries

get(at_i=None, at_t=None, at_dt=None)

Get the element of the series at a given position or at a given time.

Parameters

at_i (int) – the position of the item to get. Defaults to None.
at_t (bool) – the time (as epoch seconds) of the item to get. Defaults to None.
at_dt (bool) – the time (as datetime object) of the item to get. Defaults to None.

Returns

the item in the given position or at the given time.

Return type

object

guess_resolution(confidence=False)

Guess the (temporal) resolution of the time series.

Parameters: confidence (bool) – if to return, together with the guessed resolution, also its confidence (in a 0-1 range).
Returns: the guessed temporal resolution, as time unit.
Return type: TimeUnit

head(n=5)

Get the first n items of the series as a list, 5 by default.

Parameters: n – the number of first elements to return.
Returns: the required first n items of the series.
Return type: list

index(x, start=None, end=None)

Return zero-based index in the series of the item whose value is equal to x. Raises a ValueError if there is no such item.

The optional arguments start and end are interpreted as in the slice notation and are used to limit the search to a particular subsequence of the list. The returned index is computed relative to the beginning of the full sequence rather than the start argument.

insert(i, x): Insert an item at a given position. The first argument is the index of the element before which to insert, so series.insert(0, x) inserts at the front of the series, and series.insert(len(series), x) is equivalent to append(x). Order or succession are enforced.

inspect(limit=10)

Print a summary of the series and its elements, limited to 10 items by default.

Parameters: limit (int) – the limit of elements to print, by default 10.

integral(inplace=False, normalize=True, c=0, offset=0)

Compute the integral on the series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the integral w.r.t to the series resolution. Defaults to True.
c (float, dict) – the integrative constant, as a single value or as a dictionary of values, one for each data label. Defaults to zero.
offset (float, dict) – if to start the integrative process from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to zero.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

classmethod load(file_name)

Load a series from a file, in Timeseria CSV format.

Parameters: file_name (str) – the file name to load.

mavg(window, inplace=False)

Compute the moving average on the series. Reduces the series length by a number of values equal to the window size. A series of DataTimePoints or DataTimeSlots is required.

Parameters

window (int) – the length of the moving average window.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

max(data_label=None)

Get the maximum data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string) – if provided, compute the value only for this data label. Defaults to None.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

merge(series)

Merge the series with one or more other series.

Returns: the merged series.
Return type: Series

min(data_label=None)

Get the minimum data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string) – if provided, compute the value only for this data label. Defaults to None.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

normalize(range=[0, 1], inplace=False, source_range=None)

Normalize the data values of the series bringing them to a given range. A series of DataTimePoints or DataTimeSlots is required.

Parameters

range (list) – the normalization target range. Defaults to [0,1].
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
source_range (dict, optional) – a custom source range, by data label, to normalize with respect to.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

offset(value, inplace=False)

Offset the data values of the series by a given value. A series of DataTimePoints or DataTimeSlots is required.

Parameters

value (float, dict) – the value to use as offset. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

plot(engine='dg', *args, **kwargs): Plot the time series. The default plotting engine is Dygraphs (engine='dg'), limited support for Matplotplib (engine='mp') is also available. For plotting options for Dygraphs, see dygraphs_plot(), while for plotting options for Matplotlib, see matplotlib_plot().

pop(i=None): Remove the item at the given position in the list, and return it. If no index is specified, removes and returns the last item in the series. If items are in a succession and the index is set, a NotImplementerError is raised.

remove(x): Remove the first item from the list whose value is equal to x. It raises a ValueError if there is no such item and a NotImplementedError is the series items are in a succession as it would breake it.

remove_data_index(data_index): Remove a data index, in-place.

remove_data_label(data_label): Remove a data label, in-place.

remove_data_loss(): Remove the data_loss index, in-place.

rename_data_label(old_data_label, new_data_label): Rename a data label, in-place.

resample(unit, *args, **kwargs)

Aggregate the series in slots. A series of DataPoints or DataSlots is required.

Parameters: unit (Unit) – the unit (i.e. length) of the target sampling interval.
Returns: the resampled series.
Return type: Series

rescale(value, inplace=False)

Rescale the data values of the series by a given factor. A series of DataTimePoints or DataTimeSlots is required.

Parameters

value (float, dict) – the value to use as rescaling factor. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

reverse(): Disabled (reversing is not compatible with an ordering).

save(file_name, overwrite=False, **kwargs)

Save the time series as a file, in Timeseria CSV format.

Parameters

file_name (str) – the file name to write.
overwrite (bool) – if to overwrite the file if already existent. Defaults to False.

select(query)

Select one or more items of the series given an SQL-like query. This is a preliminary functionality supporting only the equality. A series of DataPoints or DataSlots is required.

Parameters: query (str) – the query.
Returns: the selected items of the series.
Return type: list

slice(from_i=None, to_i=None, from_t=None, to_t=None, from_dt=None, to_dt=None)

Slice the series between the given positions or times. A series of DataPoints or DataSlots is required.

Parameters

from_i (int) – the slicing start position. Defaults to None.
to_i (int) – the slicing end position. Defaults to None.
from_t (bool) – the slicing start time (as epoch seconds). Defaults to None.
to_t (bool) – the slicing end time (as epoch seconds). Defaults to None.
from_dt (bool) – the slicing start time (as datetime object). Defaults to None.
to_dt (bool) – the slicing end time (as datetime object). Defaults to None.

Returns

the sliced series.

Return type

Series

sort(key=None, reverse=False): Disabled (sorting is already guaranteed).

sum(data_label=None)

Sum every data value(s) of the series. A series of DataPoints or DataSlots is required.

Parameters: data_label (string, optional) – if provided, compute the value only for this data label.
Returns: the computed values for each data label, or a specific value if providing the data_label argument.
Return type: dict or object

summary(limit=10, newlines=False)

A summary of the series and its elements, limited to 10 items by default.

Parameters

limit (int) – the limit of elements to print, by default 10.
newlines (bool) – if to include the newline characters or not.

Returns

the summary.

Return type

str

tail(n=5)

Get the last n items of the series as a list, 5 by default.

Parameters: n – the number of last elements to return .
Returns: the required last n items of the series.
Return type: list

to_csv(file_name, overwrite=False, **kwargs)

Store the time series as a CSV file. For the options see the storages module.

Parameters

file_name (str) – the file name to write.
overwrite (bool) – if to overwrite the file if already existent. Defaults to False.

to_df()

Convert the time series as a Pandas data frame.

Returns: the Pandas data frame.
Return type: DataFrame

to_dict()

Convert the time series to a dictionary.

Returns: the time series as a dictrionary.
Return type: dict

to_json()

Convert the time series to a JSON string.

Returns: the time series as a JSON string.
Return type: string

property tz: The time zone of the time series.

view(from_i=None, to_i=None)

Get a view of the time series.

Parameters

from_i (int) – the view start position. Defaults to None.
to_i (int) – the view end position. Defaults to None.

Returns

the time series view.

Return type

TimeSeriesView

materialize()

Materialize the time series view.

Returns: the time series corresponding to the materialized view.
Return type: TimeSeries

duplicate(): Return a deep copy of the series.

timeseria.exceptions module

Exceptions.

exception timeseria.exceptions.ConsistencyException

Bases: Exception

Rasied when the internal consistency is broken.

add_note(): Exception.add_note(note) – add a note to the exception

exception timeseria.exceptions.NotFittedError

Bases: Exception

Raised when trying to save, apply or evaluate a model that requires fitting first.

add_note(): Exception.add_note(note) – add a note to the exception

exception timeseria.exceptions.AlreadyFittedError

Bases: Exception

Raised when trying to fit a model that is already fitted (instead of using the fit update method, if available).

add_note(): Exception.add_note(note) – add a note to the exception

exception timeseria.exceptions.NonContiguityError

Bases: Exception

Raised when the model only supports being applied on data contiguous with the fit data and it is not.

add_note(): Exception.add_note(note) – add a note to the exception

exception timeseria.exceptions.NoDataException

Bases: Exception

Raised if a storage get() function finds no data at all.

add_note(): Exception.add_note(note) – add a note to the exception

exception timeseria.exceptions.FloatConversionError

Bases: Exception

Raised to group the various exceptions that can lead to the impossibility of converting a value to a floating point.

add_note(): Exception.add_note(note) – add a note to the exception

exception timeseria.exceptions.NotEnoughDataError

Bases: Exception

Raised in context when there is not enough data to perform the required operation

add_note(): Exception.add_note(note) – add a note to the exception

timeseria.interpolators module

Interpolators.

class timeseria.interpolators.Interpolator(series)

Bases: object

A generic interpolator.

Parameters: series (TimeSeries) – the series on which to initialize the interpolator.

evaluate(at, prev_i, next_i)

Evaluate the interpolator (compute the value).

Parameters

at (float) – the time value (as epoch seconds) at which to evaluate the interpolator.
prev_i (int) – the previous position of the item in the series.
next_i (int) – the next position of the item in the series.

class timeseria.interpolators.LinearInterpolator(series)

Bases: Interpolator

A linear interpolator.

Parameters: series (TimeSeries) – the series on which to initialize the interpolator.

evaluate(at, prev_i=None, next_i=None)

Evaluate the interpolator (compute the value).

Parameters

at (float) – the time value (as epoch seconds) at which to evaluate the interpolator.
prev_i (int) – the previous position of the item in the series.
next_i (int) – the next position of the item in the series.

class timeseria.interpolators.UniformInterpolator(series)

Bases: Interpolator

A unform interpolator.

Parameters: series (TimeSeries) – the series on which to initialize the interpolator.

evaluate(at, prev_i=None, next_i=None)

Evaluate the interpolator (compute the value).

Parameters

at (float) – the time value (as epoch seconds) at which to evaluate the interpolator.
prev_i (int) – the previous position of the item in the series.
next_i (int) – the next position of the item in the series.

timeseria.operations module

Operations on the series.

class timeseria.operations.Operation

Bases: object

A generic series operation. Can return any data type, as a series, a scalar, a list of items, etc.

class timeseria.operations.Max

Bases: Operation

Get the maximum data value(s) of a series. A series of DataPoints or DataSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
data_label (string) – if provided, compute the value only for this data label. Defaults to None.

Returns

the computed values for each data label, or a specific value if providing the data_label argument.

Return type

dict or object

class timeseria.operations.Min

Bases: Operation

Get the minimum data value(s) of a series. A series of DataPoints or DataSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
data_label (string) – if provided, compute the value only for this data label. Defaults to None.

Returns

the computed values for each data label, or a specific value if providing the data_label argument.

Return type

dict or object

class timeseria.operations.Avg

Bases: Operation

Get the average data value(s) of a series. A series of DataPoints or DataSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
data_label (string, optional) – if provided, compute the value only for this data label.

Returns

the computed values for each data label, or a specific value if providing the data_label argument.

Return type

dict or object

class timeseria.operations.Sum

Bases: Operation

Sum every data value(s) of a series. A series of DataPoints or DataSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
data_label (string, optional) – if provided, compute the value only for this data label.

Returns

the computed values for each data label, or a specific value if providing the data_label argument.

Return type

dict or object

class timeseria.operations.Derivative

Bases: Operation

Compute the derivative on a series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the derivative w.r.t to the series resolution. Defaults to True.
diffs (bool) – if to compute the differences instead of the derivative. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.Integral

Bases: Operation

Compute the integral on a series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
normalize (bool) – if to normalize the integral w.r.t to the series resolution. Defaults to True.
c (float, dict) – the integrative constant, as a single value or as a dictionary of values, one for each data label. Defaults to zero.
offset (float, dict) – if to start the integrative process from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to zero.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.Diff

Bases: Derivative

Compute the incremental differences on a series. Reduces the series length by one (removing the first element). A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.CSum

Bases: Integral

Compute the incremental sum on a series. A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
offset (float, dict) – if to start computing the cumulative sum from a specific offset. Can be provided as a single value or as a dictionary of values, one for each data label. Defaults to None.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.Normalize

Bases: Operation

Normalize the data values of a series bringing them to a given range. A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
range (list) – the normalization target range. Defaults to [0,1].
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.
source_range (dict, optional) – a custom source range, by data label, to normalize with respect to.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.Rescale

Bases: Operation

Rescale the data values of a series by a given factor. A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
value (float, dict) – the value to use as rescaling factor. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.Offset

Bases: Operation

Offset the data values of a series by a given value. A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
value (float, dict) – the value to use as offset. Can be provided as a single value or as a dictionary of values, one for each data label.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.MAvg

Bases: Operation

Compute the moving average on a series. Reduces the series length by a number of values equal to the window size. A series of DataTimePoints or DataTimeSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
window (int) – the length of the moving average window.
inplace (bool) – if to perform the operation in-place on the series. Defaults to False.

Returns

the computed series, or None if set to perform the operation in-place.

Return type

series or None

class timeseria.operations.Filter

Bases: Operation

Filter a series keeping only the data labels provided as argument.

Parameters

series (Series) – the series on which to perform the operation.
*data_labels (str) – the data label(s) to filter against.

class timeseria.operations.Slice

Bases: Operation

Slice a series between the given positions or times. A series of DataPoints or DataSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
from_i (int) – the slicing start position. Defaults to None.
to_i (int) – the slicing end position. Defaults to None.
from_t (bool) – the slicing start time (as epoch seconds). Defaults to None.
to_t (bool) – the slicing end time (as epoch seconds). Defaults to None.
from_dt (bool) – the slicing start time (as datetime object). Defaults to None.
to_dt (bool) – the slicing end time (as datetime object). Defaults to None.

Returns

the sliced series.

Return type

Series

class timeseria.operations.Merge

Bases: Operation

Merge the series given as argument.

Returns: the merged series.
Return type: Series

class timeseria.operations.Get

Bases: Operation

Get the element of a series at a given position or at a given time.

Parameters

series (Series) – the series on which to perform the operation.
at_i (int) – the position of the item to get. Defaults to None.
at_t (bool) – the time (as epoch seconds) of the item to get. Defaults to None.
at_dt (bool) – the time (as datetime object) of the item to get. Defaults to None.

Returns

the item in the given position or at the given time.

Return type

object

class timeseria.operations.Select

Bases: Operation

Select one or more items of the series given an SQL-like query. This is a preliminary functionality supporting only the equality. A series of DataPoints or DataSlots is required.

Parameters

series (Series) – the series on which to perform the operation.
query (str) – the query.

Returns

the selected items of the series.

Return type

list

timeseria.plots module

Plotting engines.

timeseria.plots.dygraphs_plot(series, data_labels='all', data_indexes='all', aggregate=None, aggregate_by=None, full_precision=False, color=None, data_label_colors='auto', data_index_colors='auto', height=None, image=False, image_resolution='auto', html=False, save_to=None, mini_plot='auto', value_range='auto', minimal_legend=False, title=None, mark=None, mark_title=None, mark_color='auto', probabilistic='auto', probability_interval=[0.05, 0.95], legacy='auto', force_local_chromium=False)

Plot a time series using Dygraphs interactive plots.

Parameters

series (TimeSeries) – the time series to plot.
data_labels (list) – a list of data_labels to plot. By default set to all the data labels of the series.
data_indexes (list) – a list of data_indexes as the data_loss, data_reconstructed etc. to plot. By default set to all the data indexes of the series. To disable plotting data indexes entirely, use None or an empty list.
aggregate (bool) – if to aggregate the time series, in order to speed up plotting. By default, above 10000 data points the time series starts to get aggregated by a factor of ten for each order of magnitude.
aggregate_by (int) – a custom aggregation factor.
full_precision (bool) – if to use (nearly) full precision using 6 significant figures instead of the automatic rounding. Defaulted to false.
color (str) – the (HTML) color of the time series in the plot (for univariate time series).
data_label_colors (list,dict) – the (HTML) colors of the time series in the plot. If provided as list, mapping follows the ordering of the data labels, while if provided as a dictionary then the mapping can be explicit (as {“data label”: “color”}).
data_index_colors (list,dict) – the (HTML) colors of the time series data indexes in the plot. If provided as list, mapping follows the ordering of the data labels, while if provided as a dictionary then the mapping can be explicit (as {“data label”: “color”}).
height (int) – force a plot height, in the time series data units.
image (bool) – if to generate an image rendering of the plot instead of the default interactive one. To generate the image rendering, a headless Chromium web browser is downloaded on the fly in order to render the plot as a PNG image.
image_resolution (str) – the image resolution, if generating an image rendering of the plot. Automatically set between 1280x380 and 1024x400, depending on the time series legend and title.
html (bool) – if to return the HTML code for the plot instead of generating an interactive or image one. Useful for embedding it in a website or for generating multi-plot HTML pages.
save_to (str) – a file name (including its path) where to save the plot. If the plot is generated as interactive, then it is saved as a self-consistent HTML page which can be opened in a web browser. If the plot is generated as an image, then it is saved in PNG format.
mini_plot (bool) – if to include the range selector mini plot. Always automatically included unless saving the plot in image format.
value_range (list) – a value range for the y axes to force the plot to stick with, in the form [min, max].
minimal_legend (bool) – if to strip down the information in the legend to the very minimum.
title (str) – a title for the plot.
mark (str) – a mark, to be used for highlighting a portion of the plot. Required to be formatted as a list or tuple with two elements, the first from where the mark has to start and the second where it has to end.
mark_title (str) – a tile for the mark, to be displayed in the legend.
mark_color (str) – a color for the mark, defaults to light yellow.
probabilistic (bool, str) – if to enable the probabilistic support in the plots. Defaults to ‘auto’.
probability_interval (list) – the probability interval lower and upper bounds. Defaults to [0.05,0.95].
legacy (bool) – if to enable legacy mode (required for Jupyter Notebook < 7, never required for Jupyter Lab).
force_local_chromium (bool) – if to force using a local Chromium via Pyppeteer instead of looking for a system Chrome/Chromium. Defaults to False.

timeseria.plots.matplotlib_plot(series)

Plot a series using Matplotlib.

Parameters: series (Series) – the series to plot.

timeseria.storages module

Data storages, as the CSV file storage.

class timeseria.storages.Storage

Bases: object

The base storage class. Can be implemented to store one or more series. If storing more than one, then the id of which series to load or store must be provided in the get() and put() methods.

get(id=None, start=None, end=None, *args, **kwargs)

put(series, id=None, *args, **kwargs)

class timeseria.storages.CSVFileStorage(filename, timestamp_column='auto', timestamp_format='auto', time_column=None, time_format=None, date_column=None, date_format=None, tz='UTC', data_labels='all', data_type='auto', series_type='auto', sort=False, separator=',', newline='\n', comment_chars=['#', ';'], encoding='auto', skip_errors=False, silence_errors=False)

Bases: Storage

A CSV file storage. Supports both point and slot time series.

The file encoding, the series type and the timestamp columns are all auto-detect with an heuristic approach by default, and asked to be set manually only if the heuristics fails. In particular, whether to create point or slot series is based on the sampling interval automatically detected: if this is above 24 hours, then slots are used.

The header with the column labels is optional, and if not present the column numbers are used as labels. Comments in the CSV file are supported Comments in the CSV file only as full-line comments, where the line starts with one of the characters listed as comment character (# and ; by default).

The timestamp_format, date_format and time_format arguments can be set using Python strptime format codes (https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes), but the timestamp_format also supports two special formats:

epoch: the epoch timestamp, intended as the number of seconds from the 1st January 1970 UTC with decimals for sub-second precision.

iso8601: the ISO 8601 timestamp format (see https://www.w3.org/TR/NOTE-datetime)

Data can be simply comma-separated (or using a custom separator) as well as single or double quoted, check out the RFC4180 (https://datatracker.ietf.org/doc/html/rfc4180) for more details on the CSV file format specification.

Parameters

filename – the file name (including its path).
timestamp_column – the column label to be used as timestamp. Either use this or the time_column and/or date_column parameters.
timestamp_format – the timestamp column format.
time_column – the column label to be used as the time part of the timestamp.
time_format – the time column format.
date_column – the column label to be used as the date part of the timestamp.
date_format – the date column format.
tz – the timezone on which to create the time series on. If the timestamps in the file are naive, then they are assumed on such timezone. If they are instead offset-aware, including UTC, then they are just moved on the given timezone.
data_labels – the column labels to be used as data by default. Excpected as a list of strings or list of integers, in which case are treated as column numbers.
data_type – the data type (list or dict), set automatically by default.
series_type – the default type of the series, if points or slots. Set automatically by default.
sort – if to sort the data before creating the series.
separator – the separator for the records (fields), , by default.
newline – the newline character, \n by default.
comment_chars – the characters used to mark a comment line. Defaulted to # and ;.
encoding – the encoding of the file, set automatically by default.
skip_errors – if to skip errors or raise an exception.
silence_errors – if to completely silence errors when skipping them or not.

get(id=None, start=None, end=None, limit=None, filter_data_labels=[], force_tz=None, force_points=False, force_slots=False, force_slot_unit=None)

Load the time series from the CSV file.

Parameters

id – Not implemented for this storage.
start – Not implemented for this storage.
end – Not implemented for this storage.
limit – a row number limit.
filter_data_labels – get only specific data labels.
force_tz – force a specific timezone.
force_points – force generating points.
force_slots – force generating slots.
force_slot_unit – set the unit of the slots.

Returns

the time series loaded from the CSV file.

Return type

TimeSeries

put(series, id=None, overwrite=False)

Store the time series in the CSV file.

Parameters

id – Not implemented for this storage.
overwrite – if the destination file can be overwritten.

timeseria.time module

timeseria.transformations module

Series transformations as resampling and aggregation.

class timeseria.transformations.Transformation

Bases: object

A generic transformation.

process(series, start=None, end=None, validity=None, include_extremes=False, fill_with=None, force_data_loss=None)

Start the transformation process.

Parameters

series (TimeSeries) – the time series to transform.
start (float, datetime) – the start time of the transformation process. If not set, then it is set automatically based on first item of the series. Defaults to None.
end (float, datetime) – the end time of the transformation process. If not set, then it is set automatically based on first item of the series. Defaults to None.
validity (float) – the validity (sampling) interval of the original data points. Defaults to auto-detect.
include_extremes (bool) – if to include the first and last items in the transformed time series, which might not have enough data when being created. Defaults to False.
fill_with() – a fixed value to fill the data of the items showing a full data loss.
force_data_loss (float) – Force a specific data loss value for all the new series items.

class timeseria.transformations.Resampler(unit, interpolator_class=<class 'timeseria.interpolators.LinearInterpolator'>)

Bases: Transformation

Resampling transformation.

Parameters

unit (TimeUnit. str) – the time unit corresponding to the new sampling interval, or its string representation.
interpolator_class (Interpolator) – the interpolator to use for the resampling process. Defaults to LinearInterpolator.

target = 'points'

process(series, *args, **kwargs)

Start the transformation process.

Parameters

series (TimeSeries) – the time series to transform.
start (float, datetime) – the start time of the transformation process. If not set, then it is set automatically based on first item of the series. Defaults to None.
end (float, datetime) – the end time of the transformation process. If not set, then it is set automatically based on first item of the series. Defaults to None.
validity (float) – the validity (sampling) interval of the original data points. Defaults to auto-detect.
include_extremes (bool) – if to include the first and last items in the transformed time series, which might not have enough data when being created. Defaults to False.
fill_with() – a fixed value to fill the data of the items showing a full data loss.
force_data_loss (float) – Force a specific data loss value for all the new series items.

class timeseria.transformations.Aggregator(unit, operations=[avg], interpolator_class=<class 'timeseria.interpolators.LinearInterpolator'>)

Bases: Transformation

Aggregation transformation.

Parameters

unit (TimeUnit. str) – the time unit corresponding to the aggregation slots, or its string representation.
operations (list) – the list of operations to perform when aggregating the data. Supports any operation of the operations module, as well as custom ones, provided they take as input a series and return a scalar.
interpolator_class (Interpolator) – the interpolator to use to reconstruct missing samples. Defaults to LinearInterpolator.

target = 'slots'

process(series, *args, **kwargs)

Start the transformation process.

Parameters

series (TimeSeries) – the time series to transform.
start (float, datetime) – the start time of the transformation process. If not set, then it is set automatically based on first item of the series. Defaults to None.
end (float, datetime) – the end time of the transformation process. If not set, then it is set automatically based on first item of the series. Defaults to None.
validity (float) – the validity (sampling) interval of the original data points. Defaults to auto-detect.
include_extremes (bool) – if to include the first and last items in the transformed time series, which might not have enough data when being created. Defaults to False.
fill_with() – a fixed value to fill the data of the items showing a full data loss.
force_data_loss (float) – Force a specific data loss value for all the new series items.

timeseria.units module

Units, including the TimeUnit, which fully supports calendar arithmetic.

class timeseria.units.Unit(value)

Bases: object

A generic unit.

Parameters: value – the unit value.

class timeseria.units.TimeUnit(*args, **kwargs)

Bases: TimeSpan, Unit

A unit that can have both fixed (physical) or variable (calendar) time length. It can handle precision up to the microsecond and can be added and subtracted with numerical values, Time and datetime objects, and other TimeUnits.

Can be initialized both using a numerical value, a string representation, or by explicitly setting years, months, weeks, days, hours, minutes and seconds (including sub-second precision). In the string representation, the mapping is as follows:

'Y': 'years'

'M': 'months'

'W': 'weeks'

'D': 'days'

'h': 'hours'

'm': 'minutes'

's': 'seconds'

For example, to create a time unit of one hour, the following three are equivalent, where the first one uses the numerical value, the second the string representation, and the third explicitly sets the time component (hours in this case): TimeUnit('1h'), TimeUnit(hours=1), or TimeUnit(3600). Not all time units can be initialized using the numerical value, in particular calendar time units which can have variable duration: a time unit of one day, or TimeUnit('1d'), can last for 23, 24 or 24 hours depending on DST changes. On the contrary, a TimeUnit('24h') will always last 24 hours and can be initialized as TimeUnit(86400) as well.

Parameters

value – the time unit value, either as seconds (int or float) or as string representation according to the mapping above.
years – the time unit years component (int).
weeks – the time unit weeks component (int).
months – the time unit weeks component (int).
days – the time unit days component (int).
hours – the time unit hours component (int).
minutes – the time unit minutes component (int).
seconds – the time unit seconds component, including sub-second precision (int, float).

as_seconds(starting_at=None)

The length (duration) of the time unit, in seconds.

Parameters: starting_at (Time, datetime) – the starting point with respect to which compute the duration. Required for all calendar time units (involving years, months, weeks and days). Defaults to None.
Returns: the duration of the unit in seconds.
Return type: float

ceil(time)

Ceil a Time or datetime object according to this time unit.

Parameters: time (Time, datetime) – Time or datetime object to be ceiled.
Returns: the ceiled Time or datetime object.
Return type: Time or datetime

floor(time)

Floor a Time or datetime object according to this time unit.

Parameters: time (Time, datetime) – the Time or datetime object to be floored.
Returns: the floored Time or datetime object.
Return type: Time or datetime

round(time, how='half')

Round a Time or datetime object according to this time unit.

Parameters: time (Time, datetime) – the Time or datetime object to be rounded.
Returns: the rounded Time or datetime object.
Return type: Time or datetime

shift(time, times=1)

Shift a Time or datetime object n times this time unit.

Parameters

time (Time, datetime) – the Time or datetime object to be shifted.
times (int) – how many times to perform the shift. Defaults to 1.

Returns

the shifted Time or datetime object.

Return type

Time or datetime

timeseria.utils module

Utility functions.

timeseria.utils.ensure_reproducibility(): Ensure reproducibility by fixing seeds to zero for Random, Numpy, and Tensorflow.

timeseria.utils.is_numerical(item)

Check if an item is numerical (float or int, including Pandas data types).

Parameters: item (obj) – the item to check.

timeseria.utils.detect_encoding(file_name, streaming=False)

Detect the encoding of a file.

Parameters

file_name (str) – the file name for which to detect the encoding.
straming (bool) – if to perform the detection in streaming mode, for large files. Default to False.

Returns

the detected encoding.

Return type

str

timeseria.utils.detect_sampling_interval(timeseries, confidence=False)

Detect the sampling interval of a time series.

Parameters

timeseries (TimeSeries) – the time series for which to detect the sampling interval.
confidence (bool) – if to provide the confidence as well, in a 0-1 range.

Returns

the detected sampling rate or the detected sampling rate with the confidence.

Return type

float or tuple

timeseria.utils.detect_periodicity(timeseries)

Detect the periodicity of a time series.

Parameters: timeseries (TimeSeries) – the time series for which to detect the periodicity.
Returns: the detected periodicity.
Return type: int

timeseria.utils.mean_absolute_percentage_error(list1, list2)

Compute the MAPE.

Parameters

list1 (list) – the true values.
list2 (list) – the predicted values.

Returns

the computed MAPE.

Return type

float

timeseria.utils.max_absolute_percentage_error(list1, list2)

Compute the MaxAPE.

Parameters

list1 (list) – the true values.
list2 (list) – the predicted values.

Returns

the computed MaxAPE.

Return type

float

timeseria.utils.mean_absolute_error(list1, list2)

Compute the MAE.

Parameters

list1 (list) – the true values.
list2 (list) – the predicted values.

Returns

the computed MAE.

Return type

float

timeseria.utils.max_absolute_error(list1, list2)

Compute the MaxAE.

Parameters

list1 (list) – the true values.
list2 (list) – the predicted values.

Returns

the computed MaxAE.

Return type

float

timeseria.utils.mean_absolute_log_error(list1, list2)

Compute the MALE.

Parameters

list1 (list) – the true values.
list2 (list) – the predicted values.

Returns

the computed MALE.

Return type

float

timeseria.utils.max_absolute_log_error(list1, list2)

Compute the MaxALE.

Parameters

list1 (list) – the true values.
list2 (list) – the predicted values.

Returns

the computed MaxALE.

Return type

float

timeseria.utils.mean_squared_error(list1, list2)

Compute the MSE.

Parameters

list1 (list) – the true values.
list2 (list) – the predicted values.

Returns

the computed MSE.

Return type

float

timeseria.utils.rescale(value, source_from, source_to, target_from=0, target_to=1)

Rescale a value from one range to another.

Parameters

value (float, obj) – the value to rescale.
source_from (float) – the source rescaling interval start.
source_end (float) – the source rescaling interval end.
target_from (float) – the target rescaling interval start. Defaults to 0.
target_end (float) – the target rescaling interval end. Defaults to 1.

Returns

the rescaled value.

Return type

float or obj

timeseria.utils.os_shell(command, capture=False, verbose=False, interactive=False, silent=False)

Execute a command in the OS shell and print its output.

Parameters

command (str) – the command to execute.
capture (bool) – if to capture the output as a namedtuple with stdout, stderr, and exit code instead of printing it. Defaults to False.
interactive (bool) – if to run the command in interactive mode. Defaults to False.
silent (bool) – if to suppress printing the output. Defaults to False.

Returns

the output of the command, if any.

Return type

None or namedtupe

class timeseria.utils.DistributionFunction(dist, params)

Bases: object

A class representing a statistical distribution. Implemented as a callable object, so that it can be evaluated at a given x.

Parameters

dist (str) – the name of the distirbution.
params (dist) – the parameters of the distirbution

plot(x_min=-1, x_max=1, show=True)

Plot the distribution.

Parameters

x_min (float) – the minimum value of the x axis.
x_max (float) – the maximum value of the x axis.
show (bool) – if to show the plot. Default to True.

Returns

the pot object, if not set to be shown.

Return type

None or plt

find_x(y, wideness=1000, side='right')

Find the x for a given y.

Parameters

y (float) – the y to find the x for.
wideness (float) – how wide the search should be, on the x axis.
side (str) – on which side of the distribution to look.

Returns

the x found for the given y.

Return type

float

class timeseria.utils.IFloat(value, lower=None, upper=None)

Bases: float

A class representing an “interval” floating point number, based on lower and upper bounds.

describe()

plot()

as_integer_ratio()

Return a pair of integers, whose ratio is exactly equal to the original float.

The ratio is in lowest terms and has a positive denominator. Raise OverflowError on infinities and a ValueError on NaNs.

>>> (10.0).as_integer_ratio()
(10, 1)
>>> (0.0).as_integer_ratio()
(0, 1)
>>> (-.25).as_integer_ratio()
(-1, 4)

conjugate(): Return self, the complex conjugate of any float.

fromhex()

Create a floating-point number from a hexadecimal string.

>>> float.fromhex('0x1.ffffp10')
2047.984375
>>> float.fromhex('-0x1p-1074')
-5e-324

hex()

Return a hexadecimal representation of a floating-point number.

>>> (-0.1).hex()
'-0x1.999999999999ap-4'
>>> 3.14159.hex()
'0x1.921f9f01b866ep+1'

imag: the imaginary part of a complex number

is_integer(): Return True if the float is an integer.

real: the real part of a complex number

class timeseria.utils.PFloat(value, dist=None, data=None)

Bases: float

A class representing a “probabilistic” floating point number, based on a probability distribution.

distf()

describe()

plot()

classmethod from_data(data, dist_type='gennorm')

as_integer_ratio()

Return a pair of integers, whose ratio is exactly equal to the original float.

The ratio is in lowest terms and has a positive denominator. Raise OverflowError on infinities and a ValueError on NaNs.

>>> (10.0).as_integer_ratio()
(10, 1)
>>> (0.0).as_integer_ratio()
(0, 1)
>>> (-.25).as_integer_ratio()
(-1, 4)

conjugate(): Return self, the complex conjugate of any float.

fromhex()

Create a floating-point number from a hexadecimal string.

>>> float.fromhex('0x1.ffffp10')
2047.984375
>>> float.fromhex('-0x1p-1074')
-5e-324

hex()

Return a hexadecimal representation of a floating-point number.

>>> (-0.1).hex()
'-0x1.999999999999ap-4'
>>> 3.14159.hex()
'0x1.921f9f01b866ep+1'

imag: the imaginary part of a complex number

is_integer(): Return True if the float is an integer.

real: the real part of a complex number

timeseria.logger module

Library logging setup.

timeseria.logger.setup(level='CRITICAL', force=False)

Set up the library logger on a given log level.

Parameters

level (str) – the log level between DEBUG, INFO, WARNING, ERROR, and CRITICAL. Defaults to CRITICAL or the value defined by the TIMESERIA_LOGLEVEL environment variable.
force (bool) – if to force the setup, even if the logger is already configured.

timeseria package

Subpackages

Submodules

timeseria.datastructures module

timeseria.exceptions module

timeseria.interpolators module

timeseria.operations module

timeseria.plots module

timeseria.storages module

timeseria.time module

timeseria.transformations module

timeseria.units module

timeseria.utils module

timeseria.logger module

Module contents