Data Handler

Datasets

libemg.datasets.evaluate(model, window_size, window_inc, feature_list=['MAV'], feature_dic={}, included_datasets=['OneSubjectMyo', '3DC'], output_file='out.pkl', regression=False, metrics=['CA'], normalize_data=False, normalize_features=False)

Evaluates an algorithm against all included datasets.

Parameters

  • window_size (int) – The window size (in ms).

  • window_inc (int) – The window increment (in ms).

  • feature_list (list (default=['MAV'])) – A list of features. Pass in None for CNN.

  • feature_dic (dic (default={})) – A dictionary of parameters for the passed in features.

  • included_datasets (list (str) or list (DataSets)) – The name of the datasets you want to evaluate your model on. Either pass in strings (e.g., ‘3DC’) for names or the dataset objects (e.g., _3DCDataset()).

  • output_file (string (default='out.pkl')) – The name of the directory you want to incrementally save the results to (it will be a pickle file).

  • regression (boolean (default=False)) – If True, will create an EMGRegressor object. Otherwise creates an EMGClassifier object.

  • metrics (list (default=['CA']/['MSE'])) – The metrics to extract from each dataset.

  • normalize_data (boolean (default=False)) – If True, the data will be normalized.

  • normalize_features (boolean (default=False)) – If True, features will get normalized.

Returns

A dictionary with a set of accuracies for different datasets

Return type

dictionary

libemg.datasets.evaluate_crossuser(model, window_size, window_inc, feature_list=['MAV'], feature_dic={}, included_datasets=['EMGEPN612'], output_file='out_cross.pkl', regression=False, metrics=['CA'], normalize_data=False, normalize_features=False, memory_efficient=False)

Evaluates an algorithm against all the cross-user datasets.

Parameters

  • window_size (int) – The window size (in ms).

  • window_inc (int) – The window increment (in ms).

  • feature_list (list (default=['MAV'])) – A list of features.

  • feature_dic (dic or list (default={})) – A dictionary or list of dictionaries of parameters for the passed in features.

  • included_datasets (list (str) or list (DataSets)) – The name of the datasets you want to evaluate your model on. Either pass in strings (e.g., ‘3DC’) for names or the dataset objects (e.g., _3DCDataset()).

  • output_file (string (default='out.pkl')) – The name of the directory you want to incrementally save the results to (it will be a pickle file).

  • regression (boolean (default=False)) – If True, will create an EMGRegressor object. Otherwise creates an EMGClassifier object.

  • metrics (list (default=['CA'])) – The metrics to extract from each dataset.

  • normalize_data (boolean (default=False)) – If True, the data will be normalized.

  • normalize_features (boolean (default=False)) – If True, features will get normalized.

  • memory_efficient (boolean (default=false)) – If True, features will be extracted in the prepare method. You wont have access to the raw data and normalization won’t be possible.

Returns

A dictionary with a set of accuracies for different datasets

Return type

dictionary

libemg.datasets.evaluate_weaklysupervised(model, window_size, window_inc, feature_list=['MAV'], feature_dic={}, included_datasets=['CIIL_WeaklySupervised'], output_file='out.pkl', regression=False, metrics=['CA'], normalize_data=False, normalize_features=False)

Evaluates an algorithm against all included datasets.

Parameters

  • window_size (int) – The window size (in ms).

  • window_inc (int) – The window increment (in ms).

  • feature_list (list (default=['MAV'])) – A list of features. Pass in None for CNN.

  • feature_dic (dic (default={})) – A dictionary of parameters for the passed in features.

  • included_datasets (list (str) or list (DataSets)) – The name of the datasets you want to evaluate your model on. Either pass in strings (e.g., ‘3DC’) for names or the dataset objects (e.g., _3DCDataset()).

  • output_file (string (default='out.pkl')) – The name of the directory you want to incrementally save the results to (it will be a pickle file).

  • regression (boolean (default=False)) – If True, will create an EMGRegressor object. Otherwise creates an EMGClassifier object.

  • metrics (list (default=['CA']/['MSE'])) – The metrics to extract from each dataset.

  • normalize_data (boolean (default=False)) – If True, the data will be normalized.

  • normalize_features (boolean (default=False)) – If True, features will get normalized.

Returns

A dictionary with a set of accuracies for different datasets

Return type

dictionary

libemg.datasets.get_dataset_info(dataset)

Prints out the information about a certain dataset.

Parameters

dataset (string) – The name of the dataset you want the information of.

libemg.datasets.get_dataset_list(type='CLASSIFICATION', cross_user=False)

Gets a list of all available datasets.

Parameters

  • type (str (default='CLASSIFICATION')) – The type of datasets to return. Valid Options: ‘CLASSIFICATION’, ‘REGRESSION’, ‘WEAKLYSUPERVISED’, and ‘ALL’.

  • cross_user (bool (default=False)) –

Returns

A dictionary with the all available datasets and their respective classes.

Return type

dictionary

Filtering

class libemg.filtering.Filter(sampling_frequency)

A class that will perform filtering on: (1) OfflineDataHandler, (2) OnlineDataHandler, and (3) data in numpy.ndarrays.

Parameters

sampling_frequency (int) – The sampling frequency of the device used. This must be known for the digital filters to do what is intended.

filter(data)

Run installed filters on data.

Parameters

data (list or OfflineDataHandler) – The data that will be passed through the filters.

Returns

Returns the filtered data.

Return type

list

get_frequency_domain(data)

Transform a time series np.ndarray into a frequency domain representation. Assumes that self.sampling_frequency is set.

Parameters

data (np.ndarray) – The data that will be transformed into the frequency domain. This assumes that the data is NxC size, (n samples, c channels).

Returns

  • np.ndarray – The power spectrum of the signal in the frequency domain.

  • np.ndarray – The frequencies that correspond the the bins of the power spectrum.

install_common_filters()

Install a set of common filters to minimize motion arteface and power line interference in North America. This will install a bandpass filter from 20Hz-450Hz and a notch filter at 60Hz.

