NCAR Command Language NCL

1
NCAR Command Language - NCL

• Juli Rew
• CISL
• SOARS, June 4, 2008

2
What We Will Study

• Overview of NCL
• Strategies for Survival
• Work with Example Programs

3
What is NCL?

• NCAR Command Language is a complete programming
  language for processing data and producing
  high-quality 2D graphics
• NCL commands can be run at the command line, or
  they can be placed in batch scripts

4
NCL History

• NCL is built on top of NCAR Graphics, which was
  originally written in Fortran
• NCAR Graphics was re-written in object-oriented
  form, and NCL works with graphical objects
• Thanks to Mary Haley of the CISL Visualization
  and Technology Section for much of the training
  information given here

5
Why Use NCL?

• Freely available
• Easier to use than conventional programming
• Competes well with expensive products such as IDL
• Versatile - it can accept and output data in a
  variety of formats
• Produces publication-quality graphics

6
Strategies for Survival

• NCL has so many features that it can take a lot
  of time to master
• NCL has around 800 functions
• Before writing any new NCL code, look at the
  downloadable examples to see if one fits
• GSUN tutorialhttp//www.ncl.ucar.edu/Document/Man
  uals/Getting_Started/
• GSUN line-by-line exampleswww.ncl.ucar.edu/Docume
  nt/Manuals/Getting_Started/examples.shtml

7
Strategies for Survival, cont.

• Use the gsn and csm libraries
• Documentation is available online
  athttp//www.ncl.ucar.edu/
• Help from fellow users by joiningncl-talk_at_ucar.ed
  u
• Subscribe at http//mailman.ucar.edu/mailman/list
  info/ncl-talk
• Support Mary Haley (haley_at_ucar.edu, ML 35)

8
NCL Syntax

• begin/end - to start/end scripts (optional)
• - Comment
• _at_ - Attribute, e.g.,temperature_at_units Degrees
  C
• Operators like Fortran - - , .le., .lt., etc.
• All parameters are passed by reference (as in
  Fortran)

9
Arrays

• Indexes start at 0 (similar to C)
• 1D, integer a (/1,2,3/)
• 2D, float b (/ (/1.1, .01/), /(.001,.0001/) /)
• Whole-array syntax is like Fortranabab (more
  efficient than looping to copy array)

10
Syntax, cont.

• Dimensions can be namedtemperature!0
  frtimetemperature!1 lattemperature!2
  lon
• Strings - enclosed in double quotes

11
Syntax, cont.

• Coordinate variables- 1D arrays with same name
  and size as the dimensions they are assigned to-
  Represent data coordinates for each index of a
  named dimension- Must be monotonically
  increasing/decreasingtemperaturefrtime
  forecast timestemperaturelat
  lat_pointstemperaturelon lon_points
• Coordinate subscriptstemperature
  (0,2060,-95-120)

12
Graphics

• We will emphasize graphics features here
• Some examples of input and output to/from ASCII
  text and netCDF data files

13
Minimum Steps Needed to Create a Plot

• Load necessary libraries
• Open workstation to send graphics to
• Change the color map (optional)
• Set plot resources (optional)
• Draw the graphics

14
1. Load the Necessary Libraries

• load "NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_cod
  e.ncl"
• load "NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm
  .ncl
• First library contains generic interfaces and
  supplemental routines
• Second library contains gsn_csm interfaces that
  use CSM conventions. Load order is important.
• CSM conventions are accepted ways to label data,
  e.g., units

15
basic interface
metadata aware interface
16
2. Open graphics workstation

• Can be PostScript (PS or EPS), PDF, X11 window,
  or NCAR CGM (NCGM)
• Has a default color map associated with it, but
  you will probably want to change this (more
  later)
• Can have up to 15 multiple workstations open

wks gsn_open_wks(x11,test) x11
window wks gsn_open_wks(ps,test)
test.ps wks gsn_open_wks(eps,wrf)
wrf.eps wks gsn_open_wks(pdf,slp)
slp.pdf
17
3. Change the color map (optl)

• Do this before drawing anything to the frame.
• If you use the same color map a lot, can put in
  .hluresfile (more later)
• Can use one of the other 40 ones, or create your
  own.
• If you dont change the color map, heres what
  youll get

gsn_define_colormap(wks,rainbow)
18
Default color table (yuck)
19
4. Set optional resources

• Resources are the heart of your NCL graphics
  code.
• There are over 1,400 resources!
• Resources are grouped by object type.
• There are 11 graphical objects contours,
  labelbars, legends, maps, primitives,
  streamlines, text strings, tickmarks, titles,
  vectors, XY plots

20
Detour Anatomy of a resource

• Starts with 2 or 3 lower-case letters based on
  object it is associated with. Some examples
