API reference

The following is a reference guide for the functions in the modules of neurOB, sorted by submodule.

timeWarpOB

The timeWarpOB module contains the main functions for time warping. The other submodules contain functions to help with plotting.

timeWarpOB.timeWarp(a, b, method='DTW', window=0, retMat=True, **kwargs)[source]

This function is the main time warping interface, and acts as a convenient wrapper to the other functions.

Parameters:
  • a (list or numpy 1D-array) – First time series, which will be compared against time series b
  • b (list or numpy 1D-array) – Second time series (reference)
  • method (str) – Time warping method {'DTW','ERP'} - see below
  • window (int) – Time warping window constraint (default = 0)
  • retMat (bool) – Whether to include the cost matrices in the returned object
  • ERPg (int) – g-value (for method = 'ERP' only)
Returns:

  • warpObj (dict) – A timeWarpOB warp object, containing the following items:
  • warpObj.backTraceCost (float) – The sum cost of following the backtrace through the cost matrix
  • warpObj.backTracePath (list) – List or numpy array of pairs of coordinates in time-space describing the backtrace through the cost matrix
  • warpObj.cost (float) – Bottom left value on the cost matrix. With no warping window, this should equal warpObj.backTraceCost
  • warpObj.costMat (list) – A matrix (list of lists) or numpy array describing the cost matrix between the two time series. For a series of length n, this matrix will be of size n x n. Only output if retMat = True in the input parameters
  • warpObj.distMat (list) – A matrix (list of lists) or numpy array describing the L1-distance matrix between the two time series. For a series of length n, this matrix will be of size n x n. Only output if retMat = True in the input parameters
  • warpObj.warpWindow (int) – Returning the warp window parameter used (used by plotting functions)
  • warpObj.warpStats (dict) – Warp statistics object, containing:
  • warpObj.warpStats.timeAhead (int) – The number of periods that time series a was in sync with time series b.
  • warpObj.warpStats.timeAhead (int) – The number of periods that time series a was ahead of time series b.
  • warpObj.warpStats.timeBehind (int) – The number of periods that time series a was behind of time series b.
  • warpObj.warpStats.amountAhead (int) – The total sum of the number of periods that time series a was leading time series b by.
  • warpObj.warpStats.amountBehind (int) – The total sum of the number of periods that time series a was lagging time series b by.
  • warpObj.warpStats.avgAhead (int) – Average amount of periods that a was ahead of a by, i.e. amountAhead divided by timeAhead
  • warpObj.warpStats.avgAhead (int) – Average amount of periods that a was behind b by, i.e. amountBehind divided by timeBehind
  • warpObj.warpStats.avgWarp (int) – Average amount of periods that a ahead or behind b by, i.e. (amountAhead - amountBehind) / (timeAhead + timeBehind + timeSync) This will give positive values if a is on average ahead of b and negative values is a is on average behind b.

Notes

  • If lists are supplied, the output matrices will be in list form. If numpy arrays are supplied, the output will be as numpy arrays.
  • Numpy arrays will calculate faster, as no internal type conversion is required.
  • Time series should be of equal length. If they are not, the longer will be clipped from the end.
  • ERP and DTW methods are available. For information on how they work, see the module documentation.
  • Cost matricies should be returned for use by the plotting functions
timeWarpOB.L1distances(a, b)[source]

Calcluates the L1 distance matrix between two time series.

Parameters:
  • a (list) – First time series, which will be compared against time series b
  • b (list) – Second time series (reference)
Returns:

distance – A matrix (list of lists) describing the L1-distance matrix between the two time series. For a series of length n, this matrix will be of size n x n.
Return type:

list
timeWarpOB.ERPwarp(dist, x, y, w=0, g=0)[source]

Calcluates the ERP cost matrix between two time series.

Parameters:
  • dist (list) – A matrix (list of lists) describing the L1-distance matrix between two time series. For a time series of length n, this matrix must be of size n x n.
  • x (list) – First time series, which will be compared against time series y
  • y (list) – Second time series (reference)
  • w (int) – Time warping window constraint (default = 0)
  • g (int) – ERP g-value (deafult = 0)
Returns:

costMat – A matrix (list of lists) describing the ERP cost matrix between the two time series. For a series of length n, this matrix will be of size n x n.
Return type:

list
timeWarpOB.DTWwarp(dist, x, y, w=0)[source]

Calcluates the ERP cost matrix between two time series.

