updated formatting of function help

specest/ft_specest_hilbert.m

@@ -1,29 +1,30 @@
-function [spectrum,freqoi,timeoi] = ft_specest_hilbert(dat, time, varargin)
+function [spectrum, freqoi, timeoi] = ft_specest_hilbert(dat, time, varargin)
 
 % FT_SPECEST_HILBERT performs a spectral estimation of data by repeatedly applying a
 % bandpass filter and then doing a Hilbert transform.
 %
 % Use as
-%   [spectrum,freqoi,timeoi] = ft_specest_hilbert(dat,time,...)
-% where
+%   [spectrum, freqoi, timeoi] = ft_specest_hilbert(dat, time, ...)
+% where the input arguments are
 %   dat       = matrix of chan*sample
 %   time      = vector, containing time in seconds for each sample
-%   spectrum  = matrix of chan*freqoi*timeoi of fourier coefficients
+% and the output arguments are
+%   spectrum  = matrix of nchan*nfreq*ntime of fourier coefficients
 %   freqoi    = vector of frequencies in spectrum
 %   timeoi    = vector of timebins in spectrum
 %
 % Optional arguments should be specified in key-value pairs and can include
 %   timeoi     = vector, containing time points of interest (in seconds)
 %   freqoi     = vector, containing frequencies (in Hz)
 %   pad        = number, indicating time-length of data to be padded out to in seconds (split over pre/post; used for spectral interpolation, NOT filtering)
-%   padtype    = string, indicating type of padding to be used (see ft_preproc_padding, default: zero)
+%   padtype    = string, indicating type of padding to be used, can be 'zero', 'mean', 'localmean', 'edge', or 'mirror' (default = 'zero')
 %   width      = number or vector, width of band-pass surrounding each element of freqoi
 %   filttype   = string, filter type, 'but', 'firws', 'fir', 'firls'
 %   filtorder  = number or vector, filter order
-%   filtdir    = string, filter direction, 'onepass', 'onepass-reverse', 'twopass', 'twopass-reverse', 'twopass-average', 'onepass-zerophase', 'onepass-reverse-zerophase', 'onepass-minphase'
-%   verbose    = output progress to console (0 or 1, default 1)
-%   polyorder  = number, the order of the polynomial to fitted to and removed from the data prior to the fourier transform (default = 0 -> remove DC-component)
+%   filtdir    = string, filter direction, 'onepass', 'onepass-reverse', 'onepass-zerophase', 'onepass-reverse-zerophase', 'onepass-minphase', 'twopass', 'twopass-reverse', 'twopass-average'
 %   edgeartnan = 0 (default) or 1, replace edge artifacts due to filtering with NaNs (only applicable for filttype = 'fir'/'firls'/'firws')
+%   polyorder  = number, the order of the polynomial to fitted to and removed from the data prior to the fourier transform (default = 0 -> remove DC-component)
+%   verbose    = output progress to console (0 or 1, default 1)
 %
 % See also FT_FREQANALYSIS, FT_SPECEST_MTMFFT, FT_SPECEST_TFR, FT_SPECEST_MTMCONVOL, FT_SPECEST_WAVELET
 

specest/ft_specest_mtmconvol.m

@@ -1,31 +1,31 @@
-function [spectrum,ntaper,freqoi,timeoi] = ft_specest_mtmconvol(dat, time, varargin)
+function [spectrum, ntaper, freqoi, timeoi] = ft_specest_mtmconvol(dat, time, varargin)
 
 % FT_SPECEST_MTMCONVOL performs wavelet convolution in the time domain by
 % multiplication in the frequency domain.
 %
 % Use as
-%   [spectrum,ntaper,freqoi,timeoi] = ft_specest_mtmconvol(dat,time,...)
-% where input
+%   [spectrum, ntaper, freqoi, timeoi] = ft_specest_mtmconvol(dat, time, ...)
+% where the input arguments are
 %   dat       = matrix of chan*sample
 %   time      = vector, containing time in seconds for each sample
