Data Handling

class libemg.data_handler.OfflineDataHandler

OfflineDataHandler class - responsible for collecting all offline data.

The purpose of this class is to facilitate the process of accumulating offline training and testing data. This class is extensible to a wide range of file and folder structures.

active_threshold(nm_windows, active_windows, active_labels, num_std=3, nm_label=0, silent=True)

Returns an update label list of the active labels for a ramp contraction.

Parameters

  • nm_windows (list) – The no motion windows that are used to establish the threshold.

  • active_windows (list) – The active windows that should be thresholded.

  • active_labels (list) – The active window labels that need to be updated.

  • num_std (int (default=3)) – The number of standard deviations away from the no motion class that are relabeled.

  • nm_label (int) – The class label associated with the no motion class.

  • silent (bool (default=True)) – If False, it will print out the number of active windows that were relabeled.

get_data(folder_location='', filename_dic={}, delimiter=',', mrdf_key='p_signal', skiprows=0)

Method to collect data from a folder into the OfflineDataHandler object. Metadata can be collected either from the filename specifying <tag>_regex keys in the filename_dic, or from within the .csv or .txt files specifying <tag>_columns in the filename_dic.

Parameters

  • folder_location (str) – Location of the dataset relative to current file path

  • filename_dic (dict) – dictionary containing the values of the metadata and the regex or columns associated with that metadata.

  • delimiter (char) – How the columns of the files are separated in the .txt or .csv files.

  • skiprows (int) – The number of rows in the CSV file to skip (from the top).

isolate_channels(channels)

Entry point for isolating a certain range of channels.

Parameters

channels (list) – A list of values (i.e., channels) that you want to isolate. (e.g., [0,1,2]). Indexing starts at 0.

Returns

returns a new offline data handler with only the data that satisfies the requested slice.

Return type

OfflineDataHandler

isolate_data(key, values)

Entry point for isolating a single key of data within the offline data handler. First, error checking is performed within this method, then if it passes, the isolate_data_helper is called to make a new OfflineDataHandler that contains only that data.

Parameters

  • key (str) – The metadata key that will be used to filter (e.g., “subject”, “rep”, “class”, “set”, whatever you’d like).

  • values (list) – A list of values that you want to isolate. (e.g. [0,1,2,3]). Indexing starts at 0.

Returns

returns a new offline data handler with only the data that satisfies the requested slice.

Return type

OfflineDataHandler

parse_windows(window_size, window_increment)

Parses windows based on the acquired data from the get_data function.

Parameters

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

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

Returns

  • list – A np.ndarray of size windows x channels x samples.

  • list – A dictionary containing np.ndarrays for each metadata tag of the dataset. Each window will have an associated value for each metadata. Therefore, the dimensions of the metadata should be Wx1 for each field.

class libemg.data_handler.OnlineDataHandler(port=12345, ip='127.0.0.1', file_path='raw_emg.csv', file=False, std_out=False, emg_arr=True, imu_arr=False, max_buffer=None, timestamps=False, other_arr=False)

OnlineDataHandler class - responsible for collecting data streamed in through UDP socket.

This class is extensible to any device as long as the data is being streamed over UDP. By default this will start writing to an array of EMG data stored in memory.

Parameters

  • port (int (optional), default = 12345) – The UDP port to listen for events on.

  • ip (string (optional), default = '127.0.0.1') – The UDP ip to listen for events on.

  • file_path (string (optional), default = "data/") – The path of the folder/file to write the raw data to. This only gets written to if the file parameter is set to true. For example data/test_ would write data/test_EMG.csv.

  • file (bool (optional): default = False) – If True, all data acquired over the UDP port will be written to a file specified by the file_path parameter.

  • std_out (bool (optional): default = False) – If True, all data acquired over the UDP port will be written to std_out.

  • emg_arr (bool (optional): default = True) – If True, all data acquired over the UDP port will be written to an array object that can be accessed.

  • imu_arr (bool (optional): default = False) – If True, all data acquired over the UDP port will be written to an array object (of IMU data) that can be accessed.

  • max_buffer (int (optional): default = None) – The buffer for the raw data array. This should be set for visualizatons to reduce latency. Otherwise, the buffer will fill endlessly, leading to latency.

  • add_timestamps (bool(optional): default = False) – If True, timestamps will be added to the raw filese generated when setting the file flag to true.

