NCL Home > Documentation > Functions > General applied math

pdfx

Generates a univariate probability density distribution (PDF).

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 pdfx (
		x        : numeric,  
		nbin [1] : integer,  
		opt  [1] : logical   
	)

	return_val [*] :  double

Arguments

An array of any dimensionality.

nbin

Number of bins to use. Specifying 0 will result in 25 bins being used. Otherwise, this must be greater than 2.

opt

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

Setting opt=True will activate use of the options.

v510 - The original pdfx has been modified. The new [5.1.1] function was created to be more consistent with the pdfxy released with 5.1.1. Setting the v510 attribute to True will result in the original v5.1.0 version being used. [see Description]
bin_min - minimum value for the bin boundary.
bin_max - maximum value for the bin boundary.
bin_nice - "nice" bin boundary values and spacing will be calculated. If the user has specified nbin, it will be ignored and the calculated number of bins will be used.

Return value

A one-dimensional (double) array of size nbin or, if the nbin argument is set to zero, 25. The PDF units are percent [%]. The following attributes will be associated with the return variable.

nbins - the number of bins used.
bin_spacing - the spacing of the bins used.
bin_bound_min - the minimum boundary bin value.
bin_bound_max - the maximum boundary bin value.
bin_center - a one-dimensional array of size nbins containing the center points of each bin. For plotting these can be used as the "x" [abscissa].
bin_bounds - a one-dimensional array of size (nbins +1) containing the boundaries of each bin.

Description

The input array x is partitioned into nbin sections. The user may set the desired minimum, maximum and the number of bins.

The original version of pdfx was released in version 5.1.0. The pdfxy function was released with version 5.1.1. To make the pdfx consistent with the binning used with pdfxy, the function was altered: (a) The default number of bins was changed from 50 to 25; (b) the method used to create the bins was changed; (c) the returned units were changed from fraction to percent. Setting the v510 attribute to True will result in the original version of pdfx being used.

pdfx returns type "double". If type float is desired, use dble2flt.

NCL has a specialized histogram plot function. This creates very nice looking plots and returns information as attributes. See below.

Examples

Example 1

Using default settings:

  z    = random_normal (0,50, (/96,144/))
  zpdf = pdfx(z, 0, False)   ; default is 25
  printVarSummary( zpdf )

The printVarSummary yields:


Variable: zpdf
Type: double
Total Size: 200 bytes
             25 values
Number of Dimensions: 1
Dimensions and sizes:   [x | 25]
Coordinates: 
            x: [-194.2047106424968..221.6110242207845]
Number Of Attributes: 10
  bin_center :  
  bin_bounds :  
  bin_bound_min :       -202.8675384521484
  bin_bound_max :       230.2738520304362
  bin_spacing : 17.32565561930339
  nbins :       25
  nMax :        13824
  nUse :        13824
  long_name :   PDF
  units :       frequency

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

(0)    -194.205   0.000217014
(1)    -176.879   0
(2)    -159.553   0.000868056
(3)    -142.228   0.00253183
(4)    -124.902   0.00679977
(5)    -107.576   0.0143229
(6)    -90.2508   0.0284288
(7)    -72.9251   0.0485388
(8)    -55.5995   0.0744358
(9)    -38.2738   0.098235
(10    -20.9482   0.126447
(11)    -3.6225   0.1386
(12)    13.7032   0.133825
(13)    31.0288   0.112992
(14)    48.3545   0.0882523
(15)    65.6801   0.0578704
(16)    83.0058   0.0350116
(17)    100.331   0.0183738
(18)    117.657   0.00896991
(19)    134.983   0.00325521 
(20)    152.308   0.00130208
(21)    169.634   0.00036169
(22)    186.96    0.000217014
(23)    204.285   7.2338e-05
(24)    221.611   7.2338e-05

A simple x-y plot could be generated by using the returned bin_center atribute values as "x" and the "zpdf" values as "y".


  wks  = gsn_open_wks ("x11","PDFX")
  res  = True
  res@gsnCenterString = "default 25 bins"
  plot = gsn_csm_xy (wks, zpdf@bin_center, zpdf, res)

The default return type is "double". The above could be changed to "float" via

  zpdf = dble2flt(pdfx(z, 0, False) )

Example 2:

Specify that 50 bins be used and the minimum and/or maximum boundary bin values to use. This will result in a more 'ragged' PDF.

  opt         = True
  opt@bin_min = -250.
  opt@bin_max =  250.
  zpdf = pdfx(z, 50, opt)

Example 3:

Specify that 35 bins be used and have the function calculate "nice" boundary bin values and spacing.

  opt          = True
  opt@bin_nice = True
  zpdf = pdfx(z, 35, opt)

Example 4:

Calculate the probability density distributions of multiple arrays and plot the distributions of each on a single plot. The arrays need not be the same size or shape but they must be of the same variable. Let a(nt,nn,mm), b(kk), c(jdim,idim) be from different sources,

See Examples 1 and 2 at:

Probability Distributions

Example 5:

Use the original pdfx version.