pyemgpipeline.processors

Summary

Base Class

BaseProcessor

Base class of all EMG signal processors in pyemgpipeline

Classes

`AmplitudeNormalizer`	Amplitude normalizer for EMG signals
`BandpassFilter`	Bandpass filter for EMG signals
`DCOffsetRemover`	DC offset remover for EMG signals
`EndFrameCutter`	End frame cutter for EMG signals
`FullWaveRectifier`	Full wave rectifier for EMG signals
`LinearEnvelope`	Linear envelope for EMG signals
`Segmenter`	Segmenter for EMG signals

AmplitudeNormalizer

class pyemgpipeline.processors.AmplitudeNormalizer

Bases: pyemgpipeline.processors.base.BaseProcessor

Amplitude normalizer for EMG signals

apply(x, **kwargs)

Apply amplitude normalizer

Parameters

x (ndarray) – Shape (n_samples,) or (n_samples, n_channels). Signal data to be processed.
divisor (scalar, list, or ndarray) – One or more positive values. If x is in 1-dim or n_channels is 1, then divisor should be one value; otherwise divisor should be n_channels values.

Returns

x_processed – Same shape as x. The result of applying amplitude normalizer to x.

Return type

ndarray

get_param_values_in_str()

Getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str

BandpassFilter

class pyemgpipeline.processors.BandpassFilter(hz, bf_order=4, bf_cutoff_fq_lo=10, bf_cutoff_fq_hi=450)

Bases: pyemgpipeline.processors.base.BaseProcessor

Bandpass filter for EMG signals

Parameters

hz (float) – Sample rate in hertz. See class EMGMeasurementCollection for suggested values of hz.
bf_order (int, default=4) – Effective order (i.e., order after two-directional filtering) of the butterworth filter. bf_order should be a multiple of 2.
bf_cutoff_fq_lo (float, default=10) – Low cutoff frequency of the bandpass filter (i.e., frequency higher than bf_cutoff_fq_lo will pass). See Notes and References for some suggestions in different circumstances.
bf_cutoff_fq_hi (float, default=450) – High cutoff frequency of the bandpass filter (i.e., frequency lower than bf_cutoff_fq_hi will pass). See Notes and References for some suggestions in different circumstances. Note that bf_cutoff_fq_hi should be strictly less than half of hz.

Notes

Ref [1] suggests a bandwidth of 10–350 Hz for surface recording, 10–450 Hz for intramuscular recording, and 10–1500 Hz for needle recording.

Ref [2] suggests a bandwidth of from 5-10 Hz to 400-450 Hz for surface EMG and a high cutoff of at least 1500 Hz for intramuscular and needle recordings.

Ref [3] suggests a bandwidth of from 10-20 Hz to 500-1000 Hz for surface EMG.

Ref [4] suggests a low cutoff of 30 Hz when the placement of surface EMG is around the heart on the trunk.

References

[1] Editors (2018).: Standards for reporting EMG data. Journal of Electromyography and Kinesiology, 42, I-II. Doi: 10.1016/S1050-6411(18)30348-1.
[2] Merletti, R, & di Torino, P. (1999).: Standards for reporting EMG data. Journal of Electromyography and Kinesiology, 9(1), III-IV.
[3] Stegeman, D.F., & Hermens, H.J. (1999).: Standards for surface electromyography: the European project “Surface EMG for non-invasive assessment of muscles (SENIAM)”. Biomed 2 program of the European Community. European concerted action. 108-112.
[4] Drake, J.D.M., & Callaghan, J.P. (2006).: Elimination of electrocardiogram contamination from electromyogram signals: An evaluation of currently used removal techniques. Journal of Electromyography and Kinesiology, 16, 175–187.

apply(x, **kwargs)

Apply bandpass filter

Parameters: x (ndarray) – Shape (n_samples,) or (n_samples, n_channels), where n_samples > (bf_order + 1) * 3 (See Notes). Signal data to be processed.
Returns: x_processed – Same shape as x. The result of applying bandpass filter to x.
Return type: ndarray

Notes

Using scipy.signal.filtfilt requires the length of the input vector x greater than the padding length, padlen, which is (bf_order + 1) * 3 for a ‘bandpass’ Butterworth filter.

get_param_values_in_str()

Getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str

BaseProcessor

class pyemgpipeline.processors.BaseProcessor

Base class of all EMG signal processors in pyemgpipeline

abstract apply(x, **kwargs)

Abstract method of applying any EMG signal processing steps

Parameters

x (ndarray) – Shape (n_samples,) or (n_samples, n_channels), where processors may require conditions on n_samples. Signal data to be processed.
**kwargs (keyword arguments) – Processor-specific arguments.

Returns

Return type

None (in abstract method)

static assert_input(x)

Check the input signal

Parameters: x (ndarray) – Shape (n_samples,) or (n_samples, n_channels). Signal data to be processed.
Returns
Return type: None

static export_csv(filepath, x, timestamp=None, channel_names=None)

Export data to csv file

Parameters

filepath (str) – Filepath for data to export.
x (ndarray) – Shape (n_samples,) or (n_samples, n_channels). Signal data to be exported.
timestamp (ndarray or None, default None) – If ndarray, shape is (n_samples,). The timestamp corresponding to the signal.
channel_names (list of str, or None, default None) – If list, its length should be equal to n_channels. Channel names to be shown as the header of the csv file.

