Table of Contents

Functions for spectral estimation of EEG/MEG data

The spectral estimation toolbox for FieldTrip, the specest module, contains a consistent set of functions for spectral estimation and decomposition of electrophysiological data. These specest functions allow other projects (such as SPM) to re-use the implemented methods separate from FieldTrip and facilitates external contributions to FieldTrip by separating the user interface from the functionality.

The low-level functions are combined in the specest toolbox which is self-contained and does not depend on other FieldTrip functions. It is available for download here.

Specest Functions

  1. ft_specest_mtmconvol
    • Wavelet convolution in the time-domain by multiplication in the frequency domain. Wavelets used are complex sinusoids multiplied with a windowing function (e.g. Slepian, Hanning, Hamming,…).
  2. ft_specest_mtmfft
    • Non-time resolved spectral estimation by tapering the data with a windowing function (e.g. Slepian, Hanning, Hamming,…) prior to compution the Fourier transform.
  3. ft_specest_hilbert
    • Spectral estimation by bandpass filtering the data prior to computing the Hilbert transform.
  4. ft_specest_wavelet
    • Wavelet convolution in the time-domain by multiplication in the frequency domain. Wavelets used are Morlet wavelets.
  5. ft_specest_tfr
    • Wavelet convolution in the time-domain using Morlet wavelets.

Definition of the function-calls (API)

The functions should be called as 

[spectrum, ntaper, freqoi, timeoi] = ft_specest_mtmconvol(dat, time, key1, value1, ...)
        [spectrum, ntaper, freqoi] = ft_specest_mtmfft   (dat, time, key1, value1, ...)
        [spectrum, freqoi, timeoi] = ft_specest_hilbert  (dat, time, key1, value1, ...)
        [spectrum, freqoi, timeoi] = ft_specest_wavelet  (dat, time, key1, value1, ...)
        [spectrum, freqoi, timeoi] = ft_specest_tfr      (dat, time, key1, value1, ...)

Where dat consists of a matrix of dimensionality Nchan x Ntime, and time is a 1xNtime vector containing the time indices in seconds. The time vector is used to compute the sampling rate, and to determine, in the case of mtmfft, where t=0 resides with respect to dat.

Each function can take a set of common and function-specific additional arguments in key-value pairs. Which additional arguments a function can take is described in the reference documentation: ft_specest_mtmconvol, ft_specest_mtmfft, ft_specest_hilbert, ft_specest_wavelet, ft_specest_tfr.

Definition of Phase

In the case of ft_specest_mtmconvol, the phase at the peak of an oscillation in the data is defined to be 0, and the trough of an oscillation in the data is defined to be π/-π, progressing counter-clockwise around the circle.
In the case of ft_specest_mtmfft, the average phase of the data segment is from the perspective that an oscillation in the data has a phase of 0, i.e. is at it's peak (following the same convention as ft_specest_mtmconvol), at time-point t=0.
For ft_specest_hilbert how phase is defined at the peak and at the trough of an oscillation in the data depends on the type of filter and the filter order that is used to bandpass filter the data, prior to computing the Hilbert transform.
For ft_specest_wavelet and ft_specest_tfr how phase is defined at the peak and at the trough of an oscillation in the data depends on the width of the Gaussian that is used.

Recent changes to the code

2012-01-10 13:10  jansch

	* [r5106] ft_specest_hilbert.m, ft_specest_mtmconvol.m, ft_specest_mtmfft.m,
	  ft_specest_tfr.m, ft_specest_wavelet.m: change in default behavior - remove DC-component
	  only as default, rather than first order polynome

2012-01-05 09:05  eelspa

	* [r5096] private/ft_getopt.mexa64, private/ft_getopt.mexglx, private/ft_getopt.mexmaci,
	  private/ft_getopt.mexmaci64, private/ft_getopt.mexw32, private/ft_getopt.mexw64: setting
	  svn:executable property on all MEX files, properly this time I hope

2011-12-22 13:40  borreu

	* [r5076] private/ft_getopt.m: automatically synchronized identical files to revision 5075

