Learning NCL by example

Introducing the GSUN functions and procedures
Setting up your environment to run NCL
How to run the examples
General NCL example code structure
The GSUN examples

This chapter is intended to be a step-by-step guide to NCL, introducing new features and concepts through a series of NCL example scripts (also called "programs"). This chapter works best if you read through these examples in order, since new concepts are documented only in the example where they are first introduced.

Introducing the GSUN functions and procedures

The examples in this section all use a set of NCL functions and procedures that are defined in the NCL file gsn_code.ncl and prefixed with "gsn_" (from here on referred to as "GSUN"). It is not important to understand how the code in this file works, but after you read through all of the NCL examples and feel comfortable with them, it will be instructive to examine the gsn_code.ncl file. The GSUN functions and procedures are documented in the appendix, and they will also be discussed in the examples in which they are first invoked.

For examples on how to write NCL scripts that don't use the GSUN functions and procedures, see the section "NCL and object-oriented programming" in the "Going beyond the basics" chapter.

The examples in this section also use several NCL built-in functions and procedures. There are over 200 of these built-in functions and procedures, and they are documented in the "Built-in NCL functions and procedures" section of the NCL Reference Manual.

Setting up your environment to run NCL

Before you can run NCL on the examples in this chapter, the following basic requirements must be met:

NCAR Graphics Version 4.1 or later must be installed on your system.
The environment variable NCARG_ROOT must be set to the parent directory of where NCAR Graphics is installed on your system. For example, if the NCAR Graphics libraries and binaries are installed in /usr/local/lib and /usr/local/bin respectively, then NCARG_ROOT should be set to /usr/local.
The directory $NCARG_ROOT/bin must be added to your PATH environment variable.

To find out what version of NCAR Graphics you are running, type ncargversion at the UNIX prompt. If the ncargversion command cannot be found, or if the version reported is not 4.1 or later, or if you are unsure about any of the above requirements, contact your system administrator or the person responsible for installing NCAR Graphics on your system.

How to run the examples

The NCL code for the examples in this chapter all have the name gsun#n.ncl, where # is the example number (01, 02, ..., 10, 11, etc). Links are provided from each example section so you can download these examples from the web.

To run these examples, the following requirements must be met:

The examples display graphics to an X11 window (unless otherwise noted), so you must have your DISPLAY environment variable set correctly. Also, when running these examples, you'll need to click on this X11 window with your left mouse button to advance to the next frame or to close the current frame.
Some of the examples write data or graphic files, so be sure you are in a directory where you have write permission.
You must download the NCL file gsn_code.ncl and put it in the same working directory as the NCL examples that follow.
Some of the examples have additional files that you need to download, like a resource file or a data file. In the description of each example, links are provided for the extra files you need.

Once you have the gsun#n.ncl and gsn_code.ncl files in your current working directory (and any other files needed), then you can run the example with the command:

ncl < gsun#n.ncl

General NCL example code structure

The general code structure of the NCL examples in this chapter is as follows:

Read data: Data are either generated from within the NCL program or read from one of many file types (ASCII, netCDF, GRIB, etc.)
Process data: Some of the examples show how to process data by converting units, masking values, interpolating to a regular grid, etc.
Visualize data: Every example generates one or more graphical plots, including XY plots, contour plots, and vector and streamline plots.
Write data: Some of the examples show how to write data to a file.

The GSUN examples

Each example module begins with a short description of that example, followed by images of the graphical output, followed by the numbered NCL code used to generate the output, followed by a line-by-line description of the code. Note: Concepts that are used repeatedly in the examples will not be described in every example, so it's important to read them in order. Because of this, not every line of every example will be documented; only those lines that introduce new concepts or are worth repeating will be described.

