Data Handler

class libemg.data_handler.ColumnFetcher(description: str, column_mask: Union[Sequence[int], int], values: Optional[Sequence] = None)

Fetch metadata from columns within data file.

Parameters

• description (str) – Description of metadata.

• column_mask (list or int) – Integers corresponding to indices of columns that should be fetched.

• values (list or None, default=None) – List of potential values within metadata column. If a list is passed in, the metadata will be stored as the location (index) of the value within the provided list. If None, the value within the columns will be stored.

class libemg.data_handler.FilePackager(regex_filter: RegexFilter, package_function: Union[Callable[[str, str], bool], Sequence[RegexFilter]], align_method: Union[str, Callable[[ndarray[Any, dtype[ScalarType]], ndarray[Any, dtype[ScalarType]]], ndarray[Any, dtype[ScalarType]]]] = 'zoom', load: Optional[Union[Callable[[str], ndarray[Any, dtype[ScalarType]]], str]] = None, column_mask: Optional[Sequence[int]] = None)

Package data file with another file that contains relevant metadata (e.g., a labels file). Cycles through all files that match the RegexFilter and packages a data file with a metadata file based on a packaging function.

Parameters

• regex_filter (RegexFilter) – Used to find the type of metadata files. The description of this RegexFilter is used to assign the name of the field for this metadata in the OfflineDataHandler.

• package_function (callable or Sequence[RegexFilter]) – Function handle used to determine if two files should be packaged together (i.e., found the metadata file that goes with the data file). Takes in the filename of a metadata file and the filename of the data file. Should return True if the files should be packaged together and False if not. Alternatively, a list of RegexFilters can be passed in and a function will be created that packages files only if the regex metadata of the data filename and metadata filename match.

• align_method (str or callable, default='zoom') – Method for aligning the samples of the metadata file and data file. Pass in ‘zoom’ for the metadata file to be zoomed using spline interpolation to the size of the data file or pass in a callable that takes in the metadata and the EMG data and returns the aligned metadata.

• load (callable, str, or None, default=None) – Determines how metadata file is loaded. If a custom loading function, should take in the filename and return an array. If a string, it is assumed to be the MRDF key of a .hea file. If None is passed, the metadata is loaded based on the file extension (only .csv and .txt are supported).

• column_mask (list or None, default=None) – List of integers corresponding to the indices of the columns that should be extracted from the raw file data. If None is passed, all columns are extracted.

class libemg.data_handler.MetadataFetcher(description: str)

Describes a type of metadata and implements a method to fetch it.

Parameters

description (str) – Description of metadata.

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: str, regex_filters: Sequence[RegexFilter], metadata_fetchers: Optional[Sequence[MetadataFetcher]] = None, delimiter: str = ',', mrdf_key: str = 'p_signal', skiprows: int = 0, data_column: Optional[Sequence[int]] = None, downsampling_factor: Optional[int] = None)

Method to collect data from a folder into the OfflineDataHandler object. The relevant data files can be selected based on passing in RegexFilters, which will filter out non-matching files and grab metadata from the filename based on their provided description. Data can be labelled with other sources of metadata via passed in MetadataFetchers, which will associate metadata with each data file.

Parameters

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

• regex_filters (list) – List of RegexFilters used to filter data files to the desired set of files. Metadata for each RegexFilter will be pulled from the filename and stored as a field.

• metadata_fetchers (list or None, default=None) – List of MetadataFetchers used to associate metadata with each data file (e.g., FilePackager). If the provided MetadataFetchers do not suit your needs, you may inherit from the MetadataFetcher class to create your own. If None is passed, no extra metadata is fetched (other than from filenames via regex).

• delimiter (str, default=',') – Specifies how columns are separated in .txt or .csv data files.

• mrdf_key (str, default='p_signal') – Key in mrdf file associated with EMG data.

• skiprows (int, default=0) – The number of rows to skip in the file (e.g., .csv or .txt) starting from the top row.

• data_column (list or None, default=None) – List of indices representing columns of data in data file. If a list is passed in, only the data at these columns will be stored as EMG data.

