emd Documentation

emd DocumentationRelease 0.0.1

Andrew Quinn

Dec 09, 2020

Contents:

1 Features 3

2 Quick Start 52.1 EMD - Tutorial Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2 Module reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3 Indices and tables 37

Bibliography 39

Index 41

i

emd Documentation, Release 0.0.1

EMD is a python package implementing the Empirical Mode Decomposition and functionality for ananlysis of instan-taneous frequency.

THIS PAGE IS UNDER ACTIVE DEVELOPEMENT! - PLEASE WATCH THIS SPACE FOR MORE EXAMPLESAND TUTORIALS

Contents: 1


2 Contents:

CHAPTER 1

Features

• A range of sift algorithms including: sift, ensemble sift, complete ensemble sift, mask sift

• Instantaneous phase, frequency and amplitude computation

• Cycle detection and analysis

• Hilbert-Huang spectrum estimation (1d frequency spectrum or 2d time-frequency spectrum)

• Second layer sift to quantify structure in amplitude modulations

• Holospectrum estimation (3d instantaneous frequency x amplitude modulation frequency x time spectrum)

3


4 Chapter 1. Features

CHAPTER 2

Quick Start

EMD can be install from PyPI using pip:

pip install emd

and used to decompose and describe non-linear timeseries.:

# Importsimport emdimport numpy as npimport matplotlib.pyplot as plt

# Definitionssample_rate = 1000seconds = 3time_vect = np.linspace(0,seconds,seconds*sample_rate)

# A non-linear oscillationx = emd.utils.abreu2010( 5, .25, -np.pi/4, sample_rate, seconds )# ...plus a linear oscillationx += np.cos( 2*np.pi*1*time_vect )

# Siftimf = emd.sift.sift( x )

# Visualise Intrinsic Mode Functionsemd.plotting.plot_imfs( imf, scale_y=True, cmap=True )

# Compute instantaneous spectral statsIP,IF,IA = emd.spectra.frequency_stats( imf, sample_rate ,'nht' )

# Compute Hilbert-Huang transformedges,centres = emd.spectra.define_hist_bins(0,10,32)hht = emd.spectra.hilberthuang( IF, IA, edges )

(continues on next page)

5

https://pypi.org/project/emd/


(continued from previous page)

# Visualise time-frequency spectrumplt.figure()plt.pcolormesh( time_vect, centres, hht, cmap='hot_r')plt.colorbar()plt.xlabel('Time (seconds)')plt.ylabel('Instantaneous Frequency (Hz)')

2.1 EMD - Tutorial Examples

These tutorials are designed to help get started with Empirical Mode Decomposition analysis using this toolbox.

2.1.1 Running a simple EMD

This getting started tutorial shows how to use EMD to analyse a synthetic signal.

Running an EMD and frequency transform

First of all, we import both the numpy and EMD modules:

# sphinx_gallery_thumbnail_number = 2

import matplotlib.pyplot as pltimport numpy as npimport emd

We then define a simulated waveform containing a non-linear wave at 5Hz and a sinusoid at 1Hz:

sample_rate = 1000seconds = 10num_samples = sample_rate*seconds

time_vect = np.linspace(0, seconds, num_samples)

freq = 5

# Change extent of deformation from sinusoidal shape [-1 to 1]nonlinearity_deg = .25

# Change left-right skew of deformation [-pi to pi]nonlinearity_phi = -np.pi/4

# Compute the signalx = emd.utils.abreu2010(freq, nonlinearity_deg, nonlinearity_phi, sample_rate,→˓seconds)x += np.cos(2 * np.pi * 1 * time_vect)

# Visualise the time-series for analysisplt.figure(figsize=(12, 4))plt.plot(x)

6 Chapter 2. Quick Start


Out:

[<matplotlib.lines.Line2D object at 0x7f98b3e29490>]

We can then estimate the IMFs for the signal:

imf = emd.sift.sift(x)print(imf.shape)

Out:

(10000, 5)

and, from the IMFs, compute the instantaneous frequency, phase and amplitude using the Normalised Hilbert Trans-form Method:

IP, IF, IA = emd.spectra.frequency_stats(imf, sample_rate, 'nht')

From the instantaneous frequency and amplitude, we can compute the Hilbert-Huang spectrum:

freq_edges, freq_bins = emd.spectra.define_hist_bins(0, 10, 100)hht = emd.spectra.hilberthuang(IF, IA, freq_edges)

Visualising the results

we can now plot some summary information, first the IMFs:

emd.plotting.plot_imfs(imf, scale_y=True, cmap=True)

2.1. EMD - Tutorial Examples 7


and now the Hilbert-Huang transform of this decomposition

plt.figure(figsize=(10, 6))

plt.subplot(1, 1, 1)plt.pcolormesh(time_vect[:5000], freq_bins, hht[:, :5000], cmap='ocean_r')plt.ylabel('Frequency (Hz)')plt.xlabel('Time (secs)')

plt.grid(True)



Out:

/home/docs/checkouts/readthedocs.org/user_builds/emd/checkouts/v0.3.0/doc/source/→˓tutorials/plot_tutorial1.py:77: MatplotlibDeprecationWarning: shading='flat' when X→˓and Y have the same dimensions as C is deprecated since 3.3. Either specify the→˓corners of the quadrilaterals with X and Y, or pass shading='auto', 'nearest' or→˓'gouraud', or set rcParams['pcolor.shading']. This will become an error two minor→˓releases later.plt.pcolormesh(time_vect[:5000], freq_bins, hht[:, :5000], cmap='ocean_r')

Total running time of the script: ( 0 minutes 1.412 seconds)

2.1.2 Running a Holospectrum

This tutorial shows how we can compute a holospectrum to characterise the distribution of power in a signal as afunction of both frequency of the carrier wave and the frequency of any amplitude modulations

