Staging Script
The staging portion of the Lossless pipeline allows for additions to datafiles before they enter actual processing. For example, the staging script can be used to filter the data. Another use for the staging script is the automated addition of an annotation that marks break periods. Adding an annotation to mark out break periods means that these epochs will not be a part of the statistical distributions that are used during the decision criteria functions. Without this annotation, the chaotic nature of break periods may skew the statistical distributions and impact the decisions that are made during in-task periods. The last standard example is the study-wide artefact criteria. The study-wide criteria can be used to mark comically bad channels and epochs based on predetermined criteria. Decisions about artefactual channels and epochs with the study-wide criteria are determined using fixed values rather than the quantiles method used in s01. The study-wide criteria can be useful if a dataset has a wide range in quality of recording as it is helpful to enforce various types of limits. Staging scripts often finish with the code required to merge the annotations that were created into the manual mark.
If it becomes necessary to add any sort of extra filtering to datafiles after a study has been initialized, use the following code. Note that filtering can instead be applied during s01 by editing the parameters in the associated batch configuration file c01. This is a notch filter at 60Hz which is fairly standard:
EEG = pop_eegfiltnew(EEG, 59, 61,[], 1, [], 0);
The following example marks the Face13 fade portion of the datafiles:
The fact that this marker is using inexact marking can be seen by the ‘exact’,’off’ line. This means that any mark that contains ‘-f’ in its type will be valid. The first 3000 refers to the number of milliseconds that must be between events to be selected. The next two fields of ‘in_task_fhbc_fade’ and [.7 .7 1] are the name of the mark and its associated colour respectively. Future studies should keep the ‘in_task’ portion of this marks prefix as it allows the reuse of the code found at the end of the staging script where marks are merged into manual. The colour should be left as is. Note the last option: ‘invert_flags’. Since this is on, the mark being created is initialized to be the inverse of whatever is returned by the selection criteria. Thus, the function can be summed up as follows: we know that the datafile is IN TASK when there are NOT gaps in event markers more than 3000 milliseconds apart.
The second function call is similar but seeks to reject the first second of time after a break (i.e. leadup). The amount of time can be found by the difference between the original value of 3000 and the ‘offsets’ values being 1000 milliseconds greater. Note, since ‘invert_flags’ is now off, the period of time selected as ‘in_leadup_fhbc_fade’ is the same as the search criteria. The name of the mark can again be modified, but it is best to keep the ‘in_leadup’ prefix.
The following is an example of marking a datafile as in and out of task via exact marker labels:
This code is functionally equivalent to the previous section, however ‘exact’ is set to ‘on’. Unsurprisingly the second argument of the function calls must now explicitly state which event markers are to be considered.
Depending on the variance in recordings, it may become necessary to add another annotation to the data. Typically these annotations are referred to as the “study-wide” marks. This is because the values that are passed to the criteria function are chosen upon diagnostic inspection of a complete dataset. An example of a script that implements this functionality can be found in the useful scripts repository. See criteria function documentation for a worked example of what these parameters mean. Consult the diagnostics documentation for further information on how to view the study as a whole.
This section briefly outlines the end of the face13_staging.m script.
The first two lines of code in this block take advantage of the previously discussed ‘exact’ behaviour to search for the ‘in_task’ marks. It then takes the inverse of these data points and adds them to an ‘out_task’ mark. The third line of code searches for periods of time that are too small to consider for the pipeline and marks them as out of task via the ‘mark_gap’ annotation. The last line of code merges all of the marks that represent periods of time that the pipeline should not consider into the manual mark. Note that if the in_task prefix was kept, the only thing that needs to change in the above boiler plate is the list of which marks to merge. For example, ‘in_leadup_fhbc_fade’ might become ‘in_leadup_circ19’.