Data Handler

class libemg.data_handler.ColumnFetch(description: str, column_mask: Union[Sequence[int], int], values: Optional[Sequence] = None)
class libemg.data_handler.FilePackager(regex_filter: RegexFilter, package_function: Callable[[str, str], bool], align_method: Union[str, Callable[[ndarray[Any, dtype[ScalarType]], ndarray[Any, dtype[ScalarType]]], ndarray[Any, dtype[ScalarType]]]] = 'zoom', load=None, column_mask=None)
class libemg.data_handler.MetadataFetcher(description: str)
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)

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

Parameters

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

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

Returns

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

Return type

OfflineDataHandler

parse_windows(window_size, window_increment, 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.

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)

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.

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

Filtering

class libemg.filtering.Filter(sampling_frequency)

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

Parameters

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

filter(data)

Run installed filters on data.

Parameters

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

Returns

Returns the filtered data.

Return type

list

get_frequency_domain(data)

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

Parameters

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

Returns

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

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

install_common_filters()

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

install_filters(filter_dictionary={})

Install a particular filter.

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

Parameters

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

Examples

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

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

Parameters

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

visualize_filters()

Visualizes the bode plot of the installed filters.

Feature Extraction

class libemg.feature_extractor.FeatureExtractor

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

check_features(features, silent=False)

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

Parameters

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

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

Returns

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

Return type

int

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

Extracts a group of features.

Parameters

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

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

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

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

Returns

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

Return type

dictionary or list

extract_features(feature_list, windows, feature_dic={}, array=False)

Extracts a list of features.

Parameters

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

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

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

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

Returns

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

Return type

dictionary or list

getACTfeat(windows)

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

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getARfeat(windows, AR_order=4)

Extract Autoregressive Coefficients (AR) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getCCfeat(windows, CC_order=4)

Extract Cepstral Coefficient (CC) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getCOMPfeat(windows)

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

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getCORfeat(windows)

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

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getDASDVfeat(windows)

Difference Absolute Standard Deviation Value (DASDV) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getDFTRfeat(windows, DFTR_fs=1000)

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

Parameters

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

  • DFTR_fs (float, default=1000) –

Returns

The computed features associated with each window.

Return type

list

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

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

Parameters

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

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

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

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

Returns

The computed features associated with each window.

Return type

list

getIAVfeat(windows)

Extract Integral of Absolute Value (IAV) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getIRFfeat(windows)

Extract Irregularity Factor (IRF) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getISDfeat(windows)

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

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getKURTfeat(windows)

Extract Kurtosis (KURT) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getLDfeat(windows)

Extract Log Detector (LD) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getLSfeat(windows)

Extract L-Score (LS) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getM0feat(windows)

Extract First Temporal Moment (M0) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getM2feat(windows)

Extract Second Temporal Moment (M2) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getM4feat(windows)

Extract Fourth Temporal Moment (M4) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMAVFDfeat(windows)

Extract Mean Absolute Value First Difference (MAVFD) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMAVSLPfeat(windows, MAVSLP_segment=2)

Extract Mean Absolute Value Slope (MAVSLP) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getMAVfeat(windows)

Extract Mean Absolute Value (MAV) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMDFfeat(windows, MDF_fs=1000)

Extract Median Frequency (MDF) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getMDIFFfeat(windows)

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

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMEANfeat(windows)

Extract mean of signal (MEAN) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMFLfeat(windows)

Extract Maximum Fractal Length (MFL) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMLKfeat(windows)

Extract Mean Logarithm Kernel (MLK) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMNFfeat(windows, MNF_fs=1000)

Extract Mean Frequency (MNF) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getMNPfeat(windows)

Extract Mean Power (MNP) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMOBfeat(windows)

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

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMPKfeat(windows)

Extract (MPK) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMSRfeat(windows)

Extract Mean Squared Ratio (MSR) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getMZPfeat(windows)

Extract Multiplication of Power and Peaks (MZP) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getPAPfeat(windows)