analyze_hardware(analyze_time=10)

Analyzes several metrics from the hardware: (1) sampling rate (2) resolution (3) min val (4) max val (5) number of channels

Parameters

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

install_filter(fi)

Install a filter to be used on the online stream of data.

Parameters

fi (libemg.filter object) – The filter object that you’d like to run on the online data.

start_listening()

Starts listening in a seperate process for data streamed over UDP.

The options (file, std_out, and emg_arr) will determine what happens with this data.

stop_listening()

Terminates the process listening for data.

visualize(num_samples=500, y_axes=None)

Visualize the incoming raw EMG in a plot (all channels together).

Parameters

  • num_samples (int (optional), default=500) – The number of samples to show in the plot.

  • y_axes (list (optional)) – A list of two elements consisting the bounds for the y-axis (e.g., [-1,1]).

visualize_channels(channels, num_samples=500, y_axes=None)

Visualize individual channels (each channel in its own plot).

Parameters

  • channels (list) – A list of channels to graph indexing starts at 0.

  • num_samples (int (optional), default=500) – The number of samples to show in the plot.

  • y_axes (list (optional)) – A list of two elements consisting of the y-axes.

visualize_feature_space(feature_dic, window_size, window_increment, sampling_rate, hold_samples=20, projection='PCA', classes=None, normalize=True)

Visualize a live pca plot. This is reliant on previously collected training data.

Parameters

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

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

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

  • sampling_rate (int) – The sampling rate of the device. This impacts the refresh rate of the plot.

  • hold_samples (int (optional), default=20) – The number of live samples that are shown on the plot.

  • projection (string (optional), default=PCA) – The projection method. Currently, the only available option, is PCA.

  • classes (list) – A list of classes that is associated with each feature index.

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

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)

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.

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

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.

Classification

class libemg.emg_classifier.EMGClassifier(random_seed=0)

The Offline EMG Classifier.

This is the base class for any offline EMG classification.

Parameters

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

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)

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.

fit(model, feature_dictionary=None, dataloader_dictionary=None, parameters=None)

The fit function for the EMG Classification 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

  • 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.

  • 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’.

  • 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. Alternatively, these can be custom parameters in the case of custom statistical models or deep learning 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.

run(test_data, fix_feature_errors=False, silent=False)

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.

  • fix_feature_errors (bool (default=False)) – If True, the classifier will update any feature erros (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.

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.

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.

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_classifier.OnlineEMGClassifier(offline_classifier, window_size, window_increment, online_data_handler, features, port=12346, ip='127.0.0.1', std_out=False, tcp=False, output_format='predictions', channels=None)

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. These should be the same list used to train the model. Pass in None if using the raw data (this is primarily for CNNs).

  • 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.

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

  • channels (list (optional), default=None) – If not none, the list of channels that will be extracted. Used if you only want to use a subset of channels during classification.

analyze_classifier(analyze_time=10, port=12346, ip='127.0.0.1')

Analyzes the latency of the designed classifier.

Parameters

  • analyze_time (int (optional), default=10 (seconds)) – The time in seconds that you want to analyze the device 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) –

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)) – The legend to display on the plot

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 (list) – A list of the true labels associated with each prediction.

  • y_predictions (list) – 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 (list) – A list of the true labels associated with each prediction.

  • y_predictions (list) – 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).

Parameters

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

  • y_predictions (list) – 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 (list) – A list of ground truth labels.

  • y_predictions (list) – 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 (list) – A list of ground truth labels.

  • y_predictions (list) – 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 (list) – A list of ground truth labels.

  • y_predictions (list) – 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 (list) – A list of ground truth labels.

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

Returns

Returns the instability.

Return type

float

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 (list) – A list of ground truth labels.

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

Returns

Returns a list consisting of the precision for each class.

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 (list) – A list of ground truth labels.

  • y_predictions (list) – 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 (list) – A list of predicted labels. -1 in the list correspond to rejected predictions.

Returns

Returns the rejection rate.

Return type

float

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=[])

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) – The values between the two regexes.

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

libemg.streamers.delsys_streamer(stream_ip='localhost', stream_port=12345, delsys_ip='localhost', cmd_port=50040, emg_port=50043, channel_list=[0, 1, 2, 3, 4, 5, 6, 7])