-% and output
+% and the ouitput arguments are
 %   spectrum  = matrix of ntaper*chan*freqoi*timeoi of fourier coefficients
 %   ntaper    = vector containing the number of tapers per freqoi
 %   freqoi    = vector of frequencies in spectrum
 %   timeoi    = vector of timebins in spectrum
 %
 % Optional arguments should be specified in key-value pairs and can include
-%   taper     = 'dpss', 'hanning' or many others, see WINDOW (default = 'dpss')
-%   pad       = number, indicating time-length of data to be padded out to in seconds
-%   padtype   = string, indicating type of padding to be used (see ft_preproc_padding, default: zero)
+%   freqoi    = vector, containing frequencies (in Hz)
 %   timeoi    = vector, containing time points of interest (in seconds)
 %   timwin    = vector, containing length of time windows (in seconds)
-%   freqoi    = vector, containing frequencies (in Hz)
+%   taper     = 'dpss', 'hanning' or many others, see WINDOW (default = 'dpss')
+%   taperopt  = additional taper options to be used in the WINDOW function, see WINDOW
 %   tapsmofrq = number, the amount of spectral smoothing through multi-tapering. Note: 4 Hz smoothing means plus-minus 4 Hz, i.e. a 8 Hz smoothing box
+%   pad       = number, indicating time-length of data to be padded out to in seconds
+%   padtype   = string, indicating type of padding to be used (see ft_preproc_padding, default: zero)
 %   dimord    = 'tap_chan_freq_time' (default) or 'chan_time_freqtap' for memory efficiency
-%   verbose   = output progress to console (0 or 1, default 1)
-%   taperopt  = additional taper options to be used in the WINDOW function, see WINDOW
 %   polyorder = number, the order of the polynomial to fitted to and removed from the data prior to the fourier transform (default = 0 -> remove DC-component)
+%   verbose   = output progress to console (0 or 1, default 1)
 %
 % See also FT_FREQANALYSIS, FT_SPECEST_MTMFFT, FT_SPECEST_TFR, FT_SPECEST_HILBERT, FT_SPECEST_WAVELET
 
@@ -66,18 +66,19 @@
 polyorder = ft_getopt(varargin, 'polyorder', 0);
 tapopt    = ft_getopt(varargin, 'taperopt');
 
-if isempty(fbopt),
+if isempty(fbopt)
   fbopt.i = 1;
   fbopt.n = 1;
 end
 
 % throw errors for required input
-if isempty(tapsmofrq) && strcmp(taper, 'dpss')
-  ft_error('you need to specify tapsmofrq when using dpss tapers')
+if ismember(taper, {'dpss', 'sine', 'sine_old'}) && isempty(tapsmofrq)
+  % these are multitapering methods
+  ft_error('you need to specify tapsmofrq when using %s tapers', taper)
 end
 if isempty(timwin)
   ft_error('you need to specify timwin')
-elseif (length(timwin) ~= length(freqoi) && ~strcmp(freqoi,'all'))
+elseif ~strcmp(freqoi,'all') && length(timwin)~=length(freqoi)
   ft_error('timwin should be of equal length as freqoi')
 end
 
@@ -107,7 +108,7 @@
 end
 postpad    = round((pad - dattime) * fsample);
 endnsample = round(pad * fsample);  % total number of samples of padded data
-endtime    = pad;            % total time in seconds of padded data
+endtime    = pad;                   % total time in seconds of padded data
 
 % Set freqboi and freqoi
 freqoiinput = freqoi;
@@ -120,16 +121,15 @@
   freqboi    = freqboilim(1):1:freqboilim(2);
   freqoi     = (freqboi-1) ./ endtime;
 end
+
 % check for freqoi = 0 and remove it, there is no wavelet for freqoi = 0
 if freqoi(1)==0
   freqoi(1)  = [];
-  freqboi(1) = [];
   if length(timwin) == (length(freqoi) + 1)
     timwin(1) = [];
   end
 end