Extract Peak Average Power (PaP) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getRMSPHASORfeat(windows)

Extract RMS Phasor feature (RMSPHASOR) feature. This

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getRMSfeat(windows)

Extract Root Mean Square (RMS) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

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

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

Parameters

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

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

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

Returns

The computed features associated with each window.

Return type

list

getSKEWfeat(windows)

Extract Skewness (SKEW) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

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

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

Parameters

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

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

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

Returns

The computed features associated with each window.

Return type

list

getSPARSIfeat(windows)

Extract Sparsness (SPARSI) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getSSCfeat(windows, SSC_threshold=0.0)

Extract Slope Sign Change (SSC) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getTMfeat(windows, TM_order=3)

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

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getVARfeat(windows)

Extract Variance (VAR) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getWAMPfeat(windows, WAMP_threshold=0.002)

Extract Willison Amplitude (WAMP) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getWENGfeat(windows, WENG_fs=1000)

Extract Wavelet Energy (WENG) feature.

Parameters

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

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

Returns

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

Return type

list

getWENTfeat(windows, WENT_fs=1000)

Extract Wavelet Entropy (WENT) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getWLFfeat(windows)

Waveform Length Factor (WLF) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getWLPHASORfeat(windows)

Extract WL Phasor feature (WLPHASOR) feature. This

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getWLfeat(windows)

Extract Waveform Length (WL) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

getWVfeat(windows, WV_fs=1000)

Extract Wavelet Variance (WV) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getWWLfeat(windows, WWL_fs=1000)

Extract Wavelet Waveform Length (WWL) feature.

Parameters

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

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

Returns

The computed features associated with each window.

Return type

list

getZCfeat(windows)

Extract Zero Crossings (ZC) feature.

Parameters

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

Returns

The computed features associated with each window.

Return type

list

get_feature_groups()

Gets a list of all available feature groups.

Returns

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

Return type

dictionary

get_feature_list()

Gets a list of all available features.

Returns

A list of all available features.

Return type

list

get_projection_list()

Gets a list of all available feature projections.

Returns

A list of all available projections.

Return type

list

visualize(feature_dic)

Visualize a set of features.

Parameters

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

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

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

Parameters

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

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

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

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

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

Visualize the the feature space through a certain projection.

Parameters

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

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

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

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

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

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

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

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

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

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

Parameters

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

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

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

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

Feature Selection

class libemg.feature_selector.FeatureSelector

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

get_metrics()

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

Returns

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

Return type

list

print(metric, results, fs)

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

Parameters

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

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

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

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

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

Parameters

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

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

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

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

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

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

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

Returns

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

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

Classification

class libemg.emg_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.

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

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

run(block=True)

Runs the classifier - continuously streams predictions over UDP.

Parameters

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

stop_running()

Kills the process streaming classification decisions.

visualize(max_len=50, legend=None)

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

Parameters

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

  • legend ((list) (optional)) – The legend to display on the plot

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)

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.

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.

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)

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.

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

Offline Evaluation Metrics

class libemg.offline_metrics.OfflineMetrics

Offline Metrics class is used for extracting offline performance metrics.

extract_common_metrics(y_true, y_predictions, null_label=None)

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

Parameters

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

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

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

Returns

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

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

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

Extracts a set of offline performance metrics.

Parameters

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

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

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

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

Returns

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

Return type

dictionary

Examples

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

Active Error.

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

Parameters

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

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

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

Returns

Returns the active error.

Return type

float

get_CA(y_true, y_predictions)

Classification Accuracy.

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

Parameters

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

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

Returns

Returns the classification accuracy.

Return type

float

get_CONF_MAT(y_true, y_predictions)

Confusion Matrix.

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

Parameters

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

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

Returns

Returns the confusion matrix.

Return type

list

get_F1(y_true, y_predictions)

F1 Score.

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

Parameters

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

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

Returns

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

Return type

list

get_INS(y_true, y_predictions)

Instability.

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

Parameters

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

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

Returns

Returns the instability.

Return type

float

get_MAE(y_true, y_predictions)

