extention 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 derieved as (coord.val.max - coord.val.min)*(n+1)/n.

ARGUMENTS

• backward (true of false) : when true, backward FT is done; otherwise forward FT is done.
• dims (integers) : dimensions to apply FFT

RETURN VALUE

• a GPhys

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

• dim? (Integer of String): the dimension along which you want to remove trends.

RETURN VALUE

• a GPhys

EXAMPLE

• See detrend.

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 multilied by 1/0.875, which is stored as GPhys::COS_TAPER_SP_FACTOR (==1/0.875).

ARGUMENTS

• dim? (Integer of String): the dimension along which you want to remove trends.

RETURN VALUE

• a GPhys

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 waveneumber axis to cover from -K/2 to K/2 instead of from 0 to K-1, where the wavenumber is simbolically 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

• dim (integer): the dimension you want to shift spectra elements. Count starts from zero.

RETURN VALUE

• a GPhys

EXAMPLE

• To get a spectra of a variable var along the 1st and 2nd dimensions:

  fc = var.fft(nil, 0,1)    # --> Fourier coef
  sp = ( fc.abs**2 ).spect_zero_centering(0).spect_zero_centering(1)

  Note that spect_zero_centering is applied after taking |fc|^2.

• Same but if you want to have the 2nd dimension one-sided:

  fc = var.fft(nil, 0,1)
  sp = ( fc.abs**2 ).spect_zero_centering(0).spect_one_sided(1)

• Similar to the first example but for cross spectra:

  fc1 = var1.fft(nil, 0,1)
  fc2 = var2.fft(nil, 0,1)
  xsp = (fc1 * fc2.conj).spect_zero_centering(0).spect_zero_centering(1)

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

• dim (integer): the dimension you want to shift spectra elements. Count starts from zero.

RETURN VALUE

• a GPhys

EXAMPLE

• See the 2nd example of spect_zero_centering.

rawspect2powerspect(*dims)

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

ARGUMENTS

• dims (integers): the dimensions corresponding to wavenumbers.

RETURN VALUE

• a GPhys

EXAMPLE

• Suppose a 2 (or more) dimensional data gphys.

  fc = gphys.fft(nil, 0, 1)
  sp = fc.abs**2
  ps = sp.rawspect2powerspect(0,1)

  Here, sp is the raw spectum of gphys, and ps is the power spectrum. The Parseval relation for them are as follows:

  (gphys**2).mean == sp.sum
                  == pw.sum*dk*dl (== \int pw dk dl, mathematically),

  where, dk = (pw.coord(0)[1] - pw.coord(0)[0]), and dl = (pw.coord(1)[1] - pw.coord(1)[0]).