Parameters:
  • dist (list) – A matrix (list of lists) describing the L1-distance matrix between two time series. For a time series of length n, this matrix must be of size n x n.
  • x (list) – First time series, which will be compared against time series y
  • y (list) – Second time series (reference)
  • w (int) – Time warping window constraint (default = 0)
Returns:

costMat – A matrix (list of lists) describing the DTW cost matrix between the two time series. For a series of length n, this matrix will be of size n x n.
Return type:

list
timeWarpOB.backTrace(costMat, dist)[source]

Finds the optimal warping path by backtracking through the cost matrix.

Parameters:
  • dist (list) – A matrix (list of lists) describing the L1-distance matrix between two time series. For a time series of length n, this matrix must be of size n x n.
  • costMat (list) – A matrix (list of lists) describing the time-warped cost matrix between two time series. For a time series of length n, this matrix must be of size n x n.
Returns:

  • path (list) – List of pairs of coordinates in time-space describing the backtrace through the cost matrix
  • backTraceCost (float) – The sum cost of following the backtrace through the cost matrix
  • warpStats (dict) – Warp statistics object, containing:
  • warpStats.timeAhead (int) – The number of periods that time series a was in sync with time series b.
  • warpStats.timeAhead (int) – The number of periods that time series a was ahead of time series b.
  • warpStats.timeBehind (int) – The number of periods that time series a was behind of time series b.
  • warpStats.amountAhead (int) – The total sum of the number of periods that time series a was leading time series b by.
  • warpStats.amountBehind (int) – The total sum of the number of periods that time series a was lagging time series b by.
  • warpStats.avgAhead (int) – Average amount of periods that a was ahead of a by, i.e. amountAhead divided by timeAhead
  • warpStats.avgAhead (int) – Average amount of periods that a was behind b by, i.e. amountBehind divided by timeBehind
  • warpStats.avgWarp (int) – Average amount of periods that a ahead or behind b by, i.e. (amountAhead - amountBehind) / (timeAhead + timeBehind + timeSync) This will give positive values if a is on average ahead of b and negative values is a is on average behind b.

timeWarpOB.plotting

The timeWarpOB.plotting module contains functions for plotting the outcome of a time warp experiment.

timeWarpOB.plotting.plotWarp(a, b, warpObj, ts=[])[source]

Plots the comprehensive results of a time warp, including the cost matrix, backtrace path, visualisation of the warping statistics and the individual time series, with warp lines.

Parameters:
  • a (list) – First time series, which has been warped against time series b
  • b (list) – Second time series (reference)
  • warpObj (dict) – A timeWarpOB warp object - see output of timeWarpOB.timeWarp(). NB: the object must contain the calclauted cost matrix (i.e. retMat = True)
  • ts (list) – Optional list of timestamps for displaying on the graphs. If no timestamps are given, each time period will be given an incremented number, staring at 1.
Returns:

A composite plot showing the results of the time warp.
Return type:

matplotlib.pyplot
timeWarpOB.plotting.plotSeries(a, b, warpObj)[source]

Plots the two time series with warp lines as a single plot

Parameters:
  • a (list) – First time series, which has been warped against time series b
  • b (list) – Second time series (reference)
  • warpObj (dict) – A timeWarpOB warp object - see output of timeWarpOB.timeWarp().
Returns:

A single plot showing the warp lines on the two time series.
Return type:

matplotlib.pyplot

timeWarpOB.tests.basic

Basic tests of the timeWarpOB module functionality.

tests.basic.testWarp(x, y, ts)[source]
Warps two time series, displays plots and prints
the warp statistics.
Parameters:
  • x (list) – First time series, which has been warped against time series b
  • y (list) – Second time series (reference)
  • ts (list) – Optional list of timestamps for displaying on the graphs. If no timestamps are given, each time period will be given an incremented number, staring at 1.
Returns:

  • matplotlib.pyplot – A composite plot showing the results of the time warp.
  • warpStats (dict) – Warp statistics (printed to the console only)
tests.basic.sinCos(n=2, l=200)[source]

Generates a test dataset of sin and cosine over 200 points in a time series.

Parameters:
  • n (int) – Number of half-cycles to calculate the values over
  • l (int) – Number of points in the time series
Returns:

  • x (list) – A list of sin(ts) values
  • y (list) – A list of cos(ts) values
  • ts (list) – A list of ‘timestamp’ values (radian angle values)