HHGramImage: Display Hilbert spectrogram

In hht: The Hilbert-Huang Transform: Tools and Methods

Display Hilbert spectrogram

Description

This function displays the Hilbert spectrogram of EMD and EEMD results.

Usage

HHGramImage(hgram, time.span = NULL, freq.span = NULL, amp.span = NULL, 
    clustergram = FALSE, cluster.span = NULL, imf.list = NULL, 
    fit.line = FALSE, scaling = "none", grid = TRUE, colorbar = TRUE, 
    backcol = c(0, 0, 0), colormap = NULL, pretty = FALSE, ...)

Arguments

hgram	Data structure generated by HHRender.
time.span	Time span to render spectrogram over. NULL will draw the spectrogram over the entire signal.
freq.span	Frequency span to render spectrogram over. NULL plots everything up to the max frequency set when HHRender was run.
amp.span	This is the amplitude span to plot, everything below is set to backcol, everything above is set to max color, NULL scales to the range in the signal.
clustergram	If TRUE, plot the number of times data occupies a given pixel instead of plotting the signal amplitude. This is akin to the weight component returned by the as.image function in the fields package. Only applies when using EEMD. Default is FALSE.
cluster.span	Plots only parts of the signal that have a certain number of data points per pixel (see notes below). This only applies when using EEMD. The pixel range is defined as c(AT LEAST, AT MOST).
imf.list	A vector of IMFs to plot on the spectrogram, the others will not be shown. You must set combine.imfs = FALSE in HHRender for this to work correctly.
fit.line	If TRUE, plot a red line on the trace that shows the part of the signal represented by the spectrogram

.

scaling	determines whether to apply a logarithmic ("log"), or square root ("sqrt") scaling to the amplitude data, default is "none"
grid	Boolean - whether to display grid lines or not
colorbar	Boolean - whether to display amplitude colorbar or not
backcol	What background color to use behind the spectrogram, in a 3 element vector: c(red, green, blue)
colormap	What palette object to use for the spectrogram, defaults to rainbow
pretty	Boolean - to choose nice axes values or to use exactly the ranges given
...	This function supports some optional parameters as well: trace.format - the format of the trace minima and maxima in sprintf format img.x.format - the format of the X axis labels of the image in sprintf format img.y.format - the format of the Y axis labels of the image in sprintf format colorbar.format - the format of the colorbar labels in sprintf format cex.lab - the font size of the image axis labels cex.colorbar - the font size of the colorbar cex.trace - the font size of the trace axis labels img.x.lab - the X - axis label of the image, it defaults to "time" img.y.lab - the Y - axis label of the image, it defaults to "frequency" main - adds a title to the figure

Details

This function plots the image generated by HHRender along with the original signal trace. The plotter can use data from both EMD and EEMD runs. When it plots EEMD data, it shows the time frequency plot of every single trial at once. The cluster.span option is useful in this case because it can distinguish “signal” (pixels where multiple trials intersect) from “noise” (whether from EEMD or from nature) where only one trial contributes data.

Value

img	The spectrogram image, suitable for plotting with the generic image function

Note

Using the option combine.imfs = FALSE in HHRender will cause HHGramImage to run much, much slower. Unless you have a compelling reason to plot certain IMFs (as opposed to all of them combined), I recommend against using this.

It may take some trial and error to get a nice image. For example, if the data points are too small (and thus the spectrogram looks like a mist of fine points rather than continuous frequency bands), try rerunning HHRender, but with lower frequency resolution. If the spectrogram is extremely noisy, try defining cluster.span - this usually gets rid of most of the random noise. For example, a cluster.span of c(3, 10) only keeps pixels that have data from at least 3 trials, up to 10. Most noise pixels will only have one trial contributing data. The upper limit (10) is a formality - it does not make much sense at this point to put an upper limit on trial intersections unless you are interested in the noise component isolated from the signal.

Author(s)

Daniel Bowman [e-mail]

See Also

FTGramImage, HHRender, HHSpecPlot

Examples

data(PortFosterEvent)

trials <- 10
nimf <- 10
noise.amp <- 6.4e-07
trials.dir <- "test"

set.seed(628)
#Run EEMD (this may take some time)
## Not run: EEMD(sig, tt, noise.amp, trials, nimf, trials.dir = trials.dir)

#Compile the results
## Not run: EEMD.result <- EEMDCompile(trials.dir, trials, nimf)

#Calculate spectrogram
dt  <-  0.1
dfreq  <-  0.1
## Not run: hgram <- HHRender(EEMD.result, dt, dfreq)


#Plot spectrogram 
time.span <- c(4, 10)
freq.span <- c(0, 25)
## Not run: HHGramImage(hgram, time.span, freq.span,  
pretty = TRUE, img.x.format = "%.1f", img.y.format = "%.0f", 
main = "Port Foster event - ensemble Hilbert spectrogram")
## End(Not run)

#Plot intersections

## Not run: HHGramImage(hgram, time.span, freq.span, amp.span = c(1, 5),  
clustergram = TRUE, pretty = TRUE, img.x.format = "%.1f", colorbar.format = "%.0f",
img.y.format = "%.0f", main = "Port Foster event - signal stability")
## End(Not run)

#Decluster
#show only areas with stable signal 
#i.e. each pixel has data from at least 3 EEMD trials
## Not run: HHGramImage(hgram, time.span = time.span, freq.span = freq.span,
cluster.span = c(, 10), pretty = TRUE, img.x.format = "%.1f", 
img.y.format = "%.0f",
main = "Port Foster event - ensemble Hilbert spectrogram")
## End(Not run)

#Log amplitude plot

## Not run: HHGramImage(hgram, time.span = time.span, freq.span = freq.span,
scaling = "log", pretty = TRUE, img.x.format = "%.1f", img.y.format = "%.0f",
main = "Port Foster event - ensemble Hilbert spectrogram with log amplitude")
## End(Not run)

#Log frequency plot
dfreq <- 0.001
## Not run: hgram=HHRender(EEMD.result, dt, dfreq, scaling = "log")
## Not run: HHGramImage(hgram, time.span, freq.span = c(0, 2),          
pretty = TRUE, img.x.format = "%.1f", img.y.format = "%.2f",
img.y.lab = "log frequency",
main = "Port Foster event - ensemble Hilbert spectrogram with log frequency")
## End(Not run)

#Only show IMF 1
dfreq <- 0.1
## Not run: hgram=HHRender(EEMD.result, dt, dfreq, combine.imfs = FALSE)
## Not run: HHGramImage(hgram, time.span, freq.span, imf.list = 1,
pretty = TRUE, img.x.format = "%.1f", img.y.format = "%.0f",
main = "Port Foster event - ensemble Hilbert spectrogram of IMF 1")
## End(Not run)

hht documentation built on March 31, 2023, 10:08 p.m.