Home > marsbar > @mardo > add_contrasts.m

add_contrasts

PURPOSE ^

method to add contrast definitions to design

SYNOPSIS ^

function [D,Ic,changef] = add_contrasts(D, C, varargin)

DESCRIPTION ^

 method to add contrast definitions to design

 The function has many different formats

 FORMAT [D Ic changef] = add_contrasts(D, D2 [,Ic])

 where D2 is a design. If there is no third argument, all the contrasts in
 D2 will be added.  If third argument (Ic) is passed, specifies which
 contrasts in D2 to add. If Ic passed, and empty, or contains the string
 'ui', contrasts to add are fetched using the GUI

 OR
 FORMAT [D Ic changef] = add_contrasts(D, xCon)

 where xCon is a structure in SPM contrast format containing contrasts to
 add.  If there is no third argument, all the contrasts in xCon will be
 added.  If third argument (Ic) is passed, specifies which contrasts in xCon
 to add. If Ic passed, and empty, or contains the string 'ui', contrasts to
 add are fetched using the GUI

 OR
 FORMAT [D Ic changef] = add_contrasts(D, stat_struct)
 where stat_struct has fields
      'names',       string, or cell array of strings
      'types',       string ('T' or 'F'), or cell array
      'set_actions', string ('c', 'X0' or 'iX0') or array
                     (see spm_FcUtil)
                     (field is optional, defaults to 'c')
      'values',      matrix of values

 OR
 FORMAT [D Ic changef] = add_contrasts(D, names, types, values)
 where names, types, values are cell arrays of values, or values
 (defined as above)

 OR
 FORMAT [D Ic  changef] = add_contrasts(D, names, types, set_actions, values)
 where names, types, set_actions, values are cell arrays of values, or
 values (defined as above)

 Returns
 D       - possibly modified SPM design
 Ic      - indices of specified contrasts as stored in D
 changef - 1 if D has changed during call else 0

 Contrast will not be added if it is already present, but the correct
 index will be returned in Ic

 $Id$

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 function [D,Ic,changef] = add_contrasts(D, C, varargin)
0002 % method to add contrast definitions to design
0003 %
0004 % The function has many different formats
0005 %
0006 % FORMAT [D Ic changef] = add_contrasts(D, D2 [,Ic])
0007 %
0008 % where D2 is a design. If there is no third argument, all the contrasts in
0009 % D2 will be added.  If third argument (Ic) is passed, specifies which
0010 % contrasts in D2 to add. If Ic passed, and empty, or contains the string
0011 % 'ui', contrasts to add are fetched using the GUI
0012 %
0013 % OR
0014 % FORMAT [D Ic changef] = add_contrasts(D, xCon)
0015 %
0016 % where xCon is a structure in SPM contrast format containing contrasts to
0017 % add.  If there is no third argument, all the contrasts in xCon will be
0018 % added.  If third argument (Ic) is passed, specifies which contrasts in xCon
0019 % to add. If Ic passed, and empty, or contains the string 'ui', contrasts to
0020 % add are fetched using the GUI
0021 %
0022 % OR
0023 % FORMAT [D Ic changef] = add_contrasts(D, stat_struct)
0024 % where stat_struct has fields
0025 %      'names',       string, or cell array of strings
0026 %      'types',       string ('T' or 'F'), or cell array
0027 %      'set_actions', string ('c', 'X0' or 'iX0') or array
0028 %                     (see spm_FcUtil)
0029 %                     (field is optional, defaults to 'c')
0030 %      'values',      matrix of values
0031 %
0032 % OR
0033 % FORMAT [D Ic changef] = add_contrasts(D, names, types, values)
0034 % where names, types, values are cell arrays of values, or values
0035 % (defined as above)
0036 %
0037 % OR
0038 % FORMAT [D Ic  changef] = add_contrasts(D, names, types, set_actions, values)
0039 % where names, types, set_actions, values are cell arrays of values, or
0040 % values (defined as above)
0041 %
0042 % Returns
0043 % D       - possibly modified SPM design
0044 % Ic      - indices of specified contrasts as stored in D
0045 % changef - 1 if D has changed during call else 0
0046 %
0047 % Contrast will not be added if it is already present, but the correct
0048 % index will be returned in Ic
0049 %
0050 % $Id$
0051 
0052 if nargin < 2
0053   error('Need contrasts to add');
0054 end
0055 
0056 % Get parameters from current design
0057 SPM  = des_struct(D);
0058 sX   = SPM.xX.xKXs;
0059 xCon = SPM.xCon;
0060 v_f  = verbose(D);
0061 
0062 % process inputs
0063 % The ``C`` variable will hold the xCon structure for the contrasts to add
0064 if isa(C, 'mardo')        % design
0065   C = des_struct(C);
0066 end
0067 if isfield(C, 'xCon')     % design structure
0068   C = C.xCon;
0069 end
0070 if isfield(C, 'STAT')     % xCon structure
0071   % parse Ic input
0072   if nargin > 2 % There is Ic input
0073     Ic_in = varargin{1};
0074     if isempty(Ic_in) | strcmp(Ic_in,'ui')
0075       D2 = set_contrasts(D, C, 0);
0076       Ic_in = ui_get_contrasts(D2,'T&F',Inf,...
0077         'Select contrasts to merge','',1);
0078     end
0079     C = C(Ic_in);
0080   end
0081 else % contrast setting structure or values or cells
0082   if ~isstruct(C) % make stat_struct structure if not already passed
0083     C = sf_cell_to_conset(C, varargin{:});
0084   end
0085   % make xCon structure from stat_struct
0086   C = sf_conset_to_xcon(C, sX);
0087 end
0088 % Initial xCon before adding new contrasts
0089 xc_len = length(xCon);
0090 old_xc_len = xc_len;
0091 % C contains the contrasts to add
0092 for i=1:length(C)
0093   % Update this contrast using our own filtered design
0094   c_i  = refresh_con(C(i), sX);
0095   if xc_len == 0 % the xCon to add to is empty
0096     xCon = c_i;
0097     xc_len = 1;
0098     Ic(1) = 1;
0099     continue
0100   end
0101   % Check if we have this contrast already
0102   Ic(i) = spm_FcUtil('In', c_i, sX, xCon);
0103   if Ic(i) == 0
0104     xc_len = xc_len+1;
0105     xCon(xc_len) = c_i;
0106     Ic(i) = xc_len;
0107   elseif v_f
0108     fprintf('\nContrast %s (type %s) already in xCon\n', ...
0109             c_i.name, c_i.STAT);
0110   end
0111 end
0112 changef =  xc_len ~= old_xc_len;
0113 if changef
0114   SPM.xCon = xCon;
0115   D = des_struct(D, SPM);
0116 end
0117 return
0118 
0119 function xcon_re_entry = refresh_con(xcon_entry, sX)
0120 % Rebuild contrast structure from our own filtered design
0121 if isempty(xcon_entry.c)
0122     error('Empty c matrix for contrast, crashing because confused')
0123 end
0124 xcon_re_entry = spm_FcUtil('Set',...
0125         xcon_entry.name,...
0126         xcon_entry.STAT,...
0127         'c',...
0128         xcon_entry.c,...
0129         sX);
0130 
0131 function C = sf_cell_to_conset(names, types, varargin)
0132 % makes contrast setting structure from cell input
0133 if nargin < 3
0134   error('Need at least names, statistic types and values');
0135 end
0136 C = struct(...
0137     'names', names,...
0138     'types', types);
0139 if nargin < 4 % values call
0140   values = varargin{1};
0141   set_actions = 'c';
0142 else % contrast types, values call
0143   set_actions = deal(varargin{1});
0144   values      = deal(varargin{2});
0145 end
0146 C = struct(...
0147     'names', names,...
0148     'types', types,...
0149     'set_actions', set_actions,...
0150     'values', values);
0151 return
0152 
0153 function C = sf_conset_to_xcon(con_set, sX)
0154 % make xCon structure from cell or struct setting parameters
0155 if ~isfield(con_set, 'set_actions')
0156   [con_set.set_actions] = deal('c');
0157 end
0158 n_e = size(sX.X, 2);
0159 for c = 1:length(con_set)
0160   c1 = con_set(c);
0161   if size(c1.values, 1) ~= n_e & ...
0162       size(c1.values, 2) == n_e
0163       c1.values = c1.values';
0164   end
0165   C(c) = spm_FcUtil('Set',...
0166     c1.names,...
0167     c1.types,...
0168     c1.set_actions,...
0169     c1.values,...
0170     sX);
0171 end
0172 return

Generated on Thu 17-Mar-2016 01:14:46 by m2html © 2005