
demod_cmplx
Perform a complex demodulation on a time series.
Available in version 6.4.0 and later.
Prototype
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl" ; This library is automatically loaded ; from NCL V6.2.0 onward. ; No need for user to explicitly load. function demod_cmplx ( x [*] : numeric, frqdem [1] : numeric, frqcut [1] : numeric, nwt [1] : integer, ndim [1] : integer, opt [1] : logical )
Arguments
xA one-dimensional (non-stationary) time series. The 'time' should be equally spaced.
frqdemThe demodulation frequency. The choice of frqdem may be guided by theory or by a (say) Fourier analysis (e.g., a periodogram) of a series. Allowed range: 0.0 < frqdem < 0.5
frqcutThe low-pass filter cutoff frequency. The function filwgts_lanczos is used to perform the low-pass filter.
nwtA scalar indicating the total number of weights (must be an odd number; nwt >= 3). The more weights, the better the filter, but there is a greater loss of data at the ends.
ndimThe dimension of x containing the time series. Currently, this argument is ignored. Set to 0.
optA logical variable. If the default value(s) are to be used, set to False. If opt=True, then the following attribute can be set:
opt = True opt@nsigma = 2 ; default: nsigma=1
Return value
A variable of type list containing three arrays of the same size, shape and type as x. The three variables (arrays) are the:
(1) low-pass demodulated amplitudes. (2) wrapped phases (3) unwrapped phasesNOTE: The variables within the list can be accessed directly. However, many users find it clearer to explicitly extract the variables and subsequently delete the returned list variable. See examples.
Description
The term demodulation refers to extracting (recovering) information about a specific signal from a series containing information from many signals. Here, complex demodulation is a method for analyzing nonstationary time series about a harmonic (frequency) component. It enables the amplitude and phase of a particular frequency component of a time series to be described as functions of time. It is local in that the components are allowed to change slowly over time. The purpose is to estimate the amplitude [ A(t) ] and phase [ P(t) ] of a slowly varying oscillation in the neighborhood of frqdem, The resulting series must be further post-processed via a low-pass filter. This function uses filwgts_lanczos.
As noted in the S-Plus "demod" function documentation:
To better understand the results of complex demodulation several low pass filters should be tried: the smaller the low pass band, the less instantaneous in time but more specific in frequency is the result.
The complex demodulation process, implemented by demod_cmplx, consists of several steps:
(1) A demodulation frequency (frqdem) is specified. (2) Compute the real (cosine) and imaginary (sine) components at each time step. (3) Low pass filter each component using a specified low pass cutoff frequency (frqcut). (4) Compute the amplitudes [ A(t) ] and phases [ P(t) ] using the low pass filtered components (3).
The phases returned in step (4) are calculated via atan2 and range from -pi to +pi. These are called 'wrapped phases.' Unfortunately, the resulting phase plots may appear quite noisy and are difficult to interpret. For graphical and interpretation purposes, the wrapped phases are often unwrapped. NCL's unwrap_phase can be
References:
Fourier Analysis of Time Series Peter Bloomfield Wiley, 2000 Bloomfield, P. (1976) Fourier Analysis of Time series: An Introduction Wiley , 1976: Chapter 6 Kessler: U. Washington: Complex Demodulation PMEL: Complex Demodulation Thompson, R. (1999): Journal of Hydrology 224: 169-183 A time-series analysis of the changing seasonality of precipitation in the British Isles and neighbouring areas
See Also
filwgts_lanczos, atan2, wgt_runave_n, unwrap_phase, specx_anal, fourier_info
Examples
See worked examples on the Spectral Analysis and Complex Demodulation page.
Example 1: Let x(time), frqdem=0.21, frqcut=0.015, nwt=71, ndim=0, then
demod_x = demod_cmplx(x, frqdem, frqcut, nwt, ndim, False) ; demod_x[3] print(demod_x) ; type list ; For clarity, explicitly extract the 3 variables amp = demod_x[0] ; [0] list syntax; amp(time) phase_1 = demod_x[1] ; [1] phase_1(time) ; wrapped phase_2 = demod_x[2] ; [2] phase_2(time) ; unwrapped delete(demod_x) ; no longer needed printVarSummary(amp) printVarSummary(phase_1) printVarSummary(phase_2)