NCL array subscripting

Array subscripting or indexing is used to select subsets or specific elements of a data array. Data is ordered in a row x column fashion, and NCL supports three different methods of array subscripting so that users can access and manipulate their data in a way that is the most meaningful and intuitive to them. Standard subscripting is similar to array indexing used in FORTRAN 90. Coordinate subscripting uses coordinate variable data to select array subsets. Named subscripting uses the names of the dimensions to allow for array reordering operations.

Standard subscripting

Standard subscripting is used to select subsets of data from an array. The indexing is performed in a way that is very similar to the method used in FORTRAN 90. Standard subscripting allows users to thin data, select ranges, specify data strides, and reverse the order of data.

Selecting subsets

Subsets of data are selected by specifying the numerical location of the data in an array. For example, if precip is the name of a three-dimensional variable with dimensions of 5x4x8, then the first and last elements in the array are selected in the following way:


Array subscripts always begin at 0 when using standard subscripting, and they must be of type integer. Valid subscripts cannot be less than 0 nor greater than the dimension size minus one. Individual subscripts are separated by commas, and the entire subscript list is surrounded by parentheses.

A range of data is selected using the colon ':' character. The number preceding the colon represents the starting subscript, and the number after the colon represents the ending subscript. The beginning and ending subscripts are inclusive, so the following references would select a 3x1x1 and a 2x4x1 subset of the precip data array. The actual output dimensionality of these selections are 3 and 2x4 respectively. When a dimension becomes a single dimension the rank of the array is reduced by one. If the results of these selections where assigned to another array the rank of the other array would be 1 and 2 respectively.


If a number does not appear before the colon, then the beginning of the range is automatically selected. Similarly, if the number following the colon is omitted, then the end of the range is automatically selected. For example, the following statement selects the entire range of the first and last dimensions of the variable.


Data can be thinned by specifying a stride in the subscript so that every other, or every third, every fourth, etc. array element is selected. The optional stride value is specified by adding an additional colon after the subscript range followed by a positive integer value for the stride. The stride value is added to the current index to determine the subset of data selected in a given range. For example, a stride of 3 would select the 1st, 4th, 7th, 10th, etc. data elements in the range.


The above statement selects a 3x4x3 array subset.

Reversing the data order

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

The following example shows how data order is reversed by printing the same variable twice, but reversing the subscripts in the second case.

; create a 3x4 integer variable
a=new((/3,4/), integer)

; initialize the variable

The statement, print(a(0:2,0:3)), prints the data in its original order.

(0,0)   1
(0,1)   2
(0,2)   3
(0,3)   4
(1,0)   5
(1,1)   6
(1,2)   7
(1,3)   8
(2,0)   9
(2,1)   10
(2,2)   11
(2,3)   12

However, reversing the subscripts reverses the order. The statement, print(a(2:0,3:0)), prints the data in opposite order.

(0,0)   12
(0,1)   11
(0,2)   10
(0,3)   9
(1,0)   8
(1,1)   7
(1,2)   6
(1,3)   5
(2,0)   4
(2,1)   3
(2,2)   2
(2,3)   1

Using vectors to select data

A vector of integer indices can also be used as a subscript. As long as all of the entries in the vector are within the bounds of the given dimension, then the vector could be any size. You can also select a single index more than once. For example, the following statement uses a vector subscript to print several values from the array defined in the previous section.

print (a(2,(/0,0,0,1,1,1,2,2,2,1,1,1,0,0,0/)))
(0)     9
(1)     9
(2)     9
(3)     10
(4)     10
(5)     10
(6)     11
(7)     11
(8)     11
(9)     10
(10)    10
(11)    10
(12)    9
(13)    9
(14)    9

Coordinate subscripting

Coordinate subscripting was developed for users who want to access their data and specify index ranges in terms of coordinate variable values. For someone who is very familiar with a particular dataset, it may be more intuitive to select subsets of data by specifying coordinate ranges rather than using standard subscripting.

For example, if a temperature variable is defined over latitude, longitude, and time, one possible naming scheme is to name the variable's dimensions time, lat, and lon. Coordinate variables could then be assigned to these dimensions and, using coordinate subscripting, a user could select a subset of data by specifying a latitude, a longitude, and a time range, rather than using standard indexing.

Coordinate subscripting uses normal subscripting syntax of parenthesis with commas each dimension's subscript, but also uses curly braces, '{}' between each of the commas to denote the use of coordinate subscripting.

For example, suppose there is a two-dimensional variable, named temperature, with dimensions called lat and lon of size 5 and 6 respectively. Further, let's suppose that a coordinate variable called lat is assigned with values 90, 89, 88, 87, and 86. Also, suppose a coordinate variable lon is assigned with values -20, -10, 0, 10, 20, and 30. Now, coordinate subscripting can be used to make data selections from the temperature data.

The following pairs of statements all select the same data; however, the first statement in each pair uses standard subscripting, and the second uses coordinate subscripting.

t = temperature (0,0)
t = temperature ({90}, {20})
t = temperature (2:4, :3)
t = temperature ({88:86}, {:10})

When using coordinate indexing, it is very important that you know whether your coordinate arrays are monotonically increasing or decreasing to avoid accidentally reordering your data and causing unnecessary losses in efficiency. For example, if users incorrectly assume that the temperature coordinate variables in our example are monotonically increasing, then they might mistakenly make the following reference that reverses the order of the data in the first dimension and causes an unintentional efficiency loss due to the overhead of reordering the data.

; The first dimension is reversed because the coordinate array
; for the first dimension was defined to be monotonically decreasing
; ( 90 to 86). However, in the following statement, the first
; dimension subscript is referenced in an increasing order (86 to 89),
; thus reversing the order of the data.

t = temperature ({86:89}, {:10})

Standard and coordinate indexing can be mixed in the same statement as in the following example.

t = temperature (0,{20:30})

There is a simple rule for choosing the index when the coordinate given is not an exact coordinate value. NCL finds the coordinate value above and below the given value and chooses the closest exact value. This is only the case when one coordinate value is given. If a coordinate range is specified, then all coordinate values within the range are selected.

Named subscripting

Named subscripting is an extension of both standard and coordinate indexing. Named subscripting allows the flexibility of specifying subscripts in any order. With standard and coordinate indexing, subscripts have to be specified in the order in which a variable's dimensions are defined. However, with named subscripting, the subscripts can be specified in any sequence to reorder the data.

Named subscripting allows the user to use the dimension name to specify the dimension that the subscript indexes. The rule for braces is the same as the preceding indexing schemes. The difference is that in each subscript, the name of the dimension is listed followed by the pipe symbol '|' and the subscript range.

The following example shows the same data selection first using standard subscripting and the second and third using named subscripting. The variable, temp, is a 5x6 array with coordinate variables named lat and lon respectively. The values of the lat array are (/-90, -89, -87, -86, -85/), and the values in the lon array are (/-20, -10, 0, 10, 20, 30/).

; standard subscripting
t = temp (:4, 0)
; named subscripts with coordinate subscripting style
t = temp ({lat | :-85},{lon | -20})
; named subscripts with standard subscripting style
t = temp (lat | :4,lon | 0)
A feature of named subscripting is that it provides a mechanism for reordering the dimensions of data simply by switching the order of the named dimensions. For example, data is reordered in the following example because the first and second dimension names are swapped. So, rather than the longitude dimension varying the fastest, the latitude dimension varies the fastest, and the data is printed in column major order rather than the default row major order.

print (temp (lon | 0:5, lat | 0:4))

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 $