micmac Documentation

micmac DocumentationRelease 1.0.0

M. Deudon

Jan 22, 2019

Contents

1 Contents: 31.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 About micMac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1.2 Installing micMac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.2 Interface controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.3 IO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.3.1 Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.4 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.4.1 Loading a signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.4.2 Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.4.3 Export Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.4.4 Bad Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.4.5 EEG Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.4.6 Modify a Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.4.7 Channel Correspondency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.4.8 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191.4.9 Signals Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.5 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.5.1 Add a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.5.2 Modify a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

1.6 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261.6.1 Windows synchronisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.7 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.7.1 Event window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.7.2 Add an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281.7.3 Importing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291.7.4 Exporting Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301.7.5 Reject or Select events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.7.6 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

1.8 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341.8.1 Undo/Redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341.8.2 Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.8.3 Captures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.9 Detectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

i

1.9.1 Detectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

ii

micmac Documentation, Release 1.0.0

Welcome the micMac Manual!

This site can be downloaded for offline use here ?

Contents 1


2 Contents

CHAPTER 1

Contents:

1.1 Getting Started

1.1.1 About micMac

Introduction

micMac is designed to examine EEG/iEEG recordings in a simple and intuitive way. It was originally designed forresearching high frequency oscillations in intracerebral recording with both macro and micro contacts.

micMac is a Matlab interface using some parts of EEGLAB for internal processing.

Key Features

• Ability to switch between global visualization of many channels or precise visualization

• Multiple windows possibility (useful with multiple screens) - Not fully tested -

• Ability to observe multiple signals simultaneously.

• Marker system to quickly jump to events of interest.

1.1.2 Installing micMac

