NCL variables

NCL variables are symbolic representations of multidimensional arrays. Scalar variables are represented as a single dimension array of size 1. Variables can have any of the following types: float, double, short, long, integer, byte, character, or string.

Variable names are case sensitive and must begin with a letter or an underscore '_'. Any combination of characters and numbers can make up the rest of the name. The maximum length of a variable name is 256 characters.

File variables vs. variables in memory

There are two general types of variables in NCL: file variables and variables in memory. File variables are variables that are read from an external file. These variables are referenced in NCL using a file record. Variables in memory are variables that have been created through assignment statements or the "new" statement.

File variables are stored in an external file and are referenced using a file record. File records contain pointers to file variables in an external file and metadata information, such as coordinate variables, dimension definitions, and attributes. Attributes, coordinate variables, and dimension names, when assigned to a file variable, are automatically written into the file when write permissions are available.

In-memory variables, on the other hand, are variables that are dynamically created using the "new" operation and assignment statements; they are not read from an external file. Attributes, coordinate variables, dimension names, etc. are assigned using NCL statements.

File variables are operated on and subscripted in the same way as in-memory variables using the '!', '&', and '@' operators. Dimensions and coordinate variables are not unique to individual file variables; they are shared by all variables in the file with the same dimension names. This means that adding or modifying dimensions and coordinate variables for one file variable may change the dimensions and coordinates for all the variables in the file.

For example, if memvar is a two-dimensional float in-memory variable, and filevar is a file record that references an external file that contains a file variable called precip, then you could reference the dimensions in the following fashion:


; Assign a name to the first dimension of the memvar variable.
memvar!0 = "latitude"

; Assign a name to the first dimension defined in the file
; referenced by filevar.
filevar!0 = "latitude"

To reference a variable that is stored in an external file, the '->' operator must be used.


; Assign a name to the first dimension of the precip variable 
; that is stored in the external file.
filevar->precip!0 = "latitude"

Note that when file variables are changed, the external file is automatically and immediately updated if the file was opened with write permission.

Creating variables

In-memory variables are created through variable assignment on the command line or by using the "new" statement. For example, the following NCL variable assignment would create an integer variable in memory called var_1 with a value of 5.


var_1 = 5

A float variable is created by adding a decimal point to the value, and string variables are created by enclosing the value in quotes.


var_2 = 5.894

var_3 = "This is a string variable"

Logical variables are created by using the keywords "True" and "False".

var_4 = True

To create variables of type double, long, short, byte, and character, you can use the intrinsic operation called "new". The "new" operation takes two required arguments to specify the dimensions and type, and one optional argument to specify the missing or fill value in a variable.


new ( dimension_array, type, optional_missing_value )

dimension_array is an array argument of dimension sizes such as:

(/30, 50, 365/) - a three-dimensional variable with dimension sizes of 30, 50, 365.

(1) - a scalar variable.

(20) - a one-dimensional variable with a single dimension of size 20.

(/100, 200/) a two-dimensional variable with dimension sizes of 100 and 200.

type is the variable type. It may be double, float, long, integer, short, byte, string, or character.

optional_missing_value is the fill value that each element is assigned to in your variable array.

The following NCL commands create variables of various dimensions and types.


;var1 is a three-dimensional float variable of size 22x33x44.
var1 = new((/22, 33, 44/), float) 

;var2 is a scalar byte variable.
var2 = new ((1), byte)

;var3 is a single dimensioned integer variable of size 100.
;The elements in this array will all be pre-assigned the value of -999.
var3= new ((100), integer, -999)

Deleting variables

The delete function is used to delete in-memory variables from NCL. The function accepts one argument: the variable that you want to delete. For example, if you have a variable called var1 of any dimension and type, the following NCL statement will delete all of the memory associated with the variable and its reference in the symbol table.


delete(var1)

File variables are a special type of variable and can not be deleted using the delete procedure. This is primarily because the netCDF and HDF formats do not allow the deletion of variable in a file. One way to accomplish this is to create another file and only assign the variable you would like to it leaving out the ones you wish to delete.

Coordinate variables

Coordinate variables are used to represent data coordinates. Each dimension of a variable can have a one-dimensional array of coordinate points that define the coordinates of the data along a single dimension.

So, for example, if you have a two-dimensional temperature variable that contains data that is mapped over an area defined in terms of latitude and longitude, two coordinate variables (one-dimensional arrays) would define the latitude and longitude points of the data. One coordinate variable would define all the latitude points of the temperature data, and one coordinate variable would define all the longitude points. The sizes and names of these variables would be equal to the sizes of their corresponding dimensions.

The values in a coordinate variable array must be monotonically increasing or decreasing. For example, the following are valid coordinate arrays:

-3, -1, 4, 10, 15

200.4, 33.2, 0., -100.2, -311.0, -500.0

The following are not valid coordinate arrays because they are not monotonically increasing or decreasing:

-10, 5, -8, 9, -6, 13

15, 14, 13, 12, 13, 14, 15

The '&' operator is used to reference and assign coordinate variables. If the variable called temp has dimension names lat and lon, then its coordinate variables are referenced with the same names, i.e. temp&lat, temp&lon.

For example, the following NCL statements assign two coordinate variables to a temperature variable.


; create the temperature variable ( a 5x4 array of data)
temp = new((/5,4/), float)

; assign dimension names
temp!0 = "lon"
temp!1 = "lat"

; initialize the values in the coordinate arrays
lon_coordinates = (/-90, -85, -80, -75, -70/)
lat_coordinates = (/0, 20, 40, 60/)

; assign the coordinate arrays to the variable
; Note that the coordinate variables must have the same name and
; size as their corresponding dimension.
temp&lon = lon_coordinates
temp&lat = lat_coordinates

User Guide Control Panel

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

$Revision: 1.7 $ $Date: 1998/06/15 22:08:52 $