Simulating and exploring amplitude modulations

First of all, we import EMD alongside numpy and matplotlib. We will also use scipy’s ndimage module to smooth ourresults for visualisation later.

# sphinx_gallery_thumbnail_number = 5

import matplotlib.pyplot as pltfrom scipy import ndimageimport numpy as npimport emd



First we create a simulated signal to analyse. This signal will be composed of a linear trend and two oscillations, eachwith a different amplitude modulation.

seconds = 60sample_rate = 200t = np.linspace(0, seconds, seconds*sample_rate)

# First we create a slow 4.25Hz oscillation with a 0.5Hz amplitude modulationslow = np.sin(2*np.pi*5*t) * (.5+(np.cos(2*np.pi*.5*t)/2))

# Second, we create a faster 37Hz oscillation that is amplitude modulated by the→˓first.fast = .5*np.sin(2*np.pi*37*t) * (slow+(.5+(np.cos(2*np.pi*.5*t)/2)))

# We create our signal by summing the oscillation and adding some noisex = slow+fast + np.random.randn(*t.shape)*.1

# Plot the first 5 seconds of dataplt.figure(figsize=(10, 2))plt.plot(t[:sample_rate*5], x[:sample_rate*5], 'k')

Out:

[<matplotlib.lines.Line2D object at 0x7f98b3cf02d0>]

Next we run a simple sift with a cubic spline interpolation and estimate the instantaneous frequency statistics from itusing the Normalised Hilbert Transform

config = emd.sift.get_config('mask_sift')config['max_imfs'] = 7config['mask_freqs'] = 50/sample_rateconfig['mask_amp_mode'] = 'ratio_sig'config['imf_opts/sd_thresh'] = 0.05imf = emd.sift.mask_sift(x, **config)IP, IF, IA = emd.spectra.frequency_stats(imf, sample_rate, 'nht')

# Visualise the IMFsemd.plotting.plot_imfs(imf[:sample_rate*5, :], cmap=True, scale_y=True)



Out:

{'mask_amp': 1, 'mask_amp_mode': 'ratio_imf', 'mask_freqs': 'zc', 'mask_step_factor':→˓2, 'mask_type': 'all', 'ret_mask_freq': False, 'max_imfs': 9, 'sift_thresh': 1e-08,→˓'imf_opts': {}, 'envelope_opts': {}}

The first IMF contains the 30Hz oscillation and the fourth captures the 8Hz oscillation. Their amplitude modula-tions are described in the IA (Instantaneous Amplitude) variable. We can visualise these, note that the amplitudemodulations (in red) are themselves oscillatory.

plt.figure(figsize=(10, 9))plt.subplot(211)plt.plot(t[:sample_rate*6], imf[:sample_rate*6, 0], 'k')plt.plot(t[:sample_rate*6], IA[:sample_rate*6, 0], 'r', linewidth=2)plt.legend(['IMF1', 'IMF1-Instantaneous Amplitude'], fontsize=14)plt.subplot(212)plt.plot(t[:sample_rate*6], imf[:sample_rate*6, 3], 'k')plt.plot(t[:sample_rate*6], IA[:sample_rate*6, 3], 'r', linewidth=2)plt.legend(['IMF4', 'IMF4-Instantaneous Amplitude'], fontsize=14)plt.xlabel('Time')



Out:

Text(0.5, 69.7222222222222, 'Time')

We can describe the frequency content of these amplitude modulation signal with another EMD. This is called a secondlevel sift which decomposes the instantaneous amplitude of each first level IMF with an additional set of IMFs.

# Helper function for the second level siftdef mask_sift_second_layer(IA, masks, config={}):

imf2 = np.zeros((IA.shape[0], IA.shape[1], config['max_imfs']))for ii in range(IA.shape[1]):

config['mask_freqs'] = masks[ii:]tmp = emd.sift.mask_sift(IA[:, ii], **config)imf2[:, ii, :tmp.shape[1]] = tmp

return imf2

# Define sift parameters for the second levelmasks = np.array([25/2**ii for ii in range(12)])/sample_rate





config = emd.sift.get_config('mask_sift')config['mask_amp_mode'] = 'ratio_sig'config['mask_amp'] = 2config['max_imfs'] = 5config['imf_opts/sd_thresh'] = 0.05config['envelope_opts/interp_method'] = 'mono_pchip'

# Sift the first 5 first level IMFsimf2 = mask_sift_second_layer(IA, masks, config=config)

Out:

{'mask_amp': 1, 'mask_amp_mode': 'ratio_imf', 'mask_freqs': 'zc', 'mask_step_factor':→˓2, 'mask_type': 'all', 'ret_mask_freq': False, 'max_imfs': 9, 'sift_thresh': 1e-08,→˓'imf_opts': {}, 'envelope_opts': {}}

We can see that the oscillatory content in the amplitude modulations has been described with ad additional set of IMFs.Here we plot the IMFs for the amplitude modulations of IMFs 1 (as plotted above).

emd.plotting.plot_imfs(imf2[:sample_rate*5, 0, :], scale_y=True, cmap=True)

We can compute the frequency stats for the second level IMFs using the same options as for the first levels.

IP2, IF2, IA2 = emd.spectra.frequency_stats(imf2, sample_rate, 'nht')



Finally, we want to visualise our results. We first define two sets of histogram bins, one for the main carrier frequencyoscillations and one for the amplitude modulations.

# Carrier frequency histogram definitionedges, bins = emd.spectra.define_hist_bins(1, 100, 128, 'log')# AM frequency histogram definitionedges2, bins2 = emd.spectra.define_hist_bins(1e-2, 32, 64, 'log')

# Compute the 1d Hilbert-Huang transform (power over carrier frequency)spec = emd.spectra.hilberthuang_1d(IF, IA, edges)

