HFOApp: A MATLAB Graphical User Interface for High-Frequency Oscillation Marking

Summary of improvements over existing open-source HFO applications

HFOApp allows simultaneous marking of multiple channels, in contrast to other HFO applications. In HFOApp, the user can do this by simply clicking between channels: a click on any channel in any open display window will allow marking on that channel. In addition, within channels, HFOs can be marked on the raw data or on any filtered data or spectrogram window. The user can choose to simultaneously display and mark as many data channels and as many bandpass-filtered time series windows as needed.

Overview of HFOApp

HFOApp offers automated and manual HFO detection and marking options with a high degree of flexibility and user control. To use HFOApp, the user simply imports iEEG data and can then choose to run any of five preloaded automated detectors or add another automatic detector by following instructions in the manual. For manual marking, the user can first set the data display according to their preference. HFOApp allows display of raw iEEG data, bandpass-filtered data, and spectrograms embedded either into the same window or into two or more separated, but automatically synchronized, windows (Fig. 1A–C). This flexibility is very useful, as individual preferences may differ depending on how many channels are being reviewed, the size of the monitor being used, and other visual factors. Additionally, the user can generate as many bandpass-filtered data displays as needed, each with different user-defined frequency limits. To optimize the display for manual marking, the user can set viewing parameters, such as the length of time displayed in the window, the amplitude of the data, the color of the displayed time series. The user can then scroll through the data, marking the start and end locations of HFO events manually, with ergonomically efficient controls, such as using the mouse to position the cursor and using keyboard shortcuts to scroll through the data and to mark events. Events can be easily added to or removed from the Events List. Controls for the identification, marking, and management of events are intuitive and comprehensible.

• Download figure
• Open in new tab
• Download powerpoint

Figure 1.

Example usage and output of HFOApp. A–C, To visually detect HFOs in our test dataset, we opened the following three windows: a main window that shows raw data (A); a bandpass-filtered window (80–250 Hz for ripple detection; B); and a spectrogram window for the first channel (C). The cursor is indicated as a blue (A, B) or black (C) vertical line. The red dashed rectangle indicates the boundaries of a detected HFO. A summary of the characteristics of the detected event is shown above the plot in blue font.

HFOApp allows for simultaneous review and marking of multiple channels. The user can display as many channels and bandpass-filter windows as needed, reviewing and marking within any displayed window. All displayed data windows are synchronized by default. The toolbox was designed such that the user can easily switch between channels by simply clicking on any time series window.

To assist with manual review and marking, we introduce an interactive, automatic Hilbert detector assist feature that can be used on the fly within the graphical user interface (GUI). This feature allows users who are manually reviewing data to simultaneously use automatic detection to identify all events in all channels in the current time window. As the user manually scrolls through the data, they can deploy the automatic detector on their current time window with a button press, which prompts HFOApp to outline any HFOs that were detected by the automated algorithm. Identified HFOs are then easily managed with mouse and keyboard controls. In addition, when the user manually marks an HFO, they can use the automated assist to define onset thresholds for that event.

An additional strength of HFOApp is the introduction of a dynamic, automated frequency-band determination for filtering based on the peak frequency of the spectrogram, designed to increase the sensitivity of the Hilbert detector. The first step of most automatic detectors includes bandpass filtering the data into distinct, but broad, frequency bands. However, broadband display can make discrimination between artifactual and real HFOs difficult in cases where frequency components of both are present within the broad band. HFOs may be apparent only in a narrow band (Gliske et al., 2017), and, therefore, detection power could potentially be weakened by using broadband filtering. To address this problem, HFOApp allows users to simply click on hotspots in the spectrogram to initiate automated narrow-band detection, based on user-defined parameters.

Using HFOApp

HFOApp requires a MATLAB version from 2019 on (2019a&b, 2020a&b, and 2021a) and will be kept up-to-date with future MATLAB releases. In typical usage, once iEEG data are loaded into HFOApp (see the section Data structure), the raw data are displayed in a time series data window (Fig. 1A). One or more bandpass-filtered time series can then be displayed, embedded either in the original data window as a new row below the raw data or in a new window (Fig. 1B). A spectrogram window can also be generated as a separate window (Fig. 1C). All windows are automatically synchronized; as the user scrolls through the data in any window, all windows move in tandem.