2011-12-21 13:58  roboos

	* [r5065] private/ft_getopt.m, private/ft_getopt.mexglx: automatically synchronized
	  identical files to revision 5064

2011-12-20 14:03  jansch

	* [r5058] private/ft_getopt.mexmaci, private/ft_getopt.mexmaci64: automatically synchronized
	  identical files to revision 5057

2011-12-20 13:48  eelspa

	* [r5056] private/ft_getopt.m, private/ft_getopt.mexa64, private/ft_getopt.mexw32,
	  private/ft_getopt.mexw64: automatically synchronized identical files to revision 5055

2011-12-12 17:29  roevdmei

	* [r5019] ft_specest_hilbert.m, ft_specest_mtmconvol.m, ft_specest_mtmfft.m,
	  ft_specest_tfr.m, ft_specest_wavelet.m: changed all occurances of time(2)-time(1) to the
	  more accurate mean(diff(time)) to prevent/diminish issues with numerical accuracies in the
	  time vector

2011-12-09 11:53  eelspa

	* [r4963] private/ft_preproc_polyremoval.m: automatically synchronized identical files to
	  revision 4962

2011-12-07 14:57  roevdmei

	* [r4944] ft_specest_hilbert.m: fixed reversal in hp and lp freqs. Works like a charm now

2011-12-07 14:39  roevdmei

	* [r4943] ft_specest_hilbert.m: updated specest_hilbert filters, and changed status in
	  ft_freqanalysis to non-devel

2011-11-30 17:24  roevdmei

	* [r4904] ft_specest_hilbert.m: added support for variable filterorders, for when using FIR
	  filters

2011-11-30 17:20  roevdmei

	* [r4903] ft_specest_tfr.m: finished renaming specest_convol to specest_tfr, and deprecated
	  freqanalysis_tfr (JM, sorry I didn't wait for your email ;), I realized I accidentally
	  went through already with some of the changes, so I went ahead and changed the rest to
	  complete it)

2011-11-30 17:17  roevdmei

	* [r4902] ft_specest_hilbert.m: add fbopt to extraction out of key-value pairs

2011-11-30 16:45  roevdmei

	* [r4900] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_tfr.m, ft_specest_wavelet.m: renamed specest_convol to
	  tfr, and updated other specest help to reflect this

2011-11-30 16:44  roevdmei

	* [r4899] ft_specest_convol.m: updated to reflect specest_wavelet, but then in the
	  time-domain

2011-11-30 16:23  roevdmei

	* [r4897] ft_specest_hilbert.m: added new verbose option, updated help, updated progress
	  indication

2011-11-30 15:46  roevdmei

	* [r4893] ft_specest_wavelet.m: added verbose option and updated progress indication

2011-11-26 18:02  marvin

	* [r4814] ft_specest_mtmconvol.m: added option to put parameter (to be used in WINDOW) for
	  taper

2011-11-10 09:23  borreu

	* [r4702] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_wavelet.m: bugfix #1113 - replaced CVS $Log$ messages with
	  SVN $Id$.

2011-10-29 10:10  roboos

	* [r4624] private/alpha_taper.m, private/bilinear.m, private/butter.m, private/filtfilt.m,
	  private/ft_getopt.mexa64, private/ft_getopt.mexglx, private/ft_getopt.mexmaci,
	  private/ft_getopt.mexmaci64, private/ft_getopt.mexw32, private/ft_getopt.mexw64,
	  private/keyval.m, private/keyvalcheck.m, private/postpad.m, private/sftrans.m,
	  private/sine_taper.m, private/sine_taper_scaled.m, private/warning_once.m: cleaned up the
	  svn properties according to development/svn on the wiki
	  this ensures that m files are not executable and that Rev and Id are correctly replaced

