Home > matlabmk > read_bin_list_file.m

read_bin_list_file

PURPOSE ^

read_bin_list_file() - Extracts "bin" information from a text file called

SYNOPSIS ^

function [bindesc, bintype]=read_bin_list_file(blf_fname, verblevel)

DESCRIPTION ^

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

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

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

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