The data can be analyzed for marking HFOs in the following four ways: manual, manual with interactive automation-assisted thresholding, manual with interactive automation-assisted detection, and fully automatic. Within all of these methods, HFOApp allows for simultaneous analysis and marking of multiple data channels, broad flexibility of display, and a high degree of usability. For the three manual marking methods, the user can display and mark as many channels, bandpass filter windows, and spectrogram windows as needed. These windows are user-generated using plain-language, intuitive controls on popup windows prompted by drop-down menu selections.

Four marking methods of HFOApp

Manual marking of HFOs with interactive automation-assisted detection

To make manual marking even faster and more accurate, HFOApp features manual marking with interactive automation-assisted detection. This powerful automated detection tool can be quickly deployed on-the-fly during manual marking with both keyboard shortcuts and mouse clicks, while providing the user with fine control over parameters used by the automation. HFOApp starts in this setting by default; no action is needed to set this mode. As the user scrolls through the data, they can trigger automated detection of HFOs within any displayed bandpass-filtered time series in the following two ways: by simply clicking anywhere on a bandpass-filtered time series (to detect events within that channel) or by pressing “d” on the keyboard (to detect events across all channels). When the user clicks in a data window, the cursor location appears as a vertical line (Fig. 1A) and the z score of the time series is thresholded according to the user-set HFO-onset threshold [Fig. 1B, Onset threshold (SD)]. Any clusters that survive this initial threshold will be identified within a contained search range (see section Implementation of the Hilbert detector). A cluster will be considered an HFO event if it meets the following two criteria: (1) the maximal z score within the cluster meets the inclusion threshold, which is typically larger than the onset threshold [Fig. 1B, Inclusion threshold (SD)]; and (2) the number of oscillatory cycles is greater than a certain threshold (Fig. 1B, Number of cycles). Figure 1 shows an example of HFO detection using the toolbox. In this example, we display the raw data (Fig. 1A) and the bandpass-filtered data (Fig. 1B) in two distinct windows, which is useful when analyzing a large number of channels. Using the keyboard shortcut “d” to run automated detection will perform the above functions over all displayed channels and windows (Fig. 2A,B). Once the multiple-channel detection option is enabled by checking the “Enable multiple channel detection” box (Fig. 2B), the user can press “d” on the keyboard to run the automatic HFO detection as above on all channels in the current time window. Detected events that survive inclusion criteria are outlined with a red dashed line (Fig. 2A,B). Any individual event can be deselected with a right mouse click. Then all selected events can be added to the Events List by pressing “a”. This feature is interactive because it can be deployed on-the-fly across or within channels while manually marking, and because the user has fine control over the detector’s inclusion criteria, including onset threshold, number of cycles, and peak z value, as well as the definition of the background. In practice, the user can press “f” (for “Forward”) to scroll to the next time window of data across all synchronized display windows, press “d” to trigger auto detection, press “a” to add detected events to the list, and press “f” to move on to the next window, repeating this sequence while moving quickly through the data. If the user visually identifies an event missed by the automation, they can quickly add it by manually selecting it with automated thresholding, as described in the previous section. This operating mode of HFOApp allows very fast, easy, and accurate visual marking of HFOs.

• Download figure
• Open in new tab
• Download powerpoint

Figure 2.

Multiple-channel HFO detection. When the “Enable multiple channel detection” option is enabled, all events for all channels in the current time widow can be detected by pressing “d” on the keyboard. A, B, Illustration of the automatically synchronized main (raw) and bandpass-filtered windows of the toolbox. The blue vertical line indicates the cursor location, and the red dashed rectangle indicates detected HFOs. C, Example of formatted output of HFOApp. Each row shows detailed information about each event. The first 10 events are shown. D, A summary of events for each channel.

Fully automatic detection

