-
Notifications
You must be signed in to change notification settings - Fork 6
Function Reference
Tyler K. Collins edited this page Nov 8, 2019
·
15 revisions
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.
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.
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.
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)
This function creates a given mark and returns the entire mark structure
modified to include it.
Output:
marks_struct - Modified marks structure. Use this to write to EEG.marks
Input:
marks_struct - Reference to current marks structure. Typically EEG.marks
info_type - String; one of: 'chan_info', 'comp_info', 'time_info'
mark_prop - Cell array of options to create a mark. Order MATTERS.
ORDER FOR CHAN/COMP
label=mark_prop{1};
line_color=mark_prop{2};
tag_color=mark_prop{3};
order=mark_prop{4};
flags=mark_prop{5};
ORDER FOR TIME:
label=mark_prop{1};
line_color=mark_prop{2};
flags=mark_prop{3};
Function which takes a variable amount of marks structures and merges
them into a targeted mark. Typically this is used to merge all
artefactual labels into a single annotation representing rejected time
across all reasons.
Output:
EEG - Standard EEG structure with marks structure modified
com - Command ran for the purposes of EEG.history
Input:
EEG - Standard EEG structure
infotype - String; one of: 'time_info', 'chan_info', 'comp_info'
labels - Cell array of strings to be merged.
Varargs:
target_label - String; which label are marks merged into. Default is
manual.
This function computes the correlation matricies to be passed to markup functions
to either reject periods of time or individual sources.
Output:
EEG - Standard EEG structure
m_neighbr_r - Data array to pass to flagging function
chandist - Matrix storing distance between channels
y - Sorted list of channel distances
chan_win_sd - Std of EEG.data for quick use (not really necessary)
Input:
EEG - Standard EEG structure
nneigbr - Number of neighbours to compare in open interval
method - String; one of: 'max', 'mean', 'trimmean'. This is the function
which aggregates the neighbours into one value.
Vararg:
chan_inds - Arrau pf 1's and 0's marking which channels to consider. See epoch_inds.
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'.
This function searches a given mark and looks for gaps smaller than a given
size and creates a new annotation that 'marks' these gaps. This is then
used to search for epochs of time that are too small to consider for artefact
rejection techniques. By merging the newly created mark into the manual mark
these small periods of time can be rejected.
Output:
EEG - Standard EEG structure.
com - Command that was run for EEG.history to display
Input:
EEG - Standard EEG structure
mark_label - Cell array of String; Mark that is current being
investigated.
crit_dur_ms - Minimum amount of time that must exist between blocks
new_label - String; label
new_color - Array size 3; e.g. [0.5 0.5 0.5]
Vararg:
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.
Reduces the given EEG structure to a subset of the whole dataset based on
mark structure queries. Typically used to purge: time, components, and
channels. Can also be used to select given portions of the data.
Output:
EEG - New EEG structure.
com - EEG.history output
Input:
EEG - Standard EEG structure
infotype - String; one of: 'time_info', 'comp_info', 'chan_info'
indexes - Typically kept empty if using the marks structure to select
data. Otherwise allows for further subselection of time
periods.
Varargs:
labels - Cell array of Strings; which marks labels inside of infotype to
reduce the data by.
exact - String; one of: 'on', 'off'. If off, allows for pattern matching
remove - String; one of: 'on', 'off'. If on, EEG structure is reduced
based on labels queries.
gui - String; one of: 'on', 'off'
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.