# Compute the 2d Hilbert-Huang transform (power over time x carrier frequency)hht = emd.spectra.hilberthuang(IF, IA, edges)shht = ndimage.gaussian_filter(hht, 2)

# Compute the 3d Holospectrum transform (power over time x carrier frequency x AM→˓frequency)# Here we return the time averaged Holospectrum (power over carrier frequency x AM→˓frequency)holo = emd.spectra.holospectrum(IF[:, :], IF2[:, :, :], IA2[:, :, :], edges, edges2)sholo = holo

We summarise the results with a four part figure: - top-left shows a segment of our original signal - top-right shows the1D Hilbert-Huang power spectrum - bottom-left shows a segment of the 2D Hilbert-Huang transform - bottom-rightshows the Holospectrum summed over the time dimension


# Plot a section of the time-courseplt.axes([.1, .55, .6, .4])plt.plot(t[:sample_rate*5], x[:sample_rate*5], 'k', linewidth=1)plt.xlim(0, 5)plt.ylim(-2.5, 2.5)

# Plot a section of the time-courseplt.axes([.75, .55, .225, .4])plt.plot(bins, spec)

# Plot a section of the Hilbert-Huang transformplt.axes([.1, .1, .6, .4])plt.pcolormesh(t[:sample_rate*5], bins, shht[:, :sample_rate*5], cmap='ocean_r')plt.yscale('log')

# Plot a the Holospectrumplt.axes([.75, .1, .225, .4])#plt.pcolormesh(bins2, bins, sholo.T, cmap='ocean_r')plt.contour(bins2, bins, np.sqrt(sholo.T), 48, cmap='ocean_r')plt.yscale('log')plt.xscale('log')plt.plot((bins2[0], bins2[-1]), (5, 5), 'grey', linewidth=.5)plt.plot((bins2[0], bins2[-1]), (37, 37), 'grey', linewidth=.5)plt.plot((.5, .5), (bins[0], bins[-1]), 'grey', linewidth=.5)plt.plot((5, 5), (bins[0], bins[-1]), 'grey', linewidth=.5)



Out:

/home/docs/checkouts/readthedocs.org/user_builds/emd/checkouts/v0.3.0/doc/source/→˓tutorials/plot_tutorial3.py:164: MatplotlibDeprecationWarning: shading='flat' when→˓X and Y have the same dimensions as C is deprecated since 3.3. Either specify the→˓corners of the quadrilaterals with X and Y, or pass shading='auto', 'nearest' or→˓'gouraud', or set rcParams['pcolor.shading']. This will become an error two minor→˓releases later.plt.pcolormesh(t[:sample_rate*5], bins, shht[:, :sample_rate*5], cmap='ocean_r')

[<matplotlib.lines.Line2D object at 0x7f98b3c31a50>]


2.1.3 Configuring the SIFT

Here we look at how to customise the different parts of the sift algorithm. There are many options which can becustomised from top level sift parameters all the way down to extrema detection.

Lets make a simulated signal to get started.

import emdimport numpy as npimport matplotlib.pyplot as plt

sample_rate = 1000seconds = 10num_samples = sample_rate*secondstime_vect = np.linspace(0, seconds, num_samples)freq = 5





# Change extent of deformation from sinusoidal shape [-1 to 1]nonlinearity_deg = .25

# Change left-right skew of deformation [-pi to pi]nonlinearity_phi = -np.pi/4

# Compute the signalx = emd.utils.abreu2010(freq, nonlinearity_deg, nonlinearity_phi, sample_rate,→˓seconds)x += np.cos(2*np.pi*1*time_vect)

The SiftConfig object

EMD can create a config dictionary which contains all the options that can be customised for a given sift function.This can be created using the get_config function in the sift submodule. Lets import emd and create the config for astandard sift - we can view the options by calling print on the config.

The SiftConfig dictionary contains all the arguments for functions that are used in the sift algorithm.

• “sift” contains arguments for the high level sift functions such as emd.sift.sift or emd.sift.ensemble_sift

• “imf” contains arguments for emd.sift.get_next_imf

• “envelope” contains arguments for emd.sift.interpolate_envelope

• “extrema”, “mag_pad” and “loc_pad” have arguments for extrema detection and padding

config = emd.sift.get_config('sift')print(config)

Out:

{'sift_thresh': 1e-08, 'max_imfs': None, 'imf_opts': {}, 'envelope_opts': {}}sift <class 'emd.sift.SiftConfig'>sift_thresh : 1e-08max_imfs : Noneimf_opts:

sd_thresh : 0.1env_step_size : 1

envelope_opts:interp_method : splrep

extrema_opts:pad_width : 2parabolic_extrema : Falsemag_pad_opts : {'mode': 'median', 'stat_length': 1}loc_pad_opts : {'mode': 'reflect', 'reflect_type': 'odd'}

These arguments are specific for the each type of sift (particularly at the top “sift” level).

config = emd.sift.get_config('ensemble_sift')print(config)

Out:



{'nensembles': 4, 'ensemble_noise': 0.2, 'noise_mode': 'single', 'nprocesses': 1,→˓'sift_thresh': 1e-08, 'max_imfs': None, 'imf_opts': {}, 'envelope_opts': {}}ensemble_sift <class 'emd.sift.SiftConfig'>nensembles : 4ensemble_noise : 0.2noise_mode : singlenprocesses : 1sift_thresh : 1e-08max_imfs : Noneimf_opts:


envelope_opts:interp_method : splrep


The SiftConfig dictionary contains arguments and default values for functions which are called internally within thedifferent sift implementations. The dictionary can be used to viewing and editing the options before they are passedinto the sift function.

