emd.spectra.holospectrum

emd.spectra.holospectrum(IF, IF2, IA2, edges=None, edges2=None, sum_time=True, sum_first_imfs=True, sum_second_imfs=True, mode='power', sample_rate=1, scaling=None, return_sparse=False, return_Gb_limit=10)

Compute a Holospectrum.

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

The full Holospctrum is a 5-dimensional array: [nfrequencise x namplitude_frequencies x time x first_imfs x second_imfs] By default, the returned holospectrum is summed across time and IMFs, returning only the first two dimensions - this behaviour can be tuned with the sum_time, sum_first_imfs and sum_second_imfs arguments.

WARNING: returning the full Holospectrum can create some enormous arrays! Setting return_sparse=True is VERY strongly recommended if you want to work with the raw time and IMF dimensions.

Parameters:

IFndarray

2D first level instantaneous frequencies

IF2ndarray

3D second level instantaneous frequencies

IA2ndarray

3D second level instantaneous amplitudes

edges{ndarray, tuple or None}

Definition of the frequency bins used for carrier frequencies 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)

edges2{ndarray, tuple or None}

Definition of the frequency bins used for amplitude modulation frequencies in the spectrum. The options are the same as for edges.

sum_timeboolean

Flag indicating whether to sum across time dimension

sum_first_imfsboolean

Flag indicating whether to sum across first-layer IMF dimension

sum_second_imfsboolean

Flag indicating whether to sum across the second-layer IMF dimension

mode{‘power’,’amplitude’}

Flag indicating whether to sum the power or amplitude (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_sparseboolean

Flag indicating whether to return a sparse or dense (normal numpy) array.

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:

f_carrierndarray

Vector of histogram bin centers for each carrier (first-level) frequency

f_amndarray

Vector of histogram bin centers for each amplitude modulation (second-level) frequency

holondarray

Holospectrum of input data.

Notes

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

>>> fcarrier, fam, holo = emd.spectra.holospectrum(IF, IA, sample_rate=512)

Run a Holospectrum and return the spectrum for each first and second level IMF separately

>>> fcarrier, fam, holo = emd.spectra.holospectrum(IF, IA, sample_rate=512,
>>>                                                sum_first_imfs=False, sum_second_imfs=False)

Run a Holospectrum with 49 carrier frequency bins linearly spaced between 1 and 50Hz and 32 amplitude modulation frequency bins logarithmicly spaced between 0.1 and 20Hz

>>> fcarrier, fam, holo = emd.spectra.holospectrum(IF, IA, sample_rate=512,
>>>                                                edges=(1, 50, 49),
>>>                                                edges2=(0.1, 20, 32, 'log'))

Run a Holospectrum without summing over the time dimensions and return the result in a memory efficient sparse array - this is strongly recommended for very large HHTs

>>> fcarrier, fam, holo = emd.spectra.holospectrum(IF, IA, sample_rate=512,
>>>                                                edges=(1, 50, 49),
>>>                                                edges2=(0.1, 20, 32, 'log',
>>>                                                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., Hu, K., Yang, A. C. C., Chang, H.-C., Jia, D., Liang, W.-K., … Wu, Z. (2016). On Holo-Hilbert spectral analysis: a full informational spectral representation for nonlinear and non-stationary data. Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences, 374(2065), 20150206. https://doi.org/10.1098/rsta.2015.0206