emd.spectra.hilberthuang#

emd.spectra.hilberthuang(IF, IA, edges=None, sum_time=True, sum_imfs=True, mode='power', sample_rate=1, scaling=None, return_sparse=False, return_Gb_limit=10)[source]#

Compute a Hilbert-Huang transform (HHT).

The Hilbert-Huang transform takes the instataneous frequency and instantaneous amplitude of a time-series and represents the energy of a signal across time and frequency [1].

The full Hilbert-Huang array is 3-dimensional [nfrequencies x ntimes x nimfs]. By default, the returned holospectrum is summed across time and IMFs, returning only the frequency dimension.- this behaviour can be tuned with the sum_time and sum_imfs arguments. Setting return_sparse to True is strongly recommended returning very large arrays.

Parameters:
IFndarray

2D first level instantaneous frequencies

IAndarray

2D first level instantaneous amplitudes

edges{ndarray, tuple or None}

Definition of the frequency bins used in the spectrum. This may be:

  • array_like vector of bin edge values (as defined by

emd.spectra.define_hist_bins)

  • a tuple of values that can be passed to emd.spectra.define_hist_bins

(eg edges=(1,50,49) will define 49 bins between 1 and 50Hz)

  • None in which case a sensible set of bins will be defined from the

input data (this is the default option)

sum_timeboolean

Flag indicating whether to sum across time dimension

sum_imfsboolean

Flag indicating whether to sum across IMF dimension

mode{‘power’,’amplitude’}

Flag indicating whether to sum the power or amplitudes (Default value = ‘power’)

scaling{‘density’, ‘spectrum’, None}

Switch specifying the normalisation or scaling applied to the spectrum.

sample_ratefloat

Sampling rate of the data used in ‘density’ scaling

return_sparsebool

Flag indicating whether to return the full or sparse form(Default value = False)

return_Gb_limit{float, None}

Maximum array size in Gb that will be returned if a non-sparse/dense array is being returned (default = 10). If the function return would exceed this size, the function will raise an error. If set to None, then no limit is imposed. Sparse arrays are always returned.

Returns:
fndarray

Vector of histogram bin centers for each frequency

hhtndarray

2D array containing the Hilbert-Huang Transform

Notes

Run a HHT with an automatically generated set of histogram bins:

>>> f, hht = emd.spectra.hilberthuang(IF, IA, sample_rate=512)

Run a HHT and return the spectrum for each IMF separately

>>> f, hht = emd.spectra.hilberthuang(IF, IA,, sample_rate=512, sum_imfs=False)

Run a HHT with 49 bins, linearly spaced between 1 and 50Hz

>>> f, hht = emd.spectra.hilberthuang(IF, IA, edges=(1, 50, 49), sample_rate=512)

Run a HHT with 49 bins, logarithmically spaced between 0.001 and 50Hz

>>> f, hht = emd.spectra.hilberthuang(IF, IA, edges=(1, 50, 49, 'log'), sample_rate=512)

Run a HHT with an externally generated set of histogram bin edges

>>> my_edges = np.array([0.5, 2, 5, 11, 22])
>>> f, hht = emd.spectra.hilberthuang(IF, IA, edges=my_edges sample_rate=512)

Run a HHT and return the full time dimension - the HHT is summed over time by default

>>> f, hht = emd.spectra.hilberthuang(IF, IA, edges=(1, 50, 49), sample_rate=512, sum_time=False)

Run a HHT and return a memory efficient sparse array - this is strongly recommended for very large HHTs

>>> f, hht = emd.spectra.hilberthuang(IF, IA, edges=(1, 50, 49), sample_rate=512,
>>>                                   sum_time=False, return_sparse=True)

If return_sparse is set to True the returned array is a sparse matrix in COOrdinate form using sparse package (sparse.COO). This is much more memory efficient than the full form but may not behave as expected in all functions expecting full arrays.

References

[1]

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