The SiftConfig dictionary is nested, in that some items in the dictionary store further dictionaries of options. Thishierarchy of options reflects where the options are used in the sift process. The top-level of the dictionary containsarguments which may be passed directly to the sift functions, whilst options needed for internal function calls arestored in nested subdictionaries.

The parameters in the config can be changed in the same way we would change the key-value pairs in a nesteddictionary or using a h5py inspiried shorthand.

# This is a top-level argument used directly by ensemble_siftconfig['nensembles'] = 24

# This is a sub-arguemnt used by interp_envelope, which is called within# ensemble_sift.

# Standardconfig['envelope_opts']['interp_type'] = 'mono_pchip'# Shorthardconfig['envelope_opts/interp_type'] = 'mono_pchip'

print(config)

Out:

ensemble_sift <class 'emd.sift.SiftConfig'>nensembles : 24ensemble_noise : 0.2noise_mode : singlenprocesses : 1sift_thresh : 1e-08max_imfs : Noneimf_opts:






envelope_opts:interp_method : splrepinterp_type : mono_pchip


This nested structure is passed as an unpacked dictionary to our sift function.

config = emd.sift.get_config('sift')imf = emd.sift.sift(x, **config)

Out:

{'sift_thresh': 1e-08, 'max_imfs': None, 'imf_opts': {}, 'envelope_opts': {}}

Extrema detection and padding

The options are split into six types. Starting from the lowest level, extrema detection and padding in emd is imple-mented in the emd.sift.find_extrema function. This is a simple function which identifies extrema using thescipy.signal argrelmin and argrelmax functions.

max_locs, max_mag = emd.sift.find_extrema(x)min_locs, min_mag = emd.sift.find_extrema(x, ret_min=True)

plt.figure(figsize=(12, 3))plt.plot(x, 'k')plt.plot(max_locs, max_mag, 'or')plt.plot(min_locs, min_mag, 'ob')plt.legend(['Signal', 'Maxima', 'Minima'])

Out:

<matplotlib.legend.Legend object at 0x7f98b3d446d0>

Extrema padding is used to stablise the envelope at the edges of the time-series. The emd.sift.get_padded_extrema function identifies and pads extrema in a time-series. This calls the emd.sift.find_extrema internally.

max_locs, max_mag = emd.sift.get_padded_extrema(x)min_locs, min_mag = emd.sift.get_padded_extrema(-x)





min_mag = -min_mag

plt.figure(figsize=(12, 3))plt.plot(x, 'k')plt.plot(max_locs, max_mag, 'or')plt.plot(min_locs, min_mag, 'ob')plt.legend(['Signal', 'Maxima', 'Minima'])

Out:

<matplotlib.legend.Legend object at 0x7f98b3c0fed0>

The extrema detection and padding arguments are specified in the config dict under the extrema, mag_pad and loc_padkeywords. These are passed directly into emd.sift.get_padded_extrema when running the sift.

The padding is controlled by a build in numpy function np.pad. The mag_pad and loc_pad dictionaries arepassed into np.pad to define the padding in the y-axis (extrema magnitude) and x-axis (extrema time-point) respec-tively. Note that np.pad takes a mode as a positional orgument - this must be included as a keyword argumenthere.

Lets try customising the extrema padding. First we get the ‘extrema’ options from a nested config then try changing acouple of options

ext_opts = config['extrema_opts']

# The default optionsmax_locs, max_mag = emd.sift.get_padded_extrema(x, **ext_opts)min_locs, min_mag = emd.sift.get_padded_extrema(-x, **ext_opts)min_mag = -min_mag


plt.subplot(311)plt.plot(x, 'k')plt.plot(max_locs, max_mag, 'or')plt.plot(min_locs, min_mag, 'ob')plt.legend(['Signal', 'Maxima', 'Minima'])plt.title('Default')

# Increase the pad width to 5 extremaext_opts['pad_width'] = 5max_locs, max_mag = emd.sift.get_padded_extrema(x, **ext_opts)min_locs, min_mag = emd.sift.get_padded_extrema(-x, **ext_opts)min_mag = -min_mag





plt.subplot(312)plt.plot(x, 'k')plt.plot(max_locs, max_mag, 'or')plt.plot(min_locs, min_mag, 'ob')plt.legend(['Signal', 'Maxima', 'Minima'])plt.title('Increased pad width')

# Change the y-axis padding to 'reflect' rather than 'median'ext_opts['mag_pad_opts']['mode'] = 'reflect'del ext_opts['mag_pad_opts']['stat_length']max_locs, max_mag = emd.sift.get_padded_extrema(x, **ext_opts)min_locs, min_mag = emd.sift.get_padded_extrema(-x, **ext_opts)min_mag = -min_mag

plt.subplot(313)plt.plot(x, 'k')plt.plot(max_locs, max_mag, 'or')plt.plot(min_locs, min_mag, 'ob')plt.legend(['Signal', 'Maxima', 'Minima'])plt.title('Reflected extrema and increased pad width')



Out:

Text(0.5, 1.0, 'Reflected extrema and increased pad width')

Envelope interpolation

Once extrema have been detected the maxima and minima are interpolated to create an upper and lower envelope.This interpolation is performed with emd.sift.interp_envlope and the options in the envelope section ofthe config.

This interpolation starts with the padded extrema from the previous section so we will take the envelope and extremaoptions from the config object



env_opts = config['envelope_opts']

upper_env = emd.utils.interp_envelope(x, mode='upper', **env_opts)lower_env = emd.utils.interp_envelope(x, mode='lower', **env_opts)avg_env = (upper_env+lower_env) / 2

plt.figure(figsize=(12, 6))plt.subplot(211)plt.plot(x, 'k')plt.plot(upper_env, 'r')plt.plot(lower_env, 'b')plt.plot(avg_env, 'g')plt.legend(['Signal', 'Maxima', 'Upper Envelope', 'Minima', 'Lower Envelope'])

