lagspect [ parameter=value ... ] [ inputfile outputfile ] lagspect [ parameter=value ... ] [ inputfile ... directory ]
Parameters are: include_vars, fft_dim, fft_out_dim, remove_means, lag_pow_2, window, sample_freq, freq_var, freq_units, power_units.
lagspect computes power spectra from covariance functions (see xcorrel). The output variable for each input variable is an auto-spectrum in the case of a two-sided auto-correlation function, or a cross-spectrum in the case of a two-sided cross-covariance function. The names of these output variables are the input variable name(s) appended to the prefix POW_. The output variables have the same number of dimensions as the input variables, with only the length of the dimension, fft_dim, being modified. This dimension must be associated with each of the specified input variables. Its modified length is N+1, where N is a power of two. The power of two is specified by lag_pow_2. This parameter determines the number of plus (N) and minus (N) lags to keep from the covariance function(s). The first spectral value with respect to this dimension is associated with the mean, and the last value the Nyquist frequency.
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 output dimension length and the value of the sampling frequency that 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 tranformed. IMPORTANT: These variables must be covariance functions with both plus and minus lag values (see xcorrel). For covariances with N lags computed, when covariances must be ordered with the -N lag first, up to the 0 lag value, then to the +N lag value.
The default is all variables in the input dataset(s).
Specifies the dimension to be transformed, i.e. the lag dimension. Note, this dimension must include minus, 0, and plus lag values.
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_LAG', it may be appropriate to name the corresponding dimension in the output dataset 'frequency'.
The default is the name of fft_dim.
Specifies whether to remove the mean of each covariance before the fourier transform is applied.
Valid responses are [yes or no]. The default is yes.
Specifies by the power of two the number of lags to keep and use in the spectrum calculation. If 2**lag_pow_2 is less than the number of lags in the input dataset covariance function(s), then the covariances are truncated at lag 2**lag_pow_2. If 2**lag_pow_2 is greater than the number of lags in the input dataset covariance function(s), then the covariances are padded with zero out to lag 2**lag_pow_2. If lag_pow_2=0, then the power of 2 just less than or equal to the number of lags in the input dataset is used. The size of the spectral dimension, i.e. fft_out_dim in the output dataset is (2**lag_pow_2)+1.
Valid responses are [0 to 16]. The default is 0.
Specifies a Terascan dataset containing a one-dimensional variable named 'x' containing the windowing function. The length of 'x' must be the power of two to be used in the FFT computation (see lag_pow_2). For example, if lag_pow_2=10, this implies 1023 plus lags, 1023 minus lags, the 0 lag value, and a 0 value are used to construct the covariance to be transformed. The window should thus be 2048 in length, with generally the peak values in the center of the window and decreasing values at both ends. 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 exmaple, 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.
Specifies the units of output variables containing the power spectra, i.e. the variables named POW_'invar'.
The default is power.
Lets assume we have two one-dimensional time series variables in a dataset named myset. One is named wind and the other named vapor. Each is 365 (days) in length and has a single dimension named time with units days. Each can contain bad values. The example below shows how to compute their cross-covariance:
krystal_34_% xcorrel in/out files : char(255) ? myset mycov include_vars : char(255) ? [] wind cross_vars : char(255) ? [] vapor correl_dim : char( 31) ? [] time lags : int ? [] 364 ensemble_dims : char(159) ? [] keep_Ns : char( 3) ? [yes] normalize : char( 3) ? [yes] no
The dataset mycov contains the cross-covariance of wind and vapor in a one-dimensional variable named wind_vapor. The single dimension is named time_LAG and has length 729 (2*364+1). The number of observations at each lag are in a parallel variable named N_wind_vapor. The example below shows how to use lagspect to calculate the cross-spectrum for these two variables.
% lagspect in/out files : char(255) ? mycov myspect include_vars : char(255) ? [] wind_vapor fft_dim : char( 31) ? [] time_LAG fft_out_dim : char( 31) ? [] frequency remove_means : char( 3) ? [yes] lag_pow_2 : int ? [0] window : char( 31) ? [] bartlett sample_freq : real ? [1] freq_var : char( 31) ? [frequencies] freq_units : char( 31) ? [] cycles/day power_units : char( 31) ? [power] Covariance(s) will be reduced to lag 256.
Since lag_pow_2=0, lagspect will use the power of two number of lags that is just smaller than or equal to the input number (i.e. 364). Thus, the covariances are reduced to lag 256 and the size of the output dimension, named frequency in this case, is 257. The mean value of the covariance was removed before the transformation. A windowing function was also applied to the 512-length dual-sided covariance. This windowing function is contained in a one-dimensional variable named 'x' in the dataset named bartlett. These 512 points stem from 255 negative lags, 255 positive lags, zero lag value and a zero value. The output dataset will also contain a variable named 'frequencies' that holds the values of the output frequencies in cycles/day.
datasets, spectral, spect, spect2d, xspect, randata, emath, fakedata, lagspect, dimavg, xcorrel.
IMPORTANT: These variables must be covariance functions with both plus and minus lag values (see xcorrel). For covariances with N lags computed, whe covariances must be ordered with the -N lag first, up to the 0 lag value, then to the +N lag value.
Last Update: $Date: 1998/05/29 18:32:56 $