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

unwrap_phase

Unwrap (correct) phase angles to produce smoother phase plots.

Available in version 6.5.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 unwrap_phase (
		phase [*] : numeric   
	)

	return_val [dimsizes(phase)] :  float or double

Arguments

phase

Wrapped phase angles (radians; -pi to pi) derived from atan2. Missing (_FillValue) values at the beginning and ens are ignored.

Return value

A one-dimensional array of the same size as phase. The output will be double if phase is of type double. Otherwise, the returned values will be type float.

Description

This function mimics the behavior of Matlab's unwrap. Specifically, it "corrects the radian phase angles in a vector phase by adding multiples of (+/-) 2*pi when absolute jumps between consecutive elements of phase are greater than or equal to the default jump tolerance of pi radians."

NCL's unwrap_phase is a translation of the Matlab code presented on page 10 of the Gdeisat and Lilley reference.

  REFERENCES:
   Dr. Munther Gdeisat and Dr. Francis Lilley
   One-Dimensional Phase Unwrapping Problem 

   K. Itoh
   Analysis  of  the  phase  unwrapping  problem
   Applied  Optics,  Vol.  21,  No.  14,  p.  2470, July 15, 1982.

Examples

Example 1: This is Example 1 from Matlab's unwrap.

  p = (/ 0.0   ,-1.5728,-1.5747,-1.5772,-1.5790,-1.5816,-1.5852,-1.5877  \
       ,-1.5922,-1.5976,-1.6044,-1.6129,-1.6269,-1.6512,-1.6998,-1.8621  \
       , 1.7252, 1.6124, 1.5930, 1.5916, 1.5708, 1.5708, 1.5708 /)
  pha_ncl    = unwrap_phase(p)
  pha_matlab = unwrap_phase_matlab(p)    ; undocumented/unsupported function in shea_util.ncl (6.5.0)
  print(p+"   "+pha_ncl+"   "+pha_matlab)

          p      pha_ncl   pha_matlab
(0)	 0.0       0.0       0.0    
(1)	-1.5728   -1.5728   -1.5728
(2)	-1.5747   -1.5747   -1.5747
(3)	-1.5772   -1.5772   -1.5772
(4)	-1.579    -1.579    -1.579
(5)	-1.5816   -1.5816   -1.5816
(6)	-1.5852   -1.5852   -1.5852
(7)	-1.5877   -1.5877   -1.5877
(8)	-1.5922   -1.5922   -1.5922
(9)	-1.5976   -1.5976   -1.5976
(10)	-1.6044   -1.6044   -1.6044
(11)	-1.6129   -1.6129   -1.6129
(12)	-1.6269   -1.6269   -1.6269
(13)	-1.6512   -1.6512   -1.6512
(14)	-1.6998   -1.6998   -1.6998
(15)	-1.8621   -1.8621   -1.8621
(16)	 1.7252   -4.55799  -4.55799
(17)	 1.6124   -4.67079  -4.67079
(18)	 1.593    -4.69019  -4.69019
(19)	 1.5916   -4.69159  -4.69159
(20)	 1.5708   -4.71239  -4.71239
(21)	 1.5708   -4.71239  -4.71239
(22)	 1.5708   -4.71239  -4.71239

Example 2: This is one-dimensional version of Example 2 from Matlab's unwrap. The Q1 and Q2 below match the Matlab documentation.


  P1 = (/0     , 0.1963, 6.6759, 0.5890 /)         
  P2 = (/7.0686, 0.9817, 1.1781, 1.3744 /)

  Q1 = unwrap_phase(P1)
  Q2 = unwrap_phase(P2)

  print(P1+"   "+Q1+"   :   P2+"   "+Q2)