install_filters(filter_dictionary={})

Install a particular filter.

Installing filters is required prior to filtering being performed. Filters are created using the scipy.signal package. The necessary parameters for these fitlers are included in a dictionary. When multiple filters are intended to be used at a time, install them sequentially by calling this function for each filter. If there is a specific order for the filters then install them in the intended processing order.

Parameters

filter_dictionary (dict) – A dictionary containing the necessary parameters for defining a single filter.

Examples

>>> # create a notch filter for removing power line interference
>>> filter_dictionary={ "name": "notch", "cutoff": 60, "bandwidth": 3}
>>> # create a filter for removing high frequency noise and low frequency motion artefacts
>>> filter_dictionary={ "name":"bandpass", "cutoff": [20, 450], "order": 4}
>>> # create a filter for low frequency motion artefacts
>>> filter_dictionary={ "name": "highpass", "cutoff": 20, "order":2}
visualize_effect(data)

Visualizes the time and frequency domain before and after features are applied.

Parameters

data (np.ndarray) – The data that the filter is being applied to for the visualization.

visualize_filters()

Visualizes the bode plot of the installed filters.

Feature Extraction

class libemg.feature_extractor.FeatureExtractor

Feature extraction class including feature groups, feature list, and feature extraction code.

check_features(features, silent=False)

Assesses a features object for np.nan, np.inf, and -np.inf. Can be used to check for clean data.

Parameters

  • features (np.ndarray or dict) – A group of features extracted with the feature extraction package in either dictionary or np.ndarray format

  • silent (bool (default=False)) – If True, will silence all prints from this function.

Returns

violations – A number of violations found within the data. This is the number of types of violations (nan, inf, -inf) per feature summed across all features. Returning 0 indicates that the features contain no invalid elements.

Return type

int

extract_feature_group(feature_group, windows, feature_dic={}, array=False)

Extracts a group of features.

Parameters

  • feature_group (string) – The group of features to extract. See the get_feature_list() function for valid options.

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • feature_dic (dict) – A dictionary containing the parameters you’d like passed to each feature. ex. {“MDF_sf”:1000}

  • array (bool (optional), default=False) – If True, the dictionary will get converted to a list.

Returns

A dictionary where each key is a specific feature and its value is a list of the computed features for each window.

Return type

dictionary or list

extract_features(feature_list, windows, feature_dic={}, array=False, normalize=False, normalizer=None, fix_feature_errors=False)

Extracts a list of features.

Parameters

  • feature_list (list) – The group of features to extract. Run get_feature_list() or checkout the API documentation to find an up-to-date feature list.

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • feature_dic (dict) – A dictionary containing the parameters you’d like passed to each feature. ex. {“MDF_sf”:1000}

  • array (bool (optional), default=False) – If True, the dictionary will get converted to a list.

  • normalize (bool (optional), default=False) – If True, the features will be normalized between using sklearn StandardScaler. The returned object will be a list.

  • normalizer (StandardScaler, default=None) – This should be set to the output from feature extraction on the training data. Do not normalize testing features without this as this could be considered information leakage.

  • fix_feature_errors (bool (optional), default=False) – If true, fixes all feature errors (NaN=0, INF=0, -INF=0).

Returns

  • dictionary or list – A dictionary where each key is a specific feature and its value is a list of the computed features for each window.

  • StandardScaler – If normalize is true it will return the normalizer object. This should be passed into the feature extractor for test data.

getACTfeat(windows)

Extract Activation (ACT) feature. This feature is very similar to the zeroth order moment feature of TDPSD (M0); however, it undergoes no nonlinear normalization.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getARfeat(windows, AR_order=4)

Extract Autoregressive Coefficients (AR) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • AR_order (int, default=4) – The order of the autoregressive model.

Returns

The computed features associated with each window.

Return type

list

getCCfeat(windows, CC_order=4)

Extract Cepstral Coefficient (CC) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • CC_order (int, default=4) – The order of the autoregressive and cepstral coefficient models.

Returns

The computed features associated with each window.

Return type

list

getCOMPfeat(windows)

Extract Complexity (COMP) feature. This feature is sqrt(m4/m2), where m2 and m4 are the second and fourth order moments found via Parseval’s theorem. It is a measure of the the similarity of the shape of a signal compared to a pure sine waveform. Because the Gabor frequency tells us the number of zero crossings per unit time, the derivative of this metric gives us the number of extrema per unit time.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getCORfeat(windows)

Extract Coefficient of Regularization (COR) feature. Very similar formulation to some of the TDPSD features.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getDASDVfeat(windows)

Difference Absolute Standard Deviation Value (DASDV) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getDFTRfeat(windows, DFTR_fs=1000)

Extract Discrete Time Fourier Transform Representation (DFTR) feature. He et al., 2015 used this feature set with various normalization approaches (channel-wise and global), and achieved robustness to contraction intensity variability, but the normalization is required for the robustness. DFTR divides the frequency spectrum into bins (20-92, 92-163, 163-235, 235-307, 307-378, 378-450). The number of returned bands depends on the DFTR_fs supplied. Note, it will only extract the band if the entire band lies under the frequency bin.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • DFTR_fs (float, default=1000) –

Returns

The computed features associated with each window.

Return type

list

getFUZZYENfeat(windows, FUZZYEN_dim=2, FUZZYEN_tolerance=0.3, FUZZYEN_win=2)

Extract Fuzzy Entropy (FUZZYEN) feature. SAMPEN_dim should be specified and is the number of samaples that are used to define patterns. SAMPEN_tolerance depends on the dataset and is the minimum distance between patterns to be considered the same pattern; we recommend a value near 0.3.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • FUZZYEN_dim (int, default=2) – The number of samples patterns are defined under. Note: SAMPEN_dim and SAMPEN_dim+1 samples are used to get the two patterns of the final logarithmic ratio.

  • FUZZYEN_tolerance (float, default=0.3) – The threshold for patterns to be considered similar

  • FUZZYEN_win (list, default=2) – the order the distance matrix is raised to prior to determining the similarity.

