This version is still considered a beta version, but it has most of the functionality planned for version 1.0.

Requirements: Matlab 5.2 or higher. No Matlab toolboxes are required.

Installation

1. Unzip the file emglab09.zip. This zip file contains one folder named 
   'emglab09' which contains the EMGlab version 0.9 software.
   Note: if you are using WINZIP, you must type in the folder name in the 
   WINZIP file browser, like this:  c:\mydirectory\emglab09
2. Move the EMGlab09 folder to whichever directory you want it to reside in.
3. Run Matlab.
4. In Matlab, select the EMGlab09 folder as the current directory. You can do 
   this using the Current Directory window, the cd command, or the File Open
   menu.
5. At the Matlab command prompt, type:
	>> install

The install script removes any previous versions of EMGlab from the Matlab path, permanently adds the current version of EMGlab to the Matlab path, and copies your old EMGlab preference file (if there is one) into the EMGlab09 folder.

Known limitations with version 0.9

Reading binary data files in Matlab version 5 is very slow. (This is a limitation of Matlab version 5.)

The EMGlab window does not resize correctly in Matlab version 7.1. After you resize the window, you must select Redraw Window from the File Menu.

This version of EMGlab displays signals only in ADC units, not physical units.

The nyquist rate, muap width, and template width settings on the Preferences panel do not take effect immediately. They take effect the next time you open an EMG data file.

The organization of global variables may change in a future version.

The names of some highres toolbox functions may change in a future version.

Programs are not fully commented.

EMGlab Overview

EMGlab is an interactive program for viewing and decomposing EMG signals. The program is able to read binary data files in a variety of formats. It can also read and write text "annotation" files that contain the occurrence times and identities of the MUAPs in a signal. The program includes an automatic decomposition algorithm and a graphical user interface for inspecting and editing the results.

The usual procedure for decomposing a signal is as follows: First the automatic decomposition algorithm is run on the initial two seconds of data. Unless the signal is very complex, the algorithm will identify the active MUAPs and classify many of the individual discharges. The results are then inspected manually to fill in the discharge patterns and correct mistakes. After fully decomposing the first two seconds, the next two seconds of data are analyzed, and so on.

EMGlab is specifically intended for "full decomposition", in which the goal is to account for every discharge in the signal in terms of a set of physiologically realistic MUAP trains. This may require some effort, but it is the best way to ensure the accuracy of the results.

This version of EMGlab lets you load multi-channel EMG signals, but only lets you work on one channel at a time. The program keeps track of the decomposition results for each channel, but does not let you share the results between channels.

Description

To run the EMGlab, type "emglab" in the Matlab command window.

The program runs in a single Matlab window, which is divided into five panels. At the top is the signal panel, which displays a segment of the EMG signal. Below that is the template panel, which displays the MUAP templates. Below that on the left is the firing panel, which displays the firing patterns of the identified MUs. To the right is the close-up panel, which displays a section of the EMG signal at an expanded scale. At the very bottom is the navigation panel which displays a thumbnail of the EMG signal.

ToThe buttons on the edges of the panels are used to change the display characteristics.

	   +, -	  zoom in or out vertically
	   <, >  scroll left or right
	   ||, | |	zoom in or out horizontally 

Other buttons on the firing and close-up panels are described below.

At the top of the window are pull-down menus for selecting the channel and high-pass filtering.

The signal, template, firing, and close-up panels can be resized by dragging the gaps between them. The color scheme can be changed by selecting Preferences from the File menu.

The graphical commands are performed by clicking on an object or a part of the screen or by clicking on an object and dragging to a different part of the screen. Clicking may be modified by holding a modifier key as follows:

On Windows, "option-clicking" can also be accomplished by right clicking. In general, normal clicking is used for the most standard commands, shift clicking for special commands, and option clicking for deleting.

Signal Panel