To use the fully automated HFO detectors in HFOApp, the user first selects Automated HFO detection from the drop-down menu. This will prompt a popup window labeled HFO Auto Detectors. Within this window, the user can choose from five different automatic detectors, including both the HFOApp Hilbert detector (described below) and the RippleLab Hilbert detector (Crépon et al., 2010; Navarrete et al., 2016), the Short Time Energy detector (Staba et al., 2002), the Short Line Length detector (Gardner et al., 2007), and the Montreal Neurologic Institute detector (Zelmann et al., 2012). Once a detector is selected, the options of that detector will populate the window, and the user can set the parameters. Then the user simply clicks the “Run” button. The automated detection will run on all channels loaded in the Display List. Once the automation is finished, the main window will display the message “Automated detection done”, along with the number of new events detected. All new events will be displayed in the Events List. Events can then be manually reviewed by clicking on any event in the list, or by using the arrow keys on the keyboard to scroll through the list. In both cases, as each event is highlighted in the list, it is shown in all display windows (raw and filtered).

Implementation of additional automated detectors

HFOApp includes five different automated HFO detectors, as described above. In addition, users can easily add HFO detectors to HFOApp, and a detailed explanation is provided in the user manual. In brief, we designed a function (HFOAutoDetect.m) that takes a data matrix, a sampling rate, and a configuration data structure as input, and the function is independent from the graphical user interface itself. To configure the input arguments that are required by the new detector, the user simply adds the components to a graphical user interface file (ConfigAutoDetector.mlapp).

Development of the toolbox

The graphical user interface toolbox was developed using App Designer in MATLAB (version R2020b; RRID:SCR_001622). The source code and source data are freely available at https://github.com/zelanolab/hfoapp.git and also as the Extended Data 1.

Data structure

A detailed description of the data structure for this toolbox is provided in the user manual. Here, we will provide a brief description of the data structure. To begin a session, the raw data are first loaded and preprocessed into the proper format for the graphical user interface. Loading of the data can also be implemented separately from the graphical user interface using the MATLAB function HFOLoadData.m, adapted from fieldtrip (Oostenveld et al., 2011; RRID:SCR_004849). This allows loading of Micromed and European Data Format files and can be easily modified to support the user’s own data format. The resulting data are formatted into a MATLAB data structure containing the following fields: (1) mat, which is a two-dimensional data matrix of channel × sample; (2) labels, which is a cell array of channel labels; (3) srate, which is the sampling rate; (4) start_clock, which is the clock time (the type in format of yyyy-MM-dd HH:mm:ss in datetime in the MATLAB) of the first data point; and (5) file, which specifies the full path to the file.

To facilitate the integration of this toolbox with results from other automatic detector toolboxes, HFOApp can read output events that are organized as a MATLAB structure array that contains the fields label and info. The label field indicates the channel name, and info is an N × three cell array, where N is the number of events for the channel. The first column of the cell array info indicates the location of events, and the second column indicates the type of events. The event type must be one or more of the following: γ, ripple, fastripple, ultrafast, and spike. The last column of info is a data structure containing the following fields: AvgFreq (average frequency), NoCycles (number of cycles of the oscillation), PeakZscore (maximal z score of the event), and BPFreq (bandpass frequency band). Once the events are organized in this format, they can be loaded into HFOApp for reviewing or further editing. This feature makes HFOApp a useful visualization and verification tool for the review of results of other automatic detector tools.

The output of HFOApp is simply two text files. Within one file, detailed information about all events from all channels are organized as a formatted table (Fig. 2C). The user can also organize their own events in this format to be loaded into HFOApp for visual validation. The second file is a summary file, which indicates the event information of each channel (e.g., number of occurrences of each event type, total duration), which is useful for a quick glimpse at the results (Fig. 2D).

Graphical user interface layout

HFOApp displays time (Fig. 3) and spectrogram (Fig. 4) domain windows. The bandpass-filter time window shares an identical graphical user interface with the main window. The user can filter the raw data into multiple different frequency bands, and each resulting time series can be displayed either in a separate window or embedded in the main window.

• Download figure
• Open in new tab
• Download powerpoint

Figure 3.

Features of the time series graphical user interface of HFOApp. The main window and bandpass-filter window share the same graphical user interface.

• Download figure
• Open in new tab
• Download powerpoint

Figure 4.

Features of the spectrogram graphical user interface of HFOApp. The layout of the spectrogram window is similar to the main window, with an extra panel added for spectrogram event detection.