Returns

The computed features associated with each window.

Return type

list

getIAVfeat(windows)

Extract Integral of Absolute Value (IAV) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getIRFfeat(windows)

Extract Irregularity Factor (IRF) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getISDfeat(windows)

Extract Integral Square Descriptor (ISD) feature. Another signal amplitude and power feature. In the invTD feature set, this feature is meant to capture energy levels (not be robust to contraction intensity).

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getKURTfeat(windows)

Extract Kurtosis (KURT) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getLDfeat(windows)

Extract Log Detector (LD) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getLSfeat(windows)

Extract L-Score (LS) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getM0feat(windows)

Extract First Temporal Moment (M0) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getM2feat(windows)

Extract Second Temporal Moment (M2) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getM4feat(windows)

Extract Fourth Temporal Moment (M4) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMAVFDfeat(windows)

Extract Mean Absolute Value First Difference (MAVFD) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMAVSLPfeat(windows, MAVSLP_segment=2)

Extract Mean Absolute Value Slope (MAVSLP) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • MAVSLP_segment (int) – The number of segments to divide the window into

Returns

The computed features associated with each window.

Return type

list

getMAVfeat(windows)

Extract Mean Absolute Value (MAV) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMDFfeat(windows, MDF_fs=1000)

Extract Median Frequency (MDF) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • MDF_fs (int, float) – The sampling frequency of the signal

Returns

The computed features associated with each window.

Return type

list

getMDIFFfeat(windows)

Extract Mean Difference Derivative (MDIFF) feature. This is a feature that is the same metric as normRSD1 from COR.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMEANfeat(windows)

Extract mean of signal (MEAN) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMFLfeat(windows)

Extract Maximum Fractal Length (MFL) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMLKfeat(windows)

Extract Mean Logarithm Kernel (MLK) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMNFfeat(windows, MNF_fs=1000)

Extract Mean Frequency (MNF) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • MNF_fs (int, float) – The sampling frequency of the signal

Returns

The computed features associated with each window.

Return type

list

getMNPfeat(windows)

Extract Mean Power (MNP) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMOBfeat(windows)

Extract Mobility (MOB) feature. This feature is sqrt(m2/m0), where m0 and m2 are the first and second order moments found via Parseval’s theorem. Interestingly, the Gabor frequency tells us that the number of zero crossings per unit time can be described using 1/pi * mobility.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMPKfeat(windows)

Extract (MPK) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMSRfeat(windows)

Extract Mean Squared Ratio (MSR) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getMZPfeat(windows)

Extract Multiplication of Power and Peaks (MZP) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getPAPfeat(windows)

Extract Peak Average Power (PaP) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getRMSPHASORfeat(windows)

Extract RMS Phasor feature (RMSPHASOR) feature. This

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getRMSfeat(windows)

Extract Root Mean Square (RMS) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getSAMPENfeat(windows, SAMPEN_dim=2, SAMPEN_tolerance=0.3)

Extract Sample Entropy (SAMPEN) feature. SAMPEN_dim should be specified and is the number of samaples that are used to define patterns. SAMPEN_tolerance depends on the dataset and is the minimum distance between patterns to be considered the same pattern; we recommend a value near 0.3.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • SAMPEN_dim (int, default=2) – The number of samples patterns are defined under. Note: SAMPEN_dim and SAMPEN_dim+1 samples are used to get the two patterns of the final logarithmic ratio.

  • SAMPEN_tolerance (float, default=0.3) – The threshold for patterns to be considered similar

Returns

The computed features associated with each window.

Return type

list

getSKEWfeat(windows)

Extract Skewness (SKEW) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getSMfeat(windows, SM_order=2, SM_fs=1000)

Extract Spectral Moment (TM) feature. Order should be defined. Sampling frequency should be accurate for getting accurate frequency moments (physiological meaning). For pure pattern recognition problems, the sampling frequency parameter is not a large issue.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • SM_order (int, default=2) – The exponent that the frequency domain is raised to.

  • SM_fs (float, default=1000) – The sampling frequency (in Hz).

Returns

The computed features associated with each window.

Return type

list

getSPARSIfeat(windows)

Extract Sparsness (SPARSI) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getSSCfeat(windows, SSC_threshold=0.0)

Extract Slope Sign Change (SSC) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • SSC_threshold (float) – The threshold the derivative must exceed to be counted as a sign change.

Returns

The computed features associated with each window.

Return type

list

getTMfeat(windows, TM_order=3)

Extract Temporal Moment (TM) feature. Order should be defined.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • TM_order (int, default=3) – The exponent the time series is raised to before the MAV is computed.

Returns

The computed features associated with each window.

Return type

list

getVARfeat(windows)

Extract Variance (VAR) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getWAMPfeat(windows, WAMP_threshold=0.002)

Extract Willison Amplitude (WAMP) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • WAMP_threshold (float) – The value that must be exceeded by the derivative to be counted as a high variability sample

Returns

The computed features associated with each window.

Return type

list

getWENGfeat(windows, WENG_fs=1000)

Extract Wavelet Energy (WENG) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • WENG_fs (int) – The sampling frequency of the signal. This determines the number of wavelets used to decompose the signal.

Returns

The computed features associated with each window. Size: Wx((order+1)*Nchannels)

Return type

list

getWENTfeat(windows, WENT_fs=1000)

Extract Wavelet Entropy (WENT) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • WENT_fs (int) – The sampling frequency of the signal. This determines the number of wavelets used to decompose the signal.

Returns

The computed features associated with each window.

Return type

list

getWLFfeat(windows)

Waveform Length Factor (WLF) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getWLPHASORfeat(windows)

Extract WL Phasor feature (WLPHASOR) feature. This

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getWLfeat(windows)

Extract Waveform Length (WL) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

getWVfeat(windows, WV_fs=1000)

