bin_opGRP

 bin_opGRP() - Computes the difference waves from two bins or the mean of 
               two bins of a GRP variable and stores the resultant ERPs as 
               a new bin in the GRP variable.
             
 Usage:
  >> GRP=bin_opGRP(GRP,op,groupA,binA,groupB,binB,neo_bindesc,neo_ccode,neo_ccdescr)

 Required Inputs:
   GRP    - A GRP structure variable.  You can create a GRP variable 
            from files of GND variables (i.e., *.GND files)   
            using GNDs2GRP.m.  See Mass Univariate ERP Toolbox documentation
            for detailed information about the format of a GRP variable. 
   op     - [string] One of the following three "bin operators":
              'A-B'    = new bin will be the difference wave produced by
                         subtracting the bin from Group B from the bin from 
                         Group A. Grand average t-scores are based on  
                         independent samples t-statistics.
              'B-A'    = new bin will be the difference wave produced by
                         subtracting the bin from Group A from the bin from 
                         Group B. Grand average t-scores are based on two 
                         independent samples t-statistics.
              '(A+B)/n'= new bin will be the mean of the bins from Group
                         A and B.  The means will be weighted by the
                         number of participants in each bin.  Thus the
                         results are equivalent to what you would derive
                         if all participants were in the same group.
                         Grand average t-scores are based on one sample
                         t-statistics.
   groupA - [string] The group descriptor for Group A (e.g., 'patients') 
            Use the function headinfo.m to see what groups are available.
   binA   - [integer] A bin index from Group A's GND variable. Note this is
            NOT a bin in the GRP variable. Use the function headinfo.m on 
            Group A's GND variable to see what bins are available
   groupB - [string] Same as groupA but for Group B.
   binB   - [integer] Same as binA but for Group B.

 Optional Inputs:
   neo_bindesc - [string] The bin descriptor for the new bin being
                 created. {default: '$, Bin #-$$ Bin ##', where # is the 
                 value of binA, ## is the value of binB, $ is Group A's
                 descriptor, and $$ is Group B's descriptor}
   neo_ccode   - [integer] The condition code of the new bin being
                 created. {default: biggest condition code}
   neo_ccdescr - [string] The condition code descriptor for the new bin being
                 created. {default: existing descriptor for that condition
                 code or 'Not Cals' if no condition codes exist for this 
                 GRP variable}

 Notes:
 -binA and binB should index bins starting at 1 (i.e., Bin 0 is assumed to
 contain cal pulses in Kutaslab data and is stored apart from bins in GND 
 variables)

 Author:
 David Groppe
 Kutaslab, 3/2010

0001 % bin_opGRP() - Computes the difference waves from two bins or the mean of
0002 %               two bins of a GRP variable and stores the resultant ERPs as
0003 %               a new bin in the GRP variable.
0004 %
0005 % Usage:
0006 %  >> GRP=bin_opGRP(GRP,op,groupA,binA,groupB,binB,neo_bindesc,neo_ccode,neo_ccdescr)
0007 %
0008 % Required Inputs:
0009 %   GRP    - A GRP structure variable.  You can create a GRP variable
0010 %            from files of GND variables (i.e., *.GND files)
0011 %            using GNDs2GRP.m.  See Mass Univariate ERP Toolbox documentation
0012 %            for detailed information about the format of a GRP variable.
0013 %   op     - [string] One of the following three "bin operators":
0014 %              'A-B'    = new bin will be the difference wave produced by
0015 %                         subtracting the bin from Group B from the bin from
0016 %                         Group A. Grand average t-scores are based on
0017 %                         independent samples t-statistics.
0018 %              'B-A'    = new bin will be the difference wave produced by
0019 %                         subtracting the bin from Group A from the bin from
0020 %                         Group B. Grand average t-scores are based on two
0021 %                         independent samples t-statistics.
0022 %              '(A+B)/n'= new bin will be the mean of the bins from Group
0023 %                         A and B.  The means will be weighted by the
0024 %                         number of participants in each bin.  Thus the
0025 %                         results are equivalent to what you would derive
0026 %                         if all participants were in the same group.
0027 %                         Grand average t-scores are based on one sample
0028 %                         t-statistics.
0029 %   groupA - [string] The group descriptor for Group A (e.g., 'patients')
0030 %            Use the function headinfo.m to see what groups are available.
0031 %   binA   - [integer] A bin index from Group A's GND variable. Note this is
0032 %            NOT a bin in the GRP variable. Use the function headinfo.m on
0033 %            Group A's GND variable to see what bins are available
0034 %   groupB - [string] Same as groupA but for Group B.
0035 %   binB   - [integer] Same as binA but for Group B.
0036 %
0037 % Optional Inputs:
0038 %   neo_bindesc - [string] The bin descriptor for the new bin being
0039 %                 created. {default: '$, Bin #-$$ Bin ##', where # is the
0040 %                 value of binA, ## is the value of binB, $ is Group A's
0041 %                 descriptor, and $$ is Group B's descriptor}
0042 %   neo_ccode   - [integer] The condition code of the new bin being
0043 %                 created. {default: biggest condition code}
0044 %   neo_ccdescr - [string] The condition code descriptor for the new bin being
0045 %                 created. {default: existing descriptor for that condition
0046 %                 code or 'Not Cals' if no condition codes exist for this
0047 %                 GRP variable}
0048 %
0049 % Notes:
0050 % -binA and binB should index bins starting at 1 (i.e., Bin 0 is assumed to
0051 % contain cal pulses in Kutaslab data and is stored apart from bins in GND
0052 % variables)
0053 %
0054 % Author:
0055 % David Groppe
0056 % Kutaslab, 3/2010
0057 
0058 %%%%%%%%%%%%%%%% REVISION LOG %%%%%%%%%%%%%%%%%
0059 % 5/6/2010-Fixed bug with default bin descriptor when 'op'='(A+B)/n' and
0060 % made combining bins a weighted average (weighted by the number of
0061 % participants in each bin).  Function was simple taking the mean of both
0062 % bins (treating each group equally)
0063 %
0064 % 11/1/2010-Fixed bug when GRP variable initially has no bins.
0065 %
0066 % 5/24/2011-Function wouldn't work if the Group A wasn't the first group in
0067 % GRP variable.  That problem is fixed.
0068 
0069 %%%%%%%%%%%%%%%% FUTURE WORK %%%%%%%%%%%%%%%%%
0070 % - add verblevel?
0071 
0072 
0073 function GRP=bin_opGRP(GRP,op,groupA,binA,groupB,binB,neo_bindesc,neo_ccode,neo_ccdescr)
0074 
0075 if nargin<7,
0076    neo_bindesc=[]; 
0077 end
0078 
0079 if nargin<8,
0080    neo_ccode=[]; 
0081 end
0082 
0083 if nargin<9,
0084    neo_ccdescr=[]; 
0085 end
0086 
0087 if strcmpi(groupA,groupB),
0088    error('groupA and groupB are the same (%s).  For within-subject difference waves use bin_dif.m.',groupA); 
0089 end
0090 
0091 if strcmpi(op,'A-B') || strcmpi(op,'B-A'),
0092     op_sign='-';
0093 elseif strcmpi(op,'(A+B)/n')
0094     op_sign='+';
0095 else
0096     error('Argument "op" must be ''A-B'',''B-A'',or ''(A+B)/n''.');
0097 end
0098 
0099 n_chans=length(GRP.chanlocs);
0100 n_pts=length(GRP.time_pts);
0101 n_binsGRP=length(GRP.bin_info);
0102 neo_bin=n_binsGRP+1;
0103 n_groups=length(GRP.group_desc);
0104 
0105 %Get the GRP variable indices of Group A and Group B
0106 grpA_id=0;
0107 grpB_id=0;
0108 for a=1:n_groups,
0109     if strcmpi(GRP.group_desc{a},groupA),
0110         if grpA_id,
0111             error('groupA (%s) matches multiple group descriptors in this GRP variable.',groupA);
0112         else
0113             grpA_id=a;
0114         end
0115     elseif strcmpi(GRP.group_desc{a},groupB),
0116         if grpB_id,
0117             error('groupB (%s) matches multiple group descriptors in this GRP variable.',groupB);
0118         else
0119             grpB_id=a;
0120         end
0121     end
0122 end
0123 if ~grpA_id,
0124     error('groupA (%s) not found in this GRP variable.  Enter "headinfo(GRP)" to see possible names.',groupA);
0125 end
0126 if ~grpB_id,
0127     error('groupB (%s) not found in this GRP variable.  Enter "headinfo(GRP)" to see possible names.',groupB);
0128 end
0129 
0130 load(GRP.GND_fnames{grpA_id},'-MAT');
0131 n_subA=GND.sub_ct;
0132 %n_subA=sum(GRP.indiv_bin_ct{grpA_id}(:,binA)>0);
0133 %n_subB=sum(GRP.indiv_bin_ct{grpB_id}(:,binB)>0);
0134 load(GRP.GND_fnames{grpB_id},'-MAT');
0135 n_subB=GND.sub_ct;
0136 if isempty(neo_bindesc),
0137     if op_sign=='-',
0138         GRP.bin_info(neo_bin).bindesc=sprintf('%s, Bin %d%c%s, Bin %d',groupA,binA, ...
0139             op_sign,groupB,binB);
0140     else
0141         GRP.bin_info(neo_bin).bindesc=sprintf('((%d*%s, Bin %d)%c(%d*%s, Bin %d))/%d', ...
0142             n_subA,groupA,binA,op_sign,n_subB,groupB,binB,n_subA+n_subB);
0143     end
0144 else
0145     GRP.bin_info(neo_bin).bindesc=neo_bindesc;
0146 end
0147 if isempty(neo_ccode)
0148     if isempty(GRP.condesc),
0149         fprintf('No condition code specified for new bin and no condition codes exist in GRP variable.\n');
0150         fprintf('Creating new condition code 1: "Not Cals" for the new bin being created.\n');
0151         GRP.bin_info(neo_bin).condcode=1;
0152         GRP.condesc{1}='Not Cals';
0153     else
0154         neo_ccode=length(GRP.condesc);
0155         fprintf('No condition code specified for new bin.\n');
0156         fprintf('Using greatest condition code (%d: %s) for the new bin being created by default.\n', ...
0157             neo_ccode,GRP.condesc{neo_ccode});
0158         GRP.bin_info(neo_bin).condcode=neo_ccode;
0159     end
0160 else
0161     %Check to see if the new condition code greater than the current possible
0162     cur_ccodes=length(GRP.condesc);
0163     if neo_ccode>cur_ccodes,
0164         if isempty(neo_ccdescr),
0165             error('You specified a condition code of %d, but this GRP variable only has %d existing conditions and you did not specify a new condition code descriptor.', ...
0166                 neo_ccode,cur_ccodes);
0167         end
0168         GRP.bin_info(neo_bin).condcode=neo_ccode;
0169         GRP.condesc{neo_ccode}=neo_ccdescr;
0170     else
0171         GRP.bin_info(neo_bin).condcode=neo_ccode;
0172     end
0173 end
0174 GRP.bin_info(neo_bin).groupA=grpA_id;
0175 GRP.bin_info(neo_bin).groupB=grpB_id;
0176 GRP.bin_info(neo_bin).source_binA=binA;
0177 GRP.bin_info(neo_bin).source_binB=binB;
0178 
0179 
0180 %preallocate memory
0181 if strcmpi(op,'(A+B)/n'),
0182     all_subs=zeros(n_chans,n_pts,n_subA+n_subB); %third dimension is participant
0183 else
0184     sums=zeros(n_chans,n_pts,2); %third dimension is group (1=A, 2=B)
0185     means=sums;
0186     ss=sums;
0187 end
0188 bins=[binA binB];
0189 n_subs=[0 0];
0190 
0191 %get data from Group A & B
0192 for grp_ct=1:2,
0193     % Group count of 1=Group A, 2=Group B
0194     if grp_ct==1,
0195         grp_id=grpA_id;
0196     else
0197         grp_id=grpB_id;
0198     end
0199     
0200     load(GRP.GND_fnames{grp_id},'-MAT');
0201     if bins(grp_ct)>length(GND.bin_info)
0202         error('The GND variable from %s only has %d bins but you''re trying to import Bin %d.', ...
0203             GRP.GND_fnames{grp_id},length(GND.bin_info),bins(grp_ct));
0204     end
0205     
0206     %Get the set of channels to use
0207     use_chans=zeros(1,length(GND.chanlocs));
0208     for c=1:length(GND.chanlocs),
0209         for d=1:n_chans, %n_chans is the number of channels in the GRP variable
0210            if strcmpi(GND.chanlocs(c).labels,GRP.chanlocs(d).labels),
0211               use_chans(c)=1;
0212               break;
0213            end
0214         end
0215     end
0216     %Make sure channel information is compatible
0217     use_chans=find(use_chans);
0218     if ~isequal(GND.chanlocs(use_chans),GRP.chanlocs),
0219         error('The channel location information in the GND variable from file %s differs from that in the GRP variable.', ...
0220             GRP.GND_fnames{grp_id});
0221     end
0222     
0223     %Get the set of subjects to use
0224     use_subs=find(GND.indiv_bin_ct(:,bins(grp_ct)))';
0225     n_subs(grp_ct)=length(use_subs);
0226     if grp_ct==1,
0227         % # of participants who contributed to this bin from Group A
0228         GRP.bin_info(neo_bin).n_subsA=n_subs(grp_ct); 
0229     else
0230         % # of participants who contributed to this bin from Group B
0231         GRP.bin_info(neo_bin).n_subsB=n_subs(grp_ct);
0232     end
0233     
0234     %get individual participant trial counts
0235     indiv_bin_ct{grp_ct}=GND.indiv_bin_ct(:,bins(grp_ct));
0236     indiv_bin_raw_ct{grp_ct}=GND.indiv_bin_raw_ct(:,bins(grp_ct));
0237     
0238     data=squeeze(GND.indiv_erps(use_chans,:,bins(grp_ct),use_subs));
0239 
0240     %make sure squeezed data has proper dimensions
0241     if length(size(data))~=3,
0242        error('Contributing ERPs from file %s have only one participant, time point, and/or channel.  I can''t deal with that.', ...
0243            GRP.GND_fnames{grp_id});
0244     end
0245 
0246     if strcmpi(op,'(A+B)/n'),
0247          if grp_ct==1,
0248              all_subs(:,:,1:n_subs(grp_ct))=data;
0249          else
0250              all_subs(:,:,n_subs(1)+1:end)=data;
0251          end
0252     else
0253         sums(:,:,grp_ct)=sum(data,3);
0254         means(:,:,grp_ct)=sums(:,:,grp_ct)/n_subs(grp_ct);
0255         ss(:,:,grp_ct)=sum(data.^2,3)-(squeeze(sums(:,:,grp_ct)).^2)/n_subs(grp_ct);
0256     end
0257 end
0258 GRP.bin_info(neo_bin).op=op;
0259 
0260 for a=1:n_groups,
0261     n_subs_grp=length(GRP.indiv_subnames{a});
0262     if a==grpA_id,
0263         GRP.indiv_bin_ct{a}(1:n_subs_grp,neo_bin)=indiv_bin_ct{1};
0264         GRP.indiv_bin_raw_ct{a}(1:n_subs_grp,neo_bin)=indiv_bin_raw_ct{1};
0265     elseif a==grpB_id,
0266         GRP.indiv_bin_ct{a}(1:n_subs_grp,neo_bin)=indiv_bin_ct{2};
0267         GRP.indiv_bin_raw_ct{a}(1:n_subs_grp,neo_bin)=indiv_bin_raw_ct{2};
0268     else
0269         %just zeros for this groups since they don't contribute to the new
0270         %bin
0271         GRP.indiv_bin_ct{a}(1:n_subs_grp,neo_bin)=zeros(1:n_subs,1);
0272         GRP.indiv_bin_raw_ct{a}(1:n_subs_grp,neo_bin)=zeros(1:n_subs,1);
0273     end
0274 end
0275 
0276 %new ERPs
0277 if strcmpi(op,'A-B'),
0278     GRP.grands(:,:,neo_bin)=means(:,:,1)-means(:,:,2);
0279 elseif strcmpi(op,'B-A'),
0280     GRP.grands(:,:,neo_bin)=means(:,:,2)-means(:,:,1);
0281 else
0282     % weighted mean of both bins (the right thing to do for a one-sample
0283     % t-test)
0284     [p_values, t_scores, mn, stder]=fast_t1(all_subs,0,0);
0285     GRP.grands(:,:,neo_bin)=mn;
0286     GRP.grands_t(:,:,neo_bin)=t_scores;
0287     GRP.grands_stder(:,:,neo_bin)=stder;
0288 end
0289     
0290 if ~strcmpi(op,'(A+B)/n'),
0291     %pooled sum of squares
0292     ssP=(ss(:,:,1)+ss(:,:,2))/(sum(n_subs)-2);
0293     GRP.grands_stder(:,:,neo_bin)=sqrt( ssP*sum(n_subs)/(n_subs(1)*n_subs(2)) );
0294     %t-score
0295     GRP.grands_t=GRP.grands./GRP.grands_stder;
0296 end
0297 
0298 fprintf('<<New bin successfully created>>\n');
0299 cc=GRP.bin_info(neo_bin).condcode;
0300 fprintf('Condition Code %d: %s\n',cc,GRP.condesc{cc});
0301 fprintf('Bin %d: %s\n',neo_bin,GRP.bin_info(neo_bin).bindesc);
0302 hist_cmd=sprintf('GRP=bin_opGRP(GRP,''%s'',''%s'',%d,''%s'',%d,''%s'',%d,''%s'');', ...
0303     op,groupA,binA,groupB,binB,GRP.bin_info(neo_bin).bindesc,cc,GRP.condesc{cc});
0304 GRP.history{length(GRP.history)+1}=hist_cmd;
0305 GRP.saved='no';
0306 
0307