Home > matlabmk > GNDorGRP2avg.m

GNDorGRP2avg

PURPOSE ^

GNDorGRP2avg() - Writes grand average ERPs in units of t-scores or microvolts

SYNOPSIS ^

function GNDorGRP2avg(GNDorGRP,out_fname,tmplt_fname,t_or_uv,pp10uv,verblevel,overwrite)

DESCRIPTION ^

 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/2010

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 % 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

Generated on Tue 10-May-2016 16:37:45 by m2html © 2005