Extract Wavelet Variance (WV) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • WV_fs (int) – The sampling frequency of the signal. This determines the number of wavelets used to decompose the signal.

Returns

The computed features associated with each window.

Return type

list

getWWLfeat(windows, WWL_fs=1000)

Extract Wavelet Waveform Length (WWL) feature.

Parameters

  • windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

  • WWL_fs (int) – The sampling frequency of the signal. This determines the number of wavelets used to decompose the signal.

Returns

The computed features associated with each window.

Return type

list

getZCfeat(windows)

Extract Zero Crossings (ZC) feature.

Parameters

windows (list) – A list of windows - should be computed directly from the OfflineDataHandler or the utils.get_windows() method.

Returns

The computed features associated with each window.

Return type

list

get_feature_groups()

Gets a list of all available feature groups.

Returns

A dictionary with the all available feature groups and their respective features.

Return type

dictionary

get_feature_list()

Gets a list of all available features.

Returns

A list of all available features.

Return type

list

get_projection_list()

Gets a list of all available feature projections.

Returns

A list of all available projections.

Return type

list

visualize(feature_dic)

Visualize a set of features.

Parameters

feature_dic (dict) – A dictionary consisting of the different features. This is the output from the extract_features method.

visualize_all_distributions(feature_dic, classes=None, savedir=None, render=True)

Visualize the distribution of each feature using a histogram. This will render the histograms all together.

Parameters

  • feature_dic (dict) – A dictionary consisting of the different features. This is the output from the extract_features method.

  • classes (list) – The classes for each window.

  • savedir (string) – The location the plot should be saved to. Specify the full filepath i.e., “figs/subject1.png”.

  • render (boolean) – Boolean to indicate whether the plot is shown or not.

visualize_feature_space(feature_dic, projection, classes=None, savedir=None, render=True, test_feature_dic=None, t_classes=None, normalize=True, projection_params=None)

Visualize the the feature space through a certain projection.

Parameters

  • feature_dic (dict) – A dictionary consisting of the different features. This is the output from the extract_features method.

  • classes (list) – The classes for each window.

  • savedir (string) – The location the plot should be saved to. Specify the prefix i.e., “figs/subject”. Feature names and .png are appended to this prefix

  • render (boolean) – Boolean to indicate whether the plot is shown or not. Defaults to False.

  • test_feature_dic (dict) – A dictionary consisting of the different features. This is the output from the extract_features method.

  • t_classes (boolean) – The classes for each window of testing data.

  • normalize (boolean) – Whether the user wants to scale features to zero mean and unit standard deviation before projection (recommended).

  • projection_params (dict) – Extra parameters taken by the projection method.

visualize_single_distributions(feature_dic, classes=None, savedir=None, render=False)

Visualize the distribution of each feature using a histogram. This will render one histogram per feature.

Parameters

  • feature_dic (dict) – A dictionary consisting of the different features. This is the output from the extract_features method.

  • classes (list) – The classes for each window. Easily obtained from the odh.parse_windows() method.

  • savedir (string) – The location the plot should be saved to. Specify the prefix i.e., “figs/subject”. Feature names and .png are appended to this prefix

  • render (boolean) – Boolean to indicate whether the plot is shown or not. Defaults to False.

Feature Selection

class libemg.feature_selector.FeatureSelector

Feature selector class including different feature space metrics and sequential feature selection.

get_metrics()

The function to get the list of all possible metrics that can be used in feature selection.

Returns

metric_list – A list of strings that are the supported selection metrics

Return type

list

print(metric, results, fs)

The function to print the selection results in a table format to the console. This is the outward-facing function that calls helper functions for the sequential and metric print functions.

Parameters

  • metric (str) – The metric that was used in the selection

  • results (np.ndarray) – The metric values returned (wrapper or filter) from the selection procedure

  • fs (list) – The list containing the optimal feature order according to the metric used in the selection.

run_selection(data={}, metric='accuracy', class_var=[], crossvalidation_var={}, verbose=False, early_stop=None, nm_class=2)

The main method for running feature selection on a dataset. Selection will choose features that result in the ranking of features according to the specified metric and the metric values found through the selection process. This is an entry point function that calls the _get_sequential_selection_results and _get_metric_selection_results methods, after finding the metric callback (function handle for extracting the metric from data) and the metric type (sequential or metric).

Parameters

  • data (dict) – Dictionary of features where every feature has its own key. The element associated with each key is a np.ndarray of size N samples x F features. N is consistent across all features in the dictionary, but F can vary (eg., AR can have 4 features for channel and MAV has 1 feature per channel).

  • metric (str) – A string specifying what metric should be used as the basis of the selection.

  • class_var (list) – a np.ndarray containing the class labels associated with the features.

  • crossvalidation_var (dict) – A dictionary containing the method by which crossvalidation is performed (most metrics support crossvalidation). Either specify the “crossval_amount” key <int> to perform k-fold cross validation with k random folds of size (1-1/k) training (1/k) testing, or provide the “var” key to run leave-one-key-out cross validation with the np.ndarray you pass in.

  • verbose (bool (optional), default = False) – If True, automatically calls the print method after getting the results.

  • early_stop (int (optional), default = None) – The number of features to return from the selection – if None is passed, all features are returned. This only influences the computation time of wrapper-based selection.

  • nm_class (int (optioal), default=2) – The integer value of class label that corresponds to the no motion class. This is used only for active error.

Returns

  • filter_results/wrapper_results (np.ndarray) – filter_results is a 1D np.ndarray of metric values for each feature in the data dictionary wrapper_results is a 2D upper-triangle np.ndarray containing the metric values for the sequential selection processes.

  • feature_order (list) – The optimal order of features according to the metric specified. This is a list of feature names.

EMG Prediction

class libemg.emg_predictor.EMGClassifier(model, model_parameters=None, random_seed=0, fix_feature_errors=False, silent=False)

The Offline EMG Classifier.

This is the base class for any offline EMG classification.

