xspect [ parameter=value ... ] [ inputfile outputfile ] xspect [ parameter=value ... ] [ inputfile ... directory ]
Parameters are: include_vars, cross_vars, fft_dim, fft_out_dim, normalize, freq_pairs, ensemble_dims, remove_means, window, sample_freq, freq_var, freq_units, power_units.
xspect computes coherence and phase spectra between two variables with respect to a specified dimension. The spectra are computed via the fast fourier transform (FFT) method (see NOTES). The output variables for each input variable are the coherence spectrum and phase spectrum (in degrees). Optionally, un-normalized cross-spectra can be output instead of the coherence (see normalize). The names of these output variables are the original variable name(s) appended to the prefixes, COH_ (POW_ in the case of cross-spectra) and PHS_, respectively. These two output variables have the same number of dimensions they had in the input dataset(s), with only the length of the dimension being transformed, fft_dim, being modified. This dimension must be associated with each of the specified input variables. Its length must be a power of two; if not, it will be padded to the next biggest power of two with the mean value of each series. The size of this dimension in the output dataset is N/2+1, where N is the power of two used in the FFT calculation. The first spectral value with respect to this dimension is associated with the mean, and the last value the Nyquist frequency. These two values have no phase information, and therefore their values in the phase spectrum are set to badval (datasets). IMPORTANT: coherence estimates are only defined for ensemble average spectra, therefore ensemble averaging must be done over at least one dimension (see ensemble_dims) or over a set of frequency bins (see freq_pairs).
A one-dimensional variable is written to each output dataset that contains the frequency (or wavelength) values of the spectra. These values are computed from the record length and the value of the sampling frequency which is specified by sample_freq. Options are provided for removing the mean(s), applying a window to the data before transforming, for renaming the fft_dim in the output, and for specifying names for the frequency variable, its units, and the units of the power spectra.
Specifies which variables in the input dataset(s) are to be the first variable in the product transform, i.e. the X variable in the cross-spectra of variables X and Y.
The default is all variables in the input dataset(s).
Specifies which variables in the input dataset(s) are to be the second variable in the product transform, i.e. the Y variable in the cross-spectra of variables X and Y. One variable must be specified for each variable specified in include_vars.
The default is all variables in the input dataset(s).
Specifies the dimension to be transformed. If the length of this dimension is not a power of two, it will be padded out to the next biggest power of two (N) for the FFT calculation. The size of this dimension in the output dataset(s) is N/2+1.
The default is the first dimension defined in the dataset.
Specifies the name of the dimension being transformed for the output dataset. Thus, if fft_dim is 'time', it may be appropriate to name the corresponding dimension in the output dataset 'frequency'.
The default is the name of fft_dim.
If normalize=yes, coherence spectra are computed, otherwise cross-spectra are computed. Note when normalize=yes, at least one dimension for ensemble_dims must be specified or freq_pairs must be specified since coherence spectra are only defined for ensemble averages, otherwise the results at all frequencies is the value 1 (See reference in NOTES).
Valid responses are [yes or no]. The default is yes.
Specifies frequency bins to do ensemble averaging over. These frequency bins are specified as sequential, continuous pairs. For example, if a time series has 78 data points, the algorithm will pad this out to 128 and compute a spectrum which will then have 65 data points, with indices 0-64. An example set of frequency pairs would be 0 5 6 18 19 34 35 64. This would produce a spectrum with only 4 estimates of coherence/cross-spectra, one which averaged the values between frequency bins 0 and 5 (inclusive), one between 6 and 18, etc. In this case, the one-dimensional variable specifying the frequencies of the resulting spectra contain bin averaged frequency values.
The default is none.
Specifies dimensions to ensemble average over. Thus, these dimensions will not be defined in the output dataset. None of these dimensions can be the same as the fft_dim.
There is nodefault.
Specifies whether to remove the mean of each series before the fourier transform is applied.
Valid responses are [yes or no]. The default is yes.
Specifies a Terascan dataset containing a one-dimensional variable named 'x' containing the windowing function. The length of 'x' must be the the power of two to be used in the FFT computation (see fft_dim above). Simple windowing datasets can be created with fakedata or emath. Note: variance loss due to tapering is not accounted for internally in the final spectral values.
The default is none, i.e. apply no window function.
Specifies the sampling frequency of the input values with respect to the fft_dim. For example, if the sampling frequency of the input values is every five days, then a value of 0.2 might be specified if the frequency units (freq_units) are to specified as cycles/day.
The default is 1.
Specifies the name of the output variable containing the frequency values of the computed power and phase spectra. This variable will be associated with the output dimension fft_out_dim (i.e. dim->var, see datasets).
The default is frequency.
Specifies the units of output variable freq_var.
The default is no units.
If norm=no, this parameter is used to specify the units of output variables containing the cross-spectra, i.e. the variables named POW_'invar'. If norm=yes, then the units of the coherence spectra are set to "coherence" and the user is not queried for this response.
The default is power.
Lets assume we have two one-dimensional time series: 1) wind speed with units meters/second, and 2) surface temperature in degrees C, in a dataset named myset. The single dimension is named time, has length 365, and has units days. Below is an example showing how to compute the cross and phase spectra.
% xspect in/out files : char(255) ? myset myspect include_vars : char(255) ? [] windspeed cross_vars : char(255) ? [] sst fft_dim : char( 31) ? [] time fft_out_dim : char( 31) ? [] frequency normalize : char( 3) ? [yes] no freq_pairs : int ( 32) ? [] ensemble_dims : char(159) ? [] remove_means : char( 3) ? [yes] window : char( 31) ? [] bartlett sample_freq : real ? [1] freq_var : char( 31) ? [frequencies] freq_units : char( 31) ? [] cycles/day power_units : char( 31) ? [power]
In this case, the mean value of the time series was removed before the transformation and the data was padded to a length of 512 with zeroes. A windowing function was also applied to the 512-length time series. This windowing function is contained in a one-dimensional variable named 'x' in the dataset named bartlett. Since, the means are to be removed in this case, the mean of this windowed-time-series is removed before the transformation.
The output dataset, myspect, will be one dimensional. The dimension will be named frequency and its length will be 257. The output dataset will have three variables. 'POW_windspeed_sst' and 'PHS_windspeed_sst' contain the cross and phase spectra, and 'frequencies' contains the values of the output frequencies in cycles/day.
datasets, spectral, spect, spect2d, lagspect, fakedata, randata, xcorrel, dimavg, xvu, emath.
Reference: Bendat and Piersol, Random Data: Analysis and Measurement Procedures. 2nd Edition, Wiley (1986).
Last Update: $Date: 1998/05/29 21:00:05 $