The UDP streamer for the Delsys device (Avanti/Trigno).

This function connects to the Delsys and streams its data over UDP. Note that you must have the Delsys Control Utility installed for this to work.

Parameters

  • stream_port (int (optional), default=12345) – The desired port to stream over.

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

  • cmd_port (int (optional), default=50040.) – The port that commands are sent to the Delsys system (ie., the start command and the stop command.)

  • delsys_port (int (optional), default=50043.) – The port that the Delsys is streaming over. Note this value reflects the EMG data port for the Delsys Avanti system. For the Trigno system (legacy), the port is 50041.

  • delsys_ip (string (optional), default='localhost') – The ip that the Delsys is streaming over.

  • channel_list (list, default=[0,1,2,3,4,5,6,7].) – The channels (i.e., electrodes) that are being used in the experiment. The Delsys will send 16 channels over the delsys_ip, but we only take the active channels to be streamed over the stream_ip/stream_port.

Examples

>>> delsys_streamer()
libemg.streamers.emager_streamer(ip='127.0.0.1', port=12345)

The UDP streamer for the emager armband.

This function connects to the emager cuff and streams its data over UDP.

Parameters

  • port (int (optional), default=12345) – The desired port to stream over.

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

Examples

>>> emager_streamer()
libemg.streamers.mock_emg_stream(file_path, num_channels, sampling_rate=100, port=12345, ip='127.0.0.1')

Streams EMG from a test file over UDP.

This function can be used to simulate raw EMG being streamed over a UDP port. The main purpose of this function would be to explore real-time interactions without the need for a physical device. Note: This will start up a seperate process to stream data over. Additionally, this uses the time module and as such the sampling rate may not be perfect and there may be some latency.

Parameters

  • file_path (string) – The path of the csv file where the EMG data is located.

  • num_channels (int) – The number of channels to stream. This should be <= to the number of columns in the CSV.

  • sampling_rate (int (optional), default=100) – The desired sampling rate in Hz.

  • port (int (optional), default=12345) – The desired port to stream over.

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

Examples

>>> mock_emg_stream("stream_data.csv", num_channels=8, sampling_rate=100)
libemg.streamers.myo_streamer(filtered=True, ip='127.0.0.1', port=12345, imu=False)

The UDP streamer for the myo armband.

This function connects to the Myo and streams its data over UDP. It leverages the PyoMyo library. Note: this version requires the blue dongle to be plugged in.

Parameters

  • filtered (bool (optional), default=True) – If True, the data is the filtered data. Otherwise it is the raw unfiltered data.

  • port (int (optional), default=12345) – The desired port to stream over.

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

  • imu (bool (optional), default=False) – If True, the IMU data will also stream. Columns: 0,1,2,3 (quaternion), 4,5,6 (accelerometer), 7,8,9 (gyroscope).

Examples

>>> myo_streamer()
libemg.streamers.otb_muovi_plus_streamer(ip='localhost', port=12345)

OT Bioelettronica muovi+ streamer.

Parameters

  • port (int (optional), default=12345) – The desired port to stream over.

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

Examples

>>> otb_muovi_plus_streamer()
libemg.streamers.otb_muovi_streamer(ip='localhost', port=12345)

OT Bioelettronica muovi streamer.

Parameters

  • port (int (optional), default=12345) – The desired port to stream over.

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

Examples

>>> otb_muovi_streamer()
libemg.streamers.otb_sessantaquattro_plus_streamer(ip='localhost', port=12345)

OT Bioelettronica sessantaquatro streamer.

Parameters

  • port (int (optional), default=12345) – The desired port to stream over.

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

Examples

>>> otb_sessantaquattro_plus_streamer()
libemg.streamers.otb_syncstation_streamer(ip='localhost', port=12345)

OT Bioelettronica sync station streamer.

Parameters

  • port (int (optional), default=12345) – The desired port to stream over.

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

Examples

>>> otb_syncstation_streamer()
libemg.streamers.oymotion_streamer(ip='127.0.0.1', port=12345, platform='windows', sampling_rate=1000)

The UDP streamer for the oymotion armband.