Parameters

  • model (string or custom classifier (must have fit, predict and predic_proba functions)) – The type of machine learning model. Valid options include: ‘LDA’, ‘QDA’, ‘SVM’, ‘KNN’, ‘RF’ (Random Forest), ‘NB’ (Naive Bayes), ‘GB’ (Gradient Boost), ‘MLP’ (Multilayer Perceptron). Note, these models are all default sklearn models with no hyperparameter tuning and may not be optimal. Pass in custom classifiers or parameters for more control.

  • model_parameters (dictionary, default=None) – Mapping from parameter name to value based on the constructor of the specified model. Only used when a string is passed in for model.

  • random_seed (int, default=0) – Constant value to control randomization seed.

  • fix_feature_errors (bool (default=False)) – If True, the model will update any feature errors (INF, -INF, NAN) using the np.nan_to_num function.

  • silent (bool (default=False)) – If True, the outputs from the fix_feature_errors parameter will be silenced.

add_majority_vote(num_samples=5)

Adds the majority voting post-processing block onto a classifier.

Parameters

threshold (int (optional), default=5) – The number of samples that will be included in the majority vote.

add_rejection(threshold=0.9)

Adds the rejection post-processing block onto a classifier.

Parameters

threshold (float (optional), default=0.9) – The confidence threshold (0-1). All predictions with confidence under the threshold will be rejected.

add_velocity(train_windows, train_labels, velocity_metric_handle=None, velocity_mapping_handle=None)

Adds velocity (i.e., proportional) control where a multiplier is generated for the level of contraction intensity.

Note, that when using this optional, ramp contractions should be captured for training.

run(test_data)

Runs the classifier on a pre-defined set of training data.

Parameters

test_data (list) – A dictionary, np.ndarray of inputs appropriate for the model of the EMGClassifier.

Returns

  • list – A list of predictions, based on the passed in testing features.

  • list – A list of the probabilities (for each prediction), based on the passed in testing features.

visualize(test_labels, predictions, probabilities)

Visualize the decision stream of the classifier on the testing data.

You can call this visualize function to get a visual output of what the decision stream of what the particular classifier looks like.

Parameters

  • test_labels (list) – A np.ndarray containing the labels for the test data.

  • predictions (list) – A np.ndarray containing the preditions for the test data.

  • probabilities (list) – A np.ndarray containing the probabilities from the classifier for the test data. This should be N samples x C classes.

class libemg.emg_predictor.EMGPredictor(model, model_parameters=None, random_seed=0, fix_feature_errors=False, silent=False)

Base class for EMG prediction. Parent class that shares common functionality between classifiers and regressors.

Parameters

  • model (custom model (must have fit, predict and predict_proba functions)) – Object that will be used to fit and provide predictions.

  • model_parameters (dictionary, default=None) – Mapping from parameter name to value based on the constructor of the specified model. Only used when a string is passed in for model.

  • random_seed (int, default=0) – Constant value to control randomization seed.

  • fix_feature_errors (bool (default=False)) – If True, the model will update any feature errors (INF, -INF, NAN) using the np.nan_to_num function.

  • silent (bool (default=False)) – If True, the outputs from the fix_feature_errors parameter will be silenced.

fit(feature_dictionary=None, dataloader_dictionary=None, training_parameters=None)

The fit function for the EMG Prediction class.

This is the method called that actually optimizes model weights for the dataset. This method presents a fork for two different kind of models being trained. The first we call “statistical” models (i.e., LDA, QDA, SVM, etc.) and these are interfaced with sklearn. The second we call “deep learning” models and these are designed to fit around the conventional programming style of pytorch. We distinguish which of these models are being trained by passing in a feature_dictionary for “statistical” models and a “dataloader_dictionary” for deep learning models.

Parameters

  • feature_dictionary (dict) – A dictionary including the associated features and labels associated with a set of data. Dictionary keys should include ‘training_labels’ and ‘training_features’.

  • dataloader_dictionary (dict) – A dictionary including the associated dataloader objects for the dataset you’d like to train with. Dictionary keys should include ‘training_dataloader’, and ‘validation_dataloader’.

  • training_parameters (dict (optional)) – Training parameters passed to the fit() method of deep learning models (e.g., learning rate, num_epochs). Is not used for statistical models.

classmethod from_file(filename)

Loads a classifier - rather than creates a new one.

After saving a statistical model, you can recreate it by running EMGClassifier.from_file(). By default this function loads a previously saved and pickled classifier.

Parameters

filename (string) – The file path of the pickled model.

Returns

Returns an EMGClassifier object.

Return type

EMGClassifier

Examples

>>> classifier = EMGClassifier.from_file('lda.pickle')
install_feature_parameters(feature_params)

Installs the feature parameters for the classifier.

This function is used to install the feature parameters for the classifier. This is necessary for the classifier to know how to extract features from the raw data. This is used primarily by the OnlineEMGClassifier class.

Parameters

feature_params (dict) – A dictionary containing the feature parameters.

save(filename)

Saves (pickles) the EMGClassifier object to a file.

Use this save function if you want to load the object later using the from_file function. Note that this currently only support statistical models (i.e., not deep learning).

Parameters

filename (string) – The path of the outputted pickled file.

class libemg.emg_predictor.EMGRegressor(model, model_parameters=None, random_seed=0, fix_feature_errors=False, silent=False, deadband_threshold=0.0)

The Offline EMG Regressor.

This is the base class for any offline EMG regression.

Parameters

  • model (string or custom regressor (must have fit and predict functions)) – The type of machine learning model. Valid options include: ‘LR’ (Linear Regression), ‘SVM’ (Support Vector Machine), ‘RF’ (Random Forest), ‘GB’ (Gradient Boost), ‘MLP’ (Multilayer Perceptron). Note, these models are all default sklearn models with no hyperparameter tuning and may not be optimal. Pass in custom regressors or parameters for more control.

  • model_parameters (dictionary, default=None) – Mapping from parameter name to value based on the constructor of the specified model. Only used when a string is passed in for model.

  • random_seed (int, default=0) – Constant value to control randomization seed.

  • fix_feature_errors (bool (default=False)) – If True, the model will update any feature errors (INF, -INF, NAN) using the np.nan_to_num function.

  • silent (bool (default=False)) – If True, the outputs from the fix_feature_errors parameter will be silenced.

  • deadband_threshold (float, default=0.0) – Threshold that controls deadband around 0 for output predictions. Values within this deadband will be output as 0 instead of their original prediction.

