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)[source]

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 a new column and update the column map


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


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, align='l')[source]

Determine col and row indices corresponding to timestamp and col name

  • 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?
  • align (str) – “left” or “right”; governs whether or not the value given for the timestamp argument represents the left or right edge of the bin.

(t_index, c_index) (long or None)

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

Create a new TimeSeries dataset object

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

  • 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, align='l')[source]

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.

  • 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.
  • align (str) – “left” or “right”; governs whether or not the value given for the timestamp argument represents the left or right edge of the bin.

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

Return type:



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


Set the list of column names

set_timestamp_key(timestamp_key, safe=False)[source]

Set the timestamp key

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

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

swap_columns(index1, index2)[source]

Swap two columns of the dataset in-place


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


Create the mapping of column names to column indices

tokio.timeseries.sorted_nodenames(nodenames, sort_hex=False)[source]

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


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
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