Function Reference

This page contains reference documentation for the integral functions of the Lossless pipeline. More explicit documentation can be found on the Vised Marks wiki and tutorial.

chan_variance

This function creates data arrays from an epoched EEG structure to eventually
be flagged by the marks_array2flags function.
Output:
EEG - EEG Structure
data_sd - Data array for further processing
Input:
EEG - Standard EEG structure
'datafield'  - If 'data' is pair, output array is created with EEG data. 
               Otherwise, it is created via ICA data
'epoch_inds' - Array of 1's and 0's marking epochs to consider. Typically
               this array is created via marks_label2index.
'plot_figs'  - String; one of: 'on', 'off'. Default off.
'varmeasure' - String; one of: 'sd', 'absmean', 'spect'. Methodology for
               value that will represent the epoch.
'detrending' - String; one of: 'on', 'off'. Detrend epochs.
'spectrange' - Array of double, length 2. e.g. [0 7].
               Only valid for varmeasure spect.

marks_array2flags

This function takes an array typically created by chan_variance or
chan_neighbour_r and marks either periods of time or sources as outliers.
Often these discovered time periods are artefactual and are  marked as such.

An array of values representating the distribution of values inside an
epoch are passed to the function. Next, these values are put through one
of three outlier detection schemes. Epochs that are outliers are marked
as 1's and are 0 otherwise in a second data array. This array is then
averaged column-wise or row-wise. Column-wise averaging results in
flagging of time, while row-wise results in rejection of sources. This
averaged distribution is put through another round of outlier detection.
This time, if data points are outliers, they are flagged.

Output:
outarray - Mask of periods of time that are flagged as outliers
outind   - Array of 1's and 0's. 1's represent flagged sources/time. 
           Indices are only flagged if out_dist array fall above a second
           outlier threshhold.
out_dist - Distribution of rejection array. Either the mean row-wise or
           column-wise of outarray.

Input:
inarray - Data array created by eiether chan_variance or chan_neighbour_r

Varargs:
init_dir     - String; one of: 'pos', 'neg', 'both'. Allows looking for
               unusually low (neg) correlations, high (pos) or both.
flag_dim     - String; one of: 'col', 'row'. Col flags time, row flags 
               sources.
init_method  - String; one of: 'q', 'z', 'fixed'. See method section. 
init_vals    - See method section.
init_crit    - See method section.
flag_method  - String; one of: 'q', 'z', 'fixed'. See method section.
               Second pass responsible for flagging aggregate array.
flag_vals    - See method section. Second pass for flagging.
flag_crit    - See method section. Second pass for flagging.
plot_figs    - String; one of: 'on', 'off'.
title_prefix - String prefix to add to each figure.
trim         - Numerical value of trimmed mean and std. Only valid for z.

Methods:
fixed - This method does no investigation if the distribution. Instead
        specific criteria are given via vals and crit. If fixed
        is selected for the init_method option, only init_vals should be
        filled while init_crit is to be left empty. This would have the
        effect of marking some interval, e.g. [0 50] as being an outlier.
        If fixed is selected for flag_method, only flag_crit should be
        filled. This translates to a threshhold that something must pass
        to be flagged. i.e. if 0.2 (20) of channels are behaving as
        outliers, then the period of time is flagged. Conversely if
        flag_dim is row, if a source is bad 20of the time it is marked
        as a bad channel.

q     - Quantile method. init_vals allows for the specification of which
        quantiles to use, e.g. [.3 .7]. When using flag_vals only specify
        one quantile, e.g [.7]. The absolute difference between the
        median and these quantiles returns a distance. init_crit and
        flag_crit scales this distance. If values are found to be outside
        of this, they are flagged.

z     - Typical Z score calculation for distance. Vals and crit options
        not used for this methodology. See trim option above for control.

padflag

Function which given an array 'flags' of values, prepends and appends a value
around a given nonzero block of data in the given array.
This value can be customized via the vararg 'value'. (e.g. 'value',0.5)

marks_add_label

pop_marks_merge_labels

marks_epochs2continuous

chan_neighbour_r

pop_marks_flag_gaps

pop_marks_select_data

pop_marks_event_gap

This function seeks to mark periods of time based on event distances.
These distances can be relative to one another, or the lack of events
after periods of time.

Output:
EEG - Standard EEG structure with new mark
com - Command for EEG.history

Input:
EEG         - Standard EEG structure
event_type  - Cell array of strings. If exact is off, used for pattern matching
crit_dur_ms - Integer in ms. Duration marks must respect. Based on other options
              marks must be within or outside this duration.
new_label   - String new mark name
new_color   - Array size 3 for color, e.g. [0.5 0.5 0.5]

Varargs:
exact        - String; one of: 'on', 'off'. If off, pattern matching can
               be used based on mark_label.
ref_point    - String; one of: 'both', 'first', 'second'. Controls
               offsets argument.
offsets      - Array size two (e.g. [-1 1]). Allows for marking outside
               of gaps. This is done relative to the reference point.
               In the case of the ref_point being 'both' the first
               element is the offset backwards in time, the second is
               forward in time.
invert_flags - String; one of: 'on', 'off'. Invert selection.
critdir      - String; one of: 'max', 'min'. If max, after an event,
               there must be another event within crit_dur_ms. Otherwise
               time is then flagged. If min, after an event, if another
               event fires before crit_dur_ms has finished, time is then
               marked.
interval     - Either 'off', or an ordered cell array representing the
               start and stop points of some interval. Can be used to
               mark rest or break periods inside of a task. Elements of
               the ordered cell array must be the same as event_type.