-nfreqboi = length(freqboi);
-nfreqoi  = length(freqoi);
+nfreqoi = length(freqoi);
 
 % throw a warning if input freqoi is different from output freqoi
 if isnumeric(freqoiinput)
@@ -177,7 +177,6 @@
 end
 timwinsample = round(timwin .* fsample);
 
-
 % determine whether tapers need to be recomputed
 current_argin = {time, postpad, taper, timwinsample, tapsmofrq, freqoi, timeoi, tapopt}; % reasoning: if time and postpad are equal, it's the same length trial, if the rest is equal then the requested output is equal
 if isequal(current_argin, previous_argin)

specest/ft_specest_mtmfft.m

@@ -1,26 +1,27 @@
-function [spectrum,ntaper,freqoi] = ft_specest_mtmfft(dat, time, varargin)
+function [spectrum, ntaper, freqoi] = ft_specest_mtmfft(dat, time, varargin)
 
 % FT_SPECEST_MTMFFT computes a fast Fourier transform using multitapering with
 % multiple tapers from the DPSS sequence or using a variety of single tapers.
 %
 % Use as
-%   [spectrum,ntaper,freqoi] = ft_specest_mtmfft(dat,time...)
-% where
+%   [spectrum, ntaper, freqoi] = ft_specest_mtmfft(dat, time, ...)
+% where the input arguments are
 %   dat        = matrix of chan*sample
 %   time       = vector, containing time in seconds for each sample
-%   spectrum   = matrix of taper*chan*freqoi of fourier coefficients
+% and the output arguments are
+%   spectrum   = matrix of ntaper*nchan*nfreq of fourier coefficients
 %   ntaper     = vector containing number of tapers per element of freqoi
 %   freqoi     = vector of frequencies in spectrum
 %
 % Optional arguments should be specified in key-value pairs and can include
-%   taper      = 'dpss', 'hanning' or many others, see WINDOW (default = 'dpss')
-%   pad        = number, total length of data after zero padding (in seconds)
-%   padtype    = string, indicating type of padding to be used (see ft_preproc_padding, default: zero)
 %   freqoi     = vector, containing frequencies of interest
+%   taper      = 'dpss', 'hanning' or many others, see WINDOW (default = 'dpss')
+%   taperopt   = additional taper options to be used in the WINDOW function, see WINDOW
 %   tapsmofrq  = the amount of spectral smoothing through multi-tapering. Note: 4 Hz smoothing means plus-minus 4 Hz, i.e. a 8 Hz smoothing box
-%   dimord     = 'tap_chan_freq' (default) or 'chan_time_freqtap' for memory efficiency (only when use variable number slepian tapers)
+%   pad        = number, total length of data after zero padding (in seconds)
+%   padtype    = string, indicating type of padding to be used, can be 'zero', 'mean', 'localmean', 'edge', or 'mirror' (default = 'zero')
+%   dimord     = 'tap_chan_freq' (default) or 'chan_time_freqtap' for memory efficiency (only when using variable number of slepian tapers)
 %   polyorder  = number, the order of the polynomial to fitted to and removed from the data prior to the fourier transform (default = 0 -> remove DC-component)
-%   taperopt   = additional taper options to be used in the WINDOW function, see WINDOW
 %   verbose    = output progress to console (0 or 1, default 1)
 %
 % See also FT_FREQANALYSIS, FT_SPECEST_MTMCONVOL, FT_SPECEST_TFR, FT_SPECEST_HILBERT, FT_SPECEST_WAVELET

specest/ft_specest_neuvar.m

@@ -1,19 +1,22 @@
 function [spectrum, freqoi] = ft_specest_neuvar(dat, time, varargin)
 
-% FT_SPECEST_NEUVAR computes a time-domain estimation of overall signal 
-% power, having compensated for the 1/f distribution of spectral content.
+% FT_SPECEST_NEUVAR computes a time-domain estimation of overall signal power, having
+% compensated for the 1/f distribution of spectral content.
 %
 % Use as