The signal panel shows the EMG signal and the residual signal that remains after the templates of the identified MUAPs have been subtracted. The time scale shows the time in seconds from the beginning of the signal. The default time scale is 100 ms full screen. The unit numbers of the identified spikes are shown at the top of the panel. The expected firing times of the selected unit are indicated by red lines at the top. The vertical green cursors mark the interval shown in the close-up panel. The EMG file name and the vertical scale are shown above the panel.

* Clicking on the signal displays that part of the signal in the close-up panel.

* Shift-clicking on a spike identifies it as an instance of the selected unit. If no unit is selected, then the spike is identified as an instance of the unit that it matches most closely.

* Option-clicking on a unit number deletes the identification.

* Holding down the shift key while dragging a spike to the template panel creates a new template.

The channel popup selects the current channel. This version of EMGlab can read multi-channel signals, but it only lets you display and work on one channel at a time.

High-Pass Filter Popup

The filter popup selects the level of high-pass filtering to be applied to the signal. Some investigators record wide-band EMG signals in order to see low- as well as high-frequency MUAP components. For these signals, it is necessary to apply high-pass filtering before doing decomposition. The filtering converts the MUAPs into sharp spikes and suppresses background noise to produce a flat baseline. After decomposition, you can switch back to the unfiltered signal to see the MUAP waveforms.

Other investigators record signals that have already been high-pass filtered. These signals can be decomposed without applying additional filtering in EMGlab. In this case, be sure to set the "MUAP Width" parameter in the Preferences Menu to a value that is appropriate for your signal (e.g., 5 or 10 ms).

Template Panel

The template panel displays the templates of the identified MUs. The selected unit is shown in red. The "|" and "||" buttons control the number of templates displayed and the width of the displays. (The templates panel always uses the same time scale as the signal panel). The scroll buttons (<, >) are used for scrolling among the templates if they do not all fit on the screen.

* Clicking on a unit selects or deselects it.

* Shift-clicking on a template adds it to the close-up panel.

* Option-clicking on a template deletes it.

* Shift-clicking and dragging within a single template re-centers the template.

* Dragging one template to another changes their order.

* Shift-dragging one template to another allows the two templates to be compared to see whether they should be merged. The templates are shown superimposed in the close-up panel, and their firing times are shown superimposed in the firing panel. The two templates can then be merged by clicking the OK button on the close-up panel, or the merger can be cancelled by clicking the X button on the close-up panel.

* Dragging a template to the signal or close-up panels fits the template to the signal.

* Option clicking on a unit number brings up a popup menu with these options:

- Re-average. Re-averages the template over the interval shown in the firing panel.

- Hide. When a template is "hidden," it is shown in a dimmer color, and it is not subtracted from the residual signal in the signal panel. This allows the activity of the hidden unit to be observed with the activity of the other units subtracted out. The unit can be unhidden by selecting Hide from the popup menu a second time, or by the Show all command from the Analyze menu.

Firing Panel

The firing panel displays the identified firing patterns in one of two formats, either by circles marking the discharge times or by smoothed instantaneous firing rates. The style is toggled using the "o" button. For the instantaneous firing rates, the vertical scale is in Hz. The vertical green cursors indicate the interval shown in the signal panel.

* Clicking at a particular time displays that time in the signal panel.

* Clicking in the row of a particular unit selects that unit. Clicking in an empty row deselects all units.

* Option-clicking on a particular discharge deletes that discharge.

Close-up Panel

The close-up panel shows a segment of the EMG signal at an expanded scale. Interpolation is used to give higher temporal resolution. If the signal has been identified, the reconstruction is overlaid over the signal, the templates are shown in the bottom traces and the residual is shown in the middle trace. Templates can be added to the close-up panel by shift-clicking on them or dragging them from the template panel. Changes made in the close-up panel do not affect the signal and firing panels until the OK button is clicked.

* Clicking on one of the templates realigns it.

* Dragging one of the templates or one of the unit numbers adjusts the template's location.

* Option-clicking a template or unit number removes that template from the panel.

* Shift-clicking on a template or unit number locks that template in place and prevents the R button from changing its location. The template is subtracted from the EMG signal, but not shown. The template can be unlocked by shift-clicking on the unit number a second time.

