function [ev] = ft_recodeevent(cfg, event, trl)

% FT_RECODEEVENT will recode the event structure, given the trial
% definition that was analyzed
%
% In FieldTrip, you always start with defining a "trl" field containing
% the samples in the raw datafile that you want to analyze. That "trl"
% is based on the events in the dataset. After artifact rejection, it may
% be the case that trials have been removed completely, or that trials
% have been cut into pieces. This complicates finding a match between the
% original events and the pieces of data that are analyzed. This functino
% restores that match.
%
% Use as
%   [ev] = ft_recodeevent(cfg, data)
% where cfg is a structure with configuration settings and data contains the
% (nested) configuration that describes the original trial definition and
% event structure.
%
% Alternatively, you can also specify the event structure and trial definition
% yourself with
%   [ev] = ft_recodeevent(cfg, event, trl)
%
% the configuration can contain
%   cfg.eventtype   = empty, 'string' or cell-array with multiple strings
%   cfg.eventvalue  = empty or a list of event values (can be numeric or string)
%
%   cfg.searchrange = 'anywhere'      search anywhere for the event, (default)
%                     'insidetrial'   only search inside
%                     'outsidetrial'  only search outside
%                     'beforetrial'   only search before the trial
%                     'aftertrial'    only search after  the trial
%                     'beforezero'    only search before time t=0 of each trial
%                     'afterzero'     only search after  time t=0 of each trial
%
%   cfg.nearestto   = 'trialzero'     compare with time t=0 for each trial (default)
%                     'trialbegin'    compare with the begin of each trial
%                     'trialend'      compare with the end of each trial
%
%   cfg.match       = 'exact' or 'nearest'
%
%   cfg.output      = 'event'             the event itself
%                     'eventvalue'        the value of the event
%                     'eventnumber'       the number of the event
%                     'samplenumber'      the sample at which the event is located
%                     'samplefromoffset'  number of samples from t=0 (c.f. response time)
%                     'samplefrombegin'   number of samples from the begin of the trial
%                     'samplefromend'     number of samples from the end   of the trial
%
% See also FT_DEFINETRIAL, FT_REDEFINETRIAL, FT_PREPROCESSING

% Copyright (C) 2005, Robert Oostenveld
%
% 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

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

% set the defaults
cfg.eventtype   = ft_getopt(cfg, 'eventtype',   []);
cfg.eventvalue  = ft_getopt(cfg, 'eventvalue',  []);
cfg.searchrange = ft_getopt(cfg, 'searchrange', 'anywhere');
cfg.nearestto   = ft_getopt(cfg, 'nearestto',   'trialzero');
cfg.match       = ft_getopt(cfg, 'match',       'nearest');
cfg.output      = ft_getopt(cfg, 'output',      'eventvalue');

% these should be numeric lists or cell-arrays with strings
if ischar(cfg.eventtype)
  cfg.eventtype = {cfg.eventtype};
end
if ischar(cfg.eventvalue)
  cfg.eventvalue = {cfg.eventvalue};
end

if nargin==2
  % event and trl are not specified in the function call, but the data is given ->
  % try to locate event and trl in the configuration
  data  = event;                       % rename the input variable
  if isfield(data, 'cfg')
    event = ft_findcfg(data.cfg, 'event');  % search for the event field
    trl   = ft_findcfg(data.cfg, 'trl');    % search for the trl field
  else
    event = [];
    trl   = [];
  end
  if isempty(event)
    ft_error('could not locate event structure in the data');
  elseif isempty(trl)
    ft_error('could not locate trial definition in the data');
  end
elseif nargin~=3
  ft_error('incorrect number of input arguments');
end

Ntrl   = size(trl,1);
Nevent = length(event);

% select the events of interest
fprintf('trial definition describes %d trials\n', Ntrl);
fprintf('original event structure contains %d events\n', Nevent);
selecttype  = zeros(Nevent,1);
selectvalue = zeros(Nevent,1);
for i=1:Nevent
  % test whether this event should be selected
  if ~isempty(cfg.eventtype)
    selecttype(i) = ~isempty(intersect(cfg.eventtype, event(i).type));
  else
    selecttype(i) = 1;
  end
  % test whether this event should be selected
  if ~isempty(cfg.eventvalue)
    selectvalue(i) = ~isempty(intersect(cfg.eventvalue, event(i).value));
  else
    selectvalue(i) = 1;
  end
