Learning NCL by example

home | toc | about doc | intro | examples | basics | beyond basics | hints and tips | appendix | glossary

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: 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:

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.


home | toc | about doc | intro | examples | basics | beyond basics | hints and tips | appendix | glossary