M file template for filters

Filter .m files should be saved to the +filter directory in the SEV's root installation path. Currently, the file name is prefixed with filter_ and followed by the filter name. For example, the filename containing SEV's median calculator is filter_median.m. Information about the filter method must be entered in the filter.inf file, which can be edited with MATLAB or any text editor. More will be said about this later.

#Filter Prototype The SEV prototype for any MATLAB based pattern recognition classifier (i.e. an event detection algorithm) is as follows

`function filtsig = funcname(src_index, optional_params)'

where funcname should be replaced with the actual filename (sans .m) or equivalently the filter name.

src_index

src_index is either a vector of one polysomnography recording, or a cell containing two or more vectors of polysomnogram recordings. Many filter algorithms require only one channel for processing, while others (like the Adaptive Noise Cancellation for RLS) require additional channels for reference cleaning or context.

The adaptive noise cancellation for RLS filter prototype is

function filtsig = anc_rls(src_index,ref_indices, optional_params)

Note that the function takes in a variable called "ref_indices". This is because the filter requires one or more reference channels. The leg EMG data is found in src_index{1} and the reference ECG data is in ref_indices.

optional_params

Developers can choose to allow users (to include themselves) to adjust certain parameters of their algorithm if they wish. This can be helpful during development process where some fine tuning is needed on the fly or where a variety of parameter choices may be acceptable under possible settings (e.g. wavelet based methods with different kernel choices).
optional_params is an optional argument, which is either empty, or is a struct whose fields may be adjusted by the user and accessed within the event detection .m file. Event detection specific parameters are saved in a .plist (xml-based) file in order to retain user preferences.

The following code is taken from detection_artifact_hp_20hz.m and is shown here as an example of how to define which parameters will be available to users through SEV's graphical interface, and how their default values are set.

if(nargin==3 && ~isempty(optional_params)) params = optional_params; else

pfile = strcat(mfilename('fullpath'),'.plist');

if(exist(pfile,'file'))
    %load it
    params = plist.loadXMLPlist(pfile);
else
    %make it and save it for the future
    params.order = 4;
    params.sigma = 0.01; %trace initialization value
    params.lambda = 0.995; %forgetting factor
    params.samples2delay = 0;
    plist.saveXMLPlist(pfile,params);
end

end

If optional parameters are passed in, then the code stores them in the params variable.

if(~isempty(optional_params)
    params = optional_params;

Otherwise, SEV checks to see if a .plist file exists which will holds the last used parameter settings, and loads them if the file exists. The file is the same name as detection .m file, but with the .m extension replaced by .plist (this is done automatically with the strcat and mfilename('fullpath') calls:

else
    pfile = strcat(mfilename('fullpath'),'.plist');    
    if(exist(pfile,'file'))
        params = plist.loadXMLPlist(pfile);

If no file is found, then default parameter fields are added with corresponding values, and then these are saved to the .plist file for future reference, as such:

else
    params.scale_factor=1.5;
    params.rms_short_sec=2;
    params.rms_long_min=5;
    params.additional_bufer_sec = 1; 
    params.merge_within_sec = 5;        
    plist.saveXMLPlist(pfile,params);
end

Troubleshooting

If you have added or removed a params field and a .plist file already exists, you will need to delete the .plist file and run the detection .m file again. For example, if I decide that I no longer want to give the user the option to change additional_buffer_sec, and remove it from the above snippet in detection_artifact_hp_20hz.m, then I should next delete detection_artifact_hp_20hz.plist from the +filter directory before running the event detector in the SEV.

##stageStruct SEV passes sleep staging and basic sleep scoring information to the detection algorithm through the stageStruct input parameter which is a struct with the following fields

• line : vector of consecutively scored epochs for the current study. The size of the vector should be the ceiling of study_duration_in_seconds divided by standard_epoch_sec. Element values are numeric and include
• 0 for wake
• 1 stage 1
• 2 stage 2
• 3 stage 3
• 4 stage 4
• 5 Rapid eye movement sleep
• 6 unused
• 7 Artifact or unknown
• count : 8x1 vector with the total epoch count for each category of sleep
  • count(1) - Number of epochs scored as wake (Stage 0)
  • count(2) - number of epochs scored as Stage 1
  • ....
  • count(8) - number of artifact epochs (i.e. 7)
• cycles: vector of the same length as line. Each element corresponds to the consecutive epoch (i.e. first element is for the first epoch) and the values are the NREM/REM cycle for that epoch as classified by SEV.
• firstNonWake: index of the first epoch that is not scored wake (0) or unknown (7)
• filename : the filename of the .STA file that the staging data was parsed from.
• standard_epoch_sec : the epoch size in seconds that stages were scored on (30 seconds is typical)
• study_duration_in_seconds: duration of the sleep study in seconds (29850 - 30000 are typical for over night studies)

Incorporating filters into SEV

Newly created event classifiers are added to the SEV by inserting a description line into the filter.inf file found in the +detection path. This file can be edited with MATLAB (e.g. type edit +filter/filter.inf from MATLAB's console window when in SEV's working directory) or any text editor.

The first line should not be changed and contains the header, or descriptive fields that must be entered for each event detection algorithm that will be used by SEV.

#MATLAB_filename Label Number_of_channels_required Dialog_name Batch_mode_score

For example,

filter_scale filter_scale 0 plist_editor_dlg FilterScale

Each following row describes how an event detector is viewed and handled by SEV.

Once the fields have been entered, save the file and then run SEV's event detection toolbox and select your new algorithm to see your updates.