bml_definetrial

 BML_DEFINETRIAL transforms a continuous raw into a trialed raw 

 Use as
   trl_raw = bml_definetrial(cfg,raw)
   trl_raw = bml_definetrial(cfg.annot,raw)

 raw - continuous raw file, with time consistent with annot stars/ends

 cfg.annot - annotation table
 cfg.fixsamples - number of samples for each trial, or 
       false to allow different length trials, or
       'auto' to use fixsamples if duration of all annots is the same 
 cfg.trial_t0 - defines the time reference for the trials
       if false, the same time reference for all files is maintained
       if true each trial gets its own time reference, at the begging of the trial
       if char or cellstr or string, it is used to select a variable from 
         annot to use as time reference for each trial
       if table or numeric, and length matched trials, these values are
         used as time reference for each trial
 cfg.equalize_times - logical. if true times all trials get the same time vector
       defaults to true if duration of all annots is the same and trial_t0
       is not false
 cfg.timetol - double. time tolerance in seconds. Defaults to 1e-6

 returns a FT_DATATYPE_RAW with the trials defined by cfg.annot

0001 function trl_raw = bml_definetrial(cfg,raw)
0002 
0003 % BML_DEFINETRIAL transforms a continuous raw into a trialed raw
0004 %
0005 % Use as
0006 %   trl_raw = bml_definetrial(cfg,raw)
0007 %   trl_raw = bml_definetrial(cfg.annot,raw)
0008 %
0009 % raw - continuous raw file, with time consistent with annot stars/ends
0010 %
0011 % cfg.annot - annotation table
0012 % cfg.fixsamples - number of samples for each trial, or
0013 %       false to allow different length trials, or
0014 %       'auto' to use fixsamples if duration of all annots is the same
0015 % cfg.trial_t0 - defines the time reference for the trials
0016 %       if false, the same time reference for all files is maintained
0017 %       if true each trial gets its own time reference, at the begging of the trial
0018 %       if char or cellstr or string, it is used to select a variable from
0019 %         annot to use as time reference for each trial
0020 %       if table or numeric, and length matched trials, these values are
0021 %         used as time reference for each trial
0022 % cfg.equalize_times - logical. if true times all trials get the same time vector
0023 %       defaults to true if duration of all annots is the same and trial_t0
0024 %       is not false
0025 % cfg.timetol - double. time tolerance in seconds. Defaults to 1e-6
0026 %
0027 % returns a FT_DATATYPE_RAW with the trials defined by cfg.annot
0028 
0029 if istable(cfg)
0030   cfg = struct('annot',cfg);
0031 end
0032 annot            = bml_getopt(cfg,'annot');
0033 fixsamples       = bml_getopt(cfg,'fixsamples','auto');
0034 trial_t0         = bml_getopt(cfg,'trial_t0',false);
0035 equalize_times   = bml_getopt(cfg,'equalize_times');
0036 timetol          = bml_getopt(cfg,'timetol',1e-6);
0037 
0038 assert(~isempty(annot),'annot required');
0039 assert(~isempty(raw),'raw required');
0040 assert(isstruct(raw),'ivalid raw');
0041 assert(all(ismember({'label','time','trial'},fields(raw))),'ivalid raw');
0042 assert(numel(raw.trial)==1,'raw should have single trial (continuous)');
0043 
0044 if islogical(trial_t0)
0045   if trial_t0
0046     trial_t0 = annot.starts;
0047   else
0048     trial_t0 = zeros(height(annot),1);
0049   end
0050 elseif ischar(trial_t0) || isstring(trial_t0) || iscellstr(trial_t0)
0051   trial_t0 = cellstr(trial_t0);
0052   if ismember(trial_t0,annot.Properties.VariableNames)
0053     trial_t0 = annot.(trial_t0{1});
0054   else
0055     error('specified trial_t0 doesn''t coincide with annot''s variable names');
0056   end
0057 elseif istable(trial_t0)
0058   if width(trial_t0)==1 && height(trial_t0)==height(annot)
0059     trial_t0 = trial_t0{:,1};
0060   else
0061     error('invalid trial_t0');
0062   end
0063 elseif isnumeric(trial_t0)
0064   if size(trial_t0,1) <  size(trial_t0,2)
0065     trial_t0 = trial_t0';
0066   end
0067   assert(size(trial_t0,1) == height(annot),'invalid trial_t0');    
0068 else
0069   error('invalid trial_t0');
0070 end
0071   
0072 coord = bml_raw2coord(raw);
0073 trl = [bml_time2idx(coord,annot.starts), bml_time2idx(coord,annot.ends)];
0074 
0075 if isnumeric(fixsamples)
0076   trl(:,2) = trl(:,1) + fixsamples;
0077 elseif islogical(fixsamples) && ~fixsamples
0078   %do nothing
0079 elseif strcmp(fixsamples,'auto')
0080   if length(unique(annot.duration))==1
0081     trl(:,2) = trl(:,1) + min(trl(:,2)-trl(:,1));
0082   end
0083 end
0084 
0085 trl_raw=raw;
0086 trl_raw.trial = cell(1,size(trl,1));
0087 trl_raw.time = cell(1,size(trl,1));
0088 trl_raw.sampleinfo = trl;
0089 for i=1:size(trl,1)
0090   trl_raw.trial{i}=raw.trial{1}(:,trl(i,1):trl(i,2));
0091   trl_raw.time{i}=raw.time{1}(:,trl(i,1):trl(i,2)) - trial_t0(i);
0092 end
0093 
0094 if isempty(equalize_times)
0095   equalize_times = ~all(trial_t0==0) && length(unique(trl(i,2)-trl(i,1)))==1;
0096 end
0097 if equalize_times
0098   trial_len = unique(trl(i,2)-trl(i,1)+1);
0099   assert(~all(trial_t0==0) && length(trial_len)==1,...
0100     'can''t equalize times');
0101   period = cellfun(@(x)  mean(diff(x)),trl_raw.time); 
0102   period = uniquetol(period,timetol);
0103   assert(length(period)==1,'inconsistent sampling frequencies');
0104   t0 = mean(cellfun(@(x)x(1),trl_raw.time));
0105   t0 = round(t0,max([-ceil(log10(timetol)),0]));
0106   time_eq = t0 + (0:(trial_len-1))*period;
0107   for i=1:numel(trl_raw.time)
0108     trl_raw.time{i} = time_eq;
0109   end
0110 end
0111 
0112 trl_raw = ft_checkdata(trl_raw);
0113 
0114 
0115 
0116