% STD_MAKEDESIGN - create a new or edit an existing STUDY.design by

% selecting specific factors to include in subsequent

% 1x2 or 2x2 STUDY measures and statistical computations

% for this design. A STUDY may have many factors

% (task or stimulus conditions, subject groups, session

% numbers, trial types, etc.), but current EEGLAB

% STUDY statistics functions apply only to at most two

% (paired or unpaired) factors. A STUDY.design may

% also be (further) restricted to include only specific

% subjects, datasets, or trial types.

% Usage:

% >> [STUDY] = std_makedesign(STUDY, ALLEEG); % create a default design

% >> [STUDY] = std_makedesign(STUDY, ALLEEG, designind, 'key', 'val' ...);

%

% Inputs:

% STUDY - EEGLAB STUDY set

% ALLEEG - vector of the EEG datasets included in the STUDY structure

% designind - [integer > 0] index (number) of the new STUDY design {default: 1}

%

% Optional inputs:

% 'name' - ['string'] mnemonic design name (ex: 'Targets only')

% {default: 'Design d', where d = designind}

% 'variable1' - ['string'] - first independent variable or contrast. Must

% be a field name in STUDY.datasetinfo or in

% STUDY.datasetinfo.trialinfo. Typical choices include (task

% or other) 'condition', (subject) 'group', (subject) 'session',

% or other condition/group/session factors in STUDY.datasetinfo

% -- for example (subject factor) 'gender' or (condition factor)

% 'timeofday', etc. If trial type variables are defined in

% STUDY.datasetinfo.trialinfo, they may also be used here

% -- for example, 'stimcolor'. However, in this case datasets

% consist of heterogeneous sets of trials of different types,

% so many dataset Plot and Tools menu items may not give

% interpretable results and will thus be made unavailable for

% selection {default: 'condition'}

% 'values1' - {cell array of 'strings'} - 'variable1' instances to include

% in the design. For example, if 'variable1' is 'condition'and

% three values for 'condition' (e.g., 'a' , 'b', and 'c')

% are listed in STUDY.datasetinfo, then 'indval1', { 'a' 'b' }

% will contrast conditions 'a' and 'b', and datasets for

% condition 'c' will be ignored. To combine conditions, use

% nested '{}'s. For example, to combine conditions 'a' and

% 'b' into one condition and contrast it to condition 'c',

% specify 'indval1', { { 'a' 'b' } 'c' } {default: all values

% of 'variable1' in STUDY.datasetinfo}

% 'variable2' - ['string'] - second independent variable name, if any. Typically,

% this might refer to ('unpaired') subject group or (typically

% 'paired') session number, etc.

% 'values2' - {cell array of 'strings'} - variable2 values to include in the

% design {default: all}. Here, 'var[12]' must be field names

% in STUDY.datasetinfo or STUDY.datasetinfo.trialinfo.

% 'subjselect' - {cell array} subject codes of specific subjects to include

% in the STUDY design {default: all subjects in the specified

% conditions, groups, etc.} If 'datselect' is also specified,

% only datasets meeting both criteria are included.

% 'rmfiles' - ['on'|'off'] remove from the STUDY all data measure files

% NOT included in this design. Selecting this option will

% remove all the old measure files associated with the previous

% definition of this design. {default: 'off'}

% 'filepath' - [string] file path for saving precomputed files. Default is

% empty meaning it is in the same folder as the data.

% 'delfiles' - ['on'|'off'|'limited'] delete data files

% associated with the design specified as parameter. 'on'

% delete all data files related to the design. 'limited'

% deletes all data files contained in the design. 'limited'

% will not delete data files from other STUDY using the same

% files. Default is 'off'.

%

% Output:

% STUDY - The input STUDY with a new design added and designated

% as the current design.

%

% Examples:

% STUDY = std_makedesign(STUDY, ALLEEG); % make default design

%

% % create design with 1 independent variable equal to 'condition'

% STUDY = std_makedesign(STUDY, ALLEEG, 2, 'variable1', 'condition');

%

% % create design with 1 independent variable equal to 'condition'

% % but only consider the sub-condition 'stim1' and 'stim2' - of course

% % such conditions must be present in the STUDY

% STUDY = std_makedesign(STUDY, ALLEEG, 2, 'variable1', 'condition', ...

% 'values1', { 'stim1' 'stim2' });

%

% % create design and only include subject 's1' and 's2'

% STUDY = std_makedesign(STUDY, ALLEEG, 2, 'variable1', 'condition', ...

% 'subjselect', { 's1' 's2' });

%

% Author: Arnaud Delorme, Institute for Neural Computation UCSD, 2010-

% Copyright (C) Arnaud Delorme, arno@salk.edu