2011-10-09 10:52  roboos

	* [r4394] private/ft_getopt.m, private/ft_getopt.mexa64, private/ft_getopt.mexglx,
	  private/ft_getopt.mexmaci, private/ft_getopt.mexmaci64, private/ft_getopt.mexw32,
	  private/ft_getopt.mexw64: restructuring - added the ft_getopt m and mex files to the
	  private directories of the modules, see bug #502

2011-10-09 10:49  roboos

	* [r4393] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_wavelet.m: restructuring and bugfix - replaced all keyval
	  calls by ft_getopt, see bug #502. Also made some improvements to the documentation.
	  Furthermore, I noticed some cases of mixed up handling of the 'polyremoval'/'polyorder'
	  argument. See bug #502 and http://bugzilla.fcdonders.nl/show_bug.cgi?id=1024

2011-10-06 12:09  roevdmei

	* [r4364] ft_specest_convol.m: updated convol to current status of the other specest
	  functions

2011-09-12 10:25  jansch

	* [r4156] ft_specest_mtmconvol.m: bugfix - #873

2011-09-06 10:57  vlalit

	* [r4110] ft_specest_hilbert.m: added verbose option

2011-09-06 10:55  vlalit

	* [r4108] private/warning_once.m: replace also full stops with _

2011-09-05 14:23  vlalit

	* [r4105] ft_specest_hilbert.m: give a warning and adjust freqoi when excluding frequencies

2011-07-09 18:47  vlalit

	* [r3816] private/hilbert.m: added spm_hilbert without toolbox dependency.

2011-07-06 18:58  roboos

	* [r3783] test: enhancement - added test directory for fieldtrip main and standard modules

2011-07-01 08:02  jansch

	* [r3752] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_wavelet.m: functionality change - #225 built in default
	  detrending (removal of polynomial fit of order 1) prior to doing spectral analysis.this
	  can be overruled (or changed to a polynome of different order) by means of the cfg option
	  polyremoval

2011-07-01 07:54  jansch

	* [r3751] private/ft_preproc_polyremoval.m: enhancement - added ft_preproc_polyremoval to
	  specest/private

2011-06-24 13:48  eelspa

	* [r3730] ft_specest_mtmconvol.m: added option 'verbose' to ft_specest_mtmconvol to allow
	  suppression of console output

2011-05-25 08:11  jansch

	* [r3576] private/warning_once.m: bugfix - added warning_once to specest/private

2011-05-18 09:56  jansch

	* [r3558] ft_specest_mtmfft.m: enhancement - changed warning into warning_once

2011-04-29 10:24  jansch

	* [r3404] ft_specest_mtmconvol.m, ft_specest_mtmfft.m, private/sine_taper.m,
	  private/sine_taper_scaled.m: removed the default scaling of the sine_taper for the
	  computation of power. This makes the sine_taper consistent with the other tapers.
	  implemented a scaled sine taper for backward compatibility (cfg.taper = 'sine_old')

2011-04-20 18:17  roevdmei

	* [r3367] ft_specest_wavelet.m: changed phase convention to fit with mtmconvol

2011-04-05 19:27  roboos

	* [r3298] ft_specest_mtmfft.m: bugfix - typo, removed bracket from code

2011-04-05 19:26  roboos

	* [r3297] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_wavelet.m: bugfix - the sampling frequency that is
	  computed should not be rounded off to an integer number

2011-04-01 09:42  roboos

	* [r3263] ft_specest_mtmconvol.m, ft_specest_mtmfft.m: bugfix - related to ft_progress being
	  initialized in ft_freqanalysis, check the length of the stack prior to indexing the 2nd
	  argument

2011-03-24 14:06  roboos

	* [r3206] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_wavelet.m: cleaned up the specest functions, removed
	  whitespace and empty lines, some small changes in documentation and added log and
	  copyrights
	  no functional changes

2011-03-17 23:49  roevdmei

	* [r3162] ft_specest_hilbert.m, ft_specest_mtmconvol.m, ft_specest_wavelet.m: added a round
	  when computing endnsample, in the rare case that the time-vector contains errors, or when
	  numerical precision causes it to be a near-integer