The R button aligns the templates to give the best fit.

The OK button causes the current contents of the close-up panel to be updated to the other panels.

The X button resets the close-up panel to correspond with the signal panel.

Navigation Panel.

This panel shows a 10-s long thumbnail of the EMG signal. The times of all the identified discharges are also shown. There are three cursors. The short, wide cursor at the bottom shows the interval displayed in the firing panel. The middle cursor shows the interval displayed in the signal panel. The very small cursor at the top shows the interval displayed in the close-up panel.

* Clicking in the lower third of the panel changes the time interval displayed in the firing panel.

* Clicking in the upper two thirds of the panel changes the signal-panel interval.

File Menu.

Load EMG file. This brings up a file browser to select an EMG data file. When a file is selected, the program checks the extension. If it corresponds to a known data format, the program loads the file. If it doesn't correspond to a known data format, the program checks to see if there is a header file with the same filename and extension .hea in the same directory. If there is, then the program uses the information in the header to load the file. If there is no header file, then the program assumes the file is a generic binary file, and brings up a dialog box to ask for the number of channels, byte order, sampling rate, and byte offset.

Currently the program recognizes the following formats:

- MUtools format (.sc1, .sc2, .sc3).

- WFDB format (.hea). The WFBD header is able to accommodate binary files of many different formats.It is described more fully here.

Import EMG signal.This causes the program to first try to execute the function my_emgsignal, and then to import the EMG signal from the Matlab global variable EMGSIGNAL. If successful, a dialog box will ask for the sampling rate. You can create your own my_emgsignal.m file, or you can read or create signals from the Matlab command line interface. In either case, put the signal into the global variable EMGSIGNAL. The data can be in either double or int16 format. Multi-channel signals should be stored with each signal in a different column

Open/Close/Save/Save as... Decomp file. Decomposition results can be saved in a .decomp file. The .decomp files saves all the templates and firing patterns for all the channels. It also saves the name of the EMG file. When you open a .decomp file, the associated EMG file is loaded automatically. Note that closing the .decomp file without saving deletes all the templates and firing patterns for all of the channels.

Load/Save Annotations file. Firing-time information can also be saved to an annotation file (extension .ann). This is a text file with one line for each identified MUAP discharge. Each line consists of a discharge time, in seconds since the beginning of the signal, and a unit number. The annotation file only saves information for the current channel, so separate files are needed for multi-channel signals. The annotation file does not save the name of the EMG file, so you must load the EMG file before loading an annotation file.

Preferences. Brings up a dialog box for setting the following preferences:

- template width. This specifies the width of the templates in the high-pass filtered bands. The default value is 10 ms.

- muap width. This specifies the width of the templates in the unfiltered band. The default value is 60 ms. If your signals are already high-pass filtered, then you should decrease this value to perhaps 10 ms in order to improve the efficiency of template matching in the unfiltered band.

- nyquist rate. This specifies the highest expected frequency in the signal. Signals will be down-sampled to the lowest sampling rate greater than 2 times the nyquist rate. For example, if a signal has a sampling rate of 33 kHz and the nyquist rate is equal to 5 kHz, then EMGlab will down-sample the signal to 11 kHz in order to reduce memory and computation demands.

- color scheme. There are three choices: "scope" (black background), "paper" (white background), and "custom." There is currently no way to set the custom colors interactively, but you can change them by editing the function emgsettings.m.

- font size. This specifies the font size for the buttons and popups.

Changes made to the first three parameters do not have any effect on the current decomposition, but only take effect when the next EMG file is loaded. Changes made to the color scheme and font size take effect immediately.

The preferences are stored in the file EMGlab.prefs in the EMGlab directory. This file is created with default values the first time that EMGlab is run, and it is updated whenever the parameters are changed by the Preferences Menu. The size and position of the EMGlab window and the most recent EMG, .decomp, and .ann paths are also stored in this file.

Quit. This deletes the EMGlab window and returns to Matlab. Note that you can return to Matlab without quitting EMGlab by clicking on the Matlab command window, or (in some Matlab versions) by pressing the return key.

Analyze Menu.

Auto Decomp.This invokes the automatic decomposition algorithm for the interval currently shown in the firing panel. The algorithm will try to match the unidentified spikes in the interval using the current templates, and it will create new templates for MUAPs that don't match any of the current ones. Sometimes running the algorithm more than once on the same interval will identify additional discharges. Note that it is usually desirable to select high-pass filtering before running automatic decomposition.

Re-average all.This causes all the templates to be re-averaged over the interval shown in the firing panel. This option can be used to update the templates to track slow changes in MUAP shape. By default, averaging is done over a 2-second interval (the default length of the firing panel interval). If the template is changing more rapidly than this, you can zoom in the firing panel to decrease the averaging window. To improve the signal-to-noise ratios of the templates, you can zoom out the firing panel to increase the averaging window. To compute the MUAP waveforms most accurately, set the high-pass-filter to "unfiltered, zoom out the firing panel to include the entire signal, and re-average. The averaging algorithm uses interference cancellation, so the quality of the averages can be improved by re-averaging more than once.

Show all. This un-hides all units. A unit can be hidden by means of the popup menu that appears when the unit's number in the template panel is option-clicked. Hidden units are not subtracted from the residual signal in the signal panel.

Delete firings. This deletes all the discharges shown in the firing panel.

Delete all. This deletes all the units and all the firing patterns for the current channel.

Decomposition Demo.

This section describes how to use EMGlab to decompose a sample signal. Run EMGLAB by typing "emglab" in the Matlab command window.

Select "Load EMG file" from the File menu. Open the file R00108.emg, which is included in the "sample data" folder. The first 100 milliseconds of the signal are displayed in the signal panel and the entire 10 seconds are displayed in the navigation panel. This file has only one channel of data. The narrower cursor in the navigation panel shows the interval displayed in the signal panel. The wider cursor shows the analysis window.

Select 1250 Hz high-pass filtering. The filtered signal has sharp spikes and a flat baseline.

Select "Auto Decomp" from the Analysis menu. The program analyzes the first 2 seconds of the signal and identifies 8 MUAP trains. The firing patterns are nice and regular, but some gaps are apparent. The remainder of the decomposition of the first two seconds will be done manually.

Several of the spikes in the signal panel have been identified with small residuals indicating a good fit between the template and the spike. However, the large potential at 0.072 s has not been identified. Click in the signal panel on the potential at 0.072 s to show it in the close-up panel. This potential does not look like any of the templates, and so is probably a superposition. We can guess which units are involved by looking at the firing panel. Firings have been detected in the current signal panel (indicated by the cursors in the firing panel) for every unit except for units 3 and 5. Shift-click on unit 3 in the template panel to add it to the close-up panel. The program automatically aligns it, but it is not a perfect fit. Shift-click on unit 5 to add it as well. This gives a better fit. Click on the R button to align the templates optimally. This gives a good fit, with a small residual. Click the OK button to accept this identification. Note that the signal and firing panels are only updated when the OK button is clicked.

Click the > button on the signal panel several times to scroll through the signal. All the spikes seem to be correctly identified until 0.5 s. At 0.501 s there is a clear occurrence of unit 7 which the automatic algorithm for some reason did not identify. Click on unit 7 in the template panel and drag it to the potential at 0.501 s in the signal panel. The program automatically aligns the template, and the low residual indicates a good fit.

There is another superposition at 0.509 s that the automatic decomposition algorithm is able to resolve in some versions of Matlab, but does not resolve in others. (Not sure why.) If unit numbers are present above this superposition, option-click to delete them, and pretend that it hasn't been identified yet. We could try to identify it using the close-up panel or by dragging templates, but we can also see whether the program can identify it for us. Shift click on the superposition in the signal panel to have the program try to identify it. The program matches the large spike with unit 1. Shift click again and the program matches the remainder with unit 4.