end
fprintf('selected %d events based on event type\n', sum(selecttype));
fprintf('selected %d events based on event value\n', sum(selectvalue));
fprintf('selected %d events based on event type and value\n', sum(selecttype.*selectvalue));
eventnum = find(selecttype.*selectvalue);
event = event(eventnum);
Nevent = length(event);

if Nevent<1
  ft_error('there are no events to analyze');
end

% make a list with the sample, offset and duration of each event
% and sort the events according to the sample at which they occurred
sample   = zeros(Nevent,1);
offset   = zeros(Nevent,1);
duration = zeros(Nevent,1);
for i=1:Nevent
  sample(i) = event(i).sample;
  if ~isempty(event(i).offset)
    offset(i) = event(i).offset;
  else
    offset(i) = nan;
  end
  if ~isempty(event(i).duration)
    duration(i) = event(i).duration;
  else
    duration(i) = nan;
  end
end
[sample, indx] = sort(sample);   % sort the samples
offset = offset(indx);           % sort the offset accordingly
duration = duration(indx);       % sort the duration accordingly
event = event(indx);             % sort the events accordingly
eventnum = eventnum(indx);       % sort the numbers of the original events

for i=1:Ntrl
  trlbeg    = trl(i,1);
  trlend    = trl(i,2);
  trloffset = trl(i,3);
  trlzero   = trlbeg - trloffset;  % the sample that corresponds with t=0

  if strcmp(cfg.nearestto, 'trialzero')
    trlsample = trlzero;             % the sample that corresponds with t=0
  elseif strcmp(cfg.nearestto, 'trialbegin')
    trlsample = trlbeg;              % the sample at which the trial begins
  elseif strcmp(cfg.nearestto, 'trialend')
    trlsample = trlend;              % the sample at which the trial ends
  else
    ft_error('incorrect specification of cfg.nearestto')
  end

  % compute a "distance" measure for each event towards this trial
  switch cfg.searchrange
    case 'anywhere'
      distance = abs(sample - trlsample);
    case 'beforezero'
      distance = abs(sample - trlsample);
      distance(find(sample>=trlzero)) = inf;
    case 'afterzero'
      distance = abs(sample - trlsample);
      distance(find(sample<=trlzero)) = inf;
    case 'beforetrial'
      distance = abs(sample - trlsample);
      distance(find(sample>=trlbeg)) = inf;
    case 'aftertrial'
      distance = abs(sample - trlsample);
      distance(find(sample<=trlend)) = inf;
    case 'insidetrial'
      distance = abs(sample - trlsample);
      distance(find((sample<trlbeg) | (sample>trlend))) = inf;
    case 'outsidetrial'
      distance = abs(sample - trlsample);
      distance(find((sample>=trlbeg) & (sample<=trlend))) = inf;
    otherwise
      ft_error('incorrect specification of cfg.searchrange');
  end

  % determine the event that has the shortest distance towards this trial
  [mindist, minindx] = min(distance);
  if length(find(distance==mindist))>1
    ft_error('multiple events are at the same distance from the trial');
  end

  if isinf(mindist)
    % no event was found
    ev(i) = nan;
  elseif mindist~=0 && strcmp(cfg.match, 'exact')
    % the event is not an exact match
    ev(i) = nan;
  else
    switch cfg.output
      case 'event'
        ev(i) = event(minindx);
      case 'eventvalue'
        ev(i) = event(minindx).value;
      case 'eventnumber'
        ev(i) = eventnum(minindx);
      case 'samplenumber'
        ev(i) = event(minindx).sample;
      case 'samplefromoffset'
        ev(i) = event(minindx).sample - trlzero;
      case 'samplefrombegin'
        ev(i) = event(minindx).sample - trlbeg;
      case 'samplefromend'
        ev(i) = event(minindx).sample - trlend;
      otherwise
        ft_error('incorrect specification of cfg.output');
    end
  end

end % looping over all trials
