/trunk/examples/toolboxes/fieldtrip/ft_definetrial.m
MATLAB | 166 lines | 50 code | 12 blank | 104 comment | 9 complexity | 892ff52130832a9ef4bae28e9a7651f5 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, LGPL-2.0, GPL-3.0, GPL-2.0, LGPL-2.1, LGPL-3.0, BSD-2-Clause
- function [cfg] = ft_definetrial(cfg);
- % FT_DEFINETRIAL defines the trials, i.e. the pieces of data that will be read
- % in for preprocessing. Trials are defined by their begin and end sample
- % in the data file and each trial has an offset that defines where the
- % relative t=0 point (usually the point of the trigger) is for that trial.
- %
- % Use as
- % [cfg] = ft_definetrial(cfg)
- % where the configuration structure should contain either
- % cfg.trialdef = structure with details of trial definition, see below
- % cfg.trialfun = function name, see below
- %
- % A call to FT_DEFINETRIAL results in the trial definition "trl" being added
- % to the output configuration structure. The trials are defined according
- % to the triggers, trials or other events in the data, or from a
- % user-specified Matlab function which returns "trl".
- %
- % The trial definition "trl" is an Nx3 matrix, N is the number of trials.
- % The first column contains the sample-indices of the begin of each trial
- % relative to the begin of the raw data, the second column contains the
- % sample-indices of the end of each trial, and the third column contains
- % the offset of the trigger with respect to the trial. An offset of 0
- % means that the first sample of the trial corresponds to the trigger. A
- % positive offset indicates that the first sample is later than the trigger,
- % a negative offset indicates that the trial begins before the trigger.
- %
- % Simple trial definitions (e.g. based on a trigger alone) are supported by
- % FT_DEFINETRIAL itself. For this, the general and data format independent way
- % of handling trials is by relying on the FT_READ_EVENT function to
- % collect all event information (such as triggers) from your dataset and
- % select trials based on those events. This is implemented in FT_DEFINETRIAL as
- % cfg.trialdef.eventtype = 'string'
- % cfg.trialdef.eventvalue = number, string or list with numbers or strings
- % cfg.trialdef.prestim = number, latency in seconds (optional)
- % cfg.trialdef.poststim = number, latency in seconds (optional)
- %
- % If you specify cfg.trialdef.eventtype = '?' a list with the events in your
- % data file will be displayed on screen.
- %
- % However, there are also many other complex ways in which you can define
- % data pieces of interest, for example based on a conditional sequence of
- % events (e.g. stimulus trigger followed by a correct response). For those
- % cases, a general mechanism has been implemented through which you can
- % supply your own trial-defining function, the 'trialfun'.
- %
- % This 'trialfun' is a string containing the name of a function that you
- % have to write yourself. The function should take the cfg-structure as
- % input and should give a Nx3 matrix in the same format as "trl" as the
- % output. You can add extra custom fields to the configuration structure to
- % pass as arguments to your own trialfun. Furthermore, inside the trialfun
- % you can use the FT_READ_EVENT function to get the event information
- % from your data file.
- %
- % See also FT_PREPROCESSING, FT_READ_HEADER, FT_READ_DATA, FT_READ_EVENT
- % Undocumented local options:
- % cfg.datafile
- % cfg.dataset
- % cfg.event
- % cfg.trl
- % cfg.version
- % Copyright (c) 2003, Robert Oostenveld, F.C. Donders Centre
- %
- % This file is part of FieldTrip, see http://www.ru.nl/neuroimaging/fieldtrip
- % 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: ft_definetrial.m 948 2010-04-21 18:02:21Z roboos $
- fieldtripdefs
- % check if the input cfg is valid for this function
- cfg = checkconfig(cfg, 'trackconfig', 'on');
- cfg = checkconfig(cfg, 'dataset2files', {'yes'});
- if ~isfield(cfg, 'trl') && (~isfield(cfg, 'trialfun') || isempty(cfg.trialfun))
- % there used to be other system specific trialfuns in previous versions
- % of fieldtrip, but they are deprecated and not included in recent
- % versions any more
- cfg.trialfun = 'trialfun_general';
- warning('no trialfun was specified, using trialfun_general');
- end
- % create the trial definition for this dataset and condition
- if isfield(cfg, 'trl')
- % the trial definition is already part of the configuration
- fprintf('retaining exist trial definition\n');
- trl = cfg.trl;
- if isfield(cfg, 'event')
- fprintf('retaining exist event information\n');
- event = cfg.event;
- else
- event = [];
- end
- elseif isfield(cfg, 'trialfun')
- % evaluate the user-defined function that gives back the trial definition
- fprintf('evaluating trialfunction ''%s''\n', cfg.trialfun);
- % determine the number of outpout arguments of the user-supplied trial function
- try
- % the nargout function in Matlab 6.5 and older does not work on function handles
- num = nargout(cfg.trialfun);
- catch
- num = 1;
- end
- if num==1
- % the user-defined function only gives back the trial definition
- trl = feval(cfg.trialfun, cfg);
- event = [];
- else
- % the user-defined function also gives back detailed information about
- % conditions, reaction time or any other information
- [trl, event] = feval(cfg.trialfun, cfg);
- end
- else
- error('no trialfunction specified, see DEFINETRIAL for help');
- end
- if isfield(cfg, 'trialdef') && isfield(cfg.trialdef, 'eventtype') && strcmp(cfg.trialdef.eventtype, '?')
- % give a gentle message instead of an error
- fprintf('no trials have been defined yet, see DEFINETRIAL for further help\n');
- elseif size(trl,1)<1
- error('no trials were defined, see DEFINETRIAL for help');
- end
- % add the new trials and events to the output configuration
- fprintf('found %d events\n', length(event));
- cfg.event = event;
- fprintf('created %d trials\n', size(trl,1));
- cfg.trl = trl;
- % get the output cfg
- cfg = checkconfig(cfg, 'trackconfig', 'off', 'checksize', 'yes');
- % add information about the version of this function to the configuration
- try
- % get the full name of the function
- cfg.version.name = mfilename('fullpath');
- catch
- % required for compatibility with Matlab versions prior to release 13 (6.5)
- [st, i1] = dbstack;
- cfg.version.name = st(i1);
- end
- cfg.version.id = '$Id: ft_definetrial.m 948 2010-04-21 18:02:21Z roboos $';
- % % remember the exact configuration details in the output
- % cfgtmp = cfg;
- % cfg = [];
- % try cfg.trl = cfgtmp.trl; end
- % try cfg.dataset = cfgtmp.dataset; end
- % try cfg.datafile = cfgtmp.datafile; end
- % try cfg.headerfile = cfgtmp.headerfile; end
- % cfg.previous = cfgtmp;