CohPhase: CohPhase

CohPhaseR Documentation

CohPhase

Description

Plots the coherence and phase for a cross-spectrum. Optionally, returns the cospectrum in a (frequency, covariance) data.frame.

Usage

CohPhase(
  .data,
  .Var1,
  .Var2,
  col = "blue",
  spans = 25,
  smoothBins = 50,
  plotType = "ggplot",
  showErrors = 0,
  returnCospectrum = FALSE
)

Arguments

.data

A data.frame containing at least the variables "Time", ".Var1" and ".Var2". It should also have an attribute "Rate" if its rate is different from 1 Hz (the default). Any restrictions on the time range should be applied to the data.frame before it is supplied to this function. See the examples below. If subsetting removes the "Rate" attributes from the data.frame, the value from the original data.frame should be added to .data.

.Var1

The (character) name of a variable that is a column in .data and for which the variance cross-spectrum with .Var2 will be constructed. If this variable is not in .data an error message is generated.

.Var2

The (character) name of a second variable that is a column in .data and for which the variance cross-spectrum with .Var1 will be constructed. If this variable is not in .data an error message is generated.

col

The color to use when plotting this variable. The default is NA, and in this case the following plot colors will be used in order: blue, forestgreen, black, brown.

spans

An odd integer (or forced odd by incrementing upward if even) specifying the number of frequencies to span when averaging the spectral variance estimate produced by the R routine "spectrum". The smoothing uses modified Daniell smoothers. This parameter can also be a vector of odd integers, and in that case they will be applied consecutively. See help for that function for more information about the nature of this averaging. The default value is 25. If spans=NULL or spans <= 4 this averaging is suppressed. In that case "smoothBins" below should be used because the coherence for an individual frequency without smoothing is always 1.

smoothBins

If a value larger than 5 is provided, the frequency range is divided into this number of intervals evenly spaced in the logarithm of the frequency. Then estimates of the coherence and phase are binned into those intervals and averaged to smooth the spectrum. Initial smoothing can be provided by "spans" (if larger than 4); the smoothing by the "smoothBins" parameter is applied after and in addition to the smoothing via "spans". The default is smoothBins=50.

plotType

The type of plot generated. The default is 'ggplot', for which specifications for aa faceted plot using ggplot2 are generated and returned to the calling program for plotting. Any other value of this parameter causes a standard-R-graphics plot to be generated instead.

showErrors

A non-zero value shows ribbon plots of the estimated uncertainty. The uncertainty estimate is based on the calculated sample standard deviation (not the standard deviation in the mean) in each bin specified by the "smoothBins" parameter. The value is the number of standard deviations represented by the ribbon; a value of 1 shows a ribbon extending one standard deviation above and below the mean value. The default is 0, and in that case no ribbon is plotted. The ribbon is plotted using color "grey" but "alpha" of 0.15 for partial transparency. The "showErrors" parameter has no effect unless the (default) plotType='ggplot' is used. The uncertainty band is not plotted where there are fewer than two values to average in a bin.

returnCospectrum

Default is FALSE. If set TRUE, instead of a plot definition, the cospectrum and quadrature are returned in the form of a data.frame with columns "freq", "cospec' and 'quad'. These are not smoothed and probably need smoothing when they are used. The two variance spectra are also returned, as "spec1" and "spec2".

Details

For the variables provided, which must be in the supplied data.frame that must also contain the variables "Time" and a "Rate" attribute, this function constructs a plot of the squared coherence and phase for the cross-spectrum of those two variables. The only method now available is the standard "spectrum" function of R (via the spec.pgram() function. The mean and trend are removed before constructing the spectrum, and missing values are replaced by interpolation where possible. Smoothing is applied via the "spans" argument, approximately a running average in frequency, and additional smoothing in logarithmic intervals in frequency is available through the "smoothBins" parameter. To add approximate confidence intervals, this additional smoothing is necessary because the confidence intervals are based on the standard deviations in the bins.

Value

A ggplot2 definition for the plot of ((squared) coherence and phase as a function of frequency, if plotType == 'ggplot'. The resulting plot definition can be plotted (via, e.g., 'print (CohPhase(...))) or saved for later addition of more variables or for later plotting. The plot is returned with the Ranadu theme "theme_WAC()", but that can be changed by adding another theme to the plot definition before plotting. if plotType is not 'ggplot', the plots are generated using standard R plots and a data.frame is returned that contains the frequency, coherence, and phase. That can be used to plot separately and perhaps combine with other plots.

Author(s)

William Cooper

Examples

## Not run: CohPhase(RAFdata, 'GGVEW', 'VEW')
## Not run: CohPhase(RAFdata, 'ATX', 'DPXC', col='red', spans=15, smoothBins=25, showErrors=1)

NCAR/Ranadu documentation built on Jan. 27, 2023, 1:09 a.m.