micMac is a Matlab interface, Matlab is thus needed to use micMac. It will work best with Matlab 8.1 (R2103a) orhigher. EEGLAB (http://sccn.ucsd.edu/eeglab/) is also needed to run micMac.

The source code for micMac can be found here :https://github.com/tinmarD/micmac

To start using micMac, just add this folder to the Matlab path and open the interface typing micmac in the Matlabcommand prompt.

3

http://sccn.ucsd.edu/eeglab/

https://github.com/tinmarD/micmac


1.2 Interface

1.2.1 Overview

When starting micMac, the following interface appears. On the bottom are the controls for moving in time andzooming. On the left side are the channel selection, gain and view mode controls. Menus are on top.

Principles

micMac works with three basic objects, Signals, Views and Windows.

A signal is a Matlab structure (similar to an EEGLAB dataset) representing a signal. It contains the data, the samplingfrequency, the channel names. . . Signals can be filtered, thresholded or transformed with other operators to createchild signals.

Views allow to observe these signals. A view is associated with a signal, a visualisation domain, a color, and a gain.The visualisation domain is one of the following:

• Temporal - Observe the signal in the time domain

• Frequency - Uses a Fourier transform to observe the spectrum over the whole time window.

• Time-Frequency - Uses a wavelet transform to represent the frequency content over time.

• Phase - Uses a wavelet transform to estimate the phase - Not fully tested

Windows are where views are placed. Each window can have multiples views. The main window is the leadingwindow, the other windows can synchronize with it.

4 Chapter 1. Contents:


Fig. 1: Blank micMac interface

1.2. Interface 5


Warning: Closing the main window will close the whole program.

1.2.2 Interface controls

Moving in time

The middle bottom panel is used to navigate in time. The user can either enter the desired time in the edit box or usethe buttons. The four buttons allow the user to move backward or forward with a small or large time step.

Fig. 2: Time selection panel

The time window size panel is used to modify the length (in seconds) of the time window. The - and + buttonsrespectively decrement and increment this value by 0.1s.

Fig. 3: Time window size panel

Channel Selection

Channels can be selected using the left panel. Pushing the Select button or pressing the Enter key validates theselection.

Zoom buttons

Three zoom buttons are available to quickly zoom on a particular area of the signal.

The first one named t is a temporal zoom. When pressed the user is asked to delimit a temporal area.

The second zoom button c is the equivalent of the temporal one but with channels.

The third one t-c is a combination of the two previous one. This time the area to zoom on is delimited both in the timeaxis and in the channel axis.

Note: The channel zoom c and temporal-channel t-c zoom buttons are only activated on Stacked Mode (view mode1).

Gain

To modify the gain, first select the view by clicking anywhere on its axis. Then push the - or + gain buttons to eitherdecrease of increase the gain associated with this view and view mode.

Each view has his own gain. Each view mode gain is independant.



Fig. 4: Channel selection pannel

Fig. 5: zoom buttons

1.2. Interface 7


Fig. 6: Time selection with the temporal zoom button

Fig. 7: gain buttons



View mode

micMac allows two view modes. It can be switch using the top left panel.

Fig. 8: View mode buttons

The first mode, Stacked Mode shows all the channels stacked on a single axis. This is convenient for a global view ofthe signal, with many channels selected. When two views or more are on, each view has his own axis.

Warning: The Stacked Mode only shows temporal views. The frequency or temporal-frequency views can onlybe seen using the Spaced Mode.

The second mode, Spaced Mode seperates each channel on his own axis. In this mode, the interface creates an axisfor each view and each channel. It is useful for more precise view. On Stacked Mode, the axis are organized by view.With the Spaced Mode, axis are organised by channel.

Note: These two modes can be combined using multiple windows to have both global and precise views of an eventof interest.

Fig. 9: Stacked Mode

1.2. Interface 9


Fig. 10: Spaced Mode



1.3 IO

1.3.1 Input/Output

Import

micMac can import files with the following formats :

• EDF : European Data Format

• NSX : Blackrock

• TRC : Micromed

• FIF : used in MNE

micMac can also import epochs data structures from EEGLAB and from MNE

Export

micMac can export files into the following formats

• EDF : European Data Format

• MAT :

• binary : int8 or int16

1.4 Signals

The Signals menu allows to load, filter, transform, export and modify a signal.

1.4.1 Loading a signal

Go to Signals>Load raw signal to load a new signal or use the Ctrl O shortcut. After selecting the file, the followingwindow shows up :

The fields are :

1.3. IO 11


• Montage type : indicates weither the montage is monopolar or bipolar

• Signal description : name identifying the signal. It can be modified later on.

• Channel correspondency with signal : if more than one signal is loaded, this tool allow to indicates the channelcorrespondency between the different signals (See LINK).

• Add view : If checked, a temporal view of the signal will be added. On by default.

• Window : If a view is added, this is the number of the window where to add it.

• Position : Position of the view in the window.

Note: For now only EDF files can be imported into micMac. EEGLAB can be used to do the data conversion if theformat does not match this one.

1.4.2 Filtering

Go to Signals>Filter signal to filter a signal. The following windows pops up:

The parameters are :

• Raw signal : The signal to be filtered

• Filter type : first field can be high-pass, low-pass, band-pass or band-stop. Second field is filter type, FIR,Butterworth (default), Chebyshev Type I or II or Elliptic.

• Cut-off frequency : Low and/or high cut-off frequencies in Hz.

• Order : order of the filter

• Frequency Response : Shows the frequency response of the filter in a new figure.

• Add view : Add a temporal view of the filtered signal.

• Window : If a view is added, this is the number of the window where to add it.

• Position : Position of the view in the window

The Frequency Response button allow to visualize the frequency response of the filter:



1.4. Signals 13


1.4.3 Export Data

Export whole file

This functionnality allows to export data from a signal in an matlab format (.mat).

Go to Signals>Export>Export data. The following window appears:

Parameters are :

• Signal : Signal to export data from

• Chanel list : Matlab vector indicating the list of channels to export. By default, all channels will be exported.

• Data range : Two-elements vector indicating the temporal range of data to export. By default, the whole timerange is selected.

Each channel is saved in a seperate file. All the files are automatically stored in a folder named after the signal’sdescription. Once imported into Matlab, the data appears into a matlab matrix named data.

Note: This way of exporting data allows to load them easily into Wave_clus for action potential detection and sorting.

Export from global events

This menu allow you to extract or reject the signal defined by global events and export it.

Select the type of event you want to reject or select. If you need to include the events parts, check the Include checkbox.Select the signal from which the data will be extracted. Check the Merge button to merge all the event parts together(or the part between events).

Then select the output format (.mat, or binary) and the output directory. The different parts of the signal correpondingto the events (or between events) will be saved :

Note: This is similar to the Events/Reject Events tool, with in addition the possibility to merge and export the signalparts defined by the events



1.4. Signals 15


1.4.4 Bad Channels

To mark some channels as bad, first select the bad channels on the channel selection panel, then go to Signal>Markas bad channels.

This will add an “*” to the bad channels’ name in the channel selection panel. Once marked as bad, the channels willnot appear on any view. To unmark the channels, do the same operation.

1.4.5 EEG Channels

When loading a signal micMac will try to identify EEG channels based on their name. If the name of the channel startsby ‘EEG’ it will be set as an EEG channel. If none of the channel names contains ‘EEG’, all channels are set as EEGchannels.

The EEG channel indexing modify the behaviour of some functions. For instance, when filtering a signal, only EEGchannels will be filtered, non-EEG channels will be copied in the output signal without filtering.

EEG channels can be selected using the Channel Selection tool.

1.4.6 Modify a Signal

To access a signal information, modify its name, or delete the signal, go to the Signals menu and click on the name:

The following window appears:

This window sums up the signal’s properties. The signal’s name can be modify with the Rename button. The signalcan also be deleted using the Delete Signal button.

Note: Only raw signals can be renamed or deleted. When renaming a raw signal, all the child signals will also berenamed. Similarly, deleting a raw signal will also delete all child signals.

1.4.7 Channel Correspondency

When working with several related signals, the channel correpondency between the two signals has to be set. This canbe done when loading the signal or by accessing signal information.

The following interface appears :



1.4. Signals 17


To link channels between the two signals, select the corresponding channels on the two lists and clink the Link button.To remove a link, select the channels and push the Unlink button. The Reset button will remove all links.

Note: micMac will automatically try to detect the correspondency between channels based on the name of thechannels.

1.4.8 Operators

Thresholding

Threshold a signal and creates events.

A minimum threshold T_min and maximum threshold T_max must be specified. All time points whose amplitude liebetween these two threshold : $$T_{min} < x < T_{max}$$ will be selected.

Events will be created for each of the thresholded parts.

You can see the amplitude distribution across all channels and time points by clicking on the Amplitude Distributionbutton.

Teager Energy Operators

The Teager Energy Operator (TEO) is a non-linear operator. It has been used in EEG to detect interictal epilepticdischarges or action potential. See : Neural action potential detector using multi-resolution TEO - J.H. Choi and T.Kim.

The discrete time TEO can be expressed as : $$ Phi(x(n)) = x^2(n) - x(n-1)x(n+1) $$

The k-TEO is a generalization of the TEO : $$ Phi_k(x(n)) = x^2(n) - x(n-k)x(n+k) $$

The k parameter must be choosed according to the type of detection wanted and the sampling frequency of the signal.

The MTEO operator is a parallel association of several k-TEO operators with differents values of k, followed by amaximum filter.

1.4. Signals 19


Note: An IED detector based on the MTEO operator is available in micMac in the Detectors/Epileptic Spike menu,although it has not been tested thoroughly.

1.4.9 Signals Synchronization

This function can be used to synchronize two signals that are linked but out of synched. Let’s take the case of 2 signals,one signal correponding to Macro electrodes and a second signals correponding to micro electrodes.

The Macro signal is at the top and the micro signal at the bottom. These two signals record the same activity atdifferent scales but are out of synched.

Open the Re-synch panel in Signals/Re-synch signals :

Select the two signals which need to be synched, and two correponding channels. Select a large time window and maxlag. If the time offset in larger than the max lag the synchronization will not work.

You can choose a resampling frequency to improve the time resolution.

Click the Run Analysis button to get the time offset between the 2 signals. It will estimate the lag using a cross-correlation.

If the time offset is already known, you can specify it in the Known time offset box.

You can choose to either cut the beginning of the signal starting earlier of the add a blank signal before the signalstarting later.



1.5. Views 21


Fig. 11: The Views menu



1.5 Views

1.5.1 Add a view

To add a view, go to Views/Add View. The following appears:

Fig. 12: Temporal domain

Parameters are:

• Signal : Signal associated with the view.

• Domain : Domain of visualisation. Can be time, frequency, or time-frequency.

• Window : Number of the window where to add it.

• Position : Position of the view in the window.

For frequency domain views, i.e. power spectrum representation,

Fig. 13: frequency domain

additional parameters are :

• freq min : Minimum frequency visualised frequency.

• freq max : Maximum frequency visualised frequency.

1.5. Views 23


For time-frequency domain views,

Fig. 14: time-frequency domain

additional parameters are :

• wavelet name : name of wavelet. By default micMac uses a Complex Morlet wavelet (cmor1-1.5).

• freq min : Minimum pseudo-frequency visualised frequency.

• freq max : Maximum pseudo-frequency visualised frequency.

• freq step or num freqs : Step between two pseudo-frequencies OR the number of frequencies (when Log scaleis on)

• Log : If on, the frequency scale increases logarithmically.

Phase views share the same parameter as the time-frequency views.

Note: Frequency domain, time-frequency, and phase domain views do not appears on Stacked mode (visualisationmode 1). Select the Spaced mode to visualise them.

1.5.2 Modify a view

The view position and its color can be modified. Views can also be deleted.

The first way to modify a view is to click on its name on the Views menu :

The following window appears :

It is also possible to modify view’s position or color or to delete the view by right-clicking on the correponding axis :



1.5. Views 25


Note: Deleting a view will not delete the signal associated with this view.

1.6 Windows

Windows contain views. micMac can work with multiples windows.

To add a new window, go to Windows>Add window :

1.6.1 Windows synchronisation

When working with multiples windows, you can synchronise the additionnal windows with the main one.

Fig. 15: New window with synchronisation check boxes.

There are three synchronisation options :

• Channels

• Observation time



• Time window duration

1.7 Events

1.7.1 Event window

To see the event window, go to Events>See Events, or use Ctrl-E :

Fig. 16: Event window

The event window is composed of five parts :

• Events : list the characteristics of all selected events: type, time of event, duration of event, channel of eventand the signal where this event appears.

1.7. Events 27


• Order : allow to order the events given one event parameter. Up to three criteria can be combined to order theevents. In this case, the events are first ordered given the first criteria, then the second one is applied and finallythe third.

• Selection : allow to select some events based on Type, Signal or Channel criteria. Use Select All to select all theevents. Use Exclude check boxes to unselect some events. This panel also permit to delete the selected eventsusing the Delete buton

• Navigation : allow to navigate through events and to delete the current event.

• Import and Export : use these buttons to either import all the current events or to import previously storedevents.

1.7.2 Add an Event

Event Options

Before adding an event, the event type must be specified. To do this, go to Events>Add>Event Options. Adding anevent when no type is given will automatically open this event options window.

Fig. 17: Event options window

Event type can be set to an existing type or set to a new type by checking the New Type box, enter the event name andpress Enter. The channel option allow to specify whether the event is a global, defined on all channels, or the event ischannel specific.

Adding an event

To add an event go to Events>Add>Add Event or use the shortcut Ctrl-A, a crosshair cursor then appears to selectthe limits of the event.

Global event

To add a global event, use the crosshair cursor to select the start and end of the event on the temporal axis.



Fig. 18: Adding a global event

Channel specific event

Stacked Mode

To add a channel specific event in Stacked Mode, both the channel and the temporal limits of the event have to beselected. To select the channel the cursor has to cross one and only one horizontal axis.

Fig. 19: Adding a channel specific event in “Stacked” mode

Spaced Mode

To add a channel specific event in Spaced Mode, use the crosshair cursor to select the start and the end of the eventon the temporal axis.

1.7.3 Importing Events

Events can be imported into micMac using the Events/Import menu.

1.7. Events 29


Fig. 20: Adding a channel specific event in “Spaced” mode

micMac can import events from :

• micMac - when events are saved from micmac (*.csv, *.txt)

• Anywave/Delphos (*.mrk, *.csv, *.txt)

• External events

Use the Events/Import/External events to open the following window :

The fields are :

• The Latency column should give the time of each event, select the Time unit according to it, which can be inseconds or milliseconds.

• The Type column gives the type/name of each event.

• The Channel pos column should give the channel number.

• The Duration column gives the duration of the events.

If events are defined for all channels, check the Global Events ? checkbox. If the first channel is indexed by 0, checkthe Zero-index for channel?.

The Autodetect button will try to detect automatically the position of each column.

1.7.4 Exporting Events

To export events, open the event panel (Ctrl E) and use the export button.

It will export the micMac events in a csv file. The different fields of the csv file are :

• id : ID of the event

• type : The type of event

• tpos : The latency of the event in seconds (onset time)

• duration : The duration of the event in seconds

• channelind : The number of the channel - Indexing starts at 1.

• channelname : The name of the channel.



1.7. Events 31


• sigid : The ID of the signal associated with the event

• sigdesc : The description of the signal associated with the event

• rawparentid : The raw parent ID of the signal associated with event

• centerfreq : If estimated, the central frequency of the event signal

Not all these fields are relevants, but all are used by micMac for internal processing.

1.7.5 Reject or Select events

It is possible to reject or select the signal part defined by global events. It can be used for removing artefact periodsand exporting some parts of the signal. Use the Events/Reject events :

Global events must first be defined.

Select the type of event you want to reject or select. If you need to include the events parts, check the Include checkbox.Select the signal from which the data will be extracted.

For creating a new signal, composed only of the event parts (if selection of the events) or without the event parts (ifrejection of the events), check the Create new signal checkbox.

Note: This is similar to the Signal/Export/Export from Events menu. This last tool is useful for exporting signal fromevents.

1.7.6 Miscellaneous

Navigate through events

To navigate through events, you can either use the menu Events/Previous or Events/Next or use the keyboard shortcutss and f.

1.7. Events 33


Frequency Estimation

micMac can estimate the frequency of the signal defined by the events (they must be local events). For that use theEvents/Frequency Estimation menu.

Hide the events

You can hide the event visualization by using the menu Events/Hide Events or with the shortcut key h. To make theevent reappear, just click again on h.

Display event information

The event type, duration and center frequency can be displayed next to the event by using the Events/Display/HideEvent Info menu.

1.8 Tools

The Tools menu contains undo/redo commands, three different cursors, and capture commands.

1.8.1 Undo/Redo

Undo command allow to restore the previous time and channel configuration. Redo command is the opposite.



1.8. Tools 35


1.8.2 Cursors

x-y cursor

x cursor (Time cursor)

y cursor (Amplitude cursor)

1.8.3 Captures

Capture

Capture Full

1.9 Detectors

1.9.1 Detectors

HFOs detectors

micMac include High Frequency Oscillation detectors. The detector implementation comes from RIPPLELAB.

For the article see RIPPLELAB: A Comprehensive Application for the Detection, Analysis and Classification of HighFrequency Oscillations in Electroencephalographic Signals


https://github.com/BSP-Uniandes/RIPPLELAB

https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0158276

https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0158276


1.9. Detectors 37


RIPPLELAB includes four different detectors :

• Short Time Energy detector, as described by Staba

• Short Line Length detector

• Hilbert Transform based detector

• The MNI detector

Interictal Epileptic Discharges detectors

micMac also includes 2 detectors for IEDs (Intericat Epileptic Discharges). However these detectors have not beentested and should not be used, or with great care in regards with their performances.


micmac Documentation

Documents

Transcript of micmac Documentation