• xy - XY Plots cn - Contour plots
• vc - Vector plots ti - Titles
• tm - Tickmarks gsn - special resources not
  associated with any object
• Made up of full words with first letter of word
  capitalized
• xyLineColor, cnFillOn, tiMainString,
  vcRefMagnitudeF, gsnMaximize
• Some have an F on the end to indicate a
  floating point resource xyLineThicknessF

21
Anatomy of a resource (contd)

• Resources are set by attaching them as attributes
  to an NCL logical variable
• res True
• res_at_mpMinLatF 30 decimal not necessary
• Most have default values.
• There are many types
• res_at_tiMainString This is a title
• res_at_tmXBLabelFontHeightF 0.01
• res_at_cnLineLabelsOn True
• res_at_xyLineColors (/5,7,11/)
• res_at_xyLineColors (/red, green, blue/)

http//www.ncl.ucar.edu/Document/Graphics/Resource
s/
22
5. Draw the graphics

• Call one of the gsn_csm_xxxxx functions from the
  second library we loaded.
• The general format is
• plot gsn_csm_contour(wks,data,res)
• plot gsn_csm_vector(wks,u,v,res)
• plot gsn_csm_contour_map(wks,data,res)
• plot gsn_csm_pres_hgt(wks,data,res)

http//www.ncl.ucar.edu/Document/Graphics/Interfac
es/
23
Now for Some NCL Graphics Code Examples

• NCL scripts that follow can be downloaded from
  the web

http//www.ncl.ucar.edu/Training/Workshops/Scripts
/ Scripts have names like xy1a.ncl, xy1b.ncl,
The first one is usually one with no resources
set, and each subsequent script adds a few more
resources.
24
Running NCL

• setenv NCARG_ROOT /ncl-4.2.0.a034
• Go to example NCL scripts directorycd SOARS/NCL
• To run these scriptsncl xy1a.ncl
• Lets look at whats in our first script using
  vivi xy1a.ncl

25
Example xy1b.ncl gsn_csm_y

• Line color changed
• (using color index values)
• Default color map used
• Resource introduced
• xyLineColor - sets curve color

26
Example xy1c.ncl gsn_csm_xy

• X values added
• Line color changed (using named color)
• Line thickness increased
• long_name attributes set
• Resource introduced
• xyLineThicknessF - sets line thickness

27
Example xy1d.ncl gsn_csm_xy

• Axes limits changed
• Resources introduced
• trYMinF, trYMaxF, trXMinF, trXMaxF - sets mins
  and maxes for X and Y axes (transformation
  resources)
• These resources can also apply to contour,
  vector, and streamline plots

28
Example xy1e.ncl gsn_csm_xy

• Dash pattern set for curve
• Title resources set
• Resources introduced
• xyDashPattern - sets dash pattern for curve (17
  available)
• tiMainString, tiXAxisString, tiYAxisString - sets
  strings for axes and main title, can also be used
  for contour, vector, etc, plots
• If have both long_name attributes and tiX/YString
  set, ti resources will take effect

29
Example xy1f.ncl gsn_csm_xy

• Explicitly set the bottom tickmark labels
• Resources introduced
• tmXBMode, tmXBValues, tmXBLabels - sets strings
  for bottom tickmarks
• Note about tickmark resources all four sides of
  the axes have their own set of tickmarks, for
  example
• tmYLMode (Y left), tmYRMode (Y right), tmXTMode
  (X top)

30
Example rose_1.ncl

• Generating some bogus wind data
• Each array entry has two components wind speed
  and wind direction
• There is a special function for creating wind
  roses, called WindRoseBasic
• Data will be written to an ASCII file
• This example online athttp//www.ncl.ucar.edu/App
  lications/rose.shtml

31
Example rose_1a.ncl

• Now we are reading our data from an ASCII file
  called Bogus.dat that we created previously
• Recall that there are two components to each
  array entry

32
Example contour.ncl

• This example reads from a netCDF file and
  contours the temperature fields
• Fourth plot uses a predefined color table
  seewww.ncl.ucar.edu/Document/Graphics/color_table
  _gallery.shtml
• Original example online atwww.ncl.ucar.edu/Docum
  ent/Manuals/Getting_Started/Examples/gsun02n.shtml

33
Animation

• Animate NCL image files using idt (part of NCL)
• Movies Save series of images to Postscript
  files. Convert images to mpg using convert
  utility of ImageMagick
• Or use utility such as ncview to view netCDF data
  file
• Example moviehttp//www.cisl.ucar.edu/docs/hpc_m
  odeling/graphics.jsp

34
More Training Available

• NCL Workshop this summer July 8-11
• Register by July 1
• Infohttp//www.ncl.ucar.edu/Training/Workshops/