Contents

subscripts

Usage:

Ordinary subscripts: x[13], y[2,vector(4,5)]
Negative subscripts: w[-vector(1,3,5)], z[-run(5),-1]
Logical subscripts:  a[vector(T,T,F,F)], b[b < 0]

Keywords: syntax

Elements of vectors may be selected in several ways using a list of
integer or LOGICAL subscripts inside of square brackets.  The list must
be of one of three forms.  In the examples, z is assumed to be
vector(1,7,4,9,6).

A list of one or more positive integers.
  Examples: z[4] is 9 and z[vector(1,1,2,2,5,4)] is vector(1,1,7,7,6,9).

A list of negative subscripts. These indicate omission of the absolute
values of the subscripts.  If all subscripts are omitted the result is
NULL.  See topic 'NULL'.
  Examples: z[vector(-1, -3, -5)] is vector(7,9).
            z[-run(5)] is NULL

A LOGICAL vector with the same length as the source vector. The value is
a vector with elements corresponding to values of True.  If all the
elements are False, the result is a NULL variable, with no elements.
  Examples: z[z > 4] is z[vector(F,T,F,T,T)] = vector(7,9,6).
            z[z > 9] is z[vector(F,F,F,F,F)] = NULL

z[vector(1,2,?)] would be an error because MISSING values are not
allowed as subscripts.

z[vector(-3,-4,-3)] would be an error because there are duplicate
negative subscripts.

z[vector(-1,2)] would be an error because there are both positive and
negative integers in the same vector of subscripts.

Elements of matrices may be accessed in an analogous manner to vectors,
except that both dimensions must be specified, separated by a comma.  An
empty row or column specification implies all rows or columns.  Suppose
                                    [1   4]
q is the matrix  matrix(run(6),3) = [2   5] .
                                    [3   6]

Then q[3,1] is 3, and both q[vector(1,3),2] and q[-2,2] are the column
vector 4,6 with dimensions 2 and 1.  q[3,] is the row vector 3,6 and
q[q[,1]>=2,] selects those rows of q for which column 1 is not less than
2, that is rows 2 and 3.

Elements of arrays may be accessed as for matrices, except that you must
specify all subscripts.  Again, an empty subscript specifies all legal
values for that subscript.

With vectors, matrices or arrays, if any subscript is NULL or is
non-selecting (all False or a complete set of negative subscripts), the
result is a NULL variable.

It is not an error to use more subscripts than there are dimensions as
long as no extra subscript specifies an element greater than the first
for that dimension.  Extra trailing empty subscripts are ignored, so
that for example, run(5)[-1,] and run(5)[-1] are identical.  Extra
subscripts that are 1 or T have the effect of increasing the number of
dimensions.

For example, run(5)[-1,1] and run(5)[-1,T] are equivalent and result in
a 4 by 1 matrix instead of a vector of length 4, but run(5)[-1,2] is an
error.  This is a useful feature when writing macros that may operate on
vectors and matrices, or deal with both ANOVA and MANOVA SS.  For
example, SS[3,,] is equivalent to SS[3] after anova() and is also
meaningful after manova() when SS is a 3 dimensional array.

If a is a matrix or array, and i is a vector, then a[i] is equivalent to
vector(a)[i].  For example, matrix(vector(1,3,2,4,6,5),2)[vector(1,2,6)]
yields vector(1,3,5).

Except in this case, it is an error when there are fewer subscripts than
dimensions.

When a is a factor and I is an appropriate vector of subscripts, a[I] is
a factor.  For example, anova("{y[-1]} = {a[-1]}") carries out an
analysis of variance omitting the first case.  See topics factor(),
anova() and 'models'.  The "official" number of levels of a[I] is the
same as for a, even when max(a[I]) < max(a).

                      Matrix and Array Subscripts
You can also use a matrix as a single subscript in square brackets.  If
x is a vector, matrix or array with ndim dimensions, and Sub is a nrows
by ndim matrix of positive integers, then x[Sub] is a vector of length
nrows(Sub), whose i-th element x[Sub][i] is
   x[Sub[i,1],Sub[i,2],...,Sub[i,ndim]]
For example, if x is n by n, x[hconcat(run(n),run(n))] is equivalent to
diag(x) and x[hconcat(run(n),run(n,1))] extracts the cross diagonal of
x.  There can be no MISSING values in Sub.

More generally, if Sub is an array of positive integers whose last
dimension has length ndim, x[Sub] is an array with ndims(x[Sub]) =
ndims(Sub) - 1 with i,j,...,k-th element x[Sub][i,j,...,k] =
   x[Sub[i,j,...,k,1],Sub[i,j,...,k,2],...,Sub[i,j,...,k,ndim]].

See select() for a way to select a the k[i]-th element in the i-th row
of a matrix, when k is a vector of positive integers.

A structure may have a single scalar or vector subscript which selects
components of the structure in the same way a scalar or vector subscript
selects elements of a vector.  See topic 'structures'.

                        Assignment to Subscripts
You can assign to subscripts as well as extract from them.  For example,
if y is a matrix with at least 3 rows y[run(3),] <- 0 sets the first 3
rows of y to 0.  y[-vector(run(5),run(16,20)),] <- ? sets rows 6 to 15
and beyond 20 to MISSING.  A statement like 'y <- x[2,] <- 3' sets row 2
of x to all 3's and y to a row vector of 3's with dim(y)[2] = dim(x)[2].

When y is a structure, y[J] <- x changes components of y.  See subtopic
'assignment:"assignment_to_structure_components" for details.

Although you can use matrix subscripts in assignments to subscripts, you
cannot use array subscripts where more than 2 dimensions exceed 1.

See topic 'assignment' for details on assignment to subscripts,
including assignment to subscripted components of a structure.