# 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 isautomatically 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 SeriesPeter Bloomfield Wiley, 2000 Bloomfield, P. (1976) Fourier Analysis of Time series: An Introduction Wiley , 1976: Chapter 6 Kessler: U. Washington:Complex DemodulationPMEL:Complex DemodulationThompson, R. (1999): Journal of Hydrology 224: 169-183A 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]delete(demod_x) ; no longer neededprintVarSummary(amp)printVarSummary(phase_1)printVarSummary(phase_2)