bicoherence {astrochron}

bicoherence: Calculate bispectrum and bicoherence using WOSA method as detailed in Choudhury et al. (2008).

Description

bicoherence: Calculate bispectrum and bicoherence using WOSA method as detailed in Choudhury et al. (2008). Kim and Powers (1979) bicoherence normalization is used, with a conditioning factor to reduce the potential for spurious bicoherence peaks.

Usage

bicoherence(dat,overlap=50,segments=8,CF=0,CL=95,padfac=2,demean=T,detrend=T,
            taper=T,maxF=Nyq,output=0,genplot=T,color=1,id=NULL,logpwr=F,logbis=F,
            check=T,verbose=T)

Arguments

dat

Stratigraphic series to analyze. First column should be location (e.g., depth, time), second column should be data value.

overlap

Percent overlap for WOSA segments (use 0-50 percent).

segments

Number of segments for WOSA.

CF

Conditioning factor for bicoherence estimation (see pg. 70 of Choudhury et al., 2008). When CF=0, this will be automatically estimated as the 75th percentile of the magnitude-squared bicoherence denominator

CL

Confidence level to identify with a contour on the plots (0-100).

padfac

Pad with zeros to (padfac*npts) points, where npts is the original number of data points per segment.

demean

Remove mean from data series? (T or F)

detrend

Remove linear trend from data series? (T or F)

taper

Apply Hanning taper? (T or F)

maxF

Maximum frequency for analysis/plotting.

output

Return output as new data frame? 0 = none, 1 = magnitude-squared bispectrum, 2 = magnitude-squared bicoherence, 3 = magnitude-squared bicoherence confidence levels, 4 = everything.

genplot

Generate summary plots? (T or F)

color

Use (1) grayscale or (2) viridis color scale for 3D plots?

id

A vector listing frequencies to identify on the plots as diagonal lines.

logpwr

Use a log scale for power spectrum? (T or F)

logbis

Use a log scale for bispectrum? (T or F)

check

Conduct compliance checks before processing? (T or F) In general this should be activated; the option is included for Monte Carlo simulation.

verbose

Verbose output? (T or F)

Details

This function accompanies the publication Sullivan et al. (in press 2023, PNAS): "Bicoherence is a higher-order statistic, which quantifies coupling of individual frequencies (as combination and difference tones). For three frequencies, f1, f2 and f3, high bicoherence indicates that f1 + f2 = f3, with the additional property that their phases are also coupled in the data series. We employ the bicoherence approach of Choudhury, Shah and Thornhill (2008), which uses Welch Overlapping Spectral Analysis (WOSA), as this method includes improvements to the standard approach that reduce the potential for spurious bicoherence peaks. Note that reliable bicoherence estimates require a substantial increase in bandwidth resolution ("smoothing")".

References

Choudhury, A.A.S., Shah, S.L., and Thornhill, N.F. (2008), Diagnosis of Process Nonlinearities and Valve Stiction: Data Driven Approaches: Springer, 284 pp.

Kim, Y.C., and Powers, E.J. (1979), Digital Bispectral Analysis and Its Applications to Nonlinear Wave Interactions: IEEE Transactions on Plasma Science, v. PS-7, 120-131.

Sullivan, N.B., Meyers, S.R., Levy, R.H., McKay, R.M., Golledge, N.R., Cortese, G. (in press 2023), Millennial-scale variability of the Antarctic Ice Sheet during the Early Miocene: Proceedings of the National Academy of Sciences.

Welch, P.D. (1967), The use of Fast Fourier Tranform for the estimation of power spectra: A method based on time averaging over short, modified periodograms: IEEE Transactions on Audio and Electroacoustics, AU-5 (2): 70-73.

Examples

 ## Not run: 
# Generate an example quadratic phase-coupled signal as in Choudhury et al. (2008, pg. 79)
    n = rnorm(500)
    t=1:500
    signal = sin(2*pi*0.12*t + pi/3) + sin(2*pi*0.18*t + pi/12) + sin(2*pi*0.3*t + 5*pi/12) + n
    ex=data.frame(cbind(t,signal))
    bicoherence(ex)
 
## End(Not run)