%

% This file is part of EEGLAB, see http://www.eeglab.org

% for the documentation and details.

%

% Redistribution and use in source and binary forms, with or without

% modification, are permitted provided that the following conditions are met:

%

% 1. Redistributions of source code must retain the above copyright notice,

% this list of conditions and the following disclaimer.

%

% 2. Redistributions in binary form must reproduce the above copyright notice,

% this list of conditions and the following disclaimer in the documentation

% and/or other materials provided with the distribution.

%

% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

% ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

% INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

% ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF

% THE POSSIBILITY OF SUCH DAMAGE.

function [STUDY, com] = std_makedesign(STUDY, ALLEEG, designind, varargin)

if nargin < 2

help std_makedesign;

return;

end

if nargin < 3

designind = 1;

end

defdes.name = sprintf('STUDY.design %d', designind);

defdes.cases.label = 'subject';

defdes.cases.value = {};

defdes.variable(1).label = 'condition';

defdes.variable(2).label = 'group';

defdes.variable(3).label = '';

defdes.variable(4).label = '';

defdes.variable(1).value = {};

defdes.variable(2).value = {};

defdes.variable(3).value = {};

defdes.variable(4).value = {};

defdes.variable(1).vartype = 'categorical';

defdes.variable(2).vartype = 'categorical';

defdes.filepath = '';

defdes.include = {};

orivarargin = varargin;

if ~isempty(varargin) && isstruct(varargin{1})

defdes = varargin{1};

varargin(1) = [];

end

if isempty(defdes.filepath), defdes.filepath = ''; end

if length(defdes.variable) == 0, defdes.variable(1).label = 'continuous'; defdes.variable(1).vartype = 'categorical'; defdes.variable(1).value = {}; end

if length(defdes.variable) == 1, defdes.variable(2).label = 'continuous'; defdes.variable(2).vartype = 'categorical'; defdes.variable(2).value = {}; end

if length(defdes.variable) == 2, defdes.variable(3).label = 'continuous'; defdes.variable(3).vartype = 'categorical'; defdes.variable(3).value = {}; end

if length(defdes.variable) == 3, defdes.variable(4).label = 'continuous'; defdes.variable(4).vartype = 'categorical'; defdes.variable(4).value = {}; end

for iVar = 1:4

if isempty(defdes.variable(iVar).vartype), defdes.variable(iVar).vartype = 'continuous'; end

if isempty(defdes.variable(iVar).label) , defdes.variable(iVar).label = ''; end

end

opt = finputcheck(varargin, {'variable1' 'string' [] defdes.variable(1).label;

'variable2' 'string' [] defdes.variable(2).label;

'variable3' 'string' [] defdes.variable(3).label;

'variable4' 'string' [] defdes.variable(4).label;

'values1' {'real','cell' } [] defdes.variable(1).value;

'values2' {'real','cell' } [] defdes.variable(2).value;

'values3' {'real','cell' } [] defdes.variable(3).value;

'values4' {'real','cell' } [] defdes.variable(4).value;

'vartype1' 'string' {'categorical' 'continuous'} defdes.variable(1).vartype;

'vartype2' 'string' {'categorical' 'continuous'} defdes.variable(2).vartype;

'vartype3' 'string' {'categorical' 'continuous'} defdes.variable(3).vartype;

'vartype4' 'string' {'categorical' 'continuous'} defdes.variable(4).vartype;

'name' 'string' {} defdes.name;

'filepath' 'string' {} defdes.filepath;

'datselect' 'cell' {} defdes.include;

'dataselect' 'cell' {} {};

'subjselect' 'cell' {} defdes.cases.value;

'delfiles' 'string' { 'on','off', 'limited' } 'off';

'verbose' 'string' { 'on','off' } 'on';

'defaultdesign' 'string' { 'on','off','forceoff'} fastif(nargin < 3, 'on', 'off') }, ...

'std_makedesign', 'ignore');

if ischar(opt), error(opt); end

if ~isempty(opt.dataselect), opt.datselect = opt.dataselect; end

if strcmpi(opt.variable1, 'none'), opt.variable1 = ''; end

if strcmpi(opt.variable2, 'none'), opt.variable2 = ''; end

%if iscell(opt.values1), for i = 1:length(opt.values1), if iscell(opt.values1{i}), opt.values1{i} = cell2str(opt.values1{i}); end; end; end

%if iscell(opt.values2), for i = 1:length(opt.values2), if iscell(opt.values2{i}), opt.values2{i} = cell2str(opt.values2{i}); end; end; end

% check inputs

% ------------

[indvars, indvarvals, ~, paired] = std_getindvar(STUDY);

