function [data] = ft_appenddata(cfg, varargin)

% FT_APPENDDATA concatenates multiple raw data structures that have been preprocessed

% separately into a single raw data structure.

%

% Use as

% data = ft_appenddata(cfg, data1, data2, data3, ...)

%

% The following configuration options are supported:

% cfg.keepsampleinfo = 'yes', 'no', 'ifmakessense' (default = 'ifmakessense')

%

% If the input datasets all have the same channels, the trials will be concatenated.

% This is useful for example if you have different experimental conditions, which,

% besides analyzing them separately, for some reason you also want to analyze

% together. The function will check for consistency in the order of the channels. If

% the order is inconsistent the channel order of the output will be according to the

% channel order of the first data structure in the input.

%

% If the input datasets have different channels, but the same number of trials, the

% channels will be concatenated within each trial. This is useful for example if the

% data that you want to analyze contains both MEG and EMG channels which require

% different preprocessing options.

%

% If you concatenate trials and the data originates from the same original datafile,

% the sampleinfo is consistent and you can specify cfg.keepsampleinfo='yes'. If the

% data originates from different datafiles, the sampleinfo is inconsistent and does

% not point to the same recording, hence you should specify cfg.keepsampleinfo='no'.

%

% Occasionally, the data needs to be concatenated in the trial dimension while

% there's a slight discrepancy in the channels in the input data (e.g. missing

% channels in one of the data structures). The function will then return a data

% structure containing only the channels which are present in all inputs.

%

% To facilitate data-handling and distributed computing you can use

% cfg.inputfile = ...

% cfg.outputfile = ...

% If you specify one of these (or both) the input data will be read from a *.mat

% file on disk and/or the output data will be written to a *.mat file. These mat

% files should contain only a single variable, corresponding with the

% input/output structure. The data structure in the input file should be a

% cell-array for this particular function.

%

% See also FT_PREPROCESSING, FT_DATAYPE_RAW, FT_APPENDTIMELOCK, FT_APPENDFREQ,

% FT_APPENDSOURCE, FT_APPENDSENS

% Copyright (C) 2005-2008, Robert Oostenveld

% Copyright (C) 2009-2011, Jan-Mathijs Schoffelen

%

% This file is part of FieldTrip, see http://www.fieldtriptoolbox.org

% for the documentation and details.

%

% FieldTrip is free software: you can redistribute it and/or modify

% it under the terms of the GNU General Public License as published by

% the Free Software Foundation, either version 3 of the License, or

% (at your option) any later version.

%

% FieldTrip is distributed in the hope that it will be useful,

% but WITHOUT ANY WARRANTY; without even the implied warranty of

% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

% GNU General Public License for more details.

%

% You should have received a copy of the GNU General Public License

% along with FieldTrip. If not, see <http://www.gnu.org/licenses/>.

%

% $Id$

% these are used by the ft_preamble/ft_postamble function and scripts

ft_revision = '$Id$';

ft_nargin = nargin;

ft_nargout = nargout;

% do the general setup of the function

ft_defaults

ft_preamble init

ft_preamble debug

ft_preamble loadvar varargin

ft_preamble provenance varargin

% the ft_abort variable is set to true or false in ft_preamble_init

if ft_abort

return

end

% set the defaults

cfg.keepsampleinfo = ft_getopt(cfg, 'keepsampleinfo', 'ifmakessense');

try

% although not 100% robust, this could make some users becoming aware of the issue of overlapping trials

for i=1:numel(varargin)

dataset{i} = ft_findcfg(varargin{i}.cfg, 'dataset');

hassampleinfo(i) = isfield(varargin{i}, 'sampleinfo');

end

if ~all(strcmp(dataset, dataset{1})) && ~strcmp(cfg.keepsampleinfo, 'no')

ft_warning('the data has overlapping segments or originates from different recordings on disk');

ft_warning('please consider specifying cfg.keepsampleinfo=''no''')

end

end % try

haschantype = false;

haschanunit = false;

for i=1:length(varargin)

% if one of them has chantype or chanunit, we want it for the others as well

haschantype = haschantype || isfield(varargin{i}, 'chantype');

haschanunit = haschanunit || isfield(varargin{i}, 'chanunit');

end

% ensure that the input data is valid for this function

for i=1:length(varargin)

varargin{i} = ft_checkdata(varargin{i}, 'datatype', {'raw+comp', 'raw'}, 'feedback', 'no', 'haschantype', haschantype, 'haschanunit', haschanunit, 'hassampleinfo', cfg.keepsampleinfo);

end

% set the defaults

cfg.appendsens = ft_getopt(cfg, 'appendsens', 'no');

cfg.appenddim = ft_getopt(cfg, 'appenddim', []);

cfg.tolerance = ft_getopt(cfg, 'tolerance', 1e-5); % this is passed to append_common, which passes it to ft_selectdata

isequaltime = true;

isequallabel = true;

issamelabel = true;

isequalfsample = true;

for i=2:numel(varargin)

isequaltime = isequaltime && isequal(varargin{i}.time , varargin{1}.time );

isequallabel = isequallabel && isequal(varargin{i}.label, varargin{1}.label);

issamelabel = issamelabel && isempty(setxor(varargin{i}.label, varargin{1}.label));

isequalfsample = isequalfsample && isfield(varargin{i},'fsample') && isfield(varargin{1},'fsample') && isequal(varargin{i}.fsample, varargin{1}.fsample);

