extension of class NumRu::GPhys -- Fast Fourier transformation and its applications

This manual documents the methods of NumRu::GPhys defined in gphys_fft.rb

class methods

GPhys::fft_ignore_missing( ignore=true, replace_val=nil )

Set a flag (class variable) to ignore missing values. This is for data that do not have missing but is treated as potentially having missing (often by having the valid_* attributes of NetCDF.) If replace_val is specified, data missing with replaced with that value.

methods

fft(backward=false, *dims)

Fast Fourier Transformation (FFT) by using (FFTW) ver 3 or ver 2. A FFTW ver.2 interface is included in NArray, while to use FFTW ver.3, you have to install separately. Dimension specification by the argument dims is available only with ver.3. By default, FFT is applied to all dimensions.

The transformation is complex. If the input data is not complex, it will be coerced to complex before transformation.

When the FT is forward, the result is normalized (i.e., divided by the data number), unlike the default behavior of FFTW.

Each coordinate is assumed to be equally spaced without checking. The new coordinate variables will be set equal to wavenumbers, derived as 2*PI/(length of the axis)*[0,1,2,..], where the length of the axis is derived as (coord.val.max - coord.val.min)*(n+1)/n.

REMARK

ARGUMENTS

RETURN VALUE

EXAMPLE

gphy.fft           # forward, for all dimensions
gphy.fft(true)     # backward, for all dimensions
gphy.fft(nil, 0,1) # forward, for the first and second dimensions.
gphy.fft(true, -1) # backward, for the last dimension.

detrend(dim1[,dim2[,...]])

Remove means and linear trends along dimension(s) specified. Algorithm: 1st order polynomial fitting.

ARGUMENTS

RETURN VALUE

EXAMPLE

cos_taper(dim1[,dim2[,...]])

Cosine tapering along dimension(s) specified.

Algorithm: to multiply with the half cosine curves at the both 1/10 ends of the data.

cos taper shape:
         _____________
       _/             \_
     ->   <-       ->   <-
      T/10           T/10
   half-cosine     half-cosine
     shaped         shaped

The spectra of tapered data should be multiplied by 1/0.875, which is stored as GPhys::COS_TAPER_SP_FACTOR (==1/0.875).

ARGUMENTS

RETURN VALUE

EXAMPLE

dim = 0    # for the 1st dimension
fc = gphys.detrend(dim).cos_taper(dim).fft(nil,dim)
sp = fc.abs**2 * GPhys::COS_TAPER_SP_FACTOR

spect_zero_centering(dim)

Shifts the wavenumber axis to cover from -K/2 to K/2 instead of from 0 to K-1, where the wavenumber is symbolically treated as integer, which is actually not the case, though. Since the first (-K/2) and the last (K/2) elements are duplicated, both are divided by 2. Therefore, this method is to be used for spectra (squared quantity) rather than the raw Fourier coefficients. (That is why the method name is prefixed by "spect_").

The method is applied for a single dimension (specified by the argument dim). If you need to apply for multiple dimensions, use it for multiple times.

ARGUMENTS

RETURN VALUE

EXAMPLE

spect_one_sided(dim)

Similar to spect_zero_centering but to make one-sided spectra. Namely, to convert from 0..K-1 to 0..K/2. To be applied for spectra; wavenumber 2..K/2-1 are multiplied by 2.

ARGUMENTS

RETURN VALUE

EXAMPLE

rawspect2powerspect(*dims)

Converts raw spectra obtained by gphys.fft.abs**2 into power spectra by dividing by wavenumber increments along the dimensions specified by dims.

ARGUMENTS

RETURN VALUE

EXAMPLE

phase_velocity_filter(xdim, tdim, cmin=nil, cmax=nil, xconv=nil, tconv=nil, remove_xtmean=false)

Filtering by phase velocity (between cmin and cmax)

REMARKS

ARGUMENTS

RETURN VALUE

EXAMPLE

phase_velocity_binning_iso_norml(kdim, fdim, cmin, cmax, cint, kconv=nil, fconv=nil)

Same as phase_velocity_binning but exclusively for equal phase velocity spacing. Also, a normalization is additionally made, to scale spectra in terms of integration along phase velocity axis --- The result of phase_velocity_binning called inside this method is divided by cint along with corresponding units conversion. Therefore, if this method is applied to spectra, a normalization is made such that an integration (not summation) along the phase velocity gives the variance (or covariance etc.) -- This normalization is suitable to quadratic quantities (such as spectra) but is not suitable to raw Fourier coefficients.

ARGUMENTS

RETURN VALUE

phase_velocity_binning(kdim, fdim, cbins, kconv=nil, fconv=nil)

Bin a 2D spectrum in space and time based on phase velocity. The operand (self) must be Fourier coefficients or spectra, whose grid has not been altered since the call of the method fft (i.e., those that have not applied with zero centering etc, since it is done in this method).

Binning by this method is based on summation, leaving the units unchanged.

REMARKS

ARGUMENTS

RETURN VALUE

EXAMPLES