NCL Home > Documentation > Functions > General applied math

pdfxy

Generates a joint probability density distribution.

Available in version 5.1.1 or later.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"

	function pdfxy (
		x         : numeric,  
		y         : numeric,  
		nbinx [1] : integer,  
		nbiny [1] : integer,  
		opt   [1] : logical   
	)

	return_val [*] :  float

Arguments

An array of any dimensionality.

An array of the same dimensionality of x.

nbinx

Number of bins to use for x. Specifying 0 will result in 25 bins being used. This must be greater than 2.

nbiny

Number of bins to use for y. Specifying 0 will result in 25 bins being used. This must be greater than 2. This may be different than nbinx

opt

Attributes may be associated with this variable. The attributes will alter the default behavior of the pdfxy.

Setting opt=True will activate use of the options.

binx_min - minimum value for the x bin boundary.
biny_min - minimum value for the y bin boundary.
binx_max - maximum value for the x bin boundary.
biny_max - maximum value for the y bin boundary.
binx_nice - let NCL calculate "nice" bin boundary values x
biny_nice - let NCL calculate "nice" bin boundary values y

Return value

A two-dimensional array of size (nbiny,nbinx). The units will be percent (%). The following attributes will be associated with the return variable.

nbinx - the number of bins used for x.
nbiny - the number of bins used for y.
binx_spacing - the spacing of the bins used for x.
biny_spacing - the spacing of the bins used for y.
binx_bound_min - the minimum boundary bin value x.
biny_bound_min - the minimum boundary bin value y..
binx_bound_max - the maximum boundary bin value x..
biny_bound_max - the maximum boundary bin value y..
binx_center - a one-dimensional array of size nbinx containing the center points of each bin. For plotting these can be used as the "x" [abscissa].
biny_center - a one-dimensional array of size nbiny containing the center points of each bin. For plotting these can be used as the "y" [ordinate].
binx_bounds - a one-dimensional array of size (nbinx +1) containing the boundaries of each bin.
biny_bounds - a one-dimensional array of size (nbiny +1) containing the boundaries of each bin.

Description

The input arrays x and y are partitioned into nbinx and y sections. The user may set the desired minimum, maximum and the number of bins. The returned PDF will be in units of percent (%).

Examples

The following require that contributed.ncl be loaded prior to invoking the function.

       load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"

Example 1

Using default settings:

  x    = random_normal ( 0,50, (/96,144/))
  y    = random_normal (10,25, (/96,144/))
  pdf2 = pdfxy(x, y, 0, 0, False)   ; default is 25 bins
  printVarSummary( pdf2 )

The printVarSummary yields:


Variable: pdf2
Type: double
Total Size: 5000 bytes
            625 values
Number of Dimensions: 2
Dimensions and sizes:   [y | 25] x [x | 25]
Coordinates: 
            y: [-194.5512237548828..204.6318817138672]
            x: [-79.46327590942383..103.8606376647949]
Number Of Attributes: 12
  _FillValue :  1e+20
  binx_center : 
  binx_bounds : 
  biny_center : 
  biny_bounds : 
  biny_bound_min :      -202.8675
  biny_bound_max :      212.9482
  binx_bound_min :      -83.28252410888672
  binx_bound_max :      107.6798858642578
  binx_spacing :        7.638496398925781
  nbinsx :      25
  nbinsy :      25

The print(zpdf@bin_center+" "+zpdf) yields:

(0)     pdf2@binx_center=-79.4633   pdf2@biny_center=-194.551
(1)     pdf2@binx_center=-71.8248   pdf2@biny_center=-177.919
(2)     pdf2@binx_center=-64.1863   pdf2@biny_center=-161.286
(3)     pdf2@binx_center=-56.5478   pdf2@biny_center=-144.653
(4)     pdf2@binx_center=-48.9093   pdf2@biny_center=-128.021
(5)     pdf2@binx_center=-41.2708   pdf2@biny_center=-111.388
(6)     pdf2@binx_center=-33.6323   pdf2@biny_center=-94.7554
(7)     pdf2@binx_center=-25.9938   pdf2@biny_center=-78.1228
(8)     pdf2@binx_center=-18.3553   pdf2@biny_center=-61.4902
(9)     pdf2@binx_center=-10.7168   pdf2@biny_center=-44.8576
(10)    pdf2@binx_center=-3.07831   pdf2@biny_center=-28.2249
(11)    pdf2@binx_center=4.56018   pdf2@biny_center=-11.5923
(12)    pdf2@binx_center=12.1987   pdf2@biny_center=5.04033
(13)    pdf2@binx_center=19.8372   pdf2@biny_center=21.673
(14)    pdf2@binx_center=27.4757   pdf2@biny_center=38.3056
(15)    pdf2@binx_center=35.1142   pdf2@biny_center=54.9382
(16)    pdf2@binx_center=42.7527   pdf2@biny_center=71.5708
(17)    pdf2@binx_center=50.3912   pdf2@biny_center=88.2035
(18)    pdf2@binx_center=58.0297   pdf2@biny_center=104.836
(19)    pdf2@binx_center=65.6682   pdf2@biny_center=121.469
(20)    pdf2@binx_center=73.3067   pdf2@biny_center=138.101
(21)    pdf2@binx_center=80.9451   pdf2@biny_center=154.734
(22)    pdf2@binx_center=88.5836   pdf2@biny_center=171.367
(23)    pdf2@binx_center=96.2221   pdf2@biny_center=187.999
(24)    pdf2@binx_center=103.861   pdf2@biny_center=204.632

A simple contour plot could be generated by using the


  wks  = gsn_open_wks ("x11","PDFX")
  res  = True
  res@gsnCenterString = "default 25 bins"
  plot = gsn_csm_contour (wks, pdf2, res)

Example 2:

Have NCL calculate "nice" boundary bin values and spacing.

  opt          = True
  opt@bin_nice = True
  pdf2 = pdfxy(x, y, 0, 0, opt)

Example 3: