emgdecompy.viz

Module Contents

Functions

RMSE(arr1, arr2)

Evaluates root mean square error for two series.

mismatch_score(mu_data, peak_data, mu_index, method='RMSE', channel=-1)

Evaluates how well a given peak contributes to a given MUAP.

muap_dict(raw, pt, l=31)

Returns multi-level dictionary containing sample number, average signal, and channel

muap_dict_by_peak(raw, peak, mu_index=0, l=31)

Returns the dictionary of shapes for a selected peak, by channel.

channel_preset(preset='standard')

Called by muap_plot() function to determine the order of channels when plotting MUAP shapes.

muap_plot(mu_data, mu_index, peak_data=None, l=31, peak='', method='RMSE', preset='standard')

Returns a plot for MUAP shapes separated by channel.

pulse_plot(pt, c_sq_mean, mu_index, sel_type='single')

Plot firings and firing rate for a given motor unit.

select_peak(selection, mu_index, raw, shape_dict, pt, preset='standard', method='RMSE')

Retrieves a given peak (if any) and re-graphs MUAP plot via muap_plot() function.

dashboard(decomp_results, raw, mu_index=0, preset='standard', method='RMSE')

Parent function for creating interactive visual component of decomposition.

visualize_decomp(decomp_results, raw)

Wrapper function that allows for cleaner UI for user. Widgets are built within it.
emgdecompy.viz.RMSE(arr1, arr2)[source]

Evaluates root mean square error for two series.

Parameters

  • arr1 (array) – First series.

  • arr2 (array) – Second series.

Returns

Root mean square error of arr1 vs arr2.

Return type

float

Examples

>>> arr1 = [3, 4, 4, 9, 12]
>>> arr2 = [3, 5, 3, 9, 11]
>>> RMSE(arr1, arr2)
0.7745966692414834
emgdecompy.viz.mismatch_score(mu_data, peak_data, mu_index, method='RMSE', channel=- 1)[source]

Evaluates how well a given peak contributes to a given MUAP. This is called by the muap_plot() function and is used to include error in the title of the muap plot.

Parameters

  • mu_data (dict) – Dictionary containing MUAP shapes for each motor unit.

  • peak_data (dict) – Dictionary containing shapes for a given peak per channel.

  • mu_index (int) – Index of motor unit to examine.

  • method (str) – Metric to use for evaluating discrepency between mu_data and peak_data. Default: “RMSE”

  • channel (int) – Channel to run evaluation on. Default: -1 which means average of all channels.

Returns

Metric calculating difference between MU data vs Peak data. Default: Root Mean Square Error of MU data vs Peak data.

Return type

float

emgdecompy.viz.muap_dict(raw, pt, l=31)[source]

Returns multi-level dictionary containing sample number, average signal, and channel for each motor unit by averaging the peak shapes over every firing for each MUAP.

Parameters

  • raw (numpy.ndarray) – Raw EMG signal.

  • pt (numpy.ndarray) – Multi-dimensional array containing indices of firing times for each motor unit.

  • l (int) – One half of the action potential discharge time in samples. Default value of 31 corresponds to approximately 15 ms at a sampling rate of 2048 Hz.

Returns

Dictionary containing MUAP shapes for each motor unit.

Return type

dict

emgdecompy.viz.muap_dict_by_peak(raw, peak, mu_index=0, l=31)[source]

Returns the dictionary of shapes for a selected peak, by channel. It is called by the select_peak() function when a peak is selected by a user.

Parameters

  • raw (numpy.ndarray) – Raw EMG signal.

  • peak (int) – Peak timing to plot.

  • mu_index (int) – Motor Unit the peak belongs to, to keep dict format consistent.

  • l (int) – One half of the action potential discharge time in samples. Default value of 31 corresponds to approximately 15 ms at a sampling rate of 2048 Hz.

Returns

Dictionary containing shapes for a given peak per channel.

Return type

dict

emgdecompy.viz.channel_preset(preset='standard')[source]

Called by muap_plot() function to determine the order of channels when plotting MUAP shapes.

Parameters

preset (str) – Name of the preset to use.

Returns

Dictionary containing
cols: int

Number of columns for a given channel arrangement.

sort_order: list

Sort order of all the channels.

Return type

dict

Examples