This function connects to the oymotion and streams its data over UDP. It leverages the gforceprofile library. Note: this version requires the dongle to be plugged in. Note, you should run this with sudo and using sudo -E python to preserve your environment.

Parameters

  • port (int (optional), default=12345) – The desired port to stream over.

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

  • platform (string ('windows', 'linux', or 'mac'), default='windows') – The platform being used. Linux uses a different streamer than mac and windows.

  • sampling_rate (int (optional), default=1000 (options: 1000 or 500)) – The sampling rate wanted from the device. Note that 1000 Hz is 8 bit resolution and 500 Hz is 12 bit resolution

Examples

>>> oymotion_streamer()
libemg.streamers.sifi_streamer(stream_port=12345, stream_ip='127.0.0.1', sifi_port=5000, sifi_ip='127.0.0.1')

The UDP streamer for the sifi cuff.

This function connects to the Sifi cuff and streams its data over UDP. Note that you must have the Sifi UI installed for this to work.

Parameters

  • stream_port (int (optional), default=12345) – The desired port to stream over.

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

  • sifi_port (int (optional), default=5000) – The port that the SIFI cuff is streaming over.

  • sifi_ip (string (optional), default='127.0.0.1') – The ip that the SIFI cuff is streaming over.

Examples

>>> sifi_streamer()
libemg.streamers.sifibridge_streamer(ip='127.0.0.1', port=12345, version='1.2', ecg=False, emg=True, eda=False, imu=False, ppg=False, notch_on=True, notch_freq=60, emg_fir_on=True, emg_fir=[20, 450], other=False)

The UDP streamer for the sifi armband. This function connects to the sifi bridge and streams its data over UDP. This is used for the SiFi biopoint and bioarmband. Note that the IMU is acc_x, acc_y, acc_z, quat_w, quat_x, quat_y, quat_z. :param port: The desired port to stream over. :type port: int (optional), default=12345 :param ip: The ip used for streaming predictions over UDP. :type ip: string optional, default = ‘127.0.0.1’ :param version: The version for the sifi streamer. :type version: string optional, default = ‘1.2’

Examples

>>> sifibridge_streamer()

Screen Guided Training

class libemg.screen_guided_training.ScreenGuidedTraining

The Screen Guided Training module.

By default, this module has two purposes: (1) Launching a Screen Guided Training window. (2) Downloading gesture sets from our library of gestures located at: https://github.com/libemg/LibEMGGestures

download_gestures(gesture_ids, folder, download_imgs=True, download_gifs=False, redownload=False)

Downloads gesture images (either .png or .gif) from: https://github.com/libemg/LibEMGGestures.

This function dowloads gestures using the “curl” command.

Parameters

  • gesture_ids (list) – A list of indexes corresponding to the gestures you want to download. A list of indexes and their respective gesture can be found at https://github.com/libemg/LibEMGGestures.

  • folder (string) – The output folder where the downloaded gestures will be saved.

  • download_gif (bool (optional), default=False) – If True, the assocaited GIF will be downloaded.

  • redownload (bool (optional), default=False) – If True, all files will be re-downloaded (regardless if they are already downloaed).

launch_training(data_handler, num_reps=3, rep_time=3, rep_folder=None, output_folder=None, time_between_reps=3, randomize=False, continuous=False, gifs=False, exclude_files=[], wait_btwn_prompts=False)

Launches the Screen Guided Training UI.

Parameters

  • num_reps (int > 0) – The number of repetitions per class.

  • rep_time (int > 0) – The amount of time for each rep.

  • time_between_reps (int > 0) – The amount of time between subsequent class prompts.

  • rep_folder (string) – The folder path where the images associated with each rep are located. Each image should be <class_name>.<png,jpg>.

  • output_folder (string) – The folder path where the acquired data will be written to.

  • data_handler (OnlineDataHandler) – Online data handler used for acquiring raw EMG data.

  • randomize (bool, default=False) – If True the classes are presented in a random order.

  • continuous (bool, default=False) – If True there is no pause between reps.

  • gifs (bool, default=False) – If True looks and plays gifs (this option of for discrete training).

  • exclude_files (list, default=None) – A list of files (i.e., classes) to exclude.

  • wait_btwn_prompts (bool, default=False) – If True, the SGT module will wait between each prompt for user input (button click) before moving on to the next gesture.