To specify a channel to mark, the user simply clicks on the time series of a channel. The background of that channel will be highlighted, and the user can then mark events on that channel. All relevant information pertaining to the location of the click within that time series is immediately displayed in the status bar (Fig. 3, status bar, event detection information). No menu-based setting or switching is required. We believe this feature significantly reduces the time needed to mark HFOs on a dataset with multiple channels. HFOApp was designed to minimize the number of pop-up windows to speed navigation and improve the user experience.

The spectrogram window looks similar to the main window (Fig. 4). By default, only one spectrogram window is open at a time to conserve speed. However, it is possible to open multiple spectrogram windows, which is advisable only if the file size of the dataset is small. When the “Event detection with spectrogram” box (Fig. 4) is checked, the user can perform spectrogram-guided automated event detection by clicking on any hotspot in the spectrogram, as described above.

Implementation of the Hilbert detector

The default automated detector in HFOApp is custom scripted using a Hilbert detector (Crépon et al., 2010; Höller et al., 2018). This detector is used by default for fully automated detection and is used in the interactive automation-assist features. In detail, the raw time series is bandpass filtered at a specified frequency band. A notch filter can also be applied to remove 50/60 Hz power line noise. Then, the envelope of the bandpass-filtered time series is obtained using the Hilbert transform (MATLAB hilbert.m; Fig. 5A,B). Finally, the envelope is z score normalized to a baseline, which can be the entire time series or a time window of specified length (Fig. 5C). Normalization is performed by subtracting the mean of the baseline and further dividing by the SD of the baseline. By default, the toolbox uses the filter functions implemented in the fieldtrip toolbox to perform bandpass filtering. For both bandpass and notch filtering, the user can choose to use either a fourth order of Butterworth (IIR) filter or a window-based finite impulse response (FIR) filter, which uses the MATLAB fir1 function. The default FIR filter order is three times the sample rate, which is further divided by the low cutoff frequency of the bandpass filtering. However, the user can also implement their own filtering procedure in HFOFiltData.m. To characterize an event, the toolbox calculates the following features: (1) average frequency, (2) number of cycles, and (3) maximal z score (Fig. 5D). To calculate the average frequency, the peaks of the bandpass-filtered time series are located within the event time window (MATLAB findpeak.m). Then the average frequency is calculated by dividing the sampling rate by the average peak-to-peak distance. The number of cycles is obtained by dividing the duration of the event by the average peak-to-peak distance.

• Download figure
• Open in new tab
• Download powerpoint

Figure 5.

Schematic plot of Hilbert detector implementation. A, An example of raw iEEG data containing HFOs. The vertical gray line indicates cursor location. B, Bandpass filtered data (blue) and its envelope (red), obtained using the Hilbert method. C, HFO detection. The envelope time series (B) is first z score normalized. Clusters surviving an initial threshold (onset threshold) within a distance (search range) of the cursor location are identified. The cluster will be considered an HFO event if the following two criteria are met: (1) the maximal z score is greater than a user-specified threshold (in this example 5); and (2) the number of cycles meets the user-specified value (in this example 3). D, Characteristics of an event. For a detected event (red dashed rectangle), the following characteristics are retrieved: peak z score (blue dot), duration, average frequency, and number of cycles. To estimate the average frequency, oscillatory peaks for the event are identified (red dots) and all peak-to-peak distances are calculated, then the sampling rate is divided by the average peak-to-peak distance. The number of cycles is estimated by dividing the duration of the event by the average peak-to-peak distance. The red dashed boxes in B–D indicate an HFO event.

Note, HFOApp has two different Hilbert detectors built in: one introduced above, and the other from RIPPLELAB (Navarrete et al., 2016). The default Hilbert detector in HFOApp is different from that in RIPPLELAB. In RIPPLELAB, the Hilbert detector uses three parameters, including epoch length, SD threshold, and minimal duration, to detect HFOs. In HFOApp, we use two SD thresholds—onset and peak thresholds—instead of one single threshold. Furthermore, in HFOApp the duration of an HFO event is determined by the number of cycles instead of duration in milliseconds.

Implementation of the spectrogram

