syncopy.specest.mtmconvol.mtmconvol

syncopy.specest.mtmconvol.mtmconvol(trl_dat, soi, padbegin, padend, samplerate=None, noverlap=None, nperseg=None, equidistant=True, toi=None, foi=None, nTaper=1, timeAxis=0, taper=<function hann>, taperopt={}, keeptapers=True, polyremoval=None, output_fmt='pow', noCompute=False, chunkShape=None)[source]

Perform time-frequency analysis on multi-channel time series data using a sliding window FFT

Parameters
  • trl_dat (2D numpy.ndarray) – Uniformly sampled multi-channel time-series

  • soi (list of slices or slice) – Samples of interest; either a single slice encoding begin- to end-samples to perform analysis on (if sliding window centroids are equidistant) or list of slices with each slice corresponding to coverage of a single analysis window (if spacing between windows is not constant)

  • padbegin (int) – Number of samples to pre-pend to trl_dat

  • padend (int) – Number of samples to append to trl_dat

  • samplerate (float) – Samplerate of trl_dat in Hz

  • noverlap (int) – Number of samples covered by two adjacent analysis windows

  • nperseg (int) – Size of analysis windows (in samples)

  • equidistant (bool) – If True, spacing of window-centroids is equidistant.

  • toi (1D numpy.ndarray or float or str) – Either time-points to center windows on if toi is a numpy.ndarray, or percentage of overlap between windows if toi is a scalar or “all” to center windows on all samples in trl_dat. Please refer to freqanalysis() for further details. Note: The value of toi has to agree with provided padding and window settings. See Notes for more information.

  • foi (1D numpy.ndarray) – Frequencies of interest (Hz) for output. If desired frequencies cannot be matched exactly the closest possible frequencies (respecting data length and padding) are used.

  • nTaper (int) – Number of tapers to use

  • timeAxis (int) – Index of running time axis in trl_dat (0 or 1)

  • taper (callable) – Taper function to use, one of availableTapers

  • taperopt (dict) – Additional keyword arguments passed to taper (see above). For further details, please refer to the SciPy docs

  • keeptapers (bool) – If True, results of Fourier transform are preserved for each taper, otherwise spectrum is averaged across tapers.

  • polyremoval (int) – FIXME: Not implemented yet Order of polynomial used for de-trending. A value of 0 corresponds to subtracting the mean (“de-meaning”), polyremoval = 1 removes linear trends (subtracting the least squares fit of a linear function), polyremoval = N for N > 1 subtracts a polynomial of order N (N = 2 quadratic, N = 3 cubic etc.). If polyremoval is None, no de-trending is performed.

  • output_fmt (str) – Output of spectral estimation; one of availableOutputs

  • noCompute (bool) – Preprocessing flag. If True, do not perform actual calculation but instead return expected shape and numpy.dtype of output array.

  • chunkShape (None or tuple) – If not None, represents shape of output object spec (respecting provided values of nTaper, keeptapers etc.)

Returns

spec – Complex or real time-frequency representation of (padded) input data.

Return type

numpy.ndarray

Notes

This method is intended to be used as computeFunction() inside a ComputationalRoutine. Thus, input parameters are presumed to be forwarded from a parent metafunction. Consequently, this function does not perform any error checking and operates under the assumption that all inputs have been externally validated and cross-checked.

The computational heavy lifting in this code is performed by SciPy’s Short Time Fourier Transform (STFT) implementation scipy.signal.stft().

See also

syncopy.freqanalysis()

parent metafunction

MultiTaperFFTConvol()

ComputationalRoutine instance that calls this method as computeFunction()

scipy.signal.stft()

SciPy’s STFT implementation