Example 1 This example introduces the basics of NCL, like how to begin and end an NCL script, how to create and initialize variables, how to create and draw XY plots, and how to set resources to change the look of the XY plots. It also introduces the concept of NCL variables containing metadata and shows how to read data from an ASCII file.
Example 2 This example shows how to read data from a netCDF file, how to change the color map, how to create and draw contour plots, how to print variables, and how to write data to an ASCII file.
Example 3 This example shows how to read data from a netCDF file, how to retrieve coordinate variables from a file, how to change the color map, and how to create and draw vector plots. It also discusses the concept of having missing values in your data.
Example 4 This example shows how to retrieve information about and read data from a GRIB file, how to use "if-end if" statements, how to use stride values to select part of an array, how to retrieve resource values, how to create and draw streamline plots, how to write data to a netCDF file, and how to use "do" loops.
Example 5 This example reads data from a netCDF file and shows how to "name" your dimensions, how to retrieve the current color map and change its values, how to overlay contour plots on various map projections, how to fill certain contour levels, how to do masking, and how to draw text strings anywhere you want.
Example 6 This example reads data from a netCDF file, and shows how to overlay vector plots on various map projections, how to thin your vector data, and how to increase the size of your plots.
Example 7 This example shows how to use Fitgrid to do interpolations, how to draw two XY plots in the same frame, and how to use text, polyline, and polymarker procedures to draw text, lines, and markers anywhere on your frame.
Example 8 This example reads data from an ASCII file, and shows how to use Natgrid to interpolate randomly-spaced 2-dimensional coordinates with functional values to a user-defined 2-dimensional grid, how to open three different types of workstations, and how to swap dimensions in a multi-dimensioned array. It creates and draws a contour plot and an XY plot. It also shows how to use a resource file to set all the fonts in the plot to "Times-Roman".
Example 9 This example shows how to create an NCL function, how to use NCL built-in functions for doing averaging and masking, how to set resources after a plot has been created, and how to do a 12-frame contour animation. This example uses an extensive resource file.
Example 10 This example shows how to create a publication-quality XY plot, and how to use text function codes to get super/subscripting and line feeds in your text strings.
Example 11 This example reads data from an ASCII file and creates both a contour plot and an XY plot. It shows how to have different scales on your Y axis in your contour plot (including changing one of the scales to "log"), how to define your own tick mark labels, and how to retrieve your contour levels and then fill them according to what ranges they fall in.

Example 1	This example introduces the basics of NCL, like how to begin and end an NCL script, how to create and initialize variables, how to create and draw XY plots, and how to set resources to change the look of the XY plots. It also introduces the concept of NCL variables containing metadata and shows how to read data from an ASCII file.
Example 2	This example shows how to read data from a netCDF file, how to change the color map, how to create and draw contour plots, how to print variables, and how to write data to an ASCII file.
Example 3	This example shows how to read data from a netCDF file, how to retrieve coordinate variables from a file, how to change the color map, and how to create and draw vector plots. It also discusses the concept of having missing values in your data.
Example 4	This example shows how to retrieve information about and read data from a GRIB file, how to use "if-end if" statements, how to use stride values to select part of an array, how to retrieve resource values, how to create and draw streamline plots, how to write data to a netCDF file, and how to use "do" loops.
Example 5	This example reads data from a netCDF file and shows how to "name" your dimensions, how to retrieve the current color map and change its values, how to overlay contour plots on various map projections, how to fill certain contour levels, how to do masking, and how to draw text strings anywhere you want.
Example 6	This example reads data from a netCDF file, and shows how to overlay vector plots on various map projections, how to thin your vector data, and how to increase the size of your plots.
Example 7	This example shows how to use Fitgrid to do interpolations, how to draw two XY plots in the same frame, and how to use text, polyline, and polymarker procedures to draw text, lines, and markers anywhere on your frame.
Example 8	This example reads data from an ASCII file, and shows how to use Natgrid to interpolate randomly-spaced 2-dimensional coordinates with functional values to a user-defined 2-dimensional grid, how to open three different types of workstations, and how to swap dimensions in a multi-dimensioned array. It creates and draws a contour plot and an XY plot. It also shows how to use a resource file to set all the fonts in the plot to "Times-Roman".
Example 9	This example shows how to create an NCL function, how to use NCL built-in functions for doing averaging and masking, how to set resources after a plot has been created, and how to do a 12-frame contour animation. This example uses an extensive resource file.
Example 10	This example shows how to create a publication-quality XY plot, and how to use text function codes to get super/subscripting and line feeds in your text strings.
Example 11	This example reads data from an ASCII file and creates both a contour plot and an XY plot. It shows how to have different scales on your Y axis in your contour plot (including changing one of the scales to "log"), how to define your own tick mark labels, and how to retrieve your contour levels and then fill them according to what ranges they fall in.