To increase the sensitivity of the Hilbert detector, we include a feature to allow bandpass filtering of the raw time series at a narrow frequency band. To do this, we first calculate the time–frequency spectrogram (Fig. 6A) using a Wavelet transform calculated using a continuous Gabor wavelet (Navarrete et al., 2016). The wavelet is defined as follows: C(s,t)=1s∫−∞∞x(t) * ψ(t-τs)dt,⋅⋅⋅⋅ψ(t)=1(σ2Π)14exp(−t22σ2)eiηst, where the t, s, and τ represent time, scale, and translation, respectively. ηs is the angular frequency at s. σ (default value of 6/ ηs ), indicates the SD of the Gaussian window in time (Navarrete et al., 2016).

• Download figure
• Open in new tab
• Download powerpoint

Figure 6.

HFO detection using spectrogram. A, In the spectrogram detection mode, the user clicks on the hotspot of the spectrogram. The black vertical line indicates the location of the click. B, The toolbox computes the peak frequency (red dot) of the spectrogram at the cursor location (A). The HFO is then identified using the Hilbert detector with a narrow bandwidth, which can be specified by the user, centered at the peak frequency. C, A screenshot of the spectrogram window of the toolbox. The black vertical line indicates the cursor location, and the red dashed rectangle indicates the detected HFO.

The user can modify HFOSpectrogram.m to implement their preferred method of spectrogram computation. To begin the spectrogram-guided HFO detection feature, the user clicks on the hotspot of interest in the spectrogram. The spectrogram at the cursor location will be extracted and averaged over a small time window centered at the cursor, and the peak frequency will be computed (Fig. 6B). The length of the small time window can be changed by the user in the spectrogram user interface [Fig. 6C, Time window (s)]. Then, the raw time series will be bandpass filtered over a narrow frequency band centered at the peak frequency, and the HFO event will be detected and marked using the method described above (Fig. 6C). The bandwidth can be set as a fixed value [e.g., 20 Hz; Fig. 6C, Bandwidth (Hz)], but the user can also set the cutoff frequency based on the peak spectrogram. If the “Percentage of peak” box (Fig. 6C) is selected, the “Bandwidth (Hz)” will be interpreted as a percentage that ranges from 0% to 100%, and the frequencies at which the spectrogram (Fig. 6B) drops to the specified percentage of the maximum will be used as cutoff frequencies for the bandpass filtering.

Simulated datasets for validation

The simulated datasets used in the validation experiments were generated using Python toolboxes MNE (RRID:SCR_005972) and MNE-HFO [Gramfort et al., 2013; see also “MNE-HFO: an open-source Python implementation of HFO detection algorithms” (https://zenodo.org/record/4485036)]. For each simulated dataset, sinusoidal data of different frequencies (2.5, 6.0, 10.0, 16.0, 32.5, 67.5, 165.0, 250.0, 425.0, 500.0, 800.0, and 1500.0 Hz) were added together, and a few HFOs were inserted into the simulated time series. The sampling rate was set to 2000 Hz. The frequencies of the simulated HFOs were set to 100, 140, 180, and 220 Hz, each consisting of 20 events. The number of cycles for each HFO was a random integer between 3 and 10. Then, we added random noise to the simulated data such that the signal-to-noise ratio ranged from 1 to 10, in steps of 1. In total, we generated 110 datasets with varying levels of noise. Finally, the HFOs of the simulated datasets were detected using both HFOApp and RIPPLELAB, using the default Hilbert detector of each program. For HFOApp, the onset threshold, inclusion threshold, and number of cycles were set to 1, 5, and 2.4, respectively. For RIPPLELAB, the threshold and minimal duration were set to 3.5 and 10 ms, respectively. These parameters were chosen to detect HFOs with a minimum of four cycles, given the characteristics of the simulated dataset. The epoch length was set to 600 s for both HFOApp and RIPPLELAB Hilbert detectors.

Real datasets for validation experiments

The real datasets were recorded using a clinical acquisition system (Blackrock) with a 4 × 5 grid (Integra). This dataset was part of a large study that was approved by the Northwestern University Institutional Review Board. To manually mark HFO events, the data were first bipolar rereferenced and organized into the data format required by either HFOApp or RIPPLELAB. Two channels were analyzed per dataset. The raters were instructed to manually mark ripples (frequency band, 80–250 Hz) using a bandpass-filtered time series between 80 and 250 Hz. Raters used the default HFOApp manual marking setup, which includes interactive automation-assist features (Fig. 1A–C), and in RIPPLELAB they followed the instructions for manual marking in the manual of the toolbox.