GNDorGRP2avg() - Writes grand average ERPs in units of t-scores or microvolts
in Kutaslab average file format. Waveforms are taken from a
MATLABmk GND of GRP variable. Useful for visualizing/analyzing
waveforms with Kutaslab UNIX-based software (e.g., ploterps, topo).
Usage:
>> GNDorGRP2avg(GNDorGRP,out_fname,tmplt_fname,t_or_uv,pp10uv,verblevel,overwrite);
Inputs:
GNDorGRP - A MATLABmk GND or GRP struct variable that contains
grand average ERPs. GND variables are produced by the
functions avgs2GND.m or sets2GND.m. GRP variables are
produced by GNDs2GRP.m.
out_fname - The name of the Kutaslab average file that will be
produced (e.g., 'visodball.tgnd'). This should contain
the file's path unless the desired file location is the
current working directory. By convention, use the
extension '.tgnd' for grand average ERPs written in
units of t-scores.
tmplt_fname - The name of an existing Kutaslab average file or header
file that will be used as a template for the new average
file that will be created. Any average or header file
should do (e.g., it does not need to have the same number
of channels or bins as the file that will be created).
t_or_uv - ['t-score' or 'uv'] If 't-score' the grand average ERPs
will be written in units of t-scores. If 'uv,' they will
be written in microvolts.
pp10uv - [integer] The "points per 10 microvolts" that will be
used when writing the average file. The larger this
number, the greater the numeric precision of the average
file (i.e., its voltage/t-score values are more precise)
but the more limited the range of values that can be
represented. 1000 is a common value to use.
Option Input:
verblevel - An integer specifiying the amount of information you want
this function to provide about what it is doing during runtime.
Options are:
0 - quiet, only show errors, warnings, and EEGLAB reports
1 - stuff anyone should probably know
2 - stuff you should know the first time you start working
with a data set {default value if not already specified
globally}
3 - stuff that might help you debug (show all
reports)
overwrite - [1 or 0] If not 0, then the new avg file produced by this
function will automatically overwrite an existing file
of the same name (if it exists). If 1, the user will
asked what to do if a file of the same name already
exists. {default: 0}
Outputs:
A new average file is written to disk.
Notes:
-This function assumes that Bin 0 is calibration pulses and will try to
write the calibration pulses in the GND or GRP variable to that bin.
-The "subdesc" field of the avg file will indicate if the waveforms are
in units of microvolts or t-scores.
Author:
David Groppe
Kutaslab, 3/20100001 % GNDorGRP2avg() - Writes grand average ERPs in units of t-scores or microvolts 0002 % in Kutaslab average file format. Waveforms are taken from a 0003 % MATLABmk GND of GRP variable. Useful for visualizing/analyzing 0004 % waveforms with Kutaslab UNIX-based software (e.g., ploterps, topo). 0005 % 0006 % Usage: 0007 % >> GNDorGRP2avg(GNDorGRP,out_fname,tmplt_fname,t_or_uv,pp10uv,verblevel,overwrite); 0008 % 0009 % Inputs: 0010 % GNDorGRP - A MATLABmk GND or GRP struct variable that contains 0011 % grand average ERPs. GND variables are produced by the 0012 % functions avgs2GND.m or sets2GND.m. GRP variables are 0013 % produced by GNDs2GRP.m. 0014 % out_fname - The name of the Kutaslab average file that will be 0015 % produced (e.g., 'visodball.tgnd'). This should contain 0016 % the file's path unless the desired file location is the 0017 % current working directory. By convention, use the 0018 % extension '.tgnd' for grand average ERPs written in 0019 % units of t-scores. 0020 % tmplt_fname - The name of an existing Kutaslab average file or header 0021 % file that will be used as a template for the new average 0022 % file that will be created. Any average or header file 0023 % should do (e.g., it does not need to have the same number 0024 % of channels or bins as the file that will be created). 0025 % t_or_uv - ['t-score' or 'uv'] If 't-score' the grand average ERPs 0026 % will be written in units of t-scores. If 'uv,' they will 0027 % be written in microvolts. 0028 % pp10uv - [integer] The "points per 10 microvolts" that will be 0029 % used when writing the average file. The larger this 0030 % number, the greater the numeric precision of the average 0031 % file (i.e., its voltage/t-score values are more precise) 0032 % but the more limited the range of values that can be 0033 % represented. 1000 is a common value to use. 0034 % 0035 % Option Input: 0036 % verblevel - An integer specifiying the amount of information you want 0037 % this function to provide about what it is doing during runtime. 0038 % Options are: 0039 % 0 - quiet, only show errors, warnings, and EEGLAB reports 0040 % 1 - stuff anyone should probably know 0041 % 2 - stuff you should know the first time you start working 0042 % with a data set {default value if not already specified 0043 % globally} 0044 % 3 - stuff that might help you debug (show all 0045 % reports) 0046 % overwrite - [1 or 0] If not 0, then the new avg file produced by this 0047 % function will automatically overwrite an existing file 0048 % of the same name (if it exists). If 1, the user will 0049 % asked what to do if a file of the same name already 0050 % exists. {default: 0} 0051 % 0052 % Outputs: 0053 % A new average file is written to disk. 0054 % 0055 % Notes: 0056 % -This function assumes that Bin 0 is calibration pulses and will try to 0057 % write the calibration pulses in the GND or GRP variable to that bin. 0058 % 0059 % -The "subdesc" field of the avg file will indicate if the waveforms are 0060 % in units of microvolts or t-scores. 0061 % 0062 % Author: 0063 % David Groppe 0064 % Kutaslab, 3/2010 0065 0066 %%%%%%%% POSSIBLE FUTURE WORK %%%%%%%%%%%%%%%% 0067 % write odelay to avg file? currently I don't ?? 0068 0069 function GNDorGRP2avg(GNDorGRP,out_fname,tmplt_fname,t_or_uv,pp10uv,verblevel,overwrite) 0070 0071 0072 global VERBLEVEL; 0073 0074 if nargin<6, 0075 if isempty(VERBLEVEL), 0076 VERBLEVEL=2; 0077 end 0078 else 0079 VERBLEVEL=verblevel; 0080 end 0081 0082 if nargin<7, 0083 overwrite=0; 0084 end 0085 0086 if strcmpi(t_or_uv,'t-score') || strcmpi(t_or_uv,'t-scores') || ... 0087 strcmpi(t_or_uv,'tscore') || strcmpi(t_or_uv,'tscores'), ... 0088 tscore=1; 0089 elseif strcmpi(t_or_uv,'uv') || strcmpi(t_or_uv,'microvolts'), 0090 tscore=0; 0091 else 0092 error('Input argument t_or_uv needs to be ''t-score'' or ''uV''.'); 0093 end 0094 0095 % Are we dealing with a GND or GRP variable? 0096 GND=GNDorGRP; %rename everything GND for simplicity 0097 clear GNDorGRP; 0098 fldnms=fieldnames(GND); 0099 isGRP=0; 0100 if ismember('group_desc',fldnms), 0101 isGRP=1; 0102 end 0103 0104 % Data parameters 0105 n_chan=length(GND.chanlocs); 0106 n_tpt=length(GND.time_pts); 0107 n_bin=length(GND.bin_info); 0108 if ~n_bin, 0109 error('GND or GRP variable contains no bins! Thus there are no ERPs to export.'); 0110 end 0111 0112 if isGRP, 0113 n_grp=length(GND.group_desc); 0114 n_sub=0; 0115 for a=1:n_grp, 0116 n_sub=n_sub+length(GND.indiv_fnames{a}); 0117 end 0118 else 0119 n_sub=length(GND.indiv_fnames); 0120 end 0121 0122 % Check to make sure filename doesn't already exist 0123 [status, w]=unix(['ls ' out_fname]); 0124 if ~status, 0125 while ~overwrite 0126 rsp=input(sprintf('File %s already exists. Do you want to overwrite it (Y or N)?',out_fname),'s'); 0127 if strcmpi(rsp,'Y') || strcmpi(rsp,'yes'), 0128 overwrite=1; 0129 elseif strcmpi(rsp,'N') || strcmpi(rsp,'no'), 0130 overwrite=-1; 0131 end 0132 end 0133 0134 if overwrite==1, 0135 % Remove current version of output file if it already exists 0136 VerbReport(sprintf('Removing old version of file %s.',out_fname),1,VERBLEVEL); 0137 [status, w]=unix(['rm -f ' out_fname]); % ?? add an error check? 0138 %Note, status and w provide no information about the success of rm -f 0139 elseif overwrite==-1, 0140 fprintf('\n'); % line break to make command line reports look better 0141 return; 0142 end 0143 end 0144 0145 0146 % Create avg file 0147 VerbReport(sprintf('Creating average file %s using header information from %s.', ... 0148 out_fname,tmplt_fname),1,VERBLEVEL); 0149 fid=erpio('createavg',out_fname,tmplt_fname); 0150 if (fid==-1), 0151 error('Could not create ERP file %s using erpio.',out_fname); 0152 end 0153 erpio('put_hdrvar',fid,'pp10uv',pp10uv); 0154 0155 cprecis=ceil(n_tpt/256); 0156 n_pad=256*cprecis-n_tpt; % must write ERPs in multiples of 256 time points 0157 if n_pad>0, 0158 padding=zeros(n_chan,n_pad); 0159 watchit(sprintf('ERPs/Difference Waves are NOT a multiple of 256. Adding 0''s to waveforms to fix this.\nDo NOT apply frequency domain filters to these waveforms!')); 0160 else 0161 padding=[]; 0162 end 0163 0164 erpio('put_hdrvar',fid,'cprecis',cprecis); 0165 erpio('put_hdrvar',fid,'expdesc',GND.exp_desc); 0166 if tscore 0167 subdesc='t-scores of grand averages'; 0168 else 0169 subdesc='grand averages (in microvolts)'; 0170 end 0171 erpio('put_hdrvar',fid,'subdesc',subdesc); 0172 erpio('put_hdrvar',fid,'presampling',GND.time_pts(1)*sign(GND.time_pts(1))); 0173 %erpio('put_hdrvar',fid,'epoch',EEG.times(end)-EEG.times(1)+1000/EEG.srate); 0174 %--at least one of my set files had EEG.times in units of seconds (weird) 0175 erpio('put_hdrvar',fid,'epoch',1000*(n_pad+n_tpt)/GND.srate); 0176 erpio('put_hdrvar',fid,'chans',n_chan); 0177 %erpio('put_hdrvar',fid,'prfdesc','average'); ?? makes matlab crash 0178 erpio('put_hdrvar',fid,'clktick',100000/GND.srate); 0179 for c=1:n_chan, 0180 erpio('put_hdrvar',fid,'chndesc',c-1,GND.chanlocs(c).labels); 0181 end 0182 0183 %pre-allocate memory 0184 erps=zeros(n_chan,n_tpt+n_pad,n_bin); 0185 erp_ct=zeros(1,n_bin); 0186 ccode=-ones(1,n_bin); 0187 0188 crnt_cond=0; 0189 for b=0:n_bin, 0190 if b==0, 0191 erpio('put_hdrvar',fid,'condcode',GND.cals.condcode); 0192 erpio('put_hdrvar',fid,'condesc',GND.cals.caldesc); 0193 if isGRP 0194 raw_ct=zeros(n_grp); 0195 for a=1:n_grp, 0196 raw_ct(a)=mean(GND.cals.indiv_cal_ct{1}); 0197 end 0198 erpio('put_hdrvar',fid,'sums',mean(raw_ct)); % ?? should this be something like #of participants with cal pulses? 0199 erpio('put_hdrvar',fid,'totrawrecs',mean(raw_ct)); % see comment above 0200 erpio('writebin',fid,[mean(GND.cals.grand_cals,3) padding]*pp10uv/10,GND.cals.caldesc); %average over groups 0201 %note erpio returns nothing for 'writebin' (i.e. no indication 0202 %of success) 0203 else 0204 erpio('put_hdrvar',fid,'sums',sum(GND.cals.indiv_cal_ct>0)); % ?? should this be something like mean # of cal pulses? right now it's #of participants with cal pulses 0205 erpio('put_hdrvar',fid,'totrawrecs',length(GND.cals.indiv_cal_ct)); % see comment above 0206 erpio('writebin',fid,[GND.cals.grand_cals padding]*pp10uv/10,GND.cals.caldesc); 0207 end 0208 else 0209 if crnt_cond~=GND.bin_info(b).condcode, 0210 crnt_cond=GND.bin_info(b).condcode; 0211 erpio('put_hdrvar',fid,'condcode',crnt_cond); 0212 erpio('put_hdrvar',fid,'condesc',GND.condesc{crnt_cond}); 0213 end 0214 %write avg 0215 if isGRP 0216 sub_ct=0; 0217 for a=1:n_grp, 0218 sub_ct=sub_ct+sum(GND.indiv_bin_ct{a}(:,b)>0); %add up number of participants in each group that contributed to this bin 0219 %Note, indiv_bin_ct should be 0 for bins that a group 0220 %didn't contribute to 0221 end 0222 erpio('put_hdrvar',fid,'sums',sub_ct); % ?? should this be something like mean # of trials? 0223 else 0224 erpio('put_hdrvar',fid,'sums',GND.sub_ct(b)); % ?? should this be something like mean # of trials? right now it's #of participants with cal pulses 0225 end 0226 erpio('put_hdrvar',fid,'totrawrecs',n_sub); 0227 if tscore, 0228 erpio('writebin',fid,[squeeze(GND.grands_t(:,:,b))*pp10uv/10 padding],GND.bin_info(b).bindesc); 0229 else 0230 erpio('writebin',fid,[squeeze(GND.grands(:,:,b))*pp10uv/10 padding],GND.bin_info(b).bindesc); 0231 end 0232 end 0233 end 0234 0235 %close file 0236 erpio('close',fid); 0237 0238 fprintf('\n'); % line break to make command line reports look better