
gsn_histogram
Draws a histogram plot on the given workstation.
Prototype
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl" ; This library is automatically loaded ; from NCL V6.2.0 onward. ; No need for user to explicitly load. function gsn_histogram ( wks : graphic, data : numeric, res [1] : logical ) return_val [1] : graphic
Arguments
wksA Workstation identifier. The identifier is one returned either from calling gsn_open_wks or calling create to create a Workstation object.
dataThe data for the histogram. The data must either be one-dimensional for a single histogram, or two-dimensional where two histogram fields are drawn.
resA variable containing an optional list of resources to apply to the histogram, attached as attributes. Set to True if you want the attached attributes to be applied, and False if you either don't have any resources to set, or you don't want the resources applied.
Return value
A scalar id of the histogram plot created is returned. In addition, several attributes are returned:
- NumInBins - an array of the number of items in each bin.
- BinLocs - an array of the values of the bin
locations. This will be the end points of each bin if you have
intervals, or the actual values if you have discrete values.
- NumMissing - the number of missing values (if any).
- Percentages - an array of percentages indicating the distribution
of the bin values (missing values are counted in total)
- PercentagesNoMissing - an array of percentages indicating the
distribution of the bin values (missing values are not counted in
total)
- BeginBarLocs - an array indicating the X positions of the beginning location of each bar.
- MidBarLocs - an array indicating the X positions of the mid point location of each bar.
- EndBarLocs - an array indicating the X positions of the end location of each bar.
Description
This function draws a histogram plot, where values in the given data are binned into equally-spaced intervals. The intervals will be selected for you, based on the range of the data, unless you set the gsnHistogramBinIntervals resource to the desired list of interval values.
The data values will be binned as follows (assume there are n interval values, and thus n-1 bins):
bin1 <= data < bin2 bin2 <= data < bin3 ... binn-2 <= data < binn-1 binn-1 <= data <= binn
Note that the last interval is treated specially. This is intentional, to make sure that all data values that fall inclusively between the lowest and highest intervals are binned.
You can set the gsnHistogramMinMaxBinsOn resource to True to slightly alter the behavior of the binning as follows. This will effectively cause all of your data to be binned in the following fashion:
data < bin1 bin1 <= data < bin2 bin2 <= data < bin3 ... binn-1 <= data < binn binn <= data
To bin your data based on discrete values rather than intervals, use the gsnHistogramDiscreteBinValues resource.
Two histogram fields are drawn if data is two-dimensional. If missing values are encountered in data, then they are ignored.
There are many resources specific to this function. See the gsnHistogram resources for a full list.
To maximize the area that the plot is drawn in, set the special resource gsnMaximize to True.
See Also
bin_sum,
bin_avg
Special gsn resources
Examples
Example 1
The example below shows how to bin values between the given intervals. This script should produce two plots, each with three bars. The first plot will have bars all equal to 2. The second plot will have three bars with 2, 2, and 4 values respectively.
wks = gsn_open_wks("x11","histogram") res = True res@gsnMaximize = True res@gsnHistogramBinIntervals = (/1,2,5,7/) data = (/1,1.5,2,2.5,5.5,7/) plot = gsn_histogram(wks,data,res) data := (/1,1,2,2,5,5,7,7/) plot = gsn_histogram(wks,data,res)
Example 2
This example uses the same data as above, but with a different set of intervals and with gsnHistogramMinMaxBinsOn set to True.
This script should produce two plots, each with five bars. The first plot will have bar values of 2, 2, 1, and 1, respectively, and the second plot will have 2 values in each bar.
wks = gsn_open_wks("x11","histogram") res = True res@gsnMaximize = True res@gsnHistogramBinIntervals = (/2,4,6/) res@gsnHistogramMinMaxBinsOn = True data = (/1,1.5,2,2.5,5.5,7/) plot = gsn_histogram(wks,data,res) data := (/1,1,2,2,5,5,7,7/) plot = gsn_histogram(wks,data,res)
Example 3
The example below shows how to bin values exactly equal to the given values. This script should produce a plot with four bars with 3, 2, 1, and 0 values respectively.
wks = gsn_open_wks("x11","histogram") res = True res@gsnMaximize = True res@gsnHistogramDiscreteBinValues = (/1,2,5,7/) data = (/1,2.5,8.,2.1,3,5,4.2,1,1.2,0.5,2,2.5,1,5.5,2.0/) plot = gsn_histogram(wks,data,res)
Example 4
Assume you have a multi-dimensional array, x(time,lat,lon), and that a histogram of the entire array is desired. The function ndtooned can be used to reshape the array.
plot = gsn_histogram(wks,ndtooned(x),False)Example 5
If the "x" array from the previous example has lat/lon coordinate arrays, then you can plot a histogram for values between 30 south and 30 north latitude using coordinate subscripting:
plot = gsn_histogram(wks,ndtooned(x(:,{-30:30},:)),False)
For some more examples, see the suite of histogram plot examples.