add_deadband(threshold)

Add a deadband around regressor predictions that will instead be output as 0.

Parameters

threshold (float) – Deadband threshold. All output predictions from -threshold to +threshold will instead output 0.

run(test_data)

Runs the regressor on a pre-defined set of training data.

Parameters

test_data (list) – A dictionary, np.ndarray of inputs appropriate for the model of the EMGRegressor.

Returns

A list of predictions, based on the passed in testing features.

Return type

list

visualize(test_labels, predictions, single_axis=False)

Visualize the decision stream of the regressor on test data.

You can call this visualize function to get a visual output of what the decision stream looks like.

Parameters

  • test_labels (np.ndarray) – N x M array, where N = # samples and M = # DOFs, containing the labels for the test data.

  • predictions (np.ndarray) – N x M array, where N = # samples and M = # DOFs, containing the predictions for the test data.

  • single_axis (bool) – True if DOFs should be plotted on the same axis as different colours, False if DOFs should be plotted on separate axes. Defaults to False.

class libemg.emg_predictor.OnlineEMGClassifier(offline_classifier, window_size, window_increment, online_data_handler, features, file_path='.', file=False, smm=False, smm_items=None, port=12346, ip='127.0.0.1', std_out=False, tcp=False, output_format='predictions', feature_queue_length=0)

OnlineEMGClassifier.

Given a EMGClassifier and additional information, this class will stream class predictions over UDP in real-time.

Parameters

  • offline_classifier (EMGClassifier) – An EMGClassifier object.

  • window_size (int) – The number of samples in a window.

  • window_increment (int) – The number of samples that advances before next window.

  • online_data_handler (OnlineDataHandler) – An online data handler object.

  • features (list or None) – A list of features that will be extracted during real-time classification.

  • file_path (str, default = '.') – Location to store model outputs. Only used if file=True.

  • file (bool, default = False) – True if model outputs should be stored in a file, otherwise False.

  • smm (bool, default = False) – True if shared memory items should be tracked while running, otherwise False. If True, ‘model_input’ and ‘model_output’ are expected to be passed in as smm_items.

  • smm_items (list, default = None) –

    List of shared memory items. Each shared memory item should be a list of the format: [name: str, buffer size: tuple, dtype: dtype]. When modifying this variable, items with the name ‘classifier_output’ and ‘classifier_input’ are expected to be passed in to track classifier inputs and outputs. The ‘classifier_input’ item should be of the format [‘classifier_input’, (100, 1 + num_features), np.double] The ‘classifier_output’ item should be of the format [‘classifier_output’, (100, 1 + num_dofs), np.double]. If None, defaults to: [

    [“classifier_output”, (100,4), np.double], #timestamp, class prediction, confidence, velocity [‘classifier_input’, (100, 1 + 32), np.double], # timestamp <- features ->

    ]

  • port (int (optional), default = 12346) – The port used for streaming predictions over UDP.

  • ip (string (optional), default = '127.0.0.1') – The ip used for streaming predictions over UDP.

  • std_out (bool (optional), default = False) – If True, prints predictions to std_out.

  • tcp (bool (optional), default = False) – If True, will stream predictions over TCP instead of UDP.

  • output_format (str (optional), default=predictions) – If predictions, it will broadcast an integer of the prediction, if probabilities it broacasts the posterior probabilities

  • feature_queue_length (int (optional), default = 0) – Number of windows to include in online feature queue. Used for time series models that make a prediction on a sequence of feature windows (batch x feature_queue_length x features) instead of raw EMG. If the value is greater than 0, creates a queue and passes the data to the model as a 1 x feature_queue_length x num_features. If the value is 0, no feature queue is created and predictions are made on a single window (1 x features). Defaults to 0.

run(block=True)

Runs the classifier - continuously streams predictions over UDP.

Parameters

block (bool (optional), default = True) – If True, the run function blocks the main thread. Otherwise it runs in a seperate process.

stop_running()

Kills the process streaming classification decisions.

visualize(max_len=50, legend=None)

Produces a live plot of classifier decisions – Note this consumes the decisions. Do not use this alongside the actual control operation of libemg. Online classifier has to be running in “probabilties” output mode for this plot.

Parameters

  • max_len ((int) (optional)) – number of decisions to visualize

  • legend ((list) (optional)) – Labels used to populate legend. Must be passed in order of output classes.

class libemg.emg_predictor.OnlineEMGRegressor(offline_regressor, window_size, window_increment, online_data_handler, features, file_path='.', file=False, smm=False, smm_items=None, port=12346, ip='127.0.0.1', std_out=False, tcp=False, feature_queue_length=0)

OnlineEMGRegressor.

Given a EMGRegressor and additional information, this class will stream regression predictions over UDP or TCP in real-time.