Looking at the firing panel shows a gap in unit 2's firing pattern at about 0.7 s. Click in the middle of the gap to bring this interval to the signal panel. Clicking in the row of unit 2 in the firing panel also selects unit 2. This is indicated by the firing pattern and template of unit 2 being highlighted. The expected firing times of unit 2 are shown by red bars at the top of the signal panel. The bar indicates that a discharge of unit 2 is expected at about the same time as the superimposition at time 0.715 s. Shift-click on the superposition. Since unit 2 is selected, the program matches it to the signal. Then click normally to show the superposition in the close-up window. From the firing panel, it seems likely that units 3, 5, and 7 might also be involved. Successively shift-click on the templates of these units to add them to the close-up panel. Then click the R button to align them optimally. (Note that you can remove templates from the close-up panel by option-clicking on them or on their unit number.) These four units give a good fit, so click the OK button.

Try to decompose the rest of the 2 seconds by yourself. Note that you can de-select the currently selected unit by either clicking on it or by clicking on an empty column in the template panel or an empty row in the firing panel. There is a tricky superposition at 1.177 s. The units that are involved are 5, 3, 4, and 2. For some reason, the R button has trouble with this one, but gets it correct when you click R a second time. (Apparently there is a bug in the algorithm). When you're done, all the units except 1 and 5 should have full, regular firing patterns, and the residual signal should be very small everywhere. Units 1 and 5 do not fire as regularly as the others—a few of their inter-discharge intervals are considerably longer than the rest. However, a close inspection of the signal fails to reveal any missing discharges. Click the O button on the firing panel to see the instantaneous firing rates. They are all fairly steady, ranging from 6 to 12 Hz. There is not a high degree of common modulation. Click on templates 1 and 5 to highlight their firing rates. They have the lowest firing rates, which is consistent with their being newly recruited and having greater firing variability.

Once the first two seconds are completely decomposed, you can move on to the next two seconds. Click the > button on the firing panel twice to advance the analysis window. Select Auto Decomp from the Analysis Menu. This time the automatic algorithm does a better job, producing nearly full firing patterns. A couple of units have gaps in their firing patterns, but these can be filled in without too much trouble. Be sure to scroll through the signal to check the residual signal to make sure there are no mistakes.

Manual Decomposition.

It's also possible to decompose signals in an entirely manual manner. You can create a new template manually by clicking on a spike in the signal panel and dragging it to the template panel. Once you have identified several occurrences of the unit, re-average to improve the signal-to-noise ratio of the template. You can do this from the popup menu that appears when you shift click on the unit number in the template panel, or you can re-average all the units at once from the Analyze Menu.

For a fairly simple signal like this one, once the templates have been formed you can identify discharges fairly simply by just scrolling through the signal and shift-clicking on every spike. If the program puts the wrong unit, you can usually tell because the residual does not go to zero or because of firing-pattern irregularity. Correct these mistakes in the close-up window.

Another approach for manual decomposition is to start with the largest unit and scroll through the signal trying to identify all of its occurrences. The estimated-firing-time bars are helpful for this. Note that the bars indicate the most likely firing intervals, but some firings occur outside the expected intervals. After decomposing the largest unit, go back and do the next largest one, and so on. If a unit doesn't match a particular spike very well, but you are pretty sure that that must be where the unit fires, identify it anyway. As you decompose the other units, the other constituents of the spike will become apparent.

Decomposition is like solving a puzzle. As more and more of the pieces snap into place, the integrity of the overall pattern becomes more and more apparent. When you end up with a set of full, regular firing patterns that accounts for all the activity in a signal down to the level of the baseline noise, you can be fairly confident that the decomposition is correct. With sufficient work even many fairly complex signals can be decomposed with a high degree of confidence.

Of course there are many factors that affect signal decomposability, including the strength of the contraction, the steady or changing nature of the contraction, the type of electrode, etc. Some contractions are too noisy or too complex to be decomposed reliably, and it doesn't pay to put a lot of effort into them. If your decomposition is based largely on guesswork, you shouldn't have much confidence in the results.