2011-03-16 09:10  jansch

	* [r3117] ft_specest_mtmconvol.m, ft_specest_mtmfft.m: fixed bug related to variable length
	  trials in combination with keeptrials = 'no', leading to the sum over trials not being
	  correctly normalised. introduced option to suppress feedback to screen for mtmfft and
	  mtmconvol methods

2011-02-19 07:59  roevdmei

	* [r2909] ft_specest_convol.m, ft_specest_mtmconvol.m, ft_specest_mtmfft.m,
	  ft_specest_wavelet.m: fixed bug that causes duplicate frequency bins to be selected from
	  the output when freqois were not proper

2011-02-16 09:41  roboos

	* [r2885] private/alpha_taper.m, private/bilinear.m, private/butter.m, private/filtfilt.m,
	  private/keyval.m, private/keyvalcheck.m, private/postpad.m, private/sftrans.m,
	  private/sine_taper.m: svn propset svn:keyword "Id Rev" xxx.m

2011-02-12 17:51  roboos

	* [r2861] private/alpha_taper.m, private/bilinear.m, private/butter.m, private/filtfilt.m,
	  private/keyval.m, private/keyvalcheck.m, private/postpad.m, private/sftrans.m,
	  private/sine_taper.m: set the property "autosync" on all files that are copies of the
	  previous file externals

2011-02-12 17:49  roboos

	* [r2860] private/alpha_taper.m, private/bilinear.m, private/butter.m, private/filtfilt.m,
	  private/keyval.m, private/keyvalcheck.m, private/postpad.m, private/sftrans.m,
	  private/sine_taper.m: replaced all old file externals with a copy of the oiriginal file

2011-02-12 17:19  roboos

	* [r2859] private: deleted all svn:external properties
	  preparing a new implementation of the replicated files using an svn hook

2011-02-03 21:57  roboos

	* [r2803] private: fourth pass for the svn:externals

2011-02-03 21:45  roboos

	* [r2802] private: third pass at setting the new svn:externals for all files

2011-02-03 21:08  roboos

	* [r2800] private: recreated the svn:externals for all directories
	  all pointing towards branches/externals or trunk/src
	  this is the first pass, more passes may have to follow

2011-02-03 12:01  roboos

	* [r2788] private/alpha_taper.m, private/sine_taper.m: removed all actual occurences of *.m
	  files that are used elsewhere as externals
	  the files have been moved to the branches/externals and all svn:externals will have to be
	  reset to use that location

2011-02-03 11:41  roboos

	* [r2784] private, private/butter.m: turned out that there were three files replicated
	  instead of svn:external'ed
	  butter, tinv, tcdf
	  fixed the butter.m

2011-02-03 10:48  roboos

	* [r2781] private/butter.m, private/filter_with_correction.m,
	  private/ft_preproc_bandpassfilter.m: cleanup of the special properties of all files, such
	  as execute property, eol-style and keywords

2011-01-14 08:54  roevdmei

	* [r2579] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_wavelet.m: rounded fsample calculation in all functions,
	  as machine-precision errors occur easily with computed sampling rates as: 300.000000001

2011-01-06 13:26  roevdmei

	* [r2534] private/butter.m, private/filter_with_correction.m,
	  private/ft_preproc_bandpassfilter.m: added file externals for specest_hilbert

2011-01-06 13:09  roevdmei

	* [r2533] ft_specest_wavelet.m: made the switch from wltconvol to wavelet, and made all the
	  necessary changes

2010-12-21 14:54  roevdmei

	* [r2501] ft_specest_wavelet.m: minor documentation change

2010-12-21 14:41  roevdmei

	* [r2497] ft_specest_hilbert.m: further developed
	  
	  ~This line, and those below, will be ignored--
	  
	  M ft_specest_hilbert.m

2010-12-21 14:36  roevdmei

	* [r2496] ft_specest_wavelet.m: refixed the time-bin selection

2010-12-21 12:51  roevdmei

	* [r2493] ft_specest_hilbert.m: fixed time-bins selection

