VSpec: VSpec
In WilliamCooper/Ranadu: Functions for use with RAF aircraft data files

Description Usage Arguments Details Value Author(s) Examples

Produces a variance spectrum in a ggplot2 file suitable for printing.

VSpec(.data, .Variable = NA, VLabel = NA, col = NA,
  type = "spectrum", method = NA, xlim = NA, ylim = NA,
  spans = 49, ae = 0.2, smoothBins = 0, segLength = 512,
  poles = 50, resolution = 1e-04, showErrors = 0,
  WavelengthScale = TRUE, ADD = NA, add = NA, EDR = FALSE)

`.data`	A data.frame containing at least the variables "Time", "TASX" and ".Variable" where ".Variable" is the second (required) parameter. 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.
`.Variable`	The (character) name of a variable that is a column in .data and for which the variance spectrum will be constructed. If this variable is not in .data an error message is generated. If the parameter is not supplied or is set to NA (the default), up to three variables are selected from the first three (other than TASX or TIME) in the supplied data.frame.
`VLabel`	A character string or a vector of such strings that will be used as the labels in the legend. The default is .Variable. The labels should differ if they are to appear separately in the legend. For example, to plot the spectrum for the same variable using different methods, include labels that indicate the different methods. See the examples.
`col`	The color to use when plotting the spectral variance. The default is NA, and in this case the following plot colors will be used in order: blue, forestgreen, black, black, darkorange. A vector of color names can be supplied if a multiple-variable plot is to be generated.
`type`	Three choices are avaiable: "spectrum" (the default), which uses the R routine "spectrum()" from the stats package to estimate the spectral density; "Welch", which uses the implementation of the Welch method of averaging segments as implemented in the R package "bspec", and "MEM" to use the maximum-entropy method of spectral estimation as implemented in the Ranadu routines memCoef() and memEstimate(). The parameter "spans" applies only to the "spectrum" method, the argument "segLength" to the Welch method, and the arguments "poles" and "resolution" only to the "MEM" method. The type will be the same for all plotted variance spectra for a multiple-variable plot.
`method`	This is the same as "type" and over-rides it if present.
`xlim`	A two-element vector specifying the lower and upper limits for the abscissa of the plot. The default is NA, in which case c(0.001, 1) will be used if the Rate is 1 and c(0.001, 15) if the Rate is 25.
`ylim`	A two-element vector specifying the lower and upper limits for the ordinate of the plot. The default is NA, in which case c(0.0001, 1) will be used.
`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 "spectrom". 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 49. If spans=NULL or spans <= 4 this averaging is suppressed.
`ae`	A factor that scales the predicted lines representing constant eddy dissipation rate to adjust for longitudinal (where ae should be 0.15) or lateral (0.2) spectra. The default is 0.2; use 0.15 for the variables TASX, UXC, etc. This applies to only the first spectrum plotted; others use the same background for the eddy dissipation rate. To make an appropriate scale adjustment for plots that include both longitudinal and lateral variance spectra, consider multiplying the longitudinal variable by sqrt(0.15/0.2) for display purposes.
`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 spectral density are binned into those intervals and averaged to smooth the spectrum. Initial smoothing can be provided by "spans" (if larger than 4) for the "spectrum" method and by using a small number of poles for the "MEM" method; the smoothing by the "smoothBins" parameter is applied after and in addition to those smoothing methods. The default (0) suppresses this smoothing.
`segLength`	The length of segments in the time series to use when averaging to find the estimate of spectral density.
`poles`	The number of poles to use for the maximum-entropy estimates. The default (50) usually is a good first choice. For more structure, try 100. If you go beyond around 150, the method becomes too slow to be practical, esp. for high-rate files.
`resolution`	The increment (as a fraction of the logarithm of the frequency range) at which to evaluate the MEM estimate of spectral density. If a fine feature is expected in the spectrum, the resolution should be small enough to isolate it, but small values increase the variance in the individual estimates.
`showErrors`	A non-zero value shows ribbon plots of the estimated uncertainty. If smoothBins is > 9, the uncertainty estimate is based on the calculated standard deviation in the mean in each bin; otherwise, the estimate is based on the expected uncertainty for the particular method used. 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 "gray50" but "alpha" of 0.5 for partial transparency.
`WavelengthScale`	If TRUE (the default), include a wavelength scale on the plot.
`ADD`	This parameter has the default value NA, which causes the function to plot only the spectrum for the variable provided. If a spectrum for an other set of variables has already been defined by previous calls to VSpec, setting ADD to the plot definition returned by that previous call will add this plot to the previous plot. Up to four variables can be included in the final plot. See the examples.
`add`	This is only included to make it possible to specify either "ADD" or "add". Default is NA, in which case the value of ADD is used.
`EDR`	If EDR is set TRUE, the plot will be normalized such that the ordinate is constant and has the value of the eddy dissipation rate for an inertial subrange. Otherwise this is not a true density function of log(frequency) and so is difficult to determine except for the above specialized use. The variable plotted is (2pi/V)(CP(f)*f^(5/3))^(3/2) where V is the airspeed in m/s and C is a constant equal to 1.5 for lateral spectra like WIC and 2 for longitudinal spectra like TASX. The resulting units are m^2/s^3 per interval in the true abscissa coordinate of -1.5C(epsilon)^-(1/3)k^(-2/3), but the plot is displayed with a logarithmic-frequency abscissa. The result can't be interpreted as a variance spectrum but can show consistency with inertial-subrange expectations and the approximate magnitude of the eddy dissipation rate when used with wind components.

For the variable provided, which must be in the supplied data.frame that must also contain the variables "Time" and "TASX' and a "Rate" attribute, this function constructs a plot of the spectral variance of that variable. The method can be the standard "spectrum" function of R (the default), the "Welch" method as provided by the R package "bspec", or the maximum-entropy method ("MEM") as implemented in other function of Ranadu. Some options are provided for each, with defaults that are usually appropriate. If the ADD parameter is set to the ggplot definition returned from a previous call, the new spectrum is added to that plot (up to four plotted spectra on a single plot). The mean and trend are removed before constructing the spectrum, and missing values are replaced by interpolation where possible. Optional additional smoothing in logarithmic intervals in frequency is available through the "smoothBins" parameter. The plot includes background lines showing the -5/3 slope expected for homogeneous isotropic turbulence, and for wind variables the magnitude of these lines represent factor-of-10 changes in the eddy dissipation rate with the larger-dot line representing 1e-4 m^2/s^3.

A ggplot2 definition for the plot of spectral density as a function of frequency. The normalization is one-sided; i.e., the integral of the spectral variance from zero to infinity is the total variance of the variable. The resulting plot definition can be plotted (via, e.g., 'print (VarSpec(...))) or saved for later addition of more variables or for later plotting. The plot is returned with the standard ggplot theme; to use the Ranadu theme "theme_WAC()", add it to the plot definition that is returned before plotting. In addition, to make it possible to superimpose future plots, the following variables are saved in the global environment: .clinesVSpec and .VSpecDF1,2,3, .VSpecVar2,3. The function does not check for collision with other possible uses of those names in the global environment.

William Cooper

VSpec(RAFdata, 'WSC')
g <- VSpec(RAFdata, 'WSC', VLabel='std', xlim=c(0.1,1));
VSpec(RAFdata, 'WSC', VLabel='MEM', method='MEM', ADD=g)
VSpec(RAFdata,'TASX', spans=11, showErrors=1, xlim=c(0.01,1)) + theme_WAC()