if isfield(STUDY.datasetinfo, 'trialinfo')

alltrialinfo = { STUDY.datasetinfo.trialinfo };

dattrialselect = cellfun(@(x)([1:length(x)]), alltrialinfo, 'uniformoutput', false);

else alltrialinfo = cell(length(STUDY.datasetinfo));

for i=1:length(ALLEEG), dattrialselect{i} = [1:ALLEEG(i).trials]; end

end

% get values for each independent variable

% ----------------------------------------

m1 = strmatch(opt.variable1, indvars, 'exact'); if isempty(m1), opt.variable1 = ''; end

m2 = strmatch(opt.variable2, indvars, 'exact'); if isempty(m2), opt.variable2 = ''; end

m3 = strmatch(opt.variable3, indvars, 'exact'); if isempty(m3), opt.variable3 = ''; end

m4 = strmatch(opt.variable4, indvars, 'exact'); if isempty(m4), opt.variable4 = ''; end

if isempty(opt.values1) && ~isempty(opt.variable1), opt.values1 = indvarvals{m1}; end

if isempty(opt.values2) && ~isempty(opt.variable2), opt.values2 = indvarvals{m2}; end

if isempty(opt.values3) && ~isempty(opt.variable3), opt.values3 = indvarvals{m3}; end

if isempty(opt.values4) && ~isempty(opt.variable4), opt.values4 = indvarvals{m4}; end

if isempty(opt.variable1), opt.values1 = { '' }; end

if isempty(opt.variable2), opt.values2 = { '' }; end

if isempty(opt.variable3), opt.values3 = { '' }; end

if isempty(opt.variable4), opt.values4 = { '' }; end

% build command list for history

% ------------------------------

listcom = { 'name' opt.name 'delfiles' opt.delfiles 'defaultdesign' opt.defaultdesign };

if ~isempty(opt.variable1), listcom = { listcom{:} 'variable1' opt.variable1 'values1' opt.values1 'vartype1' opt.vartype1 }; end

if ~isempty(opt.variable2), listcom = { listcom{:} 'variable2' opt.variable2 'values2' opt.values2 'vartype2' opt.vartype2 }; end

if ~isempty(opt.variable3), listcom = { listcom{:} 'variable3' opt.variable3 'values3' opt.values3 'vartype3' opt.vartype3 }; end

if ~isempty(opt.variable4), listcom = { listcom{:} 'variable4' opt.variable4 'values4' opt.values4 'vartype4' opt.vartype4 }; end

if ~isempty(opt.subjselect), listcom = { listcom{:} 'subjselect' opt.subjselect }; end

if ~isempty(opt.datselect), listcom = { listcom{:} 'datselect' opt.datselect }; end

if ~isempty(opt.filepath), listcom = { listcom{:} 'filepath' opt.filepath }; end

if ~isempty(opt.datselect), listcom = { listcom{:} 'datselect' opt.datselect }; end

% select specific subjects

% ------------------------

datsubjects = { STUDY.datasetinfo.subject };

if ~isempty(opt.subjselect)

allsubjects = opt.subjselect;

else

allsubjects = unique_bc( datsubjects );

end

% delete design files

% ---------------------

if strcmpi(opt.delfiles, 'on')

myfprintf(opt.verbose, 'Deleting all files pertaining to design %d\n', designind);

for index = 1:length(ALLEEG)

files = fullfile(ALLEEG(index).filepath, sprintf(opt.verbose, 'design%d*.*', designind));

files = dir(files);

for indf = 1:length(files)

delete(fullfile(ALLEEG(index).filepath, files(indf).name));

end

end

elseif strcmpi(opt.delfiles, 'limited')

myfprintf(opt.verbose, 'Deleting all files for STUDY design %d\n', designind);

for index = 1:length(STUDY.design(designind).cell)

filedir = [ STUDY.design(designind).cell(index).filebase '.dat*' ];

filepath = fileparts(filedir);

files = dir(filedir);

for indf = 1:length(files)

%disp(fullfile(filepath, files(indf).name));

delete(fullfile(filepath, files(indf).name));

end

end

for index = 1:length(STUDY.design(designind).cell)

filedir = [ STUDY.design(designind).cell(index).filebase '.ica*' ];

filepath = fileparts(filedir);

files = dir(filedir);

for indf = 1:length(files)

%disp(fullfile(filepath, files(indf).name));

delete(fullfile(filepath, files(indf).name));

end

end

end

% preselect data

% --------------

datselect = [1:length(STUDY.datasetinfo)];

if ~isempty(opt.datselect)

fprintf(2, '**********************************\n')

fprintf(2, 'The ''datselect'' option is obsolete\n')

fprintf(2, '**********************************\n\n')

