Piecewise Linear Time Warping

This repo contains research code for time warping multi-dimensional time series. This was developed as part of the following manuscript, which focuses on analysis of large-scale neural recordings (though this code can be also be applied to many other data types):

Discovering precise temporal patterns in large-scale neural recordings through robust and interpretable time warping.
Williams AH, Poole B, Maheswaranathan N, Dhawale AK, Fisher T, Wilson CD, Brann DH, Trautmann E, Ryu S, Shusterman R, Rinberg D, Ölveczky BP, Shenoy KV, Ganguli S (2020). Neuron. 105(2):246-259.e8

The code fits time warping models with either linear or piecewise linear warping functions. These models are more constrained than the classic Dynamic Time Warping (DTW) algorithm, and are thus less prone to overfit to data with high levels of noise. This is demonstrated below on synthethic data. Briefly, a 1-dimensional time series is measured over many repetitions (trials), and exhibits a similar temporal profile but with random jitter on each trial. Simply averaging across trials produces a poor description of the typical time series (red trace at bottom). A linear time warping model identifies a much better prototypical trace (labeled "template"), while accounting for the temporal translations on each trial with warping functions (blue to red linear functions at bottom). On the right, a nonlinear warping model based on DTW (called DBA) is shown for comparison. While DBA can work well on datasets with low noise, linear warping models can be easier to interpret and less likely to overfit.

Getting started

After installing (see below), check out the demos in the examples/ folder.

Either download or clone the repo:

git clone https://github.com/ahwillia/affinewarp/

Then navigate to the downloaded folder:

cd /path/to/affinewarp

Install the package and requirements:

pip install .
pip install -r requirements.txt

You will need to repeat these steps if we update the code.

Other references / resources

• tw-pca - Time-Warping Principal Components Analysis, also supports linear and shift-only warping functions. Does not support piecewise linear warping functions and assumes that time series are low-dimensional. Nonlinear warping methods are also supported. See our conference abstract and poster.

• tslearn - A Python package supporting a variety of time series models, including DTW-based methods.

Contact

ahwillia@stanford.edu (or open an issue here).