2010-12-21 12:50  roevdmei

	* [r2492] ft_specest_wavelet.m: corrected time-bin selection

2010-12-21 11:25  roevdmei

	* [r2491] ft_specest_wavelet.m: function is now fully ready for implementation

2010-12-20 14:38  roevdmei

	* [r2484] ft_specest_wavelet.m: nearly prepared for full implementation

2010-12-20 14:02  roevdmei

	* [r2483] ft_specest_mtmconvol.m: fixed bug with selecting time-points

2010-12-20 11:13  roevdmei

	* [r2479] ft_specest_mtmconvol.m: fixed small bag in nan creation

2010-11-27 11:55  roboos

	* [r2212] ft_specest_convol.m, ft_specest_mtmconvol.m, ft_specest_mtmfft.m,
	  ft_specest_wavelet.m, private/hanning.m: fixed the svn properties (eol-style, executable,
	  keywords) on many *.m files

2010-11-24 15:20  roevdmei

	* [r2169] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_wavelet.m: switched to the new implementation of mtmconvol
	  and mtmfft *fingers crossed*

2010-11-22 13:37  roevdmei

	* [r2146] ft_specest_mtmwelch.m, ft_specest_mvar.m, ft_specest_nanfft.m, ft_specest_tfr.m,
	  ft_specest_wltconvol.m: removed functions from /specest module that should not be in here

2010-11-22 12:11  jansch

	* [r2144] ft_specest_convol.m, ft_specest_hilbert.m, ft_specest_mtmconvol.m,
	  ft_specest_mtmfft.m, ft_specest_mtmwelch.m, ft_specest_mvar.m, ft_specest_nanfft.m,
	  ft_specest_tfr.m, ft_specest_wavelet.m, ft_specest_wltconvol.m, private/alpha_taper.m,
	  private/sine_taper.m, specest_convol.m, specest_hilbert.m, specest_mtmconvol.m,
	  specest_mtmfft.m, specest_mtmwelch.m, specest_mvar.m, specest_nanfft.m, specest_tfr.m,
	  specest_wavelet.m, specest_wltconvol.m: ft_ prefixed functions

2010-11-18 13:31  roevdmei

	* [r2127] specest_mtmconvol.m: added new dimord key-value and respective code for
	  memory-optimized output

2010-11-17 14:15  jansch

	* [r2125] specest_mtmconvol.m, specest_mtmfft.m: added call to hanning-function (rather than
	  using matlab's window function) to create hanning-tapers. this is now a function in
	  specest/private and bypasses the signal processing toolbox

2010-11-17 14:12  jansch

	* [r2124] private, private/hanning.m: added drop in replacement for signal processing
	  toolbox hanning function

2010-11-02 15:58  roevdmei

	* [r2032] specest_mtmconvol.m: added some documentation

2010-11-02 15:28  roevdmei

	* [r2030] specest_mtmconvol.m: added documentation

2010-11-02 15:14  roevdmei

	* [r2029] specest_mtmconvol.m: added some old code for testing

2010-11-02 10:42  roevdmei

	* [r2023] specest_mtmfft.m: removed old references

2010-11-02 10:42  roevdmei

	* [r2022] specest_wavelet.m: removed old references

2010-11-02 10:41  roevdmei

	* [r2021] specest_hilbert.m: removed old references

2010-11-02 10:40  roevdmei

	* [r2020] specest_mtmconvol.m: removed old references

2010-10-15 09:47  jansch

	* [r1933] specest_mtmconvol.m: adjusted the wavelets such that in wavelets with an even
	  number of samples the 0-angle is in the middle (i.e. in between the 2 centre samples)

2010-10-15 08:15  jansch

	* [r1930] ., specest_convol.m, specest_hilbert.m, specest_mtmconvol.m, specest_mtmfft.m,
	  specest_mtmwelch.m, specest_mvar.m, specest_nanfft.m, specest_tfr.m, specest_wavelet.m,
	  specest_wltconvol.m: moved specest_xxx to specest module