>>> channel_preset(preset='vert63')
{
'cols': 5,
'sort_order': [
    63, 38, 37, 12, 11, 62, 39, 36, 13, 10, 61, 40, 35, 14, 9, 60, 41, 34, 15, 8, 59, 42, 33, 16, 7, 58, 43, 32, 17, 6, 57, 44, 31, 18, 5, 56, 45, 30, 19, 4, 55, 46, 29, 20, 3, 54, 47, 28, 21, 2, 53, 48, 27, 22, 1, 52, 49, 26, 23, 0, 51, 50, 25, 24
    ]
}
emgdecompy.viz.muap_plot(mu_data, mu_index, peak_data=None, l=31, peak='', method='RMSE', preset='standard')[source]

Returns a plot for MUAP shapes separated by channel. If peak_data is specified, also plots overlay of contribution of the peak to the shape per channel. Called by select_peak() function.

Parameters

  • mu_data (dict) – Dictionary containing MUAP shapes for each motor unit.

  • mu_index (int) – Index of motor unit to examine.

  • peak_data (dict) – Dictionary containing shapes for a given peak per channel. Specifying it creates the overlay of peak contribution.

  • l (int) – One half of action potential discharge time in samples. Default value of 31 corresponds to approximately 15 ms at a sampling rate of 2048 Hz.

  • peak (float:) – Time of the peak, used for the title of the plot.

  • method (str) – Metric to use to calculate mean (over all channels) mismatch score between averaged shape and given peak.

  • preset (str) – Name of preset to use, for arranging the channels on the plot.

Returns

Facetted altair plot overlaying MU shapes per channel and peak shapes per channel.

Return type

altair.vegalite.v4.api.FacetChart

emgdecompy.viz.pulse_plot(pt, c_sq_mean, mu_index, sel_type='single')[source]

Plot firings and firing rate for a given motor unit.

Parameters

  • pulse_train (np.array) – Motor unit pulse train.

  • c_sq_mean (np.array) – Centered, squared and averaged firings over the duration of the trial.

  • mu_index (int) – Motor unit of interest to plot firings for.

  • sel_type (str) – Whether to select single points or intervals.

Returns

Plots containing instantaneous firing rate plot, signal strength plots, and overlay between the two.

Return type

altair.vegalite.v4.api.VConcatChart

emgdecompy.viz.select_peak(selection, mu_index, raw, shape_dict, pt, preset='standard', method='RMSE')[source]

Retrieves a given peak (if any) and re-graphs MUAP plot via muap_plot() function. Called within dashboard() function, binded to the peak selection on pulse graphs.

Parameters

  • selection (array) – Selection object to dig into and retrieve peak index to plot.

  • mu_index (int) – Currently plotted motor unit.

  • raw (numpy.ndarray) – Raw EMG signal array.

  • shape_dict (dict) – Dictionary containing MUAP shapes for each motor unit.

  • pt (numpy.ndarray) – Multi-dimensional array containing indices of firing times for each motor unit.

  • preset (str) – Name of preset to use, for arranging the channels on the plot.

  • method (str) – Metric to use to calculate mean (over all channels) mismatch score between averaged shape and given peak.

Returns

Panel column containing facetted altair plot overlaying MU shapes per channel and peak shapes per channel.

Return type

panel.layout.base.Column

emgdecompy.viz.dashboard(decomp_results, raw, mu_index=0, preset='standard', method='RMSE')[source]

Parent function for creating interactive visual component of decomposition. Dashboard consists of four plots: 1. Plot of instantaneous firing rate and signal, primarily for zooming and navigating. 2. Plot of instantaneous firing rate, which allows for peak selection. 3. Plot of signal strength, which allows for peak selection. 4. MUAP plot of individual motor unit shapes by channel, with selected peak overlay.

Parameters

  • decomp_results (dict) – Decomposition results. Must contain MUPulses key with the motor unit firing indices.

  • raw (numpy.ndarray) – Raw EMG data.

  • mu_index (int) – Currently plotted Motor Unit.

Returns

Panel object containing interactive altair plots.

Return type

panel.layout.base.Column

emgdecompy.viz.visualize_decomp(decomp_results, raw)[source]

Wrapper function that allows for cleaner UI for user. Widgets are built within it.

Parameters

  • decomp_results (dict) – Decomposition results. Must contain MUPulses key with the motor unit firing indices.

  • raw (numpy.ndarray) – Raw EMG data.

Returns

Panel object containing four interactive altair plots. 1. Plot of instantaneous firing rate and signal, primarily for zooming and navigating. 2. Plot of instantaneous firing rate, which allows for peak selection. 3. Plot of signal strength, which allows for peak selection. 4. MUAP plot of individual motor unit shapes by channel, with selected peak overlay.

Return type

panel.layout.base.Column