# Plot the signal with the average of the upper and lower envelopes subtracted.plt.subplot(212)plt.plot(x-avg_env, 'k')plt.legend(['Signal-Average Envelope'])

Out:

<matplotlib.legend.Legend object at 0x7f98b39444d0>

IMF Extraction

The next layer is IMF extraction as implemented in emd.sift.get_next_imf. This uses the envelope inter-polation and extrema detection to carry out the sifting iterations on a time-series to return a single intrinsic modefunction.

This is the main function used when implementing novel types of sift. For instance, the ensemble sift uses this emd.sift.get_next_imf to extract IMFs from many repetitions of the signal with small amounts of noise added.Similarly the mask sift calls emd.sift.get_next_imf after adding a mask signal to the data.

Here we use get_next_imf to implement a very simple sift. We extract the first IMF, subtract it from the data andthen extract the second IMF. We then plot the original signal, the two IMFs and the residual.



# Adjust the threshold for accepting an IMFconfig['imf_opts/sd_thresh'] = 0.05# Extract the options for get_next_imfimf_opts = config['imf_opts']

imf1, continue_sift = emd.sift.get_next_imf(x[:, None], **imf_opts)print(imf1.shape)imf2, continue_sift = emd.sift.get_next_imf(x[:, None]-imf1, **imf_opts)

plt.figure(figsize=(12, 12))plt.subplot(411)plt.plot(x, 'k')plt.ylim(-3, 3)plt.title('Original Signal')

plt.subplot(412)plt.plot(imf1, 'k')plt.ylim(-3, 3)plt.title('IMF1')

plt.subplot(413)plt.plot(imf2, 'k')plt.ylim(-3, 3)plt.title('IMF2')

plt.subplot(414)plt.plot(x[:, None]-imf1-imf2, 'k')plt.ylim(-3, 3)plt.title('Residual')



Out:

(10000, 1)

Text(0.5, 1.0, 'Residual')

Sifting

Finally, the top-level of options configure the sift itself. These options vary between the type of sift that is beingperformed and many options don’t generalise between different variants of the sift.

Here we use the config object to perform a simple sift very similar to the one we implemented in the previous section.



config = emd.sift.get_config('sift')

imf = emd.sift.sift(x, **config)

emd.plotting.plot_imfs(imf, cmap=True, scale_y=True)

Out:

{'sift_thresh': 1e-08, 'max_imfs': None, 'imf_opts': {}, 'envelope_opts': {}}


2.2 Module reference

2.2.1 SIFT Functions

emd.sift.sift(X, sift_thresh=1e-08, max_imfs=None, imf_opts={}, envelope_opts={}, ex-trema_opts={})

Compute Intrinsic Mode Functions from an input data vector using the original sift algorithm [1].

Parameters

X [ndarray] 1D input array containing the time-series data to be decomposed

2.2. Module reference 25


sift_thresh [scalar] The threshold at which the overall sifting process will stop. (Default value= 1e-8)

max_imfs [int] The maximum number of IMFs to compute. (Default value = None)

Returns

imf: ndarray 2D array [samples x nimfs] containing he Intrisic Mode Functions from the de-composition of X.

Other Parameters

imf_opts [dict] Optional dictionary of keyword options to be passed to emd.get_next_imf

envelope_opts [dict] Optional dictionary of keyword options to be passed toemd.interp_envelope

extrema_opts [dict] Optional dictionary of keyword options to be passed toemd.get_padded_extrema

See also:

emd.sift.get_next_imf

References

[1]

emd.sift.ensemble_sift(X, nensembles=4, ensemble_noise=0.2, noise_mode=’single’, npro-cesses=1, sift_thresh=1e-08, max_imfs=None, imf_opts={}, enve-lope_opts={}, extrema_opts={})

Compute Intrinsic Mode Functions from an input data vector using the ensemble empirical model decompositionalgorithm [1]. This approach sifts an ensemble of signals with white-noise added and treats the mean IMFs asthe result.

The resulting IMFs from the ensemble sift resembles a dyadic filter [2].

Parameters


nensembles [int] Integer number of different ensembles to compute the sift across.

ensemble_noise [scalar] Standard deviation of noise to add to each ensemble (Default value =.2)

noise_mode [{‘single’,’flip’}] Flag indicating whether to compute each ensemble with noiseonce or twice with the noise and sign-flipped noise (Default value = ‘single’)

nprocesses [integer] Integer number of parallel processes to compute. Each process computesa single realisation of the total ensemble (Default value = 1)



Returns

imf [ndarray] 2D array [samples x nimfs] containing he Intrisic Mode Functions from the de-composition of X.

Other Parameters



imf_opts [dict] Optional dictionary of keyword options to be passed to emd.get_next_imf.



See also:


References

[1], [2]

emd.sift.complete_ensemble_sift(X, nensembles=4, ensemble_noise=0.2, noise_mode=’single’,nprocesses=1, sift_thresh=1e-08, max_imfs=None,imf_opts={}, envelope_opts={}, extrema_opts={})

Compute Intrinsic Mode Functions from an input data vector using the complete ensemble empirical modeldecomposition algorithm [1]. This approach sifts an ensemble of signals with white-noise added taking a singleIMF across all ensembles at before moving to the next IMF.

Parameters


nensembles [int] Integer number of different ensembles to compute the sift across.

ensemble_noise [scalar] Standard deviation of noise to add to each ensemble (Default value =.2)

noise_mode [{‘single’,’flip’}] Flag indicating whether to compute each ensemble with noiseonce or twice with the noise and sign-flipped noise (Default value = ‘single’)

nprocesses [integer] Integer number of parallel processes to compute. Each process computesa single realisation of the total ensemble (Default value = 1)



Returns

