API Overview

EMGFlow is broken into 4 modules: access_files for file IO, preprocess_signals for preprocessing signals, plot_signals generating visualizations, and extract_features feature extraction.

Modules

Module Structure

access_files Module

These functions provide helper methods for accessing files, as well as functions for creating an EMG workflow filestructure.

make_paths is the beginning of the EMG processing pipeline. It generates folders for storing EMG data, and returns a dictionary with the locations of these folders. These locations are accessed under the keys "Raw", "Notch", "Bandpass", "FWR", "Screened", "Filled", "Smooth" and "Feature" - each for a different stage of processing. This dictionary is passed to many of the processing functions. If you have your own file structure you want to use instead, you can create your own dictionary to use instead, manually setting the locations of the paths under these keys.

make_sample_data provides built-in data to test out a data processing pipeline. It writes EMG data files to the "Raw" directory of a provided dictionary.

map_files is widely used internally to the EMGFlow package. It takes a path to a folder, and generates a dictionary of paths to the files contained within based on their names. This makes it easier to loop over subfiles, reading and analyzing them.

This function forms the basis for the two modes of analysis offered by EMGFlow: automated or manual.

The "automated" mode is designed for bulk processing files. In these functions, input/output is handled using your filepath dictionary. The functions loop over the files in the input folder, apply the filters, and write the filtered files to the output folder. Notable functions for this workflow includes:

• notch_filter_signals
• bandpass_filter_signals
• rectify_signals
• screen_artefact_signals
• fill_missing_signals
• smooth_signals

The "manual" mode is designed for processing individual files. In these functions, input/output is handled by passing and recieving a dataframe. Notable functions include:

• apply_notch_filters
• apply_bandpass_filter
• apply_rectify
• apply_screen_artefacts
• apply_fill_missing
• apply_rms_smooth

For more information, see the documentation for the access_files module.

preprocess_signals Module

This module contains the functions used for preprocessing and cleaning sEMG signals before extracting features. The preprocessing stage is broken into 6 stages: notch filtering, bandpass filtering, full wave rectifier, artefact screening, filling missing data and smoothing.

notch_filter_signals

Notch filtering involves filtering specific frequencies. This is typically due to some sort of interference, such as the power source of the device taking the reading.

notch_filter_signals provides flexibility for use in different regions of the world. Some filtering packages only provide notch filtering for 60Hz, the frequency where power can interfere with signal readings. However, other regions use different frequencies for power, such as 50Hz. EMGFlow allows you to choose the frequency and strength of the filter in a simple wrapper.

For more information, see the documentation for the preprocess_signals module.

bandpass_filter_signals

Bandpass filtering involves filtering frequencies outside a specific range. This is because sEMG signals only produce frequencies in a specific range, so any frequencies outside this range can be assumed to be interference.

bandpass_filter_signals uses bandpass thresholds of outside 20Hz and 450Hz, as this is the standard for EMG signals (De Luca et al., 2010). However, there is some disagreement within literature for different muscles, so bandpass_filter_signals provides the option to change these thresholds.

For more information, see the documentation for the preprocess_signals module.

rectify_signals

Full Wave Rectification (FWR) involves making all values in a signal positive. This is standard practice for extracting features, and before screening for artefacts or performing interpolation.

rectify_signals applies a standard FWR filter.

screen_artefact_signals

Artefact screening involves detecting and removing outlier values that can interfere with results.

screen_artefact_signals uses a rolling window, and replaces values greater than a specified number of standard deviations away with the median.

fill_missing_signals

Filling missing values involves interpolating values for missing data. This allows the smoothing filter to work better

fill_missing_signals provides multiple interpolation methods - "spline" and "pchip".

smooth_filter_signals

Smoothing involves limiting the impacts of noise and outliers in the signal by applying a smoothing algorithm.

smooth_filter_signals uses the RMS smoothing slgorithm by default as it is the best choice for filtering EMG signals (RENSHAW et al., 2010), however, EMGFlow provides other options as well.

For more information, see the documentation for the preprocess_signals module.

plot_signals Module

This module contains the functions used for visualizing individual, or large batches of signal data. This helps to see what is going on in the signal files whether to produce graphics, to make comparisons between files, or to look for outliers.

The plot_dashboard function uses an R Shiny Dashboard to dynamically load signal files. This makes it easy to compare different stages of processing, and jump between files.

For more information, see the documentation for the plot_signals module.

extract_features Module

This module contains the functions used for extracting features from signal data. This is primarily done with the extract_features function, though each individual feature is available as its own independent function for use in your own workflow.

The extract_features function writes the feature data to a "features.csv" file, with a column for the name of the signal file, and additional columns for each feature extracted. This is the end of the EMGFlow pipeline, producing this final file.

For more information, see the documentation for the extract_features module.

Sources

De Luca, C., Gilmore, L., Kuznetsov, M., & Roy, S. (2010). Filtering the surface EMG signal: Movement artifact and baseline noise contamination. Journal of Biomechanics, 43, 1.

RENSHAW, D., BICE, M. R., CASSIDY, C., ELDRIDGE, J. A., & POWELL, D. W. (2010). A Comparison of Three Computer-based Methods Used to Determine EMG Signal Amplitude. International Journal of Exercise Science, 3(1), 43–48.