read_bin_list_file() - Extracts "bin" information from a text file called
a "bin list file." The bin list file (blf) indicates which types
of events belong to which bins. Each line of the blf needs to
start with a number followed by a closed parenthesis, which
indicates the bin number. Next comes a string, number, or a
series of numbers indicting the "type" of events that fall in
that bin (note the "type" of an event is stored in the field
EEG.epoch(#).eventtype and EEG.event(#).type of an EEGLAB EEG
variable). Finally, comes an equal sign and text that describes
the kinds of trials that fall into that bin.
For example, the following line would classify epochs of type 22 as
members of Bin 1, which is described as containing "Targets in Auditory Task".
1) 22=Targets in Auditory Task
The following would classify epochs of type 22 and 26 as members of Bin 1,
which is described as containing "Targets in Auditory Task".
1) 22 26=Targets in Auditory Task
The following would classify epochs of type 22, 23, 24 and 25 as members
of Bin 1, which is described as containing "Targets in Auditory Task"
(note that using MATLAB notation to indicate vectors is acceptable).
1) 22:25=Targets in Auditory Task
The following would classify epochs of type 'aud_targ' as members of Bin 1,
which is described as containing "Targets in Auditory Task".
1) aud_targ=Targets in Auditory Task
The following would classify epochs of type 'aud targ' as members of Bin 1,
which is described as containing "Targets in Auditory Task". Note, the
use of single quotes to include the space in the type name. Without the
single quotes, two types would be read: "aud" and "targ".
1) 'aud targ'=Targets in Auditory Task
Usage:
>> [bindesc, bintype]=read_bin_list_file(blf_fname, verblevel);
Required Input:
blf_fname - [string] A set of integers specifying the subject ID
numbers to include in the grand average. Only necessary
if a filename template is given as the input to
gui_infiles_or_tmplt.
Optional 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 globally specified}
3 - stuff that might help you debug (show all
reports)
Output:
bindesc - A cell array of strings describing the contents of each bin.
bintype - A cell array of cell arrays of strings listing the types of
events that fall in each bin
Global Variable:
VERBLEVEL - Mass Univariate ERP Toolbox level of verbosity (i.e., tells
functions how much to report about what they're doing during
runtime) set by the optional function argument 'verblevel'
NOTES:
-You can use single quotes to define type names that have spaces in them
(e.g., 'S 1'). However you may only do this once per line of your blf
file. In other words you can have exactly zero or two single quotes per
line.
Author:
David Groppe
Kutaslab, 9/20100001 % read_bin_list_file() - Extracts "bin" information from a text file called 0002 % a "bin list file." The bin list file (blf) indicates which types 0003 % of events belong to which bins. Each line of the blf needs to 0004 % start with a number followed by a closed parenthesis, which 0005 % indicates the bin number. Next comes a string, number, or a 0006 % series of numbers indicting the "type" of events that fall in 0007 % that bin (note the "type" of an event is stored in the field 0008 % EEG.epoch(#).eventtype and EEG.event(#).type of an EEGLAB EEG 0009 % variable). Finally, comes an equal sign and text that describes 0010 % the kinds of trials that fall into that bin. 0011 % 0012 % For example, the following line would classify epochs of type 22 as 0013 % members of Bin 1, which is described as containing "Targets in Auditory Task". 0014 % 1) 22=Targets in Auditory Task 0015 % 0016 % The following would classify epochs of type 22 and 26 as members of Bin 1, 0017 % which is described as containing "Targets in Auditory Task". 0018 % 1) 22 26=Targets in Auditory Task 0019 % 0020 % The following would classify epochs of type 22, 23, 24 and 25 as members 0021 % of Bin 1, which is described as containing "Targets in Auditory Task" 0022 % (note that using MATLAB notation to indicate vectors is acceptable). 0023 % 1) 22:25=Targets in Auditory Task 0024 % 0025 % The following would classify epochs of type 'aud_targ' as members of Bin 1, 0026 % which is described as containing "Targets in Auditory Task". 0027 % 1) aud_targ=Targets in Auditory Task 0028 % 0029 % The following would classify epochs of type 'aud targ' as members of Bin 1, 0030 % which is described as containing "Targets in Auditory Task". Note, the 0031 % use of single quotes to include the space in the type name. Without the 0032 % single quotes, two types would be read: "aud" and "targ". 0033 % 1) 'aud targ'=Targets in Auditory Task 0034 % 0035 % 0036 % Usage: 0037 % >> [bindesc, bintype]=read_bin_list_file(blf_fname, verblevel); 0038 % 0039 % 0040 % Required Input: 0041 % blf_fname - [string] A set of integers specifying the subject ID 0042 % numbers to include in the grand average. Only necessary 0043 % if a filename template is given as the input to 0044 % gui_infiles_or_tmplt. 0045 % 0046 % Optional Input: 0047 % verblevel - An integer specifiying the amount of information you want 0048 % this function to provide about what it is doing during runtime. 0049 % Options are: 0050 % 0 - quiet, only show errors, warnings, and EEGLAB reports 0051 % 1 - stuff anyone should probably know 0052 % 2 - stuff you should know the first time you start working 0053 % with a data set {default value if not globally specified} 0054 % 3 - stuff that might help you debug (show all 0055 % reports) 0056 % 0057 % Output: 0058 % bindesc - A cell array of strings describing the contents of each bin. 0059 % bintype - A cell array of cell arrays of strings listing the types of 0060 % events that fall in each bin 0061 % 0062 % Global Variable: 0063 % VERBLEVEL - Mass Univariate ERP Toolbox level of verbosity (i.e., tells 0064 % functions how much to report about what they're doing during 0065 % runtime) set by the optional function argument 'verblevel' 0066 % 0067 % 0068 % NOTES: 0069 % -You can use single quotes to define type names that have spaces in them 0070 % (e.g., 'S 1'). However you may only do this once per line of your blf 0071 % file. In other words you can have exactly zero or two single quotes per 0072 % line. 0073 % 0074 % Author: 0075 % David Groppe 0076 % Kutaslab, 9/2010 0077 0078 %%%%%%%%%%%%%%%% Future Work %%%%%%%%%%%%%%%%% 0079 % 0080 0081 function [bindesc, bintype]=read_bin_list_file(blf_fname, verblevel) 0082 0083 if nargin<2, 0084 verblevel=2; 0085 end 0086 0087 [fid, msg]=fopen(blf_fname); 0088 if fid==-1, 0089 error('Couldn''t open blf file %s because: %s',blf_fname,msg); 0090 end 0091 line_ct=0; 0092 n_bin=0; 0093 while 1 0094 tline = fgetl(fid); 0095 if ~ischar(tline), 0096 break; %leave while loop 0097 end 0098 line_ct=line_ct+1; 0099 [bin_str tline]=strtok(tline); 0100 bin_id(line_ct)=str2double(bin_str(1:length(bin_str)-1)); %str2double returns NaN if the string it's converting contains alpha numeric characters 0101 if isnan(bin_id(line_ct)), 0102 error('Line #%d of file %s should start with a bin number followed by a close parenthesis\n',line_ct, ... 0103 blf_fname,line_ct); 0104 end 0105 eql_id=0; 0106 for a=1:length(tline), 0107 if tline(a)=='=', 0108 eql_id=a; 0109 break; 0110 end 0111 end 0112 if eql_id, 0113 line_type=rm_leading_whitespace(tline(1:eql_id-1)); 0114 line_type_as_num=str2num(line_type); %str2num returns the empty set 0115 %if the string cannot be interpreted as numbers at the MATLAB command line (e.g., ':') 0116 if ~isempty(line_type_as_num), 0117 line_type=num2str(line_type_as_num); %convert it back to string 0118 end 0119 if line_type(1)==39, 0120 if sum(line_type==39)~=2, 0121 error('Problem with Line %d. You can only use a pair of single quotes to indicate a type.',line_ct); 0122 end 0123 quote_locs=find(line_type==39); 0124 type_array{1}=line_type(2:quote_locs(2)-1); 0125 else 0126 type_array=strread(line_type,'%s'); 0127 end 0128 else 0129 error('Line %d needs to have an equals sign\n',line_ct); 0130 end 0131 0132 if (bin_id(line_ct)>n_bin) || isempty(bindesc{bin_id(line_ct)}) 0133 %new bin 0134 bindesc{bin_id(line_ct)}=rm_leading_whitespace(tline(eql_id+1:end)); 0135 n_bin=n_bin+1; 0136 n_type=length(type_array); 0137 for x=1:n_type, 0138 bintype{bin_id(line_ct)}{x}=type_array{x}; 0139 end 0140 else 0141 %The bin for this line has already been entered, make sure it's 0142 %consistent 0143 neo_bindesc=rm_leading_whitespace(tline(eql_id+1:end)); 0144 if ~strcmpi(neo_bindesc,bindesc{bin_id(line_ct)}) 0145 error('Bin descriptor on Line %d (%s) does not equal previous descriptor for that bin (i.e., Bin %d: %s)', ... 0146 line_ct,neo_bindesc,bin_id(line_ct),bindesc{bin_id(line_ct)}); 0147 end 0148 n_old_type=length(bintype{bin_id(line_ct)}); 0149 n_new_type=length(type_array); 0150 for x=1:n_new_type, 0151 bintype{bin_id(line_ct)}{x+n_old_type}=type_array{x}; 0152 end 0153 end 0154 end 0155 fclose(fid); 0156 0157 %% Error checking 0158 0159 %Make sure Bin ID #'s are contiguous and start with 1 0160 uni_bin=unique(bin_id); 0161 if max(abs(uni_bin-[1:n_bin])), 0162 error('Bin numbers need to be contiguous and start a "1". Your bin numbers are: %s\n',num2str(uni_bin)); 0163 end 0164 0165 %Get rid of redundant types (just in case) 0166 for a=1:n_bin, 0167 bintype{a}=unique(bintype{a}); 0168 end 0169 0170 if verblevel>1, 0171 %Print which event types belong to each bin for user to double check 0172 for a=1:n_bin, 0173 fprintf('\nBin %d: %s\n',a,bindesc{a}); 0174 fprintf('Event types belonging to this bin:') 0175 for b=1:length(bintype{a}) 0176 fprintf(' ''%s''',bintype{a}{b}); 0177 end 0178 fprintf('\n') 0179 end 0180 end 0181 0182 0183 function str=rm_leading_whitespace(str) 0184 0185 n=length(str); 0186 for a=1:n, 0187 if str(a)~=' ', 0188 str=str(a:end); 0189 break; 0190 end 0191 end