end

if isempty(cfg.appenddim) || strcmp(cfg.appenddim, 'auto')

if isequallabel || issamelabel

cfg.appenddim = 'rpt';

elseif isequaltime && ~isequallabel && ~issamelabel

cfg.appenddim = 'chan';

else

ft_error('cannot append this data');

end

end

ft_info('concatenating over the "%s" dimension\n', cfg.appenddim);

% ft_selectdata cannot create the union of the data contained in cell-arrays

% make a dummy without the actual data, but keep trialinfo/sampleinfo/grad/elec/opto

% also remove the topo/unmixing/topolabel, if present, otherwise it is not

% possible to concatenate raw and comp data. Note that in append_common the

% topo etc. is removed anyhow, when appenddim = 'chan'

dummy = cell(size(varargin));

hastopo = false;

hasunmixing = false;

for i=1:numel(varargin)

dummy{i} = removefields(varargin{i}, {'trial', 'time'});

hastopo = isfield(dummy{i}, 'topo');

hasunmixing = isfield(dummy{i}, 'unmixing');

if strcmp(cfg.appenddim, 'chan')

% this avoids a bunch of confusing warnings in append_common

dummy{i} = removefields(dummy{i}, {'topo', 'unmixing', 'topolabel'});

end

% add a dummy data field, this causes the datatype to become 'chan'

dummy{i}.dummy = ones(numel(dummy{i}.label),1);

dummy{i}.dummydimord = 'chan';

end

% don't do any data appending inside the common function

cfg.parameter = {};

% use a low-level function that is shared with the other ft_appendxxx functions

% this will handle the trialinfo/sampleinfo/grad/elec/opto

data = append_common(cfg, dummy{:});

% this is the actual data field that will be appended further down

cfg.parameter = {'trial'};

switch cfg.appenddim

case 'chan'

if isequaltime

ntrl = length(varargin{1}.trial);

dat = varargin{1}.trial;

lab = varargin{1}.label(:);

if hastopo && isfield(varargin{1}, 'topo')

topo = varargin{1}.topo;

topolab = varargin{1}.topolabel(:);

else

topo = eye(numel(varargin{1}.label));

topolab = varargin{1}.label(:);

end

if hasunmixing && isfield(varargin{1}, 'unmixing')

unmixing = varargin{1}.unmixing;

else

unmixing = eye(numel(varargin{1}.label));

end

for i=2:numel(varargin)

for j=1:ntrl

dat{j} = cat(1, dat{j}, varargin{i}.trial{j});

end

lab = cat(1, lab, varargin{i}.label(:));

if hastopo && isfield(varargin{i}, 'topo')

topo = blkdiag(topo, varargin{i}.topo);

topolab = cat(1, topolab, varargin{i}.topolabel);

else

topo = blkdiag(topo, eye(numel(varargin{i}.label)));

topolab = cat(1, topolab, varargin{i}.label(:));

end

if hasunmixing && isfield(varargin{i}, 'unmixing')

unmixing = blkdiag(unmixing, varargin{i}.unmixing);

else

unmixing = blkdiag(unmixing, eye(numel(varargin{i}.label)));

end

end

data.label = lab; % replace the one from append_common

data.trial = dat;

data.time = varargin{1}.time;

if haschantype

chantype = varargin{1}.chantype(:);

for i=2:numel(varargin)

chantype = cat(1, chantype, varargin{i}.chantype(:));

end

data.chantype = chantype;

end

if haschanunit

chanunit = varargin{1}.chanunit(:);

for i=2:numel(varargin)

chanunit = cat(1, chanunit, varargin{i}.chanunit(:));

end

data.chanunit = chanunit;

end

if isfield(varargin{1}, 'topodimord'), data.topodimord = varargin{1}.topodimord; end

if isfield(varargin{1}, 'unmixingdimord'), data.unmixingdimord = varargin{1}.unmixingdimord; end

if hastopo, data.topo = topo; end

if hastopo, data.topolabel = topolab; end

if hasunmixing, data.unmixing = unmixing; end

else

ft_error('data has different time, cannot append over channels');

end

case 'rpt'

if isequallabel

% the channels are the same and sorted in the same order

dat = cell(1,0);

tim = cell(1,0);

for i=1:numel(varargin)

dat = cat(2, dat, varargin{i}.trial);

tim = cat(2, tim, varargin{i}.time);

end

data.trial = dat;

data.time = tim;

else

% the channels are not the same, or do not appear in the same order

% only return the intersection of the channels

dat = cell(1,0);

tim = cell(1,0);

for i=1:numel(varargin)

% find the indices of the channels in each dataset, sorted according to the first input

[dum, indx] = match_str(data.label, varargin{i}.label);

for j=1:numel(varargin{i}.trial)

dat = cat(2, dat, {varargin{i}.trial{j}(indx,:)});

tim = cat(2, tim, {varargin{i}.time{j}});

end

end

data.trial = dat;

data.time = tim;

data.label; % keep it as determined by append_common

end

otherwise

ft_error('unsupported cfg.appenddim');

end % switch

if isequalfsample

data.fsample = varargin{1}.fsample;

end

% do the general cleanup and bookkeeping at the end of the function

ft_postamble debug

ft_postamble previous varargin

ft_postamble provenance data

ft_postamble history data

ft_postamble savevar data