ERPIMAGE	Plot a colored image of a collection of single-trial data epochs, optionally sorted on and/or aligned to an input sorting variable and smoothed across trials with a moving-average. (To return event-aligned data without plotting, use eegalign()). Optionally sort trials on value, amplitude or phase within a specified latency window. Optionally plot the ERP mean and std. dev.and moving-window spectral amplitude and inter-trial coherence at aselected or peak frequency. Optionally 'time warp' the single trial time-domain (potential) or power data to align the plotted data to a series of events with varying latencies that occur in each trial. Click on individual figures parts to examine them separately and zoom (using axcopy.
Usage:	>> figure; erpimage(data,[],times); % image trials in input order >> figure; [outdata,outvar,outtrials,limits,axhndls, erp,amps,cohers,cohsig,ampsig,outamps, phsangls,phsamp,sortidx,erpsig] = erpimage(data,sortvar,times,'title',avewidth,decimate, flag1,arg1, flag2,arg2, ...); % use options
Required input:
data	[vector or matrix] Single-channel input data to image. Formats (1,frames*trials) or (frames,trials)
Optional ordered inputs {with defaults}:
sortvar	[vector | []] Variable to sort epochs on (length(sortvar) = nepochs)
Example:	sortvar may by subject response time in each epoch (in ms) {default|[]: plot in input order}
times	[vector | []] vector of latencies (in ms) for each epoch time point. Else [startms ntimes srate] = [start latency (ms), time points (=frames) per epoch, sampling rate (Hz)]. Else [] -> 0:nframes-1 {default: []}
'title'	['string'] Plot title {default: none}
avewidth	Number of trials to smooth (vertically) with a moving-average
Note:	May be non-integer. {default|0 -> 1}
decimate	Factor to decimate|interpolate ntrials by (may be non-integer) Else, if this is large (> sqrt(ntrials)), output this many epochs. {default|0->1}
Optional unordered 'keyword',argument pairs:
Re-align data epochs:
'align'	[latency] Time-lock data to sortvar. Plot sortvar at given latency (in ms). Else Inf -> plot sortvar at median sortvar latency {default: do not align}
'timewarp'	{[events], [warpms], {colors}} Time warp ERP, amplitude and phase time-courses before smoothing. 'events' is a matrix whose columns specify the latencies (in ms) at which a series of successive events occur in each trial. 'warpms' is an optional vector of latencies (in ms) to which the series of events should be time locked. (Note: Epoch start and end should not be declared as events or warpms}. If 'warpms' is absent or [], the median of each 'events' column will be used. {colors} contains a list of Matlab linestyles to use for vertical lines marking the occurrence of the time warped events. If '', no line will be drawn for this event column. If fewer colors than event columns, cycles through the given color labels. Note: Not compatible with 'vert' (below).
'renorm'	['yes'|'no'| formula] Normalize sorting variable to epoch
latency range and plot. 'yes'= autoscale. Example of formula:	'3*x+2'. {default: 'no'}
'noplot'	Do not plot sortvar {default: Plot sortvar if in times range}
'noshow'	['yes'|'no'] Do not plot erpimage, simply return outputs {default: 'no'}
Sort data epochs:
'nosort'	Do not sort data epochs.
{default}	Sort data epochs by sortvar (see sortvar input above).
'valsort'	[startms endms direction] Sort data on (mean) value between startms and (optional) endms. Direction is 1 or -1. If -1, plot max-value epoch at bottom {default: sort on sortvar}
'phasesort'	[ms_center prct freq maxfreq topphase] Sort epochs by phase in a 3-cycle window centered at latency ms_center (ms). Percentile (prct) in range [0,100] gives percent of trials to reject for (too) low amplitude. Else, if in range [-100,0], percent of trials to reject for (too) high amplitude; freq (Hz) is the phase-sorting frequency. With optional maxfreq, sort by phase at freq of max power in the data in the range [freq,maxfreq] (Note: 'phasesort' arg freq overrides the frequency specified in 'coher'). With optional topphase, sort by phase, putting topphase (degrees, in range [-180,180]) at the top of the image. Note: 'phasesort' now uses circular smoothing. Use 'cycles' (below) for wavelet length. {default: [0 25 8 13 180]}
'ampsort'	[center_ms prcnt freq maxfreq] Sort epochs by amplitude. (See 'phasesort' above). If ms_center is 'Inf', then sorting is by mean power across the time window specified by 'sortwin' below. If third arg, freq, is < 0, sort by mean power in the range [ abs(freq) maxfreq ].
'sortwin'	[start_ms end_ms] With center_ms == Inf in 'ampsort' ars (above), sorts by mean amplitude across window centers shifted from start_ms to end_ms by 10 ms.
'showwin'	Show sorting window behind ERP trace. {default: don't show sorting window}
Plot time-varying spectral amplitude instead of potential:
'plotamps'	Image amplitudes at each trial and latency instead of potential values. Note: Currently requires 'coher' (below) with alpha signif. Use 'cycles' (below) > (default) 3 for better frequency specificity, {default: plot potential, not amplitudes}
Specify plot parameters:
'limits'	[lotime hitime minerp maxerp loamp hiamp locoher hicoher bamp] Plot axes limits. Can use NaN (or nan, but not Nan) for missing items and omit late items. Use last input, bamp, to fix the baseline amplitude. {default: from data}
'signif'	[lo_amp, hi_amp, coher_signif_level] Use precomputed significance thresholds (as from outputs ampsig, cohsig) to save time. {default: none}
'caxis'	[lo hi] Set color axis limits. Else [fraction] Set caxis limits at (+/-)fraction*max(abs(data)) {default: symmetrical, based on data limits}
Add epoch-mean ERP to plot:
'erp'	Plot ERP time average of the trials below the image {default no ERP plotted}
'erpalpha'	[alpha] One-sided significance threshold (range: [.001 0.1]). Requires 'erp' {default: no alpha significance thresholds plotted}
'erpstd'	Plot ERP +/- stdev. Requires 'erp' {default: no std. dev. plotted}
'rmerp'	Subtract the average ERP from each trial before processing {default: no}
Add time/frequency information:
'coher'	[freq] Plot ERP average plus mean amplitude & coherence at freq (Hz) Else [minfrq maxfrq] = same, but select frequency with max power in given range. (Note: the 'phasesort' freq (above) overwrites these parameters). Else [minfrq maxfrq alpha] = plot coher. signif. level line at probability alpha (range: [0,0.1]) {default: no coher, no alpha level}
'srate'	[freq] Specify the data sampling rate in Hz for amp/coher (if not implicit in third arg, times) {default: as defined in icadefs.m}
'cycles'	Number of cycles in the wavelet time/frequency decomposition {default: 3}
Add plot features:
'cbar'	Plot color bar to right of ERP-image {default no}
'topo'	{map,chan_locs,eloc_info} Plot a 2-D scalp map at upper left of image. map may be a single integer, representing the plotted data channel, or a vector of scalp map channel values. chan_locs may be a channel locations file or a chanlocs structure (EEG.chanlocs). See '>> topoplot example' eloc_info (EEG.chaninfo), if empty ([]) or absent, implies the 'X' direction points towards the nose and all channels are plotted {default: no scalp map}
'spec'	[loHz,hiHz] Plot the mean data spectrum at upper right of image.
'horz'	[epochs_vector] Plot horizontal lines at specified epoch numbers.
'vert'	[times_vector] Plot vertical dashed lines at specified latencies
'auxvar'	[size(nvars,ntrials) matrix] Plot auxiliary variable(s) for each trial as separate traces. Else, 'auxvar',{[matrix],{colorstrings}} to specify N trace colors. Ex: colorstrings = {'r','bo-','','k:'} (See also: 'vert' and 'timewarp' above). {default: none}
'sortvarpercent'	[float vector] Plot percentiles for the sorting variable for instance, [0.1 0.5 0.9] plots the 10th percentile, the median and the 90th percentile.
Plot options:
'noxlabel'	Do not plot "Time (ms)" on the bottom x-axis
'yerplabel'	['string'] ERP ordinate axis label (default is ERP). Print uV with '\muV'
Optional outputs:
outdata	(times,epochsout) data matrix (after smoothing)
outvar	(1,epochsout) actual values trials are sorted on (after smoothing). if 'sortvarpercent' is used, this variable contains a cell array with { sorted_values { sorted_percent1 ... sorted_percentN } }
outtrials	(1,epochsout) smoothed trial numbers
limits	(1,10) array, 1-9 as in 'limits' above, then analysis frequency (Hz)
axhndls	vector of 1-7 plot axes handles (img,cbar,erp,amp,coh,topo,spec)
erp	plotted ERP average
amps	mean amplitude time course
coher	mean inter-trial phase coherence time course
cohsig	coherence significance level
ampsig	amplitude significance levels [lo high]
outamps	matrix of imaged amplitudes (from option 'plotamps')
phsangls	vector of sorted trial phases at the phase-sorting frequency
phsamp	vector of sorted trial amplitudes at the phase-sorting frequency
sortidx	indices of input data epochs in the sorting order
erpsig	trial average significance levels [2,frames]
Example:	>> figure; erpimage(data,RTs,[-400 256 256],'Test',1,1, 'erp','cbar','vert',-350); Plots an ERP-image of 1-s data epochs sampled at 256 Hz, sorted by RTs, with title ('Test'), and sorted epochs not smoothed or decimated (1,1). Overplots the (unsmoothed) RT latencies on the colored ERP-image. Also plots the epoch-mean (ERP), a color bar, and a dashed vertical line at -350 ms.
Authors:	Scott Makeig, Tzyy-Ping Jung & Arnaud Delorme, CNL/Salk Institute, La Jolla, 3-2-1998 -
See also:	erpimages(), phasecoher(), rmbase(), cbar, movav()

See the matlab file erpimage.m (may require other functions)

Back to functions