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.

precip(0,0,0) precip(4,3,7)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.

precip(1:3,3,1) precip(2:3,0:3,2)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.

precip(:,0:3,:)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.

precip(0:4:2,0:3,0:7:3)<The above statement selects a 3x4x3 array subset.

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 a=(/(/1,2,3,4/),(/5,6,7,8/),(/9,10,11,12/)/)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) 12However, 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

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

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 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

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

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