NCL syntax and semantics

NCL can be thought of as a complete programming language. As a programming language, it has a grammar and syntax rules for constructing statements and commands. This module describes the syntax, semantics, and conventions used for constructing NCL statements, identifiers, comments, array subscripts, data, metadata, and strings.

Symbol set

uppercase letters: A B C... Z

lowercase letters: a b c... z

digits: 0 1 2... 9

special characters: + = _ - ( ) * & % # ! | < > . , ; : " / { } ~ \ [ ] ^ @

Separators

Identifiers

Examples of valid identifiers:

_A_very_long_variable_name_

_

temperature

avg_temp_1988

temp.june

var$8

a variable name with spaces instead of underscores

7june

Comments

For example, the following are valid NCL comments:

; A comment can appear alone on a line. Everything after
; the semicolon is ignored by the interpreter.
temperature = 77.6  ; Comments can also appear with a command.

Strings

Strings must be enclosed in double quotes, '"'. For example, the following statements create string variables and assign character strings to them.

string_var_1 = "This is the contents of the string variable"
string_var_2 = "Special chars (@#$%^&*_+~`;') are valid"

Keywords

Operators

Arrays and subscripts

Array subscripts are enclosed in parentheses, '(' and ')'. For example, if temp is a one-dimensional array, then the first element can be specified as temp(0) when using standard subscripting. If temp is a three-dimensional array, then the subscripts are separated by commas. So, the first element in a three-dimensional array is specified as temp(0,0,0) using standard subscripting.

Ranges and strides are specified using the colon ':' character. For example, the first through tenth elements in a one-dimensional array are specified as temp(0:9) using standard subscripting. Similarly, this syntax is expanded for variables with multiple dimensions by separating the dimension ranges with commas, as in temp(0:9, 3:7, 2:20). Strides, for thinning data, are appended after the range using another colon. For example, a stride of 3 in a one-dimensional array is specified as temp(0:9:3). Again, this can be expanded to a multi-dimensional array by separating the subscripts with commas, as in temp(0:9:3, 4:7:2, 7:20). This last example uses a stride of 3 in the first dimension, a stride of 2 in the second dimension, and no stride in the third dimension.

Curly braces, '{' and '}', are used to surround subscripts when using coordinate subscripting. For example, if the coordinates for the temp array range from -200 to 600, then curly braces can be used to select individual elements and ranges. The following NCL statements demonstrate how braces are used.

; Select the element that corresponds to coordinate index -150.
; Assume temp is a one-dimensional array.
scalarvar = temp({-150}) 

; Select a range of data from the beginning to the end.
; Assume temp is a one-dimensional array.
vectorvar = temp({-200:600})

; Select a range of data from a three-dimensional variable
; Assume temp is a three-dimensional array.
var_3D = temp({-200:50}, {45}, {30:100})

; Select the first element using named subscripting.
scalarvar = temp((time|0))

; Select ranges using named subscripting. Assume temp is
; a two-dimensional array with dimensions time by lat.

var_2D = temp ((time|0:5), (lat|4:9))

; Select ranges using name subscripting but use names to
; reorder the dimensions of two-dimensional array temp to
; be lat by time

var_2D2 = temp((lat | 4:9),(time | 0:5))

Array data

For example, the following are all NCL statements containing valid array expressions.

; Create a one-dimensional array of 5 elements
var1 =  (/ 1, 2, 3, 4, 5 /)

; Create a two-dimensional array of 10 elements
var2 = (/(/ 1, 2, 3, 4, 5 /),(/ 1, 2, 3, 4, 5 /)/) 

; Create a two-dimensional array from variable references

var3 = (/var1,var2(0,:),var2(1,:)/)

Metadata

Dimensions

For example, the following NCL statements assign the names "time", "lat", and "lon" to each dimension of the temp variable.

temp!0 = "time"
temp!1 = "lat"
temp!2 = "lon"

Coordinates

For example, the following NCL statements assign coordinate vectors (defined elsewhere) to each dimension of the variable called temp.

temp&time = vector_of_time_coordinates
temp&lat = vector_of_lat_coordinates
temp&lon = vector_of_lon_coordinates

Attributes

For example, the following NCL statements demonstrate the assignment of file and variable attributes.

; File attributes called "title" and "date"
filevar@title = "South American Climate Data"
filevar@date = "November 23, 1994"

; Variable attributes called "units" and "max"
temp@units = "Degrees C"
temp@max=85.

File variable references

; Print the data from external variable called precip
print (filevar->precip)

; Print the longname of the external precip variable
print (filevar->precip@longname)

User Guide Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, UG Contents, UG WhereAmI?