Parameters

  • offline_regressor (EMGRegressor) – An EMGRegressor object.

  • window_size (int) – The number of samples in a window.

  • window_increment (int) – The number of samples that advances before next window.

  • online_data_handler (OnlineDataHandler) – An online data handler object.

  • features (list) – A list of features that will be extracted during real-time regression.

  • file_path (str, default = '.') – Location to store model outputs. Only used if file=True.

  • file (bool, default = False) – True if model outputs should be stored in a file, otherwise False.

  • smm (bool, default = False) – True if shared memory items should be tracked while running, otherwise False. If True, ‘model_input’ and ‘model_output’ are expected to be passed in as smm_items.

  • smm_items (list, default = None) –

    List of shared memory items. Each shared memory item should be a list of the format: [name: str, buffer size: tuple, dtype: dtype]. When modifying this variable, items with the name ‘model_output’ and ‘model_input’ are expected to be passed in to track model inputs and outputs. The ‘model_input’ item should be of the format [‘model_input’, (100, 1 + num_features), np.double] The ‘model_output’ item should be of the format [‘model_output’, (100, 1 + num_dofs), np.double]. If None, defaults to: [

    [‘model_output’, (100, 3), np.double], # timestamp, prediction 1, prediction 2… (assumes 2 DOFs) [‘model_input’, (100, 1 + 32), np.double], # timestamp <- features ->

    ]

  • port (int (optional), default = 12346) – The port used for streaming predictions over UDP.

  • ip (string (optional), default = '127.0.0.1') – The ip used for streaming predictions over UDP.

  • std_out (bool (optional), default = False) – If True, prints predictions to std_out.

  • tcp (bool (optional), default = False) – If True, will stream predictions over TCP instead of UDP.

  • feature_queue_length (int (optional), default = 0) – Number of windows to include in online feature queue. Used for time series models that make a prediction on a sequence of windows instead of raw EMG. If the value is greater than 0, creates a queue and passes the data to the model as a 1 (window) x feature_queue_length x num_features. If the value is 0, no feature queue is created and predictions are made on a single window. Defaults to 0.

run(block=True)

Runs the regressor - continuously streams predictions over UDP or TCP.

Parameters

block (bool (optional), default = True) – If True, the run function blocks the main thread. Otherwise it runs in a seperate process.

stop_running()

Kills the process streaming classification decisions.

visualize(max_len=50, legend=False)

Plot a live visualization of the online regressor’s predictions. Please note that the animation updates every 5 milliseconds, so keep this in mind when choosing window size and increment. For example, a window increment that’s too small may cause delay in the plotting if the regressor is making predictions faster than the plot can be updated.

Parameters

  • max_len (int (optional), default = 50) – Maximum number of predictions to plot at a time. Defaults to 50.

  • legend (bool (optional), default = False) – True if a legend should be shown, otherwise False. Defaults to False.

class libemg.emg_predictor.OnlineStreamer(offline_predictor, window_size, window_increment, online_data_handler, file_path, file, smm, smm_items, features, port, ip, std_out, tcp, feature_queue_length)

OnlineStreamer.

This is a base class for using algorithms (classifiers/regressors/other) in conjunction with online streamers.

Parameters

  • offline_predictor (EMGPredictor) – An EMGPredictor object.

  • window_size (int) – The number of samples in a window.

  • window_increment (int) – The number of samples that advances before next window.

  • online_data_handler (OnlineDataHandler) – An online data handler object.

  • features (list or None) – A list of features that will be extracted during real-time classification. These should be the same list used to train the model. Pass in None if using the raw data (this is primarily for CNNs).

  • file_path (str (optional)) – A location that the inputs and output of the classifier will be saved to.

  • file (bool (optional)) – A toggle for activating the saving of inputs and outputs of the classifier.

  • smm (bool (optional)) – A toggle for activating the storing of inputs and outputs of the classifier in the shared memory manager.

  • smm_items (list (optional)) – A list of lists containing the tag, size, and multiprocessing locks for shared memory.

  • parameters (dict (optional)) – A dictionary including all of the parameters for the sklearn models. These parameters should match those found in the sklearn docs for the given model.

  • port (int (optional), default = 12346) – The port used for streaming predictions over UDP.

  • ip (string (optional), default = '127.0.0.1') – The ip used for streaming predictions over UDP.

  • velocity (bool (optional), default = False) – If True, the classifier will output an associated velocity (used for velocity/proportional based control).

  • std_out (bool (optional), default = False) – If True, prints predictions to std_out.

  • tcp (bool (optional), default = False) – If True, will stream predictions over TCP instead of UDP.

  • feature_queue_length (int (optional), default = 0) – Number of windows to include in online feature queue. Used for time series models that make a prediction on a sequence of feature windows (batch x feature_queue_length x features) instead of raw EMG. If the value is greater than 0, creates a queue and passes the data to the model as a 1 x feature_queue_length x num_features. If the value is 0, no feature queue is created and predictions are made on a single window (1 x features). Defaults to 0.

analyze_predictor(analyze_time=10)

Analyzes the latency of the designed predictor.

Parameters

  • analyze_time (int (optional), default=10 (seconds)) – The time in seconds that you want to analyze the model for.

  • port (int (optional), default = 12346) – The port used for streaming predictions over UDP.

  • ip (string (optional), default = '127.0.0.1') – The ip used for streaming predictions over UDP.

  • (Average) ((1) Time Between Prediction) –

  • Deviation) ((2) STD Between Predictions (Standard) –

  • Predictions ((3) Total Number of) –

install_standardization(standardization: numpy.ndarray | sklearn.preprocessing._data.StandardScaler)

Install standardization to online model. Standardizes each feature based on training data (i.e., standardizes across windows). Standardization is only applied when features are extracted and is applied before feature queueing (i.e., features are standardized then queued) if relevant. To standardize data, use the standardize Filter.

Parameters

standardization (np.ndarray | StandardScaler) – Standardization data. If an array, creates a scaler and fits to the provided array. If a StandardScaler, uses the StandardScaler.

Offline Evaluation Metrics

class libemg.offline_metrics.OfflineMetrics

Offline Metrics class is used for extracting offline performance metrics.

extract_common_metrics(y_true, y_predictions, null_label=None)

Extracts the common set of offline performance metrics (CA, AER, and INS).

Parameters

  • y_true (numpy.ndarray) – A list of the true labels associated with each prediction.

  • y_predictions (numpy.ndarray) – A list of predicted outputs from a classifier.

  • null_label (int (optional)) – A null label used for the AER metric - this should correspond to the label associated with the No Movement or null class.

Returns

  • dictionary – A dictionary containing the metrics, where each metric is a key in the dictionary.

  • self.extract_offline_metrics(self.get_common_metrics(), y_true, y_predictions, null_label)

extract_offline_metrics(metrics, y_true, y_predictions, null_label=None)

Extracts a set of offline performance metrics.

Parameters

  • metrics (list) – A list of the metrics to extract. A list of metrics can be found running the get_available_metrics function.

  • y_true (numpy.ndarray) – A list of the true labels associated with each prediction.

  • y_predictions (numpy.ndarray) – A list of predicted outputs from a classifier.

  • null_label (int (optional)) – A null label used for the AER metric - this should correspond to the label associated with the No Movement or null class.

Returns

A dictionary containing the metrics, where each metric is a key in the dictionary.

Return type

dictionary

Examples

>>> y_true = np.array([1,1,1,2,2,2,3,3,3,4,4,4])
>>> y_predictions = np.array([1,1,2,2,2,1,3,3,3,4,1,4])
>>> metrics = ['CA', 'AER', 'INS', 'REJ_RATE', 'CONF_MAT', 'RECALL', 'PREC', 'F1']
>>> om = OfflineMetrics()
>>> computed_metrics = om.extract_offline_metrics(metrics, y_true, y_predictions, 2))
get_AER(y_true, y_predictions, null_class)