-%   [spectrum,ntaper,freqoi] = ft_specest_neuvar(dat,time...)
-% where
+%   [spectrum, freqoi] = ft_specest_neuvar(dat, time...)
+% where the input arguments are
 %   dat        = matrix of chan*sample
 %   time       = vector, containing time in seconds for each sample
-%   neuvar     = matrix of chan*neuvar
+% and the output arguments are
+%   spectrum   = matrix of chan*neuvar
+%   freqoi     = vector of frequencies in spectrum
 %
 % Optional arguments should be specified in key-value pairs and can include
-%   order      = number, the order of differentation for compensating for the 1/f (default: 1)
+%   order      = number, the order of differentation for compensating for the 1/f (default = 1)
 %   pad        = number, total length of data after zero padding (in seconds)
-%   padtype    = string, indicating type of padding to be used (see ft_preproc_padding, default: 0)
+%   padtype    = string, indicating type of padding to be used, can be 'zero', 'mean', 'localmean', 'edge', or 'mirror' (default = 'zero')
+%   polyorder  = number, the order of the polynomial to fitted to and removed from the data prior to the Fourier transform (default = 0, which removes the DC-component)
 %   verbose    = output progress to console (0 or 1, default 1)
 %
 % See also FT_FREQANALYSIS, FT_SPECEST_MTMFFT, FT_SPECEST_MTMCONVOL, FT_SPECEST_TFR, FT_SPECEST_HILBERT, FT_SPECEST_WAVELET
@@ -44,6 +47,7 @@
 pad       = ft_getopt(varargin, 'pad');
 padtype   = ft_getopt(varargin, 'padtype', 'zero');
 fbopt     = ft_getopt(varargin, 'feedback');
+polyorder = ft_getopt(varargin, 'polyorder', 1);
 verbose   = ft_getopt(varargin, 'verbose', true);
 
 if isempty(fbopt)
@@ -55,7 +59,7 @@
 dat = cast(dat, 'double');
 
 % Set n's
-[nchan,ndatsample] = size(dat);
+[nchan, ndatsample] = size(dat);
 
 % This does not work on integer data
 if ~isa(dat, 'double') && ~isa(dat, 'single')
@@ -66,13 +70,20 @@
 fsample = 1./mean(diff(time));
 dattime = ndatsample / fsample; % total time in seconds of input data
 
+% remove polynomial fit from the data -> default is demeaning
+if polyorder >= 0
+  dat = ft_preproc_polyremoval(dat, polyorder, 1, ndatsample);
+end
+
 % Zero padding
 if round(pad * fsample) < ndatsample
   ft_error('the padding that you specified is shorter than the data');
 end
+
 if isempty(pad) % if no padding is specified padding is equal to current data length
   pad = dattime;
 end
+
 postpad    = ceil((pad - dattime) * fsample);
 endnsample = round(pad * fsample);  % total number of samples of padded data
 endtime    = pad;                   % total time in seconds of padded data
@@ -90,5 +101,5 @@
   fprintf([str, '\n']);
 end
 spectrum = var(ft_preproc_padding(dat, padtype, 0, postpad), [], 2)'; % freq X chan
-spectrum = sqrt(spectrum); % take square root since cfg.output = 'pow' assumes the output is amplitude and squares it 
+spectrum = sqrt(spectrum); % take square root since cfg.output = 'pow' assumes the output is amplitude and squares it
 freqoi = 0; % assign to DC frequency

specest/ft_specest_tfr.m

@@ -5,11 +5,12 @@
 % domain.
 %
 % Use as
-%   [spectrum,freqoi,timeoi] = ft_specest_convol(dat,time,...)
-% where
-%   dat       = matrix of chan*sample
+%   [spectrum, freqoi, timeoi] = ft_specest_convol(dat, time, ...)
+% where the input arguments are
+%   dat       = matrix of nchan*nsample
 %   time      = vector, containing time in seconds for each sample