Mean absolute error.

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

Parameters

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

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

Returns

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

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

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

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

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

Returns

Returns a list consisting of the precision for each class.

Return type

list

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

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

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

Returns

Returns a list consisting of the recall for each class.

Return type

list

get_REJ_RATE(y_predictions)

Rejection Rate.

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

Parameters

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

Returns

Returns the rejection rate.

Return type

float

get_RMSE(y_true, y_predictions)

Root mean square error.

The RMSE measures the square root of the MSE.

Parameters

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

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

Returns

Returns a list consisting of the 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=[])

Regex creation helper for the data handler.

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

Parameters

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

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

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

Returns

The created regex.

Return type

string

Examples

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

Streamers

libemg.streamers.delsys_api_streamer(license: Optional[str] = None, key: Optional[str] = None, 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.

  • 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 sifi streamer object.

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

Examples

>>> streamer, shared_memory = delsys_streamer()
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 sifi 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 sifi 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 sifi streamer object

  • Object (shared memory) – The shared memory object

Examples

>>> streamer, shared_memory = oymotion_streamer()
libemg.streamers.sifibridge_streamer(version='1_1', shared_memory_items=None, ecg=False, emg=True, eda=False, imu=False, ppg=False, notch_on=True, notch_freq=60, emg_fir_on=True, emg_fir=[20, 450], eda_cfg=True, fc_lp=0, fc_hp=5, freq=250, streaming=False, mac=None)

The streamer for the sifi armband. This function connects to the sifi bridge and streams its data to the SharedMemory. This is used for the SiFi biopoint and bioarmband. Note that the IMU is acc_x, acc_y, acc_z, quat_w, quat_x, quat_y, quat_z. :param version: The version for the sifi streamer. :type version: string (option), default = ‘1_1’ :param shared_memory_items: The key, size, datatype, and multiprocessing Lock for all data to be shared between processes. :param default = []: The key, size, datatype, and multiprocessing Lock for all data to be shared between processes. :param ecg: The flag to enable electrocardiography recording from the main sensor unit. :param default = False: The flag to enable electrocardiography recording from the main sensor unit. :param emg: The flag to enable electromyography recording. :param default = True: The flag to enable electromyography recording. :param eda: The flag to enable electrodermal recording. :param default = False: The flag to enable electrodermal recording. :param imu: The flag to enable inertial measurement unit recording :param default = False: The flag to enable inertial measurement unit recording :param ppg: The flag to enable photoplethysmography recording :param default = False: The flag to enable photoplethysmography recording :param notch_on: The flag to enable a fc Hz notch filter on device (firmware). :param default = True: The flag to enable a fc Hz notch filter on device (firmware). :param notch_freq: The cutoff frequency of the notch filter specified by notch_on. :param default = 60: The cutoff frequency of the notch filter specified by notch_on. :param emg_fir_on: The flag to enable a bandpass filter on device (firmware). :param default = True: The flag to enable a bandpass filter on device (firmware). :param emg_fir: The low and high cutoff frequency of the bandpass filter specified by emg_fir_on. :param default = [20: The low and high cutoff frequency of the bandpass filter specified by emg_fir_on. :param 450]: The low and high cutoff frequency of the bandpass filter specified by emg_fir_on. :param eda_cfg: The flag to specify if using high or low frequency current for EDA or bioimpedance. :param default = True: The flag to specify if using high or low frequency current for EDA or bioimpedance. :param fc_lp: The low cutoff frequency for the bioimpedance. :param default = 0: The low cutoff frequency for the bioimpedance. :param fc_hp: The high cutoff frequency for the bioimpedance. :param default = 5: The high cutoff frequency for the bioimpedance. :param freq: The sampling frequency for bioimpedance. :param default = 250: The sampling frequency for bioimpedance. :param streaming: Whether to package the modalities together within packets for lower latency. :param default = False: Whether to package the modalities together within packets for lower latency. :param mac: mac address of the device to be connected to :param default = None: mac address of the device to be connected to

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

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