NCAR Command Language http://ncl.ucar.

edu/

using NCL
NCL is case sensitive NCL can be used in interactive or batch mode well only use batch

commands in file file, optional (but

recommended) .ncl extension execute the commands by

ncl filename[.ncl] or ncl < filename[.ncl]

Data types

Numeric:
double (64 bit) float (32 bit) long (32 or 64 bit) integer (32 bit) short (16 bit) byte (8 bit) complex is not

Non-numeric: Non numeric:

string character graphic file logical list

supported

Syntax symbols

; @ ! & {...} $ [...] [ ] (/.../) : | \ :: ->

begins a comment create/reference attributes create/reference named dimensions create/reference a coordinate variable use for coordinate subscripting enclose strings when importing or exporting variables via addfile subscript variables of type list constructs an array use in array syntax use as a separator p for named dimensions continue statement for spanning multiple lines use as separator when calling external codes use for inputting/outputting supported data formats

Operators

Algebraic operators:
+ addition

Logical operators:
.lt. less than .le. less than or equal .gt. greater than .ne. not equal .eq. eq equal .and. and .or. or .xor. exclusive or .not. not

subtraction * multiplication ^ exponent % modulus modulus, integers only # matrix multiply > greater than < less than

Variables

Variable names
begin with an alphabetic character can contain any mix of numeric and

alphabetic characters, plus underscore may y have ancillary y information ( (metadata) ) attached to the variable

Arrays
arrays can have multiple dimensions standard subscripting

subscripts are zero zero-based based triplets start_index start index : end_index end index [: stride]

coordinate subscripting
uses a coordinate variable

Array expressions

array processing
element by element addition, subtraction,

multiplication, p , division

array conformance
array expressions require that all operands

have the same number of dimensions and same size dimensions

Array allocation
arrays are automatically allocated when they appear on the left-hand side of an expression p explicit array declaration using

