This manual documents the methods of NumRu::GPhys defined in gphys_fft.rb
GPhys::fft_ignore_missing( ignore=true, replace_val=nil )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
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
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
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 spectrum 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]).
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
For a 4D data with [x,y,z,t] dimensions, filtering by the phase velocity in the y dimension greater than 10.0 (in the unit of y/t) can be made by
cmin = 10.0; cmax = nil gpfilt = gp.phase_velocity_filter(1, 3, cmin, cmax)
For a global data (on the Earth's surface) with [lon, lat, z, time] axes, where the units of lon is "degrees" (or "degrees_east" or "radian") and the units of time is "hours", to filter disturbances whose zonal phase speed MEASURED AT THE EQUATOR is less or equal to 30 m/s can be made by
cmin = -30.0; cmax = 30.0 xconv = UNumeric[6.37e6, "m"] # Earth's radius (i.e., m/radian) # This is a special case since "radian" is exceptionally omitted. # See the private method __predefined_coord_units_conversion. tconv = UNumeric[3.6e3, "s/hours"] gpfilt = gp.phase_velocity_filter(1, 3, cmin, cmax, xconv, tconv)
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
Example A
fu = u.fft(nil, 0, 2)
cfu = fu.phase_velocity_binning(0, 2, {"min"=>-1,"max"=>1,"int"=>0.1})Example B
fu = u.fft(nil, 0, 2) pw = fu.abs**2rawspect2powerspect(0,2) # power spectrum cbins = [-100.0, -10.0, -1.0, 1.0, 10.0, 100.0] # logarithmic spacing cpw = pw.phase_velocity_binning(0, 2, cbins)
Example C
fu = u.fft(nil, 0, 3)
fv = v.fft(nil, 0, 3)
kconv = UNumeric[1/6.37e6, "m-1"]
fconv = UNumeric[1/3.6e3, "hours/s"]
fuv = (fu * fv.conj) # cross spectra
cfuv = fuv.phase_velocity_binning(0, 3, {"min"=>-50,"max"=>50,"int"=>5},
kconv, fconv)