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)[source]#
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