error('This version of EEGLAB no longer support ''datselect''; please remove it from the list of inputs')

for ind = 1:2:length(opt.datselect)

[ dattmp, dattrialstmp ] = std_selectdataset( STUDY, ALLEEG, opt.datselect{ind}, opt.datselect{ind+1});

datselect = intersect_bc(datselect, dattmp);

dattrialselect = intersectcell(dattrialselect, dattrialstmp);

end

end

datselect = intersect_bc(datselect, strmatchmult(allsubjects, datsubjects));

des.name = opt.name;

des.filepath = opt.filepath;

if ~isempty(opt.variable1)

des.variable(1).label = opt.variable1;

des.variable(1).value = opt.values1;

des.variable(1).vartype = opt.vartype1;

des.variable(1).pairing = paired{m1};

end

if ~isempty(opt.variable2)

des.variable(2).label = opt.variable2;

des.variable(2).value = opt.values2;

des.variable(2).vartype = opt.vartype2;

des.variable(2).pairing = paired{m2};

end

if ~isempty(opt.variable3)

des.variable(3).label = opt.variable3;

des.variable(3).value = opt.values3;

des.variable(3).vartype = opt.vartype3;

des.variable(3).pairing = paired{m3};

end

if ~isempty(opt.variable4)

des.variable(4).label = opt.variable4;

des.variable(4).value = opt.values4;

des.variable(4).vartype = opt.vartype4;

des.variable(4).pairing = paired{m4};

end

des.include = opt.datselect;

des.cases.label = 'subject';

des.cases.value = opt.subjselect;

if isempty(des.cases.value), des.cases.value = STUDY.subject; end

fieldorder = { 'name' 'filepath' 'variable' 'cases' 'include' };

if ~isfield(des, 'variable'), des.variable = []; end

des = orderfields(des, fieldorder);

try

STUDY.design = orderfields(STUDY.design, fieldorder);

catch

STUDY.design = [];

end

if ~isfield(STUDY, 'design') || isempty(STUDY.design)

STUDY.design = des;

else

STUDY.design(designind) = des; % fill STUDY.design

end

STUDY = std_addvarlevel(STUDY, designind);

% remove empty variables

if designind <= length(STUDY.design)

for iVar = length(STUDY.design(designind).variable):-1:1

if isempty(STUDY.design(designind).variable(iVar).label)

STUDY.design(designind).variable(iVar) = [];

end

end

end

% reorder variable putting single value var at the end

% this allows selecting some specific conditions and still processing the

% data in EEGLAB standard stat functions

if length(STUDY.design(designind).variable) > 2

if all(cellfun(@(x)isequal(x, 'categorical'), { STUDY.design(designind).variable(3).vartype })) % only categorical

varLen = cellfun(@(x)length(x), {STUDY.design(designind).variable.value});

indLen1 = find(varLen == 1);

STUDY.design(designind).variable = [ STUDY.design(designind).variable(setdiff(1:length(varLen), indLen1)) STUDY.design(designind).variable(indLen1) ];

end

end

% select the new design in the STUDY output

% -----------------------------------------

STUDY.currentdesign = designind;

STUDY = std_selectdesign(STUDY, ALLEEG, designind);

STUDY.cache = [];

% build output command

% --------------------

com = sprintf('STUDY = std_makedesign(STUDY, ALLEEG, %d, %s);', designind, vararg2str( listcom ) );

% ---------------------------------------------------

% return intersection of cell arrays

% ----------------------------------

function res = intersectcell(a, b, c)

if nargin > 2

res = intersectcell(a, intersectcell(b, c));

else

for index = 1:length(a)

res{index} = intersect_bc(a{index}, b{index});

end

end

% perform multi strmatch

% ----------------------

function res = strmatchmult(a, b)

res = [];

for index = 1:length(a)

res = [ res strmatch(a{index}, b, 'exact')' ];

end

% remove blanks

% -------------

function res = rmblk(a)

if iscell(a), a = cell2str(a); end

if ~ischar(a), a = num2str(a); end

res = a;

res(find(res == ' ')) = '_';

res(find(res == '\')) = '_';

res(find(res == '/')) = '_';

res(find(res == ':')) = '_';

res(find(res == ';')) = '_';

res(find(res == '"')) = '_';

function strval = cell2str(vals);

strval = vals{1};

for ind = 2:length(vals)

strval = [ strval ' - ' vals{ind} ];

end

function tmpfile = checkfilelength(tmpfile)

if length(tmpfile) > 120

tmpfile = tmpfile(1:120);

end

function myfprintf(verbose, varargin)

if strcmpi(verbose, 'on'), fprintf(varargin{:}); end