• downsampling_factor (int or None, default=None) – Factor to downsample by. Signal is first filtered and then downsampled. See scipy.signal.decimate for more details (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.decimate.html#scipy-signal-decimate).

Raises

ValueError: – Raises ValueError if folder_location is not a valid directory.

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, fast=True)

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.

• fast (Boolean (default=False)) – If true, it iterates over the median value for each EMG element. This should be used when parsing on things like reps, subjects, classes, etc.

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, metadata_operations=None)

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.

• metadata_operations (dict or None (optional),default=None) – Specifies which operations should be performed on metadata attributes when performing windowing. By default, all metadata is stored as its mode in a window. To change this behaviour, specify the metadata attribute as the key and the operation as the value in the dictionary. The operation (value) should either be an accepted string (mean, median, last_sample) or a function handle that takes in an ndarray of size (window_size, ) and returns a single value to represent the metadata for that window. Passing in a string will map from that string to the specified operation. The windowing of only the attributes specified in this dictionary will be modified - all other attributes will default to the mode. If None, all attributes default to the mode. Defaults to None.

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(shared_memory_items, channel_mask=None)

OnlineDataHandler class - responsible for collecting data streamed over shared memory.

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

Parameters

• shared_memory_items (Object) – The shared memory object returned from the streamer.

• channel_mask (list or None (optional), default=None) – Mask of active channels to use online. Allows certain channels to be ignored when streaming in real-time. If None, all channels are used. Defaults to None.

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.

get_data(N=0, filter=True)

Grab the data in the shared memory buffer across all modalities.

Parameters

• N (int) – Number of samples to grab from the shared memory items. If zero, grabs all data.

• filter (bool) – Apply the installed filters to the data prior to returning or not.

Returns

• val (dict) – A dictionary with keys corresponding to the modalities. Each key will have a np.ndarray of data returned.

• count (dict) – A dictionary with keys corresponding to the modalities. Each key will have an int corresponding to the number of samples received since the streamer began (or the last reset call).

install_channel_mask(mask)

Install a channel mask to isolate certain channels for online streaming.

Parameters

mask (list or None (optional), default=None) – Mask of active channels to use online. Allows certain channels to be ignored when streaming in real-time. If None, all channels are used. Defaults to None.

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.

log_to_file(block=False, file_path='', timestamps=True)

Logs the raw data being read to a file.

Parameters

• block (bool (optional), default=False) – If true, the main thread will be blocked.

• file_path (int (optional), default='') – The prefix to the file path that will be logged for each modality.

• timestamps (bool (optional), default=True) – If true, this will log the timestamps with each recording.

reset(modality=None)

Reset the data within the shared memory buffer.

Parameters

modality (str) – The modality that should be reset. If None, all modalities are reset.

stop_all()

Terminates the processes spawned by the ODH.

visualize(num_samples=500, block=True)

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.

• block (Boolean (optional), default=False) – Blocks the main thread if True.

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_heatmap(num_samples=500, feature_list=None, remap_function=None, cmap=None)

Visualize heatmap representation of EMG signals. This is commonly used to represent HD-EMG signals.

Parameters

• num_samples (int (optional), default=500) – The number of samples to average over (i.e., window size) when showing heatmap.

• feature_list (list or None (optional), default=None) – List of feature representations to extract, where each feature will be shown in a different subplot. Compatible with all features in libemg.feature_extractor.get_feature_list() that return a single value per channel (e.g., MAV, RMS). If a feature type that returns multiple values is passed, an error will be thrown. If None, defaults to MAV.

• remap_function (callable or None (optional), default=None) – Function pointer that remaps raw data to a format that can be represented by an image (such as np.reshape). Takes in an array and should return an array. If None, no remapping is done.

• cmap (colormap or None (optional), default=None) – matplotlib colormap used to plot heatmap.

class libemg.data_handler.RegexFilter(left_bound: str, right_bound: str, values: Sequence[str], description: str)

Filters files based on filenames that match the associated regex pattern and grabs metadata based on the regex pattern.

Parameters

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

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

• values (list) – The values between the two regexes.

• description (str) – Description of filter - used to name the metadata field. Pass in an empty string to filter files without storing the values as metadata.

get_matching_files(files: Sequence[str])

