| TIMEFDETAILS | Details of the timef function parameters for time/frequency analysis of event-related 1-channel multi-epoch data. |
| Global description: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% timef performs either FFT-based or wavelet DFT time/frequency averaging. The wavelets are N-cycle Hanning-windowed sinusoids. (Note: To change the windowing to gauss, etc., see line 258 of timef.m). The two image panels of the output plot show, respectively, the event-related spectral perturbation (ERSP) and inter-trial coherence (ITC) of the input data. |
| THE ERSP: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% (S. Makeig, Electroencephalogr Clin Neurophysiol 86:283-93, 1993) shows log deviations from epoch-mean (or baseline period-mean) power at each frequency. If bootstrap statistics are computed (via the alpha input parameter), points with non-significant differences from 0 are colored green (0, but not in the output ersp variable - use the output erspboot variable to re-mask if desired). The thin bottom panel shows the ERSP envelope (the most positive and most negative values at each output time point). The thin left panel shows the mean (or baseline) log spectrum (blue trace). If bootstrap statistics are computed, the left panel (green trace) also shows the bootstrap significant levels (+/-) at each frequency. |
| THE ITC: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% (Inter-trial Coherence, cf. Tallon-Buadry "Phase-locking factor") The lower panel shows the degree of tendency for the data phase at each frequency to be in the same phase in each trial. If bootstrap statistics are computed (as per the alpha input parameter), non-significant points are colored green (0 -- but not in the itc output variable - use the itcboot output to re-mask if desired in later plotting). The lower thin panel shows the time-domain average of the input data (blue) against a zero-line (green). The output average is created principally by the resets to constant phase shown in the ITC. (While phase resets dominate, amplitude changes shown in the ERSP may also play a role). The left thin panel shows the frequency mean ITC (blue trace) and, if bootstrap statistics are computed, the ITC significance limits at each frequency (green trace). ITC math: By definition, coherence R = mean(Pxy/(abs(Pxx)*abs(Pyy))) where Pxy is the cross-spectrum and Pxx and Pyy the autospectra of processes x and y. Here, we consider y to be a stimulus-locked process such that, at each time and frequency, angle(Pyy) = 0 and abs(Pyy) = 1. Thus Pxy = Pxx, and the (complex) inter-trial coherence between x and the completely stimulus-locked process y is ITC = mean(Pxx/abs(Pxx)). |
| USAGE: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% >> [ersp,itc,powbase,times,freqs,erspboot,itcboot] = timef(data,frames,tlimits,titl, srate,cycles,winsize,timesout, padratio,maxfreq,tvec,eloc_file, alpha,marktimes,powbase,pboot,rboot); |
| INPUTS: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
data |
single-channel (1,frames*nepochs) data {none} |
frames |
frames per epoch {768}. Here, a frame is a data point (one channel at one time point) and the data is assumed to be composed of concatenated epochs of the same length (frames). |
tlimits |
epoch time limits (ms) [mintime maxtime]{[-1000 2000]} These should be the starting and ending times of the input epochs. |
titl |
figure title {none} |
srate |
data sampling rate (Hz) {256} This is sample rate per channel (i.e., data frames per second). |
cycles |
>0 -> number of cycles in each analysis window =0 -> use FFT (constant window length) {0} Here, the user chooses either to use the FFT method (fixed window size for all frequencies) or the wavelet DFT method (the data window length depends inversely on the frequency, e.g. '3' means that the data windows will each be three cycles wide (at each frequency). A higher number here (e.g., '5') will narrow the frequency band and widen the time window. |
winsize |
subepoch length: determines the lowest output frequency cycles=0: data subwindow length (2^k |
timesout |
number of output times (int |
padratio |
if cycles==0, FFT-length/winsize (2^k) {2} if cycles >0, analysis frequencies per Hz. This factor multiplies the number of output frequencies. In the FFT method (cycles=0), this is done by zero-padding each analysis window. In the wavelet DFT method (cycles>0), this gives the number of frequencies per Hz. |
maxfreq |
maximum frequency to plot (Hz) {50} |
tvec |
scalp topography (map) to plot {[]} |
eloc_file |
electrode location file for scalp map {no default} ascii file in format of >> topoplot example This is an optional map-plotting feature. Given an input map vector (one weight at each channel, and a electrode location file, timef plots a topoplote 2-d scalp map on the left side of the figure. |
alpha |
Two-tailed bootstrap significance prob. level {none} Sets n.s. plotted output values to green (0). This is optional, and lengthens the computation time. It gives bootstrap estimates of which ERSP and ITC values are significantly different from 0, by setting to 0 (green) all non-significant values in the ERSP and ITC images. Normal values for alpha are 0 (or no argument) -> no bootstrap computation, or 0.02 (which should allow about 2% of random images to appear "significant" (non-green)) |
marktimes |
times to mark with a dotted vertical line{def|nan->none} Use this to add extra vertical dashed lines at significant times in the epoch. Time 0 is marked by default. |
powbase |
baseline spectrum to log-subtract {def|nan->from data} This is useful only when you want to use a known baseline spectrum (e.g. from another condition) instead of using the actual mean baseline spectrum of the data. Otherwise, leave this out or as 'nan' (not a number). |
pboot |
bootstrap power limits (cf. timef out){def|nan -> from data} |
rboot |
bootstrap ITC limits (cf. timef out) {def|nan -> from data} This is useful if you want to apply significance limits from another condition to new data. Else, leave these out or as 'nan'. |
| OUTPUTS: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
ersp |
log spectral differences from baseline (nfreqs,timesout) |
itc |
inter-trial coherencies (nfreqs,timesout) Note that when cycles=0, nfreqs is total number of FFT frequencies, which may include frequencies higher than maxfreq. When cycles>0, no extra (higher) frequencies are computed. |
powbase |
baseline power spectrum (in whole epoch or given baseline) |
times |
vector of output times (subwindow centers) in ms. |
freqs |
vector of frequency bin centers in Hz. |
erspboot |
[2,nfreqs] matrix of [lower;upper] ERSP significance diffs. |
itcboot |
[2,nfreqs] matrix of [lower;upper] ITC thresholds (not diffs). Note that the itcboot lower bound is practically meaningless. |
| CONSTANTS SET NEAR THE TOP OF timef.m: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
PLOT_ERSP |
1; % Flag plot of spectral perturb. (ERSP) (1/0) |
PLOT_ITC |
1; % Flag plot of inter-trial coherence (1/0) |
LINEWIDTH |
2; % Plot thick (2) or thin (1) traces (can be non-int) |
BASE_BOOT |
0; % 0 = bootstrap ERSP data drawn from whole epoch (def) % 1 = bootstrap ERSP data drawn from baseline only |
BASELINE_END |
200; % Window center times < this are in the baseline. |
NACCU |
200; % Number of bootstrap repetitions to accumulate |
ERSP_CAXIS_LIMIT |
5; % 0 -> use data limits; else positive value % giving symmetric +/- caxis limits. |
ITC_CAXIS_LIMIT |
0.5; % 0 -> use data limits; else positive value % giving symmetric +/- caxis limits. |
AXES_FONT |
10; % Axis text FontSize |
TITLE_FONT |
8; % Figure Title Font |
| History: | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% timef was coded by Sigurd Enghoff and Scott Makeig at The Salk Institute, La Jolla CA in August, 1998, using methods developed in the first reference above. |