spect [ parameter=value ... ] [ inputfile outputfile ] spect [ parameter=value ... ] [ inputfile ... directory ]
Parameters are: include_vars, forward, fft_dim, window, mag_phase, remove_means, sample_freq, freq_var, freq_units, power_units, fft_out_dim.
spect computes forward and inverse spectra of variables with respect to a specified dimension. The spectra are computed via the fast fourier transform (FFT) method. The forward spectra can be power and phase spectra, or real and imaginary spectra. The real and imaginary spectra are intended to be used for band-pass filtering, so that subsequent inverse transforms can be performed.
In the case of forward transforms to power and phase spectra:
The output variables for each input variable are the power spectrum and phase spectrum (in degrees). The names of these output variables are the original variable name(s) appended to the prefixes, POW_ 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 padding is done symmetrically on either end of the 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).
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.
In the case of forward transforms to real and imaginary spectra:
The output variable for each input variable is a complex spectrum. The name of this output variable is the original variable name, its units are modified to have the prefix "CMPLX_". This output variable has the same dimensions it had in the input, although: 1) it has one more dimension named "complex" that has length two, and 2) the length of the dimension being transformed, fft_dim, is modified. The fft_dim dimension must be associated with each of the specified input variables. Its input 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 imaginary parts, and therefore their values in the imaginary part of the complex spectrum (2nd index of dimension "complex") are set to badval (datasets).
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 and its units.
In the case of inverse transforms of real and imaginary spectra:
The data are assumed to be complex output from spect (see above). The fft_dim should be a power of two plus one. Its last dimension should be named "complex" and of length two with the first index being the real part and the second index the imaginary. The units of the variables being transformed should have the prefix "CMPLX_".
The output variable will have the same name it had originally on input, with the same (original) units. Its length will be the original length or the power of 2 it was padded to (see above).
In this case, a window can be applied in order to filter the data. The window should have the same length as the fft dimension being inverse transformed.
Specifies which variables in the input dataset(s) are to be transformed.
The default is all variables in the input dataset(s).
Specifies whether a forward or inverse transform should be performed. See explanation above and parameter descriptions below for more detailed description of inputs and outputs for these cases.
Valid responses are [yes or no]. The default is yes.
Specifies the dimension to be transformed. If forward=yes, then the length of this dimension should be a power of two, if not, 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. If forward=no, then the length of this dimension should be the N/2+1 just referenced, and the output dimensions will be N (the power of two in the original input series).
The default is the first dimension defined in the dataset.
Specifies a Terascan dataset containing a one-dimensional variable named "x" containing the windowing function. If forward=yes, the length of "x" must be the the power of two to be used in the forward FFT computation (see fft_dim above). In this case the window is applied before the transform as a means of reducing variance leakage. If forward=no, the length of "x" must be the length of the fft_dim being inverse transformed (see above). In this case, the window is used for band-pass filtering the data to remove unwanted frequencies. Simple windowing datasets can be created with fakedata or emath. Note: variance loss due to tapering is not accounted for internally in the final forward-transform spectral values.
The default is none, i.e. apply no window function.
If forward=yes, this specifies whether to output the forward transform as two separate power and phase spectra variables or one two-dimensional complex spectrum so that band-pass filtering can be performed.
Valid responses are [yes or no]. The default is yes.
If forward=yes, this 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.
If forward=yes, this 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 specified as cycles/day (see below).
The default is 1.
If forward=yes, this specifies the name of the output variable containing the frequency values of the computed spectra. This variable will be associated with the output dimension fft_out_dim (i.e. dim->var, see datasets).
The default is frequency.
If forward=yes, this specifies the name of the units of output variable freq_var.
The default is no units.
If forward=yes and mag_phase=yes, this specifies the units of output variables containing the power spectra, i.e. the variables named POW_"invar".
The default is power.
If forward=yes and mag_phase=yes, this 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.
Example 1.
Lets assume we have a one dimensional time series of wind speed with units meters/second, 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 power and phase spectra.
% spect in/out files : char(255) ? myset myspect include_vars : char(255) ? [] windspeed forward : char( 3) ? [yes] fft_dim : char( 31) ? [] time window : char( 31) ? [] bartlett mag_phase : char( 3) ? [yes] remove_means : char( 3) ? [yes] sample_freq : real ? [1] freq_var : char( 31) ? [frequencies] freq_units : char( 31) ? [] cycles/day power_units : char( 31) ? [power] fft_out_dim : char( 31) ? [] frequency
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" and "PHS_windspeedfR contain the power and phase spectra, and "frequencies" contains the values of the output frequencies in cycles/day.
Example 2.
Lets assume we have the above data set and we would like to remove the high frequency variations by band-pass filtering the data. The following is an example of forward transforming the data into complex spectra then applying a low-pass filter to the data upon inverse transforming the spectrum.
% spect in/out files : char(255) ? myset myspect include_vars : char(255) ? [] windspeed forward : char( 3) ? [yes] fft_dim : char( 31) ? [] time window : char( 31) ? [] mag_phase : char( 3) ? [yes] no remove_means : char( 3) ? [yes] no sample_freq : real ? [1] freq_var : char( 31) ? [frequencies] freq_units : char( 31) ? [] cycles/day
In this case, the mean value of the time series was not removed before the transformation. The data was padded to a length of 512 with the mean value of the series. In this case no windowing function was applied.
The output dataset, myspect, will be two dimensional. The first dimension will be "time" and its length will be 257. The second dimension will be named "complex" and its length will be 2. The output dataset will have two variables. "windspeed" contains the complex spectrum and have units "CMPLX_meters/second", and "frequencies" contains the values of the output frequencies in cycles/day.
% spect in/out files : char(255) ? myspect mylowpass include_vars : char(255) ? [] windspeed forward : char( 3) ? [yes] no fft_dim : char( 31) ? [] time window : char( 31) ? [] lowpass
In this case, the complex spectrum in "myspect" was inverse transformed. The data were band-pass filtered using the dataset lowpass which contains a variable named x. This variable has length 257. The first window value is applied to the mean, the last applied to the Nyquist frequency. Thus, in this case, the first several (or more) values of the window variable would be one, and the last several (or more) would be zero. The output variable will be the band-passed version of the original input variable in myset, however its length will be 512.
datasets, spectral, xspect, randata, emath, fakedata, lagspect, spect2d, dimavg, xcorrel.
In the case of forward transforms to power spectra, the variance (integrated sum of power spectra) can be reduced from that in the input series due to tapering which is dependent on the window function. The variance can also be reduced due to padding the input out to the nearest power of 2. In the case of padding a series of length M to N, the variance is reduced by M/N.
Reference: Bendat, J.S. and Piersol, A. B., Random Data: Analysis and Measurement Procedures, 2nd Edition, Wiley, 1986.
Last Update: $Date: 1998/05/29 20:44:59 $