numkit.timeseries — Time series manipulation and analysis

numkit.timeseries.autocorrelation_fft(series, remove_mean=True, paddingcorrection=True, normalize=False, **kwargs)

Calculate the auto correlation function.

autocorrelation_fft(series,remove_mean=False,**kwargs) –> acf

The time series is correlated with itself across its whole length. Only the [0,len(series)[ interval is returned.

By default, the mean of the series is subtracted and the correlation of the fluctuations around the mean are investigated.

For the default setting remove_mean=True, acf[0] equals the variance of the series, acf[0] = Var(series) = <(series - <series>)**2>.

Optional:

• The series can be normalized to its 0-th element so that acf[0] == 1.
• For calculating the acf, 0-padding is used. The ACF should be corrected for the 0-padding (the values for larger lags are increased) unless mode=’valid’ is set (see below).

Note that the series for mode=’same’|’full’ is inaccurate for long times and should probably be truncated at 1/2*len(series)

Arguments :

series

(time) series, a 1D numpy array of length N

remove_mean

False: use series as is; True: subtract mean(series) from series [True]

paddingcorrection

False: corrected for 0-padding; True: return as is it is. (the latter is appropriate for periodic signals). The correction for element 0=<i<N amounts to a factor N/(N-i). Only applied for modes != “valid” [True]

normalize

True divides by acf[0] so that the first element is 1; False leaves un-normalized [False]

mode

“full” | “same” | “valid”: see scipy.signal.fftconvolve() [“full”]

kwargs

other keyword arguments for scipy.signal.fftconvolve()

numkit.timeseries.tcorrel(x, y, nstep=100, debug=False)

Calculate the correlation time and an estimate of the error of the mean <y>.

The autocorrelation function f(t) is calculated via FFT on every nstep of the fluctuations of the data around the mean (y-<y>). The normalized ACF f(t)/f(0) is assumed to decay exponentially, f(t)/f(0) = exp(-t/tc) and the decay constant tc is estimated as the integral of the ACF from the start up to its first root.

See [FrenkelSmit2002] p526 for details.

Note

nstep should be set sufficiently large so that there are less than ~50,000 entries in the input.

[FrenkelSmit2002]

D. Frenkel and B. Smit, Understanding Molecular Simulation. Academic Press, San Diego 2002

Arguments :

x

1D array of abscissa values (typically time)

y

1D array of the ibservable y(x)

nstep

only analyze every nstep datapoint to speed up calculation [100]

Returns :

dictionary with entries tc (decay constant in units of x), t0 (value of the first root along x (y(t0) = 0)), sigma (error estimate for the mean of y, <y>, corrected for correlations in the data).

exception numkit.timeseries.LowAccuracyWarning

Warns that results may possibly have low accuracy.