Brain Imaging & Analysis Center

Any individual element within a variable, or any rectangular subset of a variable, can be accessed directly using subscripts. Subscripts are entered in parentheses, which must come immediately after the name of the variable (see VARIABLES(1)). The number of subscripts depends on the dimensions of the variable. If there is more than one dimension, then the first subscript represents the horizontal dimension and varies the fastest (except for STRING LIST variables, see below). For each dimension, subscripts can either be a single value or a range of values separated by a colon. NOTE: All subscripts start counting with 0 as the first element.

For example, suppose you have a matrix variable MM and a string variable SS containing:

     mm = {                                ss = 'hiho silver'
           1  2  3  4  5
           6  7  8  9 10
          20 30 40 50 60
     }

You could access a single element in each as:

     mm(2,1)     is the number: 8          ss(8) is 'v'

or a range as:

     mm(1,1:2)   is an array:  7 30
     mm(2:4,1:2) is a matrix:  8  9 10     ss(3:7) is 'o sil'
                              40 50 60

If any dimension has no subscript then the full range in that dimension is assumed. For example,

     mm(2)       is:  3  8 40
     mm(,2)      is: 20 30 40 50 60

If no value follows the colon then the range defaults to the end of the variable. For example,

     mm(1:,1:)   is:  7  8  9 10
                     30 40 50 60

Subscripts can be numbers, as in these examples, or they can be any CIGAL variable or arithmetic expression that returns the equivalent of a number. For example, suppose that you are running in graphics mode, in which case the internally declared image variable “@0” refers to the graphics display region of video memory. Two useful internal variables are CURSX and CURSY, which refer to the current X and Y positions of the cursor. Therefore,

                @0(cursx,cursy)

refers to the pixel value at the current cursor position, whereas

                @0(cursx-4:cursx+5,cursy-4:cursy+5)

refers to the 10 x 10 region of the display around the current cursor position. Moreover, you can get the average intensity of the display at the cursor as:

                mean(@0(cursx-4:cursx+5,cursy-4:cursy+5))

Vector Subscripts

VECTOR variables have somewhat unusual subscripts. Vectors are unusual in that they contain 6 elements of different sizes (see VARIABLES(1)). Because of this you are allowed access to the whole vector, or to any single element, but a range can only select among the first three elements (Xvalue,Yvalue, and Zvalue) because they are all the same size. For example, if you have a vector VV, you can access:

           vv         ; the whole vector
           vv(0)      ; the Xvalue
           vv(5)      ; the intensity
           vv(1:2)    ; the Yvalue and Zvalue

but not:

           vv(2:3)    ; Zvalue and Key are incompatible
           vv(3:4)    ; Key and Width are incompatible

VECTOR LISTs obey the same rules as VECTORs, with the addition that the second subscript selects which vectors. Thus, you can select from VECS (the internal vector list variable containing the active display vectors) as, for example:

           vecs(,10:20)      ; the 11th through 21st vectors
           vecs(1)           ; all Yvalues
           vecs(0,3)         ; the Xvalue in the 4th vector
           vecs(2,3:)        ; the z values of all vectors after the third

String List Subscripts

STRING LIST variables also have unusual subscripts in that the order is reversed compared to normal. Generally, the first subscript refers to the positions of elements that are changing most rapidly, which in the case of string lists would be the characters within each string. However, this is not the case. The first subscript is used to select a particular string out of the list, and the second subscript may be used to identify letters within strings. This is done because each string can have a different number of letters, and because most references to elements within a string list are in fact references to whole strings and it is a nuisance to have always to remember to skip past the first subscript.

For example, if you declare and load a string list variable FLIST as:

         declare string list flist
         flist = {
         filename1
         filename2
         ...etc.
         filenameN
         }

Then the values: Correspond to:

         flist(0)             the first string in the list
         flist(3:6)           the 4th through 7th strings
         flist(1,3)           the 4th letter in the 2nd string
         flist(,0:5)          the first 6 characters of every string

Illegal Subscript Values

If you specify a subscript value that is out of range, it is clipped to the nearest legal value. Values less than zero are clipped to zero, and values greater than or equal to the number of elements are clipped to the number of elements - 1.

See Also:
CIGAL Home, CIGAL Manual, Topics List, Manual Help