imf: ndarray 2D array [samples x nimfs] containing he Intrisic Mode Functions from the de-composition of X.

noise: array_like The Intrisic Mode Functions from the decomposition of X.

Other Parameters

imf_opts [dict] Optional dictionary of keyword options to be passed to emd.get_next_imf.



See also:




References

[1]

emd.sift.mask_sift_adaptive(X, sift_thresh=1e-08, max_imfs=None, mask_amp=1,mask_amp_mode=’ratio_imf’, mask_step_factor=2,ret_mask_freq=False, first_mask_mode=’if’, imf_opts={}, enve-lope_opts={}, extrema_opts={})

Compute Intrinsic Mode Functions from a dataset using a set of masking signals to reduce mixing of componentsbetween modes.

The simplest masking signal approach uses single mask for each IMF after the first is computed as normal [1].This has since been expanded to the complete mask sift which uses a set of positive and negative sign sine andcosine signals as masks for each IMF. The mean of the four is taken as the IMF.

Parameters


sd_thresh [scalar] The threshold at which the sift of each IMF will be stopped. (Default value= .1)



mask_amp [scalar or array_like] Amplitude of mask signals as specified by mask_amp_mode.If scalar the same value is applied to all IMFs, if an array is passed each value is applied toeach IMF in turn (Default value = 1)

mask_amp_mode [{‘abs’,’imf_ratio’,’sig_ratio’}] Method for computing mask amplitude. Ei-ther in absolute units (‘abs’), or as a ratio of the amplitude of the input signal (‘ratio_signal’)or previous imf (‘ratio_imf’) (Default value = ‘ratio_imf’)

mask_step_factor [scalar] Step in frequency between successive masks (Default value = 2)

ret_mask_freq [bool] Boolean flag indicating whether mask frequencies are returned (Defaultvalue = False)

mask_initial_freq [scalar] Frequency of initial mask as a proportion of the sampling frequency(Default value = None)

interp_method [{‘mono_pchip’,’splrep’,’pchip’}] The interpolation method used when com-puting upper and lower envelopes (Default value = ‘mono_pchip’)

Returns


mask_freqs [ndarray] 1D array of mask frequencies, if ret_mask_freq is set to True.

Other Parameters

imf_opts [dict] Optional dictionary of keyword arguments to be passed to emd.get_next_imf





References

[1]

emd.sift.mask_sift_specified(X, sd_thresh=0.1, max_imfs=None, mask_amp=1,mask_amp_mode=’ratio_imf’, mask_step_factor=2,ret_mask_freq=False, mask_initial_freq=None, mask_freqs=None,mask_amps=None, imf_opts={}, envelope_opts={}, ex-trema_opts={})

Compute Intrinsic Mode Functions from a dataset using a set of masking signals to reduce mixing of componentsbetween modes.

The simplest masking signal approach uses single mask for each IMF after the first is computed as normal [1].This has since been expanded to the complete mask sift which uses a set of positive and negative sign sine andcosine signals as masks for each IMF. The mean of the four is taken as the IMF.

Parameters





mask_amp [scalar or array_like] Amplitude of mask signals as specified by mask_amp_mode.If scalar the same value is applied to all IMFs, if an array is passed each value is applied toeach IMF in turn (Default value = 1)

mask_amp_mode [{‘abs’,’imf_ratio’,’sig_ratio’}] Method for computing mask amplitude. Ei-ther in absolute units (‘abs’), or as a ratio of the amplitude of the input signal (‘ratio_signal’)or previous imf (‘ratio_imf’) (Default value = ‘ratio_imf’)

mask_step_factor [scalar] Step in frequency between successive masks (Default value = 2)

ret_mask_freq [bool] Boolean flag indicating whether mask frequencies are returned (Defaultvalue = False)

mask_initial_freq [scalar] Frequency of initial mask as a proportion of the sampling frequency(Default value = None)

mask_freqs [array_like] 1D array, list or tuple of mask frequencies as a proportion of the sam-pling frequency (Default value = None)

interp_method [{‘mono_pchip’,’splrep’,’pchip’}] The interpolation method used when com-puting upper and lower envelopes (Default value = ‘mono_pchip’)

Returns


mask_freqs [ndarray] 1D array of mask frequencies, if ret_mask_freq is set to True.

Other Parameters






References

[1]

emd.sift.get_next_imf(X, sd_thresh=0.1, env_step_size=1, envelope_opts={}, extrema_opts={})Compute the next IMF from a data set. This is a helper function used within the more general sifting functions.

Parameters

X [ndarray [nsamples x 1]] 1D input array containing the time-series data to be decomposed


env_step_size [float] Scaling of envelope prior to removal at each iteration of sift. The averageof the upper and lower envelope is muliplied by this value before being subtracted from thedata. Values should be between 0 > x >= 1 (Default value = 1)

Returns

proto_imf [ndarray] 1D vector containing the next IMF extracted from X

continue_flag [bool] Boolean indicating whether the sift can be continued beyond this IMF

Other Parameters

envelope_opts [dict] Optional dictionary of keyword arguments to be passed toemd.interp_envelope


See also:

emd.sift.sift

emd.sift.interp_envelope

emd.sift.get_next_imf_mask(X, z, amp, mask_type=’all’, imf_opts={}, envelope_opts={}, ex-trema_opts={})

Compute the next IMF from a data set using the mask sift appraoch. This is a helper function used within themore general sifting functions.

Parameters


z [scalar] Mask frequency as a proportion of the sampling rate, values between 0->z->.5

amp [scalar] Mask amplitude

mask_type [{‘all’,’sine’,’cosine’}] Flag indicating whether to apply sine, cosine or all masks(Default value = ‘all’)

Returns

proto_imf [ndarray] 1D vector containing the next IMF extracted from X

Other Parameters






See also:

emd.sift.mask_sift


