tokio.timeseries module

TimeSeries class to simplify updating and manipulating the in-memory representation of time series data.

class tokio.timeseries.TimeSeries(dataset_name=None, start=None, end=None, timestep=None, num_columns=None, column_names=None, timestamp_key=None, sort_hex=False)

Bases: object

In-memory representation of an HDF5 group in a TokioFile. Can either initialize with no datasets, or initialize against an existing HDF5 group.

add_column(column_name)

Add a new column and update the column map

add_rows(num_rows=1)

Add additional rows to the end of self.dataset and self.timestamps

convert_to_deltas(align='l')

Converts a matrix of monotonically increasing rows into deltas.

Replaces self.dataset with a matrix with the same number of columns but one fewer row (taken off the bottom of the matrix). Also adjusts the timestamps dataset.

Parameters:align (str) – “left” or “right”. Determines whether the contents of a cell labeled with timestamp t0 contains the data between t0 and t0 + dt (left) or t0 and t0 - dt (right).

get_insert_pos(timestamp, column_name, create_col=False)

Determine col and row indices corresponding to timestamp and col name

Parameters:

• timestamp (datetime.datetime) – Timestamp to map to a row index
• column_name (str) – Name of column to map to a column index
• create_col (bool) – If column_name does not exist, create it?

Returns:

(t_index, c_index) (long or None)

init(start, end, timestep, num_columns, dataset_name, column_names=None, timestamp_key=None)

Create a new TimeSeries dataset object

Responsible for setting self.timestep, self.timestamp_key, and self.timestamps

Parameters:

• start (datetime) – timestamp to correspond with the 0th index
• end (datetime) – timestamp at which timeseries will end (exclusive)
• timestep (int) – seconds between consecutive timestamp indices
• num_columns (int) – number of columns to initialize in the numpy.ndarray
• dataset_name (str) – an HDF5-compatible name for this timeseries
• column_names (list of str, optional) – strings by which each column should be indexed. Must be less than or equal to num_columns in length; difference remains uninitialized
• timestamp_key (str, optional) – an HDF5-compatible name for this timeseries’ timestamp vector. Default is /groupname/timestamps

insert_element(timestamp, column_name, value, reducer=None)

Inserts a value into a (timestamp, column) element

Given a timestamp (datetime.datetime object) and a column name (string), update an element of the dataset. If a reducer function is provided, use that function to reconcile any existing values in the element to be updated.

Parameters:

• timestamp (datetime.datetime) – Determines the row index into which value should be inserted
• column_name (str) – Determines the column into which value should be inserted
• value – Value to insert into the dataset
• reducer (function or None) – If a value already exists for the given (timestamp, column_name) coordinate, apply this function to the existing value and the input value and store the result If None, just overwrite the existing value.

Returns:

True if insertion was successful, False if no action was taken

Return type:

bool

rearrange_columns(new_order)

Rearrange the dataset’s columnar data by an arbitrary column order given as an enumerable list

set_columns(column_names)

Set the list of column names

set_timestamp_key(timestamp_key, safe=False)

Set the timestamp key

Parameters:

• timestamp_key (str) – The key for the timestamp dataset.
• safe (bool) – If true, do not overwrite an existing timestamp key

sort_columns()

Rearrange the dataset’s column data by sorting them by their headings

swap_columns(index1, index2)

Swap two columns of the dataset in-place

trim_rows(num_rows=1)

Trim some rows off the end of self.dataset and self.timestamps

update_column_map()

Create the mapping of column names to column indices

tokio.timeseries.sorted_nodenames(nodenames, sort_hex=False)

Gnarly routine to sort nodenames naturally. Required for nodes named things like ‘bb23’ and ‘bb231’.

tokio.timeseries.timeseries_deltas(dataset)

Convert monotonically increasing values into deltas

Subtract every row of the dataset from the row that precedes it to convert a matrix of monotonically increasing rows into deltas. This is a lossy process because the deltas for the final measurement of the time series cannot be calculated.

Parameters:dataset (numpy.ndarray) – The dataset to convert from absolute values into deltas. rows should correspond to time, and columns to individual components Returns:

The deltas between each row in the given input dataset.

Will have the same number of columns as the input dataset and one fewer rows.

Return type:numpy.ndarray