Filter out files that don’t match the regex pattern and return the matching files.

Parameters

files (list) – List of potential files that need to be filtered.

Returns

matching_files – List of files that match regex pattern.

Return type

list

get_metadata(filename: str)

Get metadata from the filename.

Parameters

filename (str) – Name of file.

Returns

metadata_idx – Index of value (relative to list of values passed in).

Return type

int

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)

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 (N x M array, where N = # samples and M = # DOFs, containing the labels for the test data.) – np.ndarray

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

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

libemg.streamers.delsys_api_streamer(license: str, key: str, num_channels: Optional[int] = None, dll_folder: str = 'resources/', shared_memory_items: Optional[list] = None, emg: bool = True)

The streamer for the Delsys devices that use their new C#.NET API.

This function connects to the Delsys. Note that you must have the Delsys .dll files (found here: https://github.com/delsys-inc/Example-Applications/tree/main/Python/resources), C#.NET 8.0 SDK, and the delsys license + key. Additionally, for using any device that connects over USB, make sure that the usb driver is version >= 6.0.0.

Parameters

• license (str) – Delsys license

• key (str) – Delsys key

• num_channels (int) – The number of delsys sensors you are using. Not used if shared_memory_items is passed, otherwise is a required parameter.

• dll_folder (string : optional (default='resources/')) – The location of the DLL files installed from the Delsys Github.

• shared_memory_items (list (optional)) – Shared memory configuration parameters for the streamer in format: [“tag”, (size), datatype].

• emg (bool : (optional)) – Whether to collect emg data or not.

Returns

• Object (streamer) – The delsys streamer object.

• Object (shared memory) – The shared memory object.

Examples

>>> streamer, shared_memory = delsys_api_streamer(LICENSE, KEY, num_channels=4)

libemg.streamers.delsys_streamer(shared_memory_items: Optional[list] = None, emg: bool = True, imu: bool = False, delsys_ip: str = 'localhost', cmd_port: int = 50040, emg_port: int = 50043, aux_port: int = 50044, channel_list: list = [0, 1, 2, 3, 4, 5, 6, 7], timeout: int = 10)

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

This function connects to the Delsys. Note that you must have the Delsys Control Utility installed for this to work.

Parameters

• shared_memory_items (list (optional)) – Shared memory configuration parameters for the streamer in format: [“tag”, (size), datatype].

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

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

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

• aux_port (int (optional), default=50044.) – The port that the Delsys is streaming IMU data 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.

• timeout (int) – Timeout for commands sent to Delsys.

Returns

• Object (streamer) – The delsys streamer object.

• Object (shared memory) – The shared memory object.

Examples

>>> streamer, shared_memory = delsys_streamer()

libemg.streamers.emager_streamer(shared_memory_items=None)

The streamer for the emager armband.

This function connects to the emager cuff and streams its data over a serial port and access it via shared memory.

Parameters

shared_memory_items (list (optional)) – Shared memory configuration parameters for the streamer in format: [“tag”, (size), datatype].

Returns

• Object (streamer) – The emager streamer object.

• Object (shared memory) – The shared memory object.

Examples

>>> streamer, shared_memory = emager_streamer()

libemg.streamers.myo_streamer(shared_memory_items: Optional[list] = None, emg: bool = True, imu: bool = False, filtered: bool = True)

The streamer for the myo armband.

This function connects to the Myo. It leverages the PyoMyo library. Note: this version requires the blue dongle to be plugged in.

Parameters

• shared_memory_items (list (optional)) – Shared memory configuration parameters for the streamer in format: [“tag”, (size), datatype].

• emg (bool (optional)) – Specifies whether EMG data should be forwarded to shared memory.

• imu (bool (optional)) – Specifies whether IMU data should be forwarded to shared memory.

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

Returns

• Object (streamer) – The sifi streamer object.

• Object (shared memory) – The shared memory object.

Examples

>>> streamer, shared_memory = myo_streamer()

libemg.streamers.oymotion_streamer(shared_memory_items: Optional[list] = None, sampling_rate: int = 1000, emg: bool = True, imu: bool = False)

The streamer for the oymotion armband.

This function connects to the oymotion and streams its data. 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 in Linux.

Parameters

• shared_memory_items (list (optional)) – Shared memory configuration parameters for the streamer in format: [“tag”, (size), datatype].

• 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

• emg (bool (optional),) – Detemines whether EMG data will be forwarded

• imu (bool (optional),) – Determines whether IMU data will be forwarded

Returns

• Object (streamer) – The oymotion streamer object

• Object (shared memory) – The shared memory object

Examples

>>> streamer, shared_memory = oymotion_streamer()

libemg.streamers.sifi_bioarmband_streamer(name='BioPoint_v1_1', shared_memory_items=None, ecg=False, emg=True, eda=False, imu=False, ppg=False, filtering=True, emg_notch_freq=60, emg_bandpass=(20, 450), eda_bandpass=(0, 5), eda_freq=0, streaming=False, mac=None)

The streamer for the SiFi BioArmband.

This function connects to SiFi Bridge and streams its data to the SharedMemory.

Note: The IMU keys are:

• Acceleration: ax, ay, az

• Quaternions: qw, qx, qy, qz

Parameters

• name (string, default = BioArmband) – The name of the Sifi Device. For example: BioArmband, BioPoint_v1_3, etc.

• shared_memory_items – The key, size, datatype, and multiprocessing Lock for all data to be shared between processes.

• [] (default =) – The key, size, datatype, and multiprocessing Lock for all data to be shared between processes.

• ecg – Enable electrocardiography recording from the main sensor unit.

• False (default =) – Enable electrocardiography recording from the main sensor unit.

• emg – Enable electromyography recording.

• True (default =) – Enable electromyography recording.

• eda – Enable electrodermal recording.

• False – Enable electrodermal recording.

• imu – Enable inertial measurement unit recording

• False – Enable inertial measurement unit recording

• ppg – The flag to enable photoplethysmography recording

• False – The flag to enable photoplethysmography recording

• filtering – Enable on-device filtering, including bandpass filters and notch filters.

• True – Enable on-device filtering, including bandpass filters and notch filters.

• emg_notch_freq – EMG notch filter frequency, useful for eliminating Mains power interference. Can be {None, 50, 60} Hz.

• 60 (default =) – EMG notch filter frequency, useful for eliminating Mains power interference. Can be {None, 50, 60} Hz.

• emg_bandpass – The low and high cutoff frequency of the EMG bandpass filter.

• (20 (default =) – The low and high cutoff frequency of the EMG bandpass filter.

• 450) – The low and high cutoff frequency of the EMG bandpass filter.

• eda_bandpass – The low and high cutoff frequency of the EDA bandpass filter.

• (0 (default =) – The low and high cutoff frequency of the EDA bandpass filter.

• 5) – The low and high cutoff frequency of the EDA bandpass filter.

• eda_freq – The excitation signal frequency for EDA/BIOZ. Setting an AC value may inject a lot of noise into the EMG sensor.

• 0 (default =) – The excitation signal frequency for EDA/BIOZ. Setting an AC value may inject a lot of noise into the EMG sensor.

• streaming – Whether to package the modalities together within packets for lower latency, only supported for BioPoint v1.3 and up.

• False – Whether to package the modalities together within packets for lower latency, only supported for BioPoint v1.3 and up.

• mac – Optional MAC address the device to connect to, useful when multiple devices are in the vicinity and you want to connect to a specific one.

• None (default =) – Optional MAC address the device to connect to, useful when multiple devices are in the vicinity and you want to connect to a specific one.

Returns

• Object (streamer) – The sifi streamer process object.

• Object (shared memory) – The shared memory items list to be passed to the OnlineDataHandler.

Examples

>>> streamer, shared_memory = sifibridge_streamer()

libemg.streamers.sifi_biopoint_streamer(name='BioPoint_v1_3', shared_memory_items=None, ecg=False, emg=True, eda=False, imu=False, ppg=False, filtering=True, emg_notch_freq=60, emg_bandpass=(20, 450), eda_bandpass=(0, 5), eda_freq=0, streaming=False, mac=None)

The streamer for the SiFi BioPoint.

This function connects to SiFi Bridge and streams its data to the SharedMemory.

Note: The IMU keys are:

• Acceleration: ax, ay, az

• Quaternions: qw, qx, qy, qz

Parameters

• device (string, default = BioPoint_v1_3) – The name or MAC of the device.

• shared_memory_items – The key, size, datatype, and multiprocessing Lock for all data to be shared between processes.

• [] (default =) – The key, size, datatype, and multiprocessing Lock for all data to be shared between processes.

• ecg – Enable electrocardiography recording from the main sensor unit.

• False (default =) – Enable electrocardiography recording from the main sensor unit.

• emg – Enable electromyography recording.

• True (default =) – Enable electromyography recording.

• eda – Enable electrodermal recording.

• False – Enable electrodermal recording.

• imu – Enable inertial measurement unit recording

• False – Enable inertial measurement unit recording

• ppg – The flag to enable photoplethysmography recording

• False – The flag to enable photoplethysmography recording

• filtering – Enable on-device filtering, including bandpass filters and notch filters.

• True – Enable on-device filtering, including bandpass filters and notch filters.

• emg_notch_freq – EMG notch filter frequency, useful for eliminating Mains power interference. Can be {None, 50, 60} Hz.

• 60 (default =) – EMG notch filter frequency, useful for eliminating Mains power interference. Can be {None, 50, 60} Hz.

• emg_bandpass – The low and high cutoff frequency of the EMG bandpass filter.

• (20 (default =) – The low and high cutoff frequency of the EMG bandpass filter.

• 450) – The low and high cutoff frequency of the EMG bandpass filter.

• eda_bandpass – The low and high cutoff frequency of the EDA bandpass filter.

• (0 (default =) – The low and high cutoff frequency of the EDA bandpass filter.

• 5) – The low and high cutoff frequency of the EDA bandpass filter.

• eda_freq – The excitation signal frequency for EDA/BIOZ. Setting an AC value may inject a lot of noise into the EMG sensor.

• 0 (default =) – The excitation signal frequency for EDA/BIOZ. Setting an AC value may inject a lot of noise into the EMG sensor.

• streaming – Whether to package the modalities together within packets for lower latency, only supported for BioPoint v1.3 and up.

• False – Whether to package the modalities together within packets for lower latency, only supported for BioPoint v1.3 and up.

• mac – Optional MAC address the device to connect to, useful when multiple devices are in the vicinity and you want to connect to a specific one.

• None (default =) – Optional MAC address the device to connect to, useful when multiple devices are in the vicinity and you want to connect to a specific one.

Returns

• Object (streamer) – The sifi streamer process object.

• Object (shared memory) – The shared memory items list to be passed to the OnlineDataHandler.

Examples

>>> streamer, shared_memory = sifibridge_streamer()

Screen Guided Training

class libemg.gui.GUI(online_data_handler, args={'auto_advance': True, 'data_folder': 'data/', 'media_folder': 'images/', 'num_reps': 3, 'rep_time': 5, 'rest_time': 3}, width=1920, height=1080, debug=False, gesture_width=500, gesture_height=500, clean_up_on_kill=False)

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

Parameters

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

• args (dic, default={'media_folder': 'images/', 'data_folder':'data/', 'num_reps': 3, 'rep_time': 5, 'rest_time': 3, 'auto_advance': True}) – The dictionary that defines the SGT window. Keys are: ‘media_folder’, ‘data_folder’, ‘num_reps’, ‘rep_time’, ‘rest_time’, and ‘auto_advance’. All media (i.e., images and videos) in ‘media_folder’ will be played in alphabetical order. For video files, a matching labels file of the same name will be searched for and added to the ‘data_folder’ if found. ‘rep_time’ is only used for images since the duration of videos is automatically calculated based on the number of frames (assumed to be 24 FPS).

• width (int, default=1920) – The width of the SGT window.

• height (int, default=1080) – The height of the SGT window.

• gesture_width (int, default=500) – The width of the embedded gesture image/video.

• gesture_height (int, default=500) – The height of the embedded gesture image/video.

• clean_up_on_call (Boolean, default=False) – If true, this will cleanup (and kill) the streamer reference.

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

start_gui()

Launches the Screen Guided Training UI.