NCL Website header
NCL Home> Application examples> Special plots || Data files for some examples

Example pages containing: tips | resources | functions/procedures

Special Topics: Histograms

gsn_histogram is available from NCL version 4.2.0.a017.

There is one other histogram resource that has not been demonstrated on this page:

gsnHistogramBinWidth Instead of indicating number of bins, you can specify a bin width. Depending on how gsnHistogramSelectNiceIntervals is set, you will either get bins of exactly this size, or approximately this size.

histo_1.ncl: Example of a default histogram. The default number of bins is approximately 10. NCL will determine the number of bins that result in nice intervals.

gsn_histogram is the plot interface that creates histograms.

histo_2.ncl: Histograms can be panelled.

tmXBLabelStride = 2, Plots every other x-axis tickmark label.

gsnHistogramNumberOfBins, Selects the number of bins. Note, in this example, you are still getting less than the expected number of bins, because NCL is still automatically selecting nice bin intervals.

histo_3.ncl: An example of integer data in discrete bins.

By default, gsn_histogram will bin your data into intervals. If you set gsnHistogramDiscreteBinValues, then your data is assumed to already be "binned", and it just counts the number of values exactly equal to the mid points. The resource gsnHistogramDiscreteClassValues behaves the same way.

In this example we used ispan to create an integer array of bin values.

histo_4.ncl: Overriding the default behavior to force the exact number of bins. This results in float labels.

gsnHistogramSelectNiceIntervals turns off the nice labels and allows the data to be binned in the exact number specified.

gsnHistogramComputePercentages = True, Then percentage values will be put on right axis. This resource will include missing values in the calculation. If you do not want missing values included, then set gsnHistogramComputePercentagesNoMissing = True. If you would rather have a percent sign rather than "percent" label this axis, then set gsnHistogramPercentSign= True.

tmXBLabelAngleF = 315., will rotate a tick mark label.

histo_5.ncl: Explicitly select the bin intervals.

gsnHistogramClassIntervals allows the user to specify bin intervals. Note that with these different sized bins, the size of the histogram column remains the same by default.

If there is data outside the range of the bins you have chosen, they will not be counted. You can set gsnHistogramMinMaxBinsOn to get a bins that include all values that are greater than and less than the max and min bins you have selected. This resource only works when gsnHistogramClassIntervals or gsnHistogramBinIntervals is also selected.

histo_6.ncl: Compares two arrays. Both arrays are combined into a single array with the first dimension equal to 2.

gsnHistogramCompare, will create two histograms, one set of bars drawn behind the other.

In the second frame, the colors for each bar are explicitly set with gsnHistogramBarColors, a new resource only available in NCL V6.4.0 or later.

histo_6a.ncl: This example uses the same data as the previous histo_6.ncl example, except it shows how to improve the look of a histogram by setting resources to increase the density of the fill patterns, increase the thickness of the fill pattern lines, and increase the thickness of the axis border and the tickmarks.

The histogram axes and filled bars are drawn internally by using calls to gsn_csm_xy and gsn_add_polygon, so by setting various GraphicStyle (gsXXXX) and TickMark (tmXXXX) resources, this affects the look of the histogram bars. Here are the resources set in this example:

histo_7.ncl: Demonstrates changing the color of the bins.

gsFillColor controls the color of the bins. If you set it equal to one color the entire histogram will be that color. If you set it to an array of colors it will cycle through that array and repeat if necessary.

gsFillIndex will change the fill pattern. Default is 0 or solid fill. There are many fill patterns to choose from. gsFillIndex will change the fill pattern. Default is 0 or solid fill. There are many fill patterns to choose from.

histo_8.ncl: A horizontal histogram.

gsnHistogramHorizontal will draw a horizontal histogram.

histo_9.ncl: A highly specialized plot that draws a histogram on top of a map.
histo_10.ncl: Demonstrates how to overlay multiple histograms on top of each other so that more than two histograms can be compared. If you only have two, see example 6.

First we set the color of the histograms to transparent using gsFillColor, and then color the bin edges using gsEdgeColor. With the various colors, you can distinguish the height of the various bins. The color of the last overlay will be the one on top .

histo_11.ncl: Demonstrates how to change the width of the histogram bars using the gsnHistogramBarWidthPercent resource.
histo_12.ncl: Demonstrates how to add text at the top of each bar, using information returned from gsn_histogram.

The third frame was added later, showing how to do a histogram comparison and lots of customization of tickmarks.

histo_13.ncl: The tickmarks on the bottom axis of a histogram are labelled by setting tmXBMode to "Explicit", and setting tmXBValues and tmXBLabels to internally calculated values. The normal resources for trying to control precision and/or formatting will not work as expected.

This example demonstrates a kludgy method for reformatting the tickmark labels on the bottom axis, by using the "BinLocs" attribute returned by gsn_histogram.

histo_14.ncl: As explained in the previous example, you don't have much control over the tickmarks on the bottom axis. This example shows how to work around this to add minor tickmarks.

The special resource "MidBarLocs" is used to get the X axis locations of the middle of each bar, so we can add a minor tickmark. We have to draw the plot twice, so we can get both major and minor tickmarks. Because the size of the plot will actually change the second time, we need to retrieve the vpXF, vpYF, vpWidthF, and vpHeightF resources, and set these for the second plot.

histo_15.ncl: Demonstrates how to control the labeling of the X axis. You first have to create the histogram, and then the return plot it will have several attributes attached that provide information about the histogram:

  • NumInBins - An array containing the number of elements in each bin or range.
  • BinLocs - An array containing the location value of each bin.
  • BeginBarLocs - An array that gives the X NDC position of the beginning of each bar.
  • MidBarLocs - An array that gives the X NDC position of the midpoint of each bar.
  • EndBarLocs - An array that gives the X NDC position of the end of each bar.
For this example, the MidBarLocs array was used to select which tickmarks to label, and the labels were created manually.
histo_16.ncl: Demonstrates how to use return information from a histogram plot to further annotate it with text strings indicating the values of each bar.

The return information used is the NumInBins attribute for the number of values in each bar, and the MidBarLocs attribute for the X location for the midpoint of each bar.

The gsn_add_text function is used to attach labels to the top of each bar (first plot), and then inside each bar (second plot).

histo_17.ncl: Demonstrates how to stack histograms.

This script does it the "lazy" way, by drawing one histogram on top of another. The key is to draw the histograms with the largest number of values in each bin first. Each histogram is created first, so we can calculate the largest bin value. We use this value to "fix" the Y axis for each plot.