PyEMD Documentation

PyEMD is a Python implementation of Empirical Mode Decomposition (EMD) and its variations, such as Ensemble Empirical Mode Decomposition (EEMD).

Core Concept: Intrinsic Mode Functions (IMF) Methods in this package decompose a signal into a set of components called Intrinsic Mode Functions (IMF). These IMFs represent specific oscillations within the analyzed signal, characterized by their own frequency and amplitude, which may change over time.

The EMD2D module is an experimental feature for performing EMD on images. This version uses 2D splines for envelopes, which are spanned on extrema defined through a maximum filter.

Warning: This is an experimental module. Results are not guaranteed to be reasonable or computationally optimal.

Complete Ensemble EMD with Adaptive Noise (CEEMDAN) is an extension of EEMD where information about the noise is shared among all workers.

Parallelization: By default, CEEMDAN enables parallel execution, automatically utilizing all available CPU cores to speed up computation. You can control this behavior via the parallel parameter during initialization.

The BEMD (Bidimensional Empirical Mode Decomposition) module is an experimental feature for performing EMD on 2D data, such as images. It uses morphological operators to detect regional maxima, which are then used to span a surface envelope using a radial basis function.

Warning: This is an experimental module. Results are not guaranteed to be reasonable or computationally optimal.

Ensemble Empirical Mode Decomposition (EEMD) decomposes an input signal by creating an ensemble of workers. Each worker performs a standard Empirical Mode Decomposition (EMD) on a copy of the input signal that has been augmented with added noise. Once all workers complete their tasks, the final result is calculated as the mean across all workers.

Note on Reproducibility: Because EEMD relies on random noise, every decomposition will produce a different set of components by default. To achieve reproducible results, you must both set a seed using the noise_seed method and disable parallel execution by setting parallel=False.

eemd = EEMD(parallel=False)
eemd.noise_seed(12345)
imfs = eemd(signal)

By default, EMD methods decompose the signal until all components are returned. If your use case only requires a specific number of components (e.g., only the first component), you can limit the output by setting the max_imfs parameter.

from PyEMD import EEMD

# Limit the decomposition to return only 2 IMFs
eemd = EEMD(max_imfs=2)

In EEMD and CEEMDAN, the trials parameter determines how many times the EMD is performed with noise-perturbed signals. While more trials increase convergence certainty, they also increase computation time. You can decrease the trials value to speed up the process if the default is too high for your specific signal.

from PyEMD import CEEMDAN

# Reduce the number of iterations to speed up computation
ceemdan = CEEMDAN(trials=20)

To install the latest version directly from the GitHub repository, you can either clone the repository and install it locally, or install it directly using a git URL with pip.

# Option 1: Clone and install locally
$ git clone https://github.com/laszukdawid/PyEMD
$ python -m pip install .

# Option 2: Install directly via git URL
$ python -m pip install git+https://github.com/laszukdawid/PyEMD.git

After installation, you can verify that the package is correctly installed and check its version by running the following command in your terminal:

$ python -c "import PyEMD; print(PyEMD.__version__)"

To perform Ensemble Empirical Mode Decomposition, import the EEMD class and use its eemd method. You can also configure the underlying EMD settings, such as the extrema detection method, by accessing the eemd.EMD attribute.

from PyEMD import EEMD
import numpy as np

t = np.linspace(0, 1, 200)
S = np.sin(2*np.pi*t) # Example signal

eemd = EEMD()

# Configure underlying EMD settings (e.g., extrema detection)
eemd.EMD.extrema_detection = "parabol"

eIMFs = eemd.eemd(S, t)