2.2.2 Frequency Functions

emd.spectra.frequency_stats(imf, sample_rate, method, smooth_phase=31)Compute instantaneous phase, frequency and amplitude from a set of IMFs. Several approaches are imple-mented from [1] and [2].

Parameters

imf [ndarray] Input array of IMFs.

sample_rate [scalar] Sampling frequency of the signal in Hz

method [{‘hilbert’,’quad’,’direct_quad’,’nht’}] The method for computing the frequency stats

smooth_phase [integer] Length of window when smoothing the unwrapped phase (Defaultvalue = 31)

Returns

IP [ndarray] Array of instantaneous phase estimates

IF [ndarray] Array of instantaneous frequency estimates

IA [ndarray] Array of instantaneous amplitude estimates

References

[1], [2]

emd.spectra.quadrature_transform(X)Compute the quadrature transform on a set of time-series as defined in equation 34 of [1]. The return is acomplex array with the input data as the real part and the quadrature transform as the imaginary part.

Parameters

X [ndarray] Array containing time-series to transform

Returns

quad_signal [ndarray] Complex valued array containing the quadrature transformed signal

References

[1]

emd.spectra.phase_from_complex_signal(complex_signal, smoothing=None,ret_phase=’wrapped’, phase_jump=’ascending’)

Compute the instantaneous phase from a complex signal obtained from either the Hilbert Transform or by DirectQuadrature.



Parameters

complex_signal [complex ndarray] Complex valued input array

smoothing [int] Integer window length used in phase smoothing (Default value = None)

ret_phase [{‘wrapped’,’unwrapped’}] Flag indicating whether to return the wrapped or un-wrapped phase (Default value = ‘wrapped’)

phase_jump [{‘ascending’,’peak’,’descending’,’trough’}] Flag indicating where in the cyclethe phase jump should be (Default value = ‘ascending’)

Returns

IP [ndarray] Array of instantaneous phase values

emd.spectra.freq_from_phase(iphase, sample_rate)Compute the instantaneous frequency from the differential of the instantaneous phase.

Parameters

iphase [ndarray] Input array containing the unwrapped instantaneous phase time-course

sample_rate [scalar] The sampling frequency of the data

Returns

IF [ndarray] Array containing the instantaneous frequencies

emd.spectra.phase_from_freq(ifrequency, sample_rate, phase_start=-3.141592653589793)Compute the instantaneous phase of a signal from its instantaneous phase.

Parameters

ifrequency [ndarray] Input array containing the instantaneous frequencies of a signal

sample_rate [scalar] The sampling frequency of the data

phase_start [scalar] Start value of the phase output (Default value = -np.pi)

Returns

IP [ndarray] The instantaneous phase of the signal

emd.spectra.direct_quadrature(fm)Section 3.2 of ‘on instantaneous frequency’ Compute the quadrature transform on a set of time-series as definedin equation 35 of [1].

THIS IS IN DEVELOPMENT

Parameters

fm :

References

[1]

emd.spectra.phase_angle(fm)Compute the quadrature transform on a set of time-series as defined in equation 35 of [1].

THIS IS IN DEVELOPMENT

Parameters

X [ndarray] Array containing time-series to transform



Returns

quad_signal [ndarray] Complex valued array containing the quadrature transformed signal

References

[1]

2.2.3 Spectrum Functions

emd.spectra.hilberthuang_1d(infr, inam, freq_edges, mode=’energy’)Compute the Hilbert-Huang transform from the instataneous frequency statistics of a dataset. The 1D Hilbert-Huang Transform represents the energy in a signal across frequencies and IMFs [1].

Parameters

infr [ndarray] 2D first level instantaneous frequencies

inam [ndarray] 2D first level instantaneous amplitudes

freq_edges [ndarray] Vector of frequency bins for carrier frequencies

mode [{‘energy’,’amplitude’}] Flag indicating whether to sum the energy or amplitudes (De-fault value = ‘energy’)

Returns

specs [ndarray] 2D array containing Hilbert-Huang Spectrum [ frequencies x imfs ]

References

[1]

emd.spectra.hilberthuang(infr, inam, freq_edges, mode=’energy’, return_sparse=False)Compute the Hilbert-Huang transform from the instataneous frequency statistics of a dataset. The Hilbert-HuangTransform represents the energy of a signal across time and frequency [1].

Parameters


inam [ndarray] 2D first level instantaneous amplitudes



return_sparse [bool] Flag indicating whether to return the full or sparse form(Default value =True)

Returns

hht [ndarray] 2D array containing the Hilbert-Huang Transform

Notes

If return_sparse is set to True the returned array is a sparse matrix in COOrdinate form (scipy.sparse.coo_matrix),also known as ‘ijv’ or ‘triplet’ form. This is much more memory efficient than the full form but may not behaveas expected in functions expecting full arrays.



References

[1]

emd.spectra.holospectrum(infr, infr2, inam2, freq_edges, freq_edges2, mode=’energy’,squash_time=’sum’)

Compute the Holospectrum from the first and second layer frequecy statistics of a dataset. The Holospectrumrepresents the energy of a signal across time, carrier frequency and amplitude-modulation frequency [1].

Parameters


infr2 [ndarray] 3D second level instantaneous frequencies

inam2 [ndarray] 3D second level instantaneous amplitudes


freq_edges2 : Vector of frequency bins for amplitude-modulation frequencies


squash_time [{‘sum’,’mean’,False}] Flag indicating whether to marginalise over the time di-mension (Default value = ‘sum’)

Returns

holo [ndarray] Holospectrum of input data.

Notes

Output will be a 3D [samples x am_freq x carrier_freq] array if squash_time is False and a 2D [ am_freq xcarrier_freq ] array if squash_time is true.

References

[1]

2.2.4 Spectrum Utils

