Using NCL in the Yellowstone environment

Interactive use | Submitting a batch script | Visualization examples

The Yellowstone environment supports the use of NCAR Command Language (NCL) both interactively and in batch mode to analyze and visualize data.

As described below, to use NCL in the Yellowstone environment you will:

  • Log in to Yellowstone,
  • Start an interactive job on Geyser (recommended) or Caldera and execute the NCL script from that window, or
  • Submit a batch job to execute an NCL script.

Follow the instructions below to get started, and customize the sample scripts and commands as necessary to work with your own data.

Other resources

See the NCL web site for complete documentation of the language's extensive analysis and visualization capabilities.

See the NCL Applications page for links to hundreds of complete NCL scripts that you can download and modify as needed.

See the NCL on Yellowstone webinar video and slides.


Interactive use

To start an interactive window from which to modify and execute NCL scripts, log in to Yellowstone.

ssh -X yellowstone.ucar.edu

Submit a bsub command as follows to open a new shell on Geyser. (Adjust the wall-clock time as needed and insert your own project code.)

bsub -Is -q geyser -W 1:00 -n 1 -P project_code $SHELL

When your job starts, run this command in your new shell to load the default module for NCL:

module load ncl

Modify your NCL script if necessary using a UNIX editor, and execute it as shown here, substituting the name of your own NCL script for script_name.ncl.

ncl script_name.ncl

Submitting a batch script

If you expect running your NCL script to take longer than you would want to work interactively — overnight, for example — submit your NCL script in a batch job so it can run unattended.

To submit a batch job, use the command bsub with the redirect sign (<) and the name of your batch script file.

bsub < myjob.bsub

You can use the following sample script. Be sure to adjust the wall-clock time as needed, insert your own project code, and substitute the name of your own NCL script for script_name.ncl.

You might also find LSF's "command file" feature useful for performing a number of related NCL tasks in parallel. See Using command files in batch jobs for more information.

Sample batch script

#!/bin/tcsh
#
# LSF batch script to run an NCL script
#
#BSUB -P project_code        # project code
#BSUB -W 02:00               # wall-clock time (hrs:mins)
#BSUB -n 1                   # number of tasks in job         
#BSUB -J myjob               # job name
#BSUB -o myjob.%J.out        # output file name in which %J is replaced by the job ID
#BSUB -e myjob.%J.err        # error file name in which %J is replaced by the job ID
#BSUB -q geyser              # queue


source /glade/u/apps/opt/lmod/4.2.1/init/tcsh
module load ncl
ncl script_name.ncl

Visualization examples

Example 1

Make an NCL script file named contour_ts_line.ncl using the sample script below.

When you run it on Geyser, it will create a simple line contour plot (Figure 1) using a sample CMIP5 NetCDF data file in the /glade/u/sampledata/ncl/CESM/CAM5 directory. The output to your working directory will be a graphic file called contour_ts_line.png.

NCL visualization
Figure 1 - Click to see a larger image.

 

Sample NCL script

;----------------------------------------------------------------------
; This script creates a simple line contour plot of the first timestep
; of the "ts" variable on the given NetCDF file.
;----------------------------------------------------------------------

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl" 

begin
;---Open file and read data
  dir      = "/glade/u/sampledata/ncl/CESM/CAM5/"
  filename = "ts_Amon_CESM1-CAM5_historical_r1i1p1_185001-200512.nc"
  a        = addfile(dir+filename,"r") 

  ts       = a->ts(0,:,:)            ; Read first time step
  ts       = ts-273.15               ; convert from Kelvin->Celsius
  ts@units = "degC"

;---Look at the variable's metadata, if desired
  printVarSummary(ts)

;---Open file or window to send graphical output to.
  wks = gsn_open_wks("png","contour_ts_line")   ; "png", "ps", "pdf", "x11"

;---Create a default line contour plot.
  res  = True
  plot = gsn_csm_contour_map(wks,ts,res)

end

 

Example 2

Using a different script, you can create a more interesting visualization with the data that was used in the first example.

Make an NCL script file named contour_ts_color.ncl using the sample script below.

When you run it on Geyser, the output to your working directory will be a color-filled contour (Figure 2) called contour_ts_color.png.

NCL visualization
Figure 2 - Click to see a larger image.

 

Sample NCL script

;----------------------------------------------------------------------
; This script creates filled contour plot of the first timestep of
; the "ts" variable on the given NetCDF file.
;----------------------------------------------------------------------

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl" 

begin
;---Open file and read data
  dir      = "/glade/u/sampledata/ncl/CESM/CAM5/"
  filename = "ts_Amon_CESM1-CAM5_historical_r1i1p1_185001-200512.nc"
  a        = addfile(dir+filename,"r")

  ts       = a->ts(0,:,:)        ; Read first time step.
  ts       = ts-273.15           ; Convert from Kelvin -> Celsius.
  ts@units = "degC"

;---Look at the variable's metadata, if desired
  printVarSummary(ts)

;---Open file or window to send graphical output to.
  wks = gsn_open_wks("png","contour_ts_color")   ; "png", "ps", "pdf", "x11"

;---Set some graphical resources to customize the contour plot.
  res                   = True

  res@gsnMaximize       = True        ; Maximize plot in frame

  res@cnFillOn          = True        ; Turn on contour fill
  res@cnLinesOn         = False       ; Turn off contour lines
  res@cnLineLabelsOn    = False       ; Turn off line labels

  res@tiMainString      = filename    ; Add a main title

  res@gsnAddCyclic      = True        ; Add longitude cyclic point

;--Set the contour levels using "nice_mnmxintvl" function.
  mnmxint = nice_mnmxintvl( min(ts), max(ts), 18, False)
  res@cnLevelSelectionMode = "ManualLevels"
  res@cnMinLevelValF       = mnmxint(0)
  res@cnMaxLevelValF       = mnmxint(1)
  res@cnLevelSpacingF      = mnmxint(2)/4.  ; Decrease spacing for more levels

;---Create and draw the plot.
  plot = gsn_csm_contour_map(wks,ts,res)
end