array constructor (/ (//) /) new function

array constructor
a_integer a integer = (/1,2,3/) (/1 2 3/) a_float = (/1.0, 2.0, 3.0/) a_double a double = (/4d0,5d(/4d0,5d (/4d0 5d-5,1d30/) 5 1d30/) a_string = (/" (/"a","b","c a","b","c"/) "/) a_logical = (/True,False,True (/True,False,True/) /) a_2darray = (/(/1,2,3/),(/5,6,7/)/)

2 rows x 3 cols

new function

new(array_size_shape,type,[_FillValue])
a = new(3,float) ( ) b = new(10,float,1.e+20) c = new((/5,6,7/),integer) d = new(dimsizes(U),string) S = new(100,string)

File I/O

supported formats
netCDF HDF GRIB

or

HDF-EOS HDF EOS

binary files ascii files

addfile
addfile is used to read all supported file formats f = addfile( addfile(filename filename.ext ext, status)

ext: nc, grb, hdf, hdfeos optional on actual filename required in addfile to designate type status: r ( (read), ),

c ( (create) ) or w ( (write) )

importing/exporting data
addfile creates a reference to the file that can be used to import/export data from the file x = f->X

imports the variable X from file referenced

by f into the variable x also imports p metadata for X

binary files

fbinrecread fbinrecwrite fbinrecread,

unformatted, sequential file

fbindirread, fbindirwrite
direct access, access fixed record length

ascii files

asciiread asciiwrite asciiread,

Printing

p printVarSummary y
provides an overview of a variable including all

metadata

print i t
same as printVarSummary, followed by the

values for each element

sprinti, sprintf
provides some format control

write_matrix
prints data in tabular form

functions and procedures

functions return a value or values

appear in expressions

procedures do a specific task

100s of built-in functions and procedures http://www.ncl.ucar.edu/Document/Functions http://www ncl ucar edu/Document/Functions http://ww.ncl.ucar.edu/Document/Functions/Co ntributed user-defined functions and procedures

accessing useful libraries

include the following lines at the beginning of your ncl script

load $NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl l d $NCARG load $NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl ROOT/lib/ / l i t / / l load $NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl load $NCARG_ROOT/lib/ncarg/nclscripts/wrf/WRFUserARW.ncl load $NCARG $NCARG_ROOT/lib/ncarg/nclscripts/wrf/WRF_contrubuted.ncl ROOT/lib/ncarg/nclscripts/wrf/WRF contrubuted ncl

not all are required for everything you will do, do but all have nice features
as you get more proficient, you will know which library or libraries you

actually need to load

program control

by tradition, entire ncl program is contained within a begin end block, following any load statements begin : NCL statements : end

conditional execution
if (logical_expr) (logical expr) then : [ else :] end if

loops
do n = start, start end [ [,stride] stride] : end do do while (logical_expression) : end do

loop variation

break
jump to first statement after end do

continue
proceed directly to the next iteration

Lets make some pictures!

NCL graphics
NCL uses the concept of a workstation workstation that receives graphics objects graphics objects have attributes that can be modified

set through resources resources

high-level high level interfaces

setting resources for graphical objects can be tedious NCL had two high-level interfaces that simplify this process by providing templates for a wide variety of plot types

resources can be changed to modify default

style

some examples

http://www ncl ucar edu/gallery shtml http://www.ncl.ucar.edu/gallery.shtml

XY plots

Contour plots

contours over map

more contour/map plots

vector plots

vectors over maps

vectors contours & maps vectors,

streamlines over maps

time/lon or time/lat plots

Basic NCL graphics

load necessary libraries open workstation for graphics output change color map (optional) set graphics resources (optional) draw graphics

basic NCL graphics script

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl" l d "$ load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl" C G OO /lib/ / l i / / l" begin y = sin(0.0628*ispan(0,100,1)) wks = gsn_open_wks(ps,test) gsn_define_colormap(wks,rainbow) res = True res@xyLineColor = HotPink plot = gsn_csm_y(wks,y,res) end

; 101 points ; open workstation ; change colormap ; plot options ; line color ; no X values

1 Load necessary libraries 1.

Two ways of doing graphics in NCL:

a) Using object-oriented method b) Using high-level graphical interfaces

we will be using the second method, which requires that libraries be loaded loaded. two libraries: one is more metadata aware and contains functions that set aware more plot options on behalf of user

The two libraries

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

First library contains generic interfaces and supplemental routines

Second library contains gsn_csm gsn csm interfaces that use CSM conventions. Second library uses functions in first library, so load order is important.

What are CSM conventions?

_FillValue FillValue attribute recognized as missing value Attributes such as long_name g_ and units used for titles Coordinate arrays used for axes values If geo-referenced coordinate arrays, then units attribute of degrees_east or degrees_north d th expected t d

basic interface

metadata aware interface

automatic subtitles

contour line labels informational label tick marks out & lat/lon labels automatic label bar

2. Open graphics workstation

Can be PostScript (PS or EPS), PDF, X11 window, or NCAR CGM (NCGM) ( )

2. Open graphics workstation

Can be PostScript (PS or EPS), PDF, X11 window, or NCAR CGM (NCGM) ( )
; x11 window, titled test ; test.ps ; wrf.eps ; slp.pdf

wks = gsn_open_wks(x11,test) _ _ wks = gsn_open_wks(ps,test) wks = gsn_open_wks(eps,wrf) wks = gsn_open_wks(pdf,slp)

2. Open graphics workstation

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

3. Change the color map (optl)

Do thi D this b before f d drawing i anything thi to t the th frame.

gsn_define_colormap(wks,rainbow)

If you use the same color map a lot, can put in .hluresfile hluresfile (more later) Can use one of the other 80+ ones, or create your own own. If you dont change the color map, heres youll get g what y

Default color table (yuck)

Index 0 is the background color Index 1 is the foreground color

Pick a better color table or create your own

http://www.ncl.ucar.edu/Document/Graphics/color_table_gallery.shtml http://www.ncl.ucar.edu/Document/Graphics/create color table.shtml http://www.ncl.ucar.edu/Document/Graphics/create_color_table.shtml

4 Set optional resources 4.

Resources are the heart of your NCL graphics code. There are over 1 1,400 400 resources! Resources are grouped by object type. There are 11 graphical graphical objects: contours, labelbars, legends, maps, primitives, p , streamlines, , text strings, g , tick marks, titles, vectors, xyplots

titles

Examples of graphical objects in an XY plot

XY plot l t

tick marks and d their th i labels legend

More examples of graphical objects subtitles

main title

map

contours tickmarks labelbar

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 vc - Vector p plots tm - Tickmarks cn - Contour plots ti - Titles gsn - special resources not associated with any object

Made up of full words with first letter of word capitalized:

xyLineColor, Li C l cnFillOn, FillO tiMainString, tiM i St i

vcRefMagnitudeF, gsnMaximize

Some have an F F on the end to indicate a floating point resource: xyLineThicknessF

Anatomy of a resource (contd)

Resources are set by attaching them as attributes to an NCL logical variable:

res = True T res@mpMinLatF = 30 ; decimal not necessary

Most have default values values. There are many types:

res@tiMainString @ g = This is a title res@tmXBLabelFontHeightF = 0.01 res@cnLineLabelsOn = True res@xyLineColors = (/5,7,11/) (/5 7 11/) res@xyLineColors = (/red, green, blue/)

http://www.ncl.ucar.edu/Document/Graphics/Resources

Anatomy of a resource (contd)

Resources across objects are similarly named, for easier recollection:

xyLineColor, cnLineColor, gsLineColor,

p , tmBorderLineColor mpGridLineColor,
tiMainFontHeightF, tmXBLabelFontHeightF,

lbLabelFontHeightF cnLineLabelFontHeightF lbLabelFontHeightF,

xyDashPattern, y , mpPerimLineDashPattern, p ,

lbBoxLineDashPattern, cnLineDashPattern

5 Draw the graphics 5.

Call C ll one of f th the gsn_csm_xxxxx functions f ti from f the second library we loaded. The general format is:
= = = = = gsn_csm_contour(wks,data,res) gsn_csm_vector(wks,u,v,res g , , , ) gsn_csm_contour_map(wks,data,res) gsn_csm_contour_overlay(wks,data1,data2,res1,res2) gsn_csm_pres_hgt(wks,data,res)

plot plot p plot plot plot

http://www.ncl.ucar.edu/Document/Graphics/Interfaces/

overlays and panels

by default default, the high-level high level interfaces draw the plot and advance the workstation to the next frame (page) (p g ) need to change this to plot overlays or multi-panel multi panel plots resources:

gsnDraw = False gsnFrame = False

Paneling
two or more plots on the same page special gsn interface: gsn_panel

all panels same size plots are stored in array of graphic objects

plot = new(2,graphic) res res@cnFillOn res@gsnDraw res@gsnFrame = True = True = False = False

; create graphic array ; plot resources

plot(0) = gsn_csm_contour(wks,u,res) plot(1) = gsn_csm_contour(wks,v,res) gsn csm contour(wks v res)

; first plot ; second plot

resP = True ; panel resources resP@txString = common title gsn_panel(wks,plot,(/2,1/),resP) ; draw panels in column

panel orientation
(/3,1/) (/3,2/) (/1,3,2/)

gsnPanelRowSpec = True

overlays

overlays are done using high-level high level interfaces, if possible

gsn_csm_contour_map_overlay gsn csm contour map overlay gsn_csm_vector_scalar_map g gsn_csm_streamline_contour_map p others

complex overlays
sometimes, there is no higher-level sometimes higher level interface for the overlays you want special gsn interface: overlay

all panels same size plots are stored in array of graphic objects

plot = new(2,graphic) res res@cnFillOn res@gsnDraw res@gsnFrame = True = True = False = False

; create graphic array ; plot resources

plot1 = gsn_csm_contour(wks,spd,res) ; first plot plot2 = gsn_csm_vector(wks,u,v,res) gsn csm vector(wks u v res) ; second plot overlay(plot1,plot2) draw(plot1) frame(wks) ( ) ; overlay plots ; need to draw plot ; and advance frame

other useful resources

gsnMaximize = True gsnSpreadColors = True

gsnSpreadColorStart = color_index color index gsnSpreadColorEnd = color_index

gsnXxxxString = string string

where Xxxx is Left, Center or Right

http://www.ncl.ucar.edu/Training/Worksh http://www ncl ucar edu/Training/Worksh ops/lectures.shtml

WRF/NCL

http://www.mmm.ucar.edu/wrf/OnLineTu http://www mmm ucar edu/wrf/OnLineTu torial/Graphics/NCL/

http://www.mmm.ucar.edu/wrf/OnLineTutoria

l/Graphics/NCL/NCL_examples.htm

http://www.ncl.ucar.edu/Applications/wrf. shtml

WRF Functions [ wrf_ wrf ]

Special WRF NCL Built-in Functions Mainly functions to calculate diagnostics Seldom need to use these directly
slp = wrf_slp( z, tk, P, QVAPOR ) http://www.mmm.ucar.edu/wrf/OnLineTutorial/Graphics/NCL/NCL_functions http://www mmm ucar edu/wrf/OnLineTutorial/Graphics/NCL/NCL functions _built-in.htm

Special WRF library functions Developed to make it easier to generate plots

$NCARG_ROOT/lib/ncarg/nclscripts/wrf/WRFUserARW.ncl

slp = wrf_user_getvar(nc_file,slp,time)

http://www.ncl.ucar.edu/Document/Functions/wrf.sht ml http://www.mmm.ucar.edu/wrf/OnLineTutorial/Graphi p p cs/NCL/NCL_functions.htm

use the example WRF/NCL scripts as a starting point to do what you want easier than starting from scratch!