NCL Home > Documentation > Functions > General applied math, unknown

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

x

A one-dimensional (non-stationary) time series. The 'time' should be equally spaced.

frqdem

The 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

frqcut

The low-pass filter cutoff frequency. The function filwgts_lanczos is used to perform the low-pass filter.

nwt

A 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.

ndim

The dimension of x containing the time series. Currently, this argument is ignored. Set to 0.

opt

A 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 phases

NOTE: 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)

Contact the Webmaster