emd.spectra.define_hist_bins(data_min, data_max, nbins, scale=’linear’)Define the bin edges and centre values for use in a histogram

Parameters

data_min [scalar] Value for minimum edge

data_max [scalar] Value for maximum edge

nbins [integer] Number of bins to create

scale [{‘linear’,’log’}] Flag indicating whether to use a linear or log spacing between bins (De-fault value = ‘linear’)

Returns

edges [ndarray] 1D array of bin edges

centres [ndarray] 1D array of bin centres



Notes

>> edges,centres = emd.spectra.define_hist_bins( 1, 5, 3 )

>> print(edges)

[1. 2. 3. 4. 5.]

>> print(centres)

[1.5 2.5 3.5 4.5]

emd.spectra.define_hist_bins_from_data(X, nbins=None, mode=’sqrt’, scale=’linear’)Find the bin edges and centre frequencies for use in a histogram

if nbins is defined, mode is ignored

Parameters

X [ndarray] Dataset whose summary stats will define the histogram

nbins [int] Number of bins to create, if undefined this is derived from the data (Default value =None)

mode [{‘sqrt’}] Method for deriving number of bins if nbins is undefined (Default value =‘sqrt’)

scale [{‘linear’,’log’}] (Default value = ‘linear’)

Returns

edges [ndarray] 1D array of bin edges

centres [ndarray] 1D array of bin centres


CHAPTER 3

Indices and tables

• genindex

• modindex

• search

37


38 Chapter 3. Indices and tables

Bibliography

[1] Huang, N. E., Shen, Z., Long, S. R., Wu, M. C., Shih, H. H., Zheng, Q., . . . Liu, H. H. (1998). The empiricalmode decomposition and the Hilbert spectrum for nonlinear and non-stationary time series analysis. Proceedingsof the Royal Society of London. Series A: Mathematical, Physical and Engineering Sciences, 454(1971), 903–995.https://doi.org/10.1098/rspa.1998.0193

[1] Wu, Z., & Huang, N. E. (2009). Ensemble Empirical Mode Decomposition: A Noise-Assisted Data AnalysisMethod. Advances in Adaptive Data Analysis, 1(1), 1–41. https://doi.org/10.1142/s1793536909000047

[2] Wu, Z., & Huang, N. E. (2004). A study of the characteristics of white noise using the empirical mode decom-position method. Proceedings of the Royal Society of London. Series A: Mathematical, Physical and EngineeringSciences, 460(2046), 1597–1611. https://doi.org/10.1098/rspa.2003.1221

[1] Torres, M. E., Colominas, M. A., Schlotthauer, G., & Flandrin, P. (2011). A complete ensemble empirical modedecomposition with adaptive noise. In 2011 IEEE International Conference on Acoustics, Speech and SignalProcessing (ICASSP). IEEE. https://doi.org/10.1109/icassp.2011.5947265

[1] Ryan Deering, & James F. Kaiser. (2005). The Use of a Masking Signal to Improve Empirical Mode Decomposi-tion. In Proceedings. (ICASSP ’05). IEEE International Conference on Acoustics, Speech, and Signal Processing,2005. IEEE. https://doi.org/10.1109/icassp.2005.1416051

[1] Ryan Deering, & James F. Kaiser. (2005). The Use of a Masking Signal to Improve Empirical Mode Decomposi-tion. In Proceedings. (ICASSP ’05). IEEE International Conference on Acoustics, Speech, and Signal Processing,2005. IEEE. https://doi.org/10.1109/icassp.2005.1416051


[2] Huang, N. E., Wu, Z., Long, S. R., Arnold, K. C., Chen, X., & Blank, K. (2009). On Instantaneous Frequency.Advances in Adaptive Data Analysis, 1(2), 177–229. https://doi.org/10.1142/s1793536909000096




39

https://doi.org/10.1098/rspa.1998.0193

https://doi.org/10.1142/s1793536909000047


https://doi.org/10.1109/icassp.2011.5947265




https://doi.org/10.1142/s1793536909000096

https://doi.org/10.1142/s1793536909000096

https://doi.org/10.1142/s1793536909000096

https://doi.org/10.1142/s1793536909000096




[1] Huang, N. E., Hu, K., Yang, A. C. C., Chang, H.-C., Jia, D., Liang, W.-K., . . . Wu, Z. (2016). On Holo-Hilbertspectral analysis: a full informational spectral representation for nonlinear and non-stationary data. PhilosophicalTransactions of the Royal Society A: Mathematical, Physical and Engineering Sciences, 374(2065), 20150206.https://doi.org/10.1098/rsta.2015.0206

40 Bibliography



https://doi.org/10.1098/rsta.2015.0206

Index

Ccomplete_ensemble_sift() (in module emd.sift),

27

Ddefine_hist_bins() (in module emd.spectra), 34define_hist_bins_from_data() (in module

emd.spectra), 35direct_quadrature() (in module emd.spectra), 32

Eensemble_sift() (in module emd.sift), 26

Ffreq_from_phase() (in module emd.spectra), 32frequency_stats() (in module emd.spectra), 31

Gget_next_imf() (in module emd.sift), 30get_next_imf_mask() (in module emd.sift), 30

Hhilberthuang() (in module emd.spectra), 33hilberthuang_1d() (in module emd.spectra), 33holospectrum() (in module emd.spectra), 34

Mmask_sift_adaptive() (in module emd.sift), 28mask_sift_specified() (in module emd.sift), 29

Pphase_angle() (in module emd.spectra), 32phase_from_complex_signal() (in module

emd.spectra), 31phase_from_freq() (in module emd.spectra), 32

Qquadrature_transform() (in module

emd.spectra), 31

Ssift() (in module emd.sift), 25

41

emd Documentation

Documents

Transcript of emd Documentation