Differences

This shows you the differences between two versions of the page.

Link to this comparison view

reference:ft_definetrial [2018/08/23 14:43] (current)
Line 1: Line 1:
 +=====  FT_DEFINETRIAL =====
 +
 +Note that this reference documentation is identical to the help that is displayed in MATLAB when you type "help ft_definetrial"​.
 +
 +<​html><​pre>​
 +  <a href=/​reference/​ft_definetrial><​font color=green>​FT_DEFINETRIAL</​font></​a>​ defines the segments of data that will be used for
 +  further processing and analysis, i.e. the pieces of data that will
 +  be read in by <a href=/​reference/​ft_preprocessing><​font color=green>​FT_PREPROCESSING</​font></​a>​. 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.
 + 
 +  Use as
 +    [cfg] = ft_definetrial(cfg)
 +  where the configuration structure should contain
 +    cfg.trialdef ​  = structure with details of trial definition, see below
 +    cfg.trialfun ​  = string with function name, see below (default = '​ft_trialfun_general'​)
 +  and also
 +    cfg.dataset ​   = pathname to dataset from which to read the events
 + 
 +  A call to <a href=/​reference/​ft_definetrial><​font color=green>​FT_DEFINETRIAL</​font></​a>​ 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 (subsequently referred to as
 +  the trial function) which returns "​trl"​. The user can specify the
 +  name of his/her custom trial function that is tailored to the
 +  experimental paradigm, or use the default trial function
 +  FT_TRIALFUN_GENERAL.
 + 
 +  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.
 + 
 +  The trial definition "​trl"​ can contain additional columns besides the
 +  required three that represent begin, end and offset. These additional
 +  columns can be used by a custom trialfun to provide numeric information
 +  about each trial such as trigger codes, response latencies, trial
 +  type and response correctness. The additional columns of the "​trl"​
 +  matrix will be represented in data.trialinfo after <a href=/​reference/​ft_preprocessing><​font color=green>​FT_PREPROCESSING</​font></​a>​.
 + 
 +  If FT_TRIALFUN_GENERAL has been used to generate the "​trl"​ matrix, the
 +  function may return a fourth column in the trl-matrix, that refers to
 +  the event-code for the corresponding trial. It depends on the acquisition
 +  system whether or not this fourth column is returned. 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)
 + 
 +  Simple trial definitions (e.g. based on a single trigger) are supported
 +  by FT_TRIALFUN_GENERAL,​ which is the default trial function. This function
 +  supports the following options
 +    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.
 + 
 +  If you want to read all data from a continous file in a single or in
 +  multiple segments, 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)
 + 
 +  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),
 +  you should supply your own trial function and specify that as cfg.trialfun.
 +  See below for pointers to some examples.
 + 
 +  Both the default trial function and your own supplied custom trial
 +  functions in general will call <a href=/​reference/​ft_read_event><​font color=green>​FT_READ_EVENT</​font></​a>​ to collect all event
 +  information (such as triggers) from your dataset and to select
 +  pieces of data according to this information.
 + 
 +  The cfg.trialfun option is a string containing the name of a function
 +  that you wrote yourself and that <a href=/​reference/​ft_definetrial><​font color=green>​FT_DEFINETRIAL</​font></​a>​ will call. The
 +  function should take the cfg-structure as input and should give a
 +  NxM matrix with M equal to or larger than 3) 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 <a href=/​reference/​ft_read_event><​font color=green>​FT_READ_EVENT</​font></​a>​
 +  function to get the event information from your data file.
 + 
 +  See also <a href=/​reference/​ft_preprocessing><​font color=green>​FT_PREPROCESSING</​font></​a>,​ <a href=/​reference/​ft_read_header><​font color=green>​FT_READ_HEADER</​font></​a>,​ <a href=/​reference/​ft_read_data><​font color=green>​FT_READ_DATA</​font></​a>,​ <a href=/​reference/​ft_read_event><​font color=green>​FT_READ_EVENT</​font></​a>,​
 +  FT_TRIALFUN_GENERAL,​ FT_TRIALFUN_EXAMPLE1,​ FT_TRIALFUN_EXAMPLE2
 +</​pre></​html>​