Permalink
247 lines (227 sloc)
10.5 KB
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
function [cfg] = ft_definetrial(cfg) | |
% FT_DEFINETRIAL defines the trials or segments of data that will be used for further | |
% processing and analysis, i.e. the pieces of data that will be read in by | |
% FT_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 | |
% sample at which the trigger is detected) is for that trial or segment. | |
% | |
% Use as | |
% [cfg] = ft_definetrial(cfg) | |
% where the configuration structure should contain | |
% cfg.trialdef = structure with the details of trial definition, see below | |
% cfg.trialfun = string with the function name, see below (default = 'ft_trialfun_general') | |
% cfg.representation = [], 'numeric' or 'table', determines how the trial definition is returned (default is automatic) | |
% and furthermore | |
% cfg.dataset = string with the filename | |
% or | |
% cfg.headerfile = string with the filename | |
% cfg.datafile = string with the filename | |
% and optionally | |
% cfg.headerformat = string, see FT_FILETYPE (default is automatic) | |
% cfg.dataformat = string, see FT_FILETYPE (default is automatic) | |
% cfg.eventformat = string, see FT_FILETYPE (default is automatic) | |
% | |
% In general, a call to FT_DEFINETRIAL results in the trial definition "trl" being | |
% added to the output configuration. The trials are defined on the basis of events or | |
% triggers by a user-specified MATLAB function that is subsequently referred to as | |
% the trial function. The user can specify their own custom function tailored to the | |
% experimental paradigm, or use one of the default trial functions (see below). | |
% | |
% Simple trial definitions (for example based on a single trigger) are supported by | |
% FT_TRIALFUN_GENERAL, which is specified as the default. It supports the following | |
% options | |
% cfg.trialdef.eventtype = string, or cell-array with strings | |
% 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) | |
% | |
% To read all data from a continuous file in a single or in multiple segments, | |
% FT_TRIALFUN_GENERAL understands the following options | |
% cfg.trialdef.triallength = duration in seconds (can also be 1 or Inf) | |
% cfg.trialdef.ntrials = number of trials (can also be 1 or Inf) | |
% cfg.trialdef.overlap = number between 0 and 1 (exclusive) specifying the fraction of overlap between snippets (0 = no overlap) | |
% | |
% To display a list with the events in your data on screen, you can use | |
% FT_TRIALFUN_SHOW. This is useful for diagnostics; no actual trials will be defined. | |
% | |
% To display a graphical user interface dialog that allows you to select events of | |
% interest, you can use FT_TRIALFUN_GUI. | |
% | |
% The trial definition "trl" is an Nx3 matrix or table, where N is the number of | |
% trials. The first column contains the sample-indices of the start of each trial | |
% relative to the start 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, and a negative offset indicates that the trial | |
% begins before the trigger. | |
% | |
% Besides the required three columns in the trial definition "trl" that represent | |
% start, end and offset, it can have contain additional columns . These additional | |
% columns can be used by a custom trialfun to provide information about each trial, | |
% such as trigger codes, response latencies, trial type and response correctness. | |
% After FT_PREPROCESSING these additional columns of the "trl" matrix will be | |
% represented in the "trialinfo" field. | |
% | |
% If FT_TRIALFUN_GENERAL or FT_TRIALFUN_GUI has been used to generate the "trl" | |
% matrix or table, the function may return a fourth column that refers to the | |
% event-code for the corresponding trial. Whether or not this column is returned | |
% depends on the acquisition system. In general, this fourth column is generated by | |
% default if the event codes are represented numerically, or as a string starting | |
% with 'S' or 'R' (for BrainVision data). | |
% | |
% If you need to define the segments of interest on the basis of a conditional | |
% sequence of events (e.g. stimulus trigger followed by a correct response) or on | |
% basis of some signal feature that needs to be detected in the data, you should | |
% supply in cfg.trialfun the name of a function that you wrote yourself and that | |
% FT_DEFINETRIAL will call. The function receives the cfg structure as input and | |
% should return a NxM matrix in the same format as "trl" as the output. You can add | |
% extra custom fields to cfg.trialdef to pass to your own trialfun. See below for | |
% pointers to some examples. | |
% | |
% See also FT_PREPROCESSING, FT_READ_HEADER, FT_READ_EVENT, FT_TRIALFUN_GENERAL, | |
% FT_TRIALFUN_GUI, FT_TRIALFUN_SHOW, FT_TRIALFUN_BIDS, FT_TRIALFUN_EXAMPLE1, | |
% FT_TRIALFUN_EXAMPLE2 | |
% Undocumented local options: | |
% cfg.datafile | |
% cfg.dataset | |
% cfg.event | |
% cfg.trl | |
% cfg.version | |
% Copyright (C) 2003-2021, Robert Oostenveld, FCDC | |
% | |
% 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 provenance | |
ft_preamble trackconfig | |
% the ft_abort variable is set to true or false in ft_preamble_init | |
if ft_abort | |
return | |
end | |
% check if the input cfg is valid for this function | |
cfg = ft_checkconfig(cfg, 'dataset2files', 'yes'); | |
% this is deprecated as of 26 Sept 2021, it can be removed in a few years | |
if issubfield(cfg, 'trialdef.eventtype') | |
if isequal(cfg.trialdef.eventtype, '?') | |
ft_warning('cfg.trialdef.eventtype=''?'' is deprecated, please specify cfg.trialfun=''ft_trialfun_show'''); | |
cfg.trialfun = 'ft_trialfun_show'; | |
cfg.trialdef = rmfield(cfg.trialdef, 'eventtype'); | |
elseif isequal(cfg.trialdef.eventtype, 'gui') | |
ft_warning('cfg.trialdef.eventtype=''gui'' is deprecated, please specify cfg.trialfun=''ft_trialfun_gui'''); | |
cfg.trialfun = 'ft_trialfun_gui'; | |
cfg.trialdef = rmfield(cfg.trialdef, 'eventtype'); | |
end | |
end % default based on eventtype | |
if issubfield(cfg, 'trialdef.eventvalue') | |
if isequal(cfg.trialdef.eventvalue, '?') | |
ft_warning('cfg.trialdef.eventvalue=''?'' is deprecated, please specify cfg.trialfun=''ft_trialfun_show'''); | |
cfg.trialfun = 'ft_trialfun_show'; | |
cfg.trialdef = rmfield(cfg.trialdef, 'eventvalue'); | |
elseif isequal(cfg.trialdef.eventvalue, 'gui') | |
ft_warning('cfg.trialdef.eventvalue=''gui'' is deprecated, please specify cfg.trialfun=''ft_trialfun_gui'''); | |
cfg.trialfun = 'ft_trialfun_gui'; | |
cfg.trialdef = rmfield(cfg.trialdef, 'eventvalue'); | |
end | |
end % default based on eventvalue | |
% set the default options | |
cfg.trialfun = ft_getopt(cfg, 'trialfun', 'ft_trialfun_general'); % the default might already be set above | |
cfg.representation = ft_getopt(cfg, 'representation'); % this can be empty, 'numeric' or 'table' | |
if isfield(cfg, 'trl') | |
% the trial definition is already part of the configuration | |
ft_info('retaining existing trial definition\n'); | |
trl = cfg.trl; | |
if isfield(cfg, 'event') | |
ft_info('retaining existing event information\n'); | |
event = cfg.event; | |
else | |
event = []; | |
end | |
else | |
% try to locate the trialfun | |
trialfunSpecified = cfg.trialfun; | |
cfg.trialfun = ft_getuserfun(cfg.trialfun, 'trialfun'); | |
if isempty(cfg.trialfun) | |
ft_error('the specified trialfun ''%s'' was not found', trialfunSpecified); | |
else | |
ft_info('evaluating trial function ''%s''\n', func2str(cfg.trialfun)); | |
end | |
% 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 | |
end % if trl is present or trialfun specified | |
if size(trl,1)<1 | |
if isequal(cfg.trialfun, 'ft_trialfun_show') || isequal(cfg.trialfun, str2func('ft_trialfun_show')) | |
% give a gentle message instead of an error | |
ft_notice('no trials have been defined yet, see FT_DEFINETRIAL for further help\n'); | |
else | |
% give an error in all other cases | |
ft_error('no trials were defined, see FT_DEFINETRIAL for help'); | |
end | |
elseif size(trl,2) < 3 | |
ft_error('trl must have at least 3 columns, see FT_DEFINETRIAL for help'); | |
end | |
% set trl to requested type | |
if isempty(cfg.representation) | |
% keep the format as is | |
elseif strcmp(cfg.representation, 'numeric') && istable(trl) | |
% convert from table to numeric | |
trl = table2array(trl); | |
elseif strcmp(cfg.representation, 'table') && isnumeric(trl) | |
% convert the numeric array to a table | |
trl = array2table(trl); | |
% the 3 first columns are named begsample, endsample and offset, and the rest get default names | |
trl.Properties.VariableNames(1:3) = {'begsample', 'endsample', 'offset'}; | |
end | |
% add the events to the output configuration | |
if isstruct(event) | |
ft_info('found %d events\n', length(event)); | |
cfg.event = event; | |
elseif istable(event) | |
ft_info('found %d events\n', size(event, 1)); | |
cfg.event = event; | |
end | |
% add the trial definition to the output configuration | |
if size(trl,1)>0 | |
ft_info('created %d trials\n', size(trl,1)); | |
cfg.trl = trl; | |
end | |
% do the general cleanup and bookkeeping at the end of the function | |
ft_postamble trackconfig | |
ft_postamble provenance | |
ft_postamble debug |