-%   spectrum  = array of chan*freqoi*timeoi of fourier coefficients
+% and the output arguments are
+%   spectrum  = array of nchan*nfreq*ntime of fourier coefficients
 %   freqoi    = vector of frequencies in spectrum
 %   timeoi    = vector of timebins in spectrum
 %
@@ -18,8 +19,8 @@
 %   freqoi    = vector, containing frequencies (in Hz)
 %   width     = number or vector, width of the wavelet, determines the temporal and spectral resolution (default = 7)
 %   gwidth    = number, determines the length of the used wavelets in standard deviations of the implicit Gaussian kernel
-%   verbose   = output progress to console (0 or 1, default 1)
 %   polyorder = number, the order of the polynomial to fitted to and removed from the data prior to the fourier transform (default = 0 -> remove DC-component)
+%   verbose   = output progress to console (0 or 1, default 1)
 %
 % See also FT_FREQANALYSIS, FT_SPECEST_MTMFFT, FT_SPECEST_MTMCONVOL, FT_SPECEST_HILBERT, FT_SPECEST_NANFFT, FT_SPECEST_WAVELET
 

specest/ft_specest_wavelet.m

@@ -1,27 +1,28 @@
-function [spectrum,freqoi,timeoi] = ft_specest_wavelet(dat, time, varargin)
+function [spectrum, freqoi, timeoi] = ft_specest_wavelet(dat, time, varargin)
 
 % FT_SPECEST_WAVELET performs time-frequency analysis on any time series trial data
 % using the 'wavelet method' based on Morlet wavelets, doing convolution in the time
 % domain by multiplication in the frequency domain.
 %
 % Use as
-%   [spectrum,freqoi,timeoi] = ft_specest_wavelet(dat,time...)
-% where
+%   [spectrum, freqoi, timeoi] = ft_specest_wavelet(dat, time, ...)
+% where the input arguments are
 %   dat       = matrix of chan*sample
 %   time      = vector, containing time in seconds for each sample
+% and the output arguments are
 %   spectrum  = array of chan*freqoi*timeoi of fourier coefficients
 %   freqoi    = vector of frequencies in spectrum
 %   timeoi    = vector of timebins in spectrum
 %
 % Optional arguments should be specified in key-value pairs and can include
-%   pad       = number, total length of data after zero padding (in seconds)
-%   padtype   = string, indicating type of padding to be used (see ft_preproc_padding, default = 'zero')
-%   freqoi    = vector, containing frequencies of interest
 %   timeoi    = vector, containing time points of interest (in seconds)
+%   freqoi    = vector, containing frequencies of interest
 %   width     = number or vector, width of the wavelet, determines the temporal and spectral resolution
 %   gwidth    = number, determines the length of the used wavelets in standard deviations of the implicit Gaussian kernel
-%   verbose   = output progress to console (0 or 1, default 1)
+%   pad       = number, total length of data after zero padding (in seconds)
+%   padtype   = string, indicating type of padding to be used, can be 'zero', 'mean', 'localmean', 'edge', or 'mirror' (default = 'zero')
 %   polyorder = number, the order of the polynomial to fitted to and removed from the data prior to the fourier transform (default = 0 -> remove DC-component)
+%   verbose   = output progress to console (0 or 1, default 1)
 %
 % See also FT_FREQANALYSIS, FT_SPECEST_MTMCONVOL, FT_SPECEST_TFR, FT_SPECEST_HILBERT, FT_SPECEST_MTMFFT
 
@@ -148,7 +149,6 @@
   end
 end
 
-
 % Creating wavelets
 % expand width to array if constant width
 if numel(width) == 1
@@ -203,7 +203,6 @@
 
 end
 
-
 % Compute fft
 spectrum = complex(nan(nchan,nfreqoi,ntimeboi),nan(nchan,nfreqoi,ntimeboi));
 datspectrum = fft(ft_preproc_padding(dat, padtype, 0, postpad), [], 2);
@@ -230,4 +229,3 @@
     spectrum(:,ifreqoi,reqtimeboiind) = dum(:,reqtimeboi);
   end
 end
-