Returns

Return type

None

static get_indices_from_timestamp(timestamp, beg_ts, end_ts)

Get the corresponding indices from timestamp

Parameters

timestamp (ndarray) – In 1-dim.
beg_ts (float) – Beginning time of interest. beg_ts <= timestamp[-1].
end_ts (float) – End time of interest. end_ts >= timestamp[0]. Also beg_ts < end_ts.

Returns

beg_idx (int) – The smallest index of timestamp in which the time is greater than or equal to beg_ts.
end_idx (int) – The largest index of timestamp in which the time is less than or equal to end_ts.

abstract get_param_values_in_str()

Abstract method of getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str

static get_timestamp(x_shape, timestamp=None, hz=None)

Get the timestamp from one of the arguments

Parameters

x_shape (tuple) – Shape of the signal data in ndarray. x_shape is (n_samples,) or (n_samples, n_channels).
timestamp (ndarray or None, default None) – The actual timestamp corresponding to the signal. If it is an ndarray, it should be in 1-dim and have length equal to x_shape[0].
hz (float or None, default None) – Sample rate in hertz.

Returns

timestamp – Shape (n_samples,). The deduced timestamp corresponding to the signal. If getting None for both timestamp and hz from the input, this return value will be integers starting from 0.

Return type

ndarray

DCOffsetRemover

class pyemgpipeline.processors.DCOffsetRemover

Bases: pyemgpipeline.processors.base.BaseProcessor

DC offset remover for EMG signals

apply(x, **kwargs)

Apply DC offset remover

Parameters: x (ndarray) – Shape (n_samples,) or (n_samples, n_channels). Signal data to be processed.
Returns: x_processed – Same shape as x. The result of applying DC offset remover to x.
Return type: ndarray

get_param_values_in_str()

Getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str

EndFrameCutter

class pyemgpipeline.processors.EndFrameCutter(n_end_frames=30)

Bases: pyemgpipeline.processors.base.BaseProcessor

End frame cutter for EMG signals

Parameters: n_end_frames (int, default=30) – Number of frames to be cut off in both ends of the signal. n_end_frames >= 0.

apply(x, **kwargs)

Apply end frame cutter

Parameters: x (ndarray) – Shape (n_samples,) or (n_samples, n_channels), where n_samples > 2 * n_end_frame. Signal data to be processed or timestamp corresponding to the signal.
Returns: x_processed – Same dimension as x, where the first dimension reduces its length from ‘n_samples’ to ‘n_samples - 2 * n_end_frame’. The result of applying end frame cutter to x.
Return type: ndarray

get_param_values_in_str()

Getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str

FullWaveRectifier

class pyemgpipeline.processors.FullWaveRectifier

Bases: pyemgpipeline.processors.base.BaseProcessor

Full wave rectifier for EMG signals

apply(x, **kwargs)

Apply full wave rectifier

Parameters: x (ndarray) – Shape (n_samples,) or (n_samples, n_channels). Signal data to be processed.
Returns: x_processed – Same shape as x. The result of applying full wave rectifier to x.
Return type: ndarray

get_param_values_in_str()

Getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str

LinearEnvelope

class pyemgpipeline.processors.LinearEnvelope(hz, le_order=4, le_cutoff_fq=6)

Bases: pyemgpipeline.processors.base.BaseProcessor

Linear envelope for EMG signals

Parameters

hz (float) – Sample rate in hertz. See class EMGMeasurementCollection for suggested values of hz.
le_order (int, default=4) – Effective order (i.e., order after two-directional filtering) of the butterworth filter for linear envelope. le_order should be a multiple of 2.
le_cutoff_fq (float, default=6) – Cutoff frequency of the lowpass filter. Suggested value is 1~10. For standing scenario, use 1~2. For running scenario, use 10.

apply(x, **kwargs)

Apply linear envelope

Parameters: x (ndarray) – Shape (n_samples,) or (n_samples, n_channels), where n_samples > (le_order + 1) * 3 (See Notes). Signal data to be processed.
Returns: x_processed – Same shape as x. The result of applying linear envelope to x.
Return type: ndarray

Notes

Using scipy.signal.filtfilt requires the length of the input vector x greater than the padding length, padlen, which is (le_order / 2 + 1) * 3 for a ‘lowpass’ Butterworth filter.

get_param_values_in_str()

Getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str

Segmenter

class pyemgpipeline.processors.Segmenter

Bases: pyemgpipeline.processors.base.BaseProcessor

Segmenter for EMG signals

apply(x, **kwargs)

Apply segmenter

Parameters

x (ndarray) – Shape (n_samples,) or (n_samples, n_channels). Signal data to be processed or timestamp corresponding to the signal.
beg_idx (int) – Beginning index (inclusive) for segmentation of x at its first dimension. 0 <= beg_idx <= end_idx < n_samples.
end_idx (int) – End index (inclusive) for segmentation of x at its first dimension. 0 <= beg_idx <= end_idx < n_samples.

Returns

x_processed – Same dimension as x, where the first dimension reduces its length from ‘n_samples’ to ‘end_idx - beg_idx + 1’. The result of applying segmenter to x.

Return type

ndarray

get_param_values_in_str()

Getting the parameter values of the processor for display purpose

Returns: params_in_str – Parameter values.
Return type: str