API documentation

Main decomposition routines

pyeemd.eemd(inp, num_imfs=None, ensemble_size=250, noise_strength=0.2, S_number=None, num_siftings=None, rng_seed=0)[source]

Decompose input data array inp to Intrinsic Mode Functions (IMFs) with the Ensemble Empirical Mode Decomposition algorithm [R12].

The size of the ensemble and the relative magnitude of the added noise are given by parameters ensemble_size and noise_strength, respectively. The stopping criterion for the decomposition is given by either a S-number or an absolute number of siftings. In the case that both are positive numbers, the sifting ends when either of the conditions is fulfilled. By default, num_siftings=50 and S_number=4. If only S_number is set to a positive value, num_siftings defaults to 50. If only num_siftings is set to a positive value, S_number defaults to 0.

Parameters:

inp : array_like, shape (N,)

The input signal to decompose. Has to be a one-dimensional array-like object.

num_imfs : int, optional

Number of IMFs to extract. If set to None, a default value given by emd_num_imfs(N) is used. Note that the residual is also counted in this number, so num_imfs=1 will simply give you the input signal plus noise.

ensemble_size : int, optional

Number of copies of the input signal to use as the ensemble.

noise_strength : float, optional

Standard deviation of the Gaussian random numbers used as additional noise. This value is relative to the standard deviation of the input signal.

S_number : int, optional

Use the S-number stopping criterion [R22] for the EMD procedure with the given values of S. That is, iterate until the number of extrema and zero crossings in the signal differ at most by one, and stay the same for S consecutive iterations. Typical values are in the range 3 .. 8. If S_number is zero, this stopping criterion is ignored.

num_siftings : int, optional

Use a maximum number of siftings as a stopping criterion. If num_siftings is zero, this stopping criterion is ignored.

rng_seed : int, optional

A seed for the random number generator. A value of zero denotes an implementation-defined default value.
Returns:

imfs : ndarray, shape (M, N)

A MxN array with M = num_imfs. The rows of the array are the IMFs of the input signal, with the last row being the final residual.

See also

emd
The regular Empirical Mode Decomposition routine.
emd_num_imfs
The number of IMFs returned for a given input length N unless a specific number is set by num_imfs.

Notes

At least one of S_number and num_siftings must be positive. If both are positive, the iteration stops when either of the criteria is fulfilled.

References

[R12](1, 2) Z. Wu and N. Huang, “Ensemble Empirical Mode Decomposition: A Noise-Assisted Data Analysis Method”, Advances in Adaptive Data Analysis, Vol. 1 (2009) 1–41
[R22](1, 2) N. E. Huang, Z. Shen and S. R. Long, “A new view of nonlinear water waves: The Hilbert spectrum”, Annual Review of Fluid Mechanics, Vol. 31 (1999) 417–457
pyeemd.emd(inp, num_imfs=None, S_number=None, num_siftings=None)[source]

A convenience function for performing EMD (not EEMD). This simply calls function eemd() with ensemble_size=1 and noise_strength=0.

pyeemd.ceemdan(inp, num_imfs=None, ensemble_size=250, noise_strength=0.2, S_number=None, num_siftings=None, rng_seed=0)[source]

Decompose input data array inp to Intrinsic Mode Functions (IMFs) with the Complete Ensemble Empirical Mode Decomposition with Adaptive Noise (CEEMDAN) algorithm [R55], a variant of EEMD. For description of the input parameters and output, please see documentation of eemd().

See also

eemd
The regular Ensemble Empirical Mode Decomposition routine.
emd_num_imfs
The number of IMFs returned for a given input length.

References

[R55](1, 2) M. Torres et al, “A Complete Ensemble Empirical Mode Decomposition with Adaptive Noise” IEEE Int. Conf. on Acoust., Speech and Signal Proc. ICASSP-11, (2011) 4144–4147

Auxiliary routines

pyeemd.emd_num_imfs(N)[source]

Return number of IMFs that will be extracted from input data of length N, including the final residual.

pyeemd.emd_find_extrema(x)[source]

Find the local minima and maxima from input data x. This includes the artificial extrema added to the ends of the data as specified in the original EEMD article [R77].

Parameters:

x : array_like, shape (N,)

The input data. Has to be a one-dimensional array_like object.
Returns:

maxx : ndarray

The x-coordinates of the local maxima.

maxy : ndarray

The y-coordinates of the local maxima.

minx : ndarray

The x-coordinates of the local minima.

miny : ndarray

The y-coordinates of the local minima.

References

[R77](1, 2) Z. Wu and N. Huang, “Ensemble Empirical Mode Decomposition: A Noise-Assisted Data Analysis Method”, Advances in Adaptive Data Analysis, Vol. 1 (2009) 1–41
pyeemd.emd_evaluate_spline(x, y)[source]

Evaluates a cubic spline with the given (x, y) points as knots.

Parameters:

x : array_like, shape (N,)

The x coordinates of the knots. The array must be sorted, start from 0 and end at an integer.

y : array_like, shape (N,)

The y coordinates of the knots.
Returns:

spline_y : ndarray

The cubic spline curve defined by the knots and the “not-a-knot” end conditions, evaluated at integer points from 0 to max(x).

See also

emd_find_extrema
A method of finding the extrema for spline fitting.

Notes

As you can see from the definition, this method is tuned to work only in the case needed by EMD. This method is made available mainly for visualization and unit testing purposes. Better general purpose spline methods exist already in scipy.interpolate.

Utility code: pyeemd.utils

pyeemd.utils.plot_imfs(imfs, new_figs=True, plot_splines=True)[source]

Plot utility method for plotting IMFs and their envelope splines with pylab.

Parameters:

imfs : ndarray

The IMFs as returned by pyeemd.emd(), pyeemd.eemd(), or pyeemd.ceemdan().

new_figs : bool, optional

Whether to plot the IMFs in separate figures.

plot_splines : bool, optional

Whether to plot the envelope spline curves as well.