NCL variables overview

Variable names must begin with an alphabetic character, but they can contain any mix of numbers and alphabetic characters. The underscore ('_') is also allowed. Variable names are also case sensitive. The maximum variable name length is currently 256 characters. Variables reference arrays of multi-dimensional data. These data can be described by variable attributes, named dimensions, and coordinate variables. Variables can also reference files and graphical objects.

The following are examples of unique variable names:

	a
	A
	forecast_time
	s092389
	__t__

Variables can be created by the assignment statement, or by the new statement.

Creating variables

        a = new((/5,6,7/),float)

The following is an example of how to assign a specific missing value:

        a = new((/5,6,7/),float,-1e12)

File data types are created differently. Files are only created by the intrinsic addfile. Arrays of type graphic can be created with new, but none of the elements of the array will actually reference an existing HLU object. Each element will contain a missing value.

Attributes

	temperature@units = "Degrees C"
	temperature@long_name = "Temperature at Tropopause"
	temperature@_FillValue = -9999.0
	temperature@scale_factors = (/ .233, .452, .434, .621 /)

Attributes can be treated just like variables. They can be used in expressions and subscripted in the same fashion as variables. The attribute _FillValue is a special reserved attribute name that denotes what values in the variable are missing or filled values. Missing values are significant when evaluating expressions. In the above examples, if the attributes were already defined, they are reassigned the new value. In the case of the _FillValue attribute, every occurrence of the previous value in the variable temperature is replaced with the new _FillValue. The _FillValue attribute must be the same type as the data type referenced by the variable.

Dimensions

	temperature!0 = "frtime"
	temperature!1 = "lat"
	temperature!2 = "lon"

Coordinate variables

	temperature&frtime = forecast_times
	temperature&lat = lat_points
	temperature&lon = lon_points

Subscripts

Standard subscripts

Standard subscripting includes the capability of selection ranges and strides as subscript in addition to the ability to select data using a vector of integer indices. All of this functionality is more or less duplicated from FORTRAN 90. The following is a simple example of a set of single subscripts for a three-dimensional variable with dimensions 5x6x7. Unlike FORTRAN, the array indices begin at 0. Standard subscript indices must always be integer; floating point numbers and strings are not accepted. Note individual subscripts are separated by commas ',' and the entire subscript list is enclosed in parentheses.

	temperature(0,5,6)

A range subscript selection accepts a beginning and ending index separated by a colon ':'. Both the beginning index and the ending index are included in the selection, therefore the range is inclusive. For example,

	temperature(1:3,5,6)
	temperature(1:3,4:5,5:6)

The first selection above selects a 3x1x1 subsection of the array temperature, and the second selection selects a 3x2x2 subsection. In addition to the above style of selection, a stride can also be specified that causes the selection to skip over a given number of elements. For example, a value of 1 means that every element from the beginning of the range and the end of the range will be selected. With values greater than 1, the first index of the subscript is followed by the stride plus the current index. Therefore a value of 3 selects the first, fourth, seventh, and so on.

	temperature(0:4:2,0:5:3,0:6:4)

The above selection uses strides to produce a 3x2x2 array.

There is no restriction on having the start of a subscript range be less than the end of the subscript range. When the start is greater than the end, a reverse selection is done, meaning the order output selection is reversed from the original variable.

Another option for selection is to leave out the start, end, or both. This means that the start or end will default to the beginning or end respectively.

	temperature(:2,:1,5:)
	temperature(:,:,:)

The first selection selects from the beginning to index 2 for the first dimension, the beginning to index 1 for the second dimension, and the final subscript selects from index 5 to the end for the 3rd dimension. The second example shows how the entire array can be selected.

Finally, a vector of integer indices can be used as a subscript. As long as all of the entries in the vector are within the bounds of the given dimension, the vector could be any size. This also selecting a single index more than one. For example, take the following array and its use as a vector subscript on the variable temperature:

	(/1,1,1,2,2,2/)

	temperature((/1,1,1,2,2,2,/),:,:)

This selection creates an array 6x6x7 which is actually bigger than the original. The first, second, and third indices of the first dimension contain identical arrays. The vector must always be a single-dimensioned array of integers.

Coordinate subscripts

Coordinate subscripts use the coordinate variables associated with a variable to make the subselections. When specifying a coordinate subscript, braces ('{' '}') are used to state that the subscript should use the indices that the start and end values are located in from the coordinate variable. Essentially, the start and end values are "looked" up in the coordinate variable, and the indices are used to make the subselection. The following are examples of coordinate subscripts. Note that coordinate and standard subscripting can be mixed in the same variable subscript. Also, stride is still specified as an integer stride.

	temperature(0,{20:60},{-95:-120})
	temperature(0,{20},{-95})
	temperature(0,{:20:2},{:-95:2})

Coordinate subscripting only works when the coordinate variables assigned to the variables are monotonically increasing or decreasing. If an attempt is made to subscript a coordinate variable that is not monotonic, an error message is generated.

Named subscripting

Named subscripting is a means by which arrays can be reordered. Named subscripting requires that each dimension of the variable being subscripted is named. If one or more are not named, an error messages is printed. The following are examples of named subscripting. The dimension names of the variable temperature are "time," "lat," and "lon" for dimensions 0 through 2 respectively.

	temperature( time | 0, lon | :, lat | :)
	temperature( time | :, {lon | 20 : 60}, {lat | -95 : -120})

The first example "swaps" the lat and lon dimensions. The second example shows a similar dimension reordering but utilizes coordinate subscripting.

Files and file variables

It is very important to understand the distinction between a variable that references a file and a file variable. When a file is opened with the addfile command, a reference to the file is assigned to a variable. The type of the variable's data type is file. This variable is a variable that references a file. On the other hand, a file variable is a variable that is contained within a file.

Variables that reference files have a few special exceptions. First, dimension names and numbers do not represent the shape of the file variable; they are the dimensions used by the variables stored in the file. Coordinate variables are handled similarly. Attributes, coordinate variables, and dimension names, when assigned to a variable referencing a file, are written into the file rather than saved in memory as with normal variables.

Furthermore, when a variable references a file, the '->' operator is used to select variables stored in the file.

	file->variable1

File variables can be operated on and subscripted in the exact same fashion that standard variables can be with 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 dimensions. This means that adding or modifying dimension names and coordinate variables for one file variable changes them for all variables with the same dimension.

Variables that reference files are created by the addfile intrinsic function.

Reference Manual Control Panel

NG4 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?