Active Error.

Classification accuracy on active classes (i.e., all classes but no movement/rest). Rejected samples are ignored.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

  • null_class (int) – The null class that shouldn’t be considered.

Returns

Returns the active error.

Return type

float

get_CA(y_true, y_predictions)

Classification Accuracy.

The number of correct predictions normalized by the total number of predictions.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns the classification accuracy.

Return type

float

get_CONF_MAT(y_true, y_predictions)

Confusion Matrix.

A NxN matric where N is the number of classes. Each column represents the predicted class and each row represents the true class.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns the confusion matrix.

Return type

list

get_F1(y_true, y_predictions)

F1 Score.

The f1 score is simply: 2 * (Precision * Recall)/(Precision + Recall). This metric takes into account the corresponding weights of each class.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the f1 score for each class.

Return type

list

get_INS(y_true, y_predictions)

Instability.

The number of subsequent predicitons that change normalized by the total number of predicitons.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns the instability.

Return type

float

get_MAE(y_true, y_predictions)

Mean absolute error.

The MAE measures the average L1 error between the true labels and predictions.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the MAE score for each DOF.

Return type

list

get_MAPE(y_true, y_predictions)

Mean absolute percentage error.

The MAPE measures the average error between the true labels and predictions as a percentage of the true value.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the MAPE score for each DOF.

Return type

list

get_MSE(y_true, y_predictions)

Mean squared error.

The MSE measures the averages squared errors between the true labels and predictions.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the MSE score for each DOF.

Return type

list

get_NRMSE(y_true, y_predictions)

Normalized root mean square error.

The NRMSE measures the RMSE normalized by the range of possible values.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the RMSE score for each DOF.

Return type

list

get_PREC(y_true, y_predictions)

Precision Score.

The precision is simply: True Positives / (True Positives + False Positive). This metric takes into account the corresponding weights of each class.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the precision for each class.

Return type

list

get_R2(y_true, y_predictions)

R2 score.

The R^2 score measures how well a regression model captures the variance in the predictions.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the R2 score for each DOF.

Return type

list

get_RECALL(y_true, y_predictions)

Recall Score.

The recall is simply: True Positives / (True Positives + False Negatives). This metric takes into account the corresponding weights of each class.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the recall for each class.

Return type

list

get_REJ_RATE(y_predictions)

Rejection Rate.

The number of rejected predictions, normalized by the total number of predictions.

Parameters

y_predictions (numpy.ndarray) – A list of predicted labels. -1 in the list correspond to rejected predictions.

Returns

Returns the rejection rate.

Return type

float

get_RMSE(y_true, y_predictions)

Root mean square error.

The RMSE measures the square root of the MSE.

Parameters

  • y_true (numpy.ndarray) – A list of ground truth labels.

  • y_predictions (numpy.ndarray) – A list of predicted labels.

Returns

Returns a list consisting of the RMSE score for each DOF.

Return type

list

get_available_metrics()

Gets a list of all available offline performance metrics.

Returns

A list of all available metrics.

Return type

list

get_common_metrics()

Gets a list of the common metrics used for assessing EMG performance.

Returns

A list of common metrics (CA, AER, and INS).

Return type

list

visualize(dic, y_axis=[0, 1])

Visualize the computed metrics in a bar chart.

Parameters

  • dic (dict) – The output from the extract_offline_metrics function.

  • y_axis (dict (optional), default=[0,1]) – A dictionary for lower and upper bounds of y axis.

visualize_conf_matrix(mat, labels=None)

Visualize the 2D confusion matrix.

Parameters

mat (list (2D)) – A NxN confusion matrix.

Utils

libemg.utils.get_windows(data, window_size, window_increment)

Extracts windows from a given set of data.

Parameters

  • data (list) – An NxM stream of data with N samples and M channels

  • window_size (int) – The number of samples in a window.

  • window_increment (int) – The number of samples that advances before next window.

Returns

The set of windows extracted from the data as a NxCxL where N is the number of windows, C is the number of channels and L is the length of each window.

Return type

list

Examples

>>> data = np.loadtxt('data.csv', delimiter=',')
>>> windows = get_windows(data, 100, 50)
libemg.utils.make_regex(left_bound, right_bound, values=None)

Regex creation helper for the data handler.

The OfflineDataHandler relies on regexes to parse the file/folder structures and extract data. This function makes the creation of regexes easier.

Parameters

  • left_bound (string) – The left bound of the regex.

  • right_bound (string) – The right bound of the regex.

  • values (list or None (optional), default = None) – The values between the two regexes. If None, will try to find the values using a wildcard. Defaults to None.

Returns

The created regex.

Return type

string

Examples

>>> make_regex(left_bound = "_C_", right_bound="_EMG.csv", values = [0,1,2,3,4,5])

Streamers

Screen Guided Training