Create a structure: Str <- structure(Name1:x,Name2:y,...[, compnames:Name]) Str <- strconcat(Name1:x,Name2:y,...[, compnames:Name]) Extract components of a structure: Str$name or Str[J] or Str[[J]] Number of components of a structure: ncomps(Str) Component names of a structure: compnames(Str) Test whether variable is a structure: isstruc(x) Modify a structure: Str[J] <- x or Str[[J]] <- x, legal subscript vector J Str[[i]][[J]] <- x, integer scalar i, legal subscript vector J Str$a <- x, Str$a$b <- x, ... Str <- changestr(Str,"compname",x), equiv. to Str$compname <- x Str <- changestr(Str,compname:x), same as preceding Str <- changestr(Str,n,x), positive integer n <= ncomps(Str)+1 Str <- changestr(Str,-n), equivalent to Str <- Str[-n] |

A 'structure' is made up of one or more named components, each of which may itself be a variable or another structure. A single component can be extracted by name using a '$'. For example, if structure Stats has 2 components with names 'mean' and 'var', then xbar <- Stats$mean and s_sq <- Stats$var set xbar and s_sq to the values of components 'mean' and 'var', respectively. When a component of a structure is itself a structure, you can use a chain of component names. For example, if structure Str has component 'a' which is a structure with component 'b', Str$a$b accesses that component. If Str$a$b is itself a structure with component 'c', Str$a$b$c accesses that component Some functions and macros, for example secoefs(), describe() and eigen(), return structures as their values. You can use structure() and strconcat() to create a structure with specified components. You can use split(y, f), where y is a vector or matrix and f is a factor, to create a structure whose j-th component consists of the rows of y associated with level j of f. split(y) returns a structure, each of whose components is a column of y. split(y,byrows:T) returns a structure, each of whose components is a row of y. See split(). split(y) and split(y, , and changestr() to delete components from, replace components in, or add new components to an existing structure. See structure(), strconcat() and changestr(). You can also modify an existing structure by assigning a variable to one or more components selected by a subscript. See below. vector(Str) "unpacks" a structure Str, returning all the elements in its non-structure components as a vector. All the non-structure components must be of the same type, REAL, CHARACTER or LOGICAL. ncomps(Str) returns the number of (top level) components in structure Str. See also ncomps(). compnames(Str) returns a CHARACTER vector of the names of the (top level) components in structure Str. See also compnames(). isstruc(x) returns True when x is a structure. More generally, isstruc(x1, x2, ...) returns a LOGICAL vector whose elements are True or False depending on whether the corresponding argument is a structure. Str[J] <- x, where J is a legal vector of subscripts and x is a variable, often a structure with ncomps(x) = number of components selected by J, replaces elements of an existing structure Str. See topics 'subscripts' and 'assignment'. Many functions accept structures as arguments, including describe(), sum(), prod(), max(), and min(), and all the transformations. Each component of the result is obtained as the function of the corresponding component argument. For example, sum(structure(x,y)) is the same as structure(x:sum(x),y:sum(y)). Both binary (for example, +, *, %*%) and unary (-, +, !) operators accept structures as operands. Most of these produce a structure of the same shape as the argument(s) or operands(s). For example, structure(a1,a2) %*% structure(b1,b2) = structure(a1 %*% b1,a2 %*% b2). In addition, if one operand of a binary operation is a structure and the other is not, the result is a structure, each of whose components is computed by combining a component of the structure argument with the other argument. For example, 3*structure(a,b,c) is the same as structure(a:3*a,b:3*b, c:3*c), and structure(a,b) %C% c, is the same as structure(a:a %C% c,b:b %C% c). Note: You cannot use a structure as an operand to %/% or %\%. See topic 'matrices'. You can extract components of structure Str using subscripts instead of a name. For example, if Stats is as described above, 'Stats[1]' and 'Stats[2]' are equivalent to 'Stats$mean' and 'Stats$var', respectively. If there are more than one component with the same name or if the structure name is not a legal variable name, this is the only way to extract the component. For example Str <- structure(dim(x)[1], dim(x)[2], sqrt(x)) creates a structure with three components, named NUMBER, NUMBER, and MATRIX, but Str$NUMBER retrieves only the first component and Str[2] must be used to retrieve the second. Usually it is preferable to name components using keywords. For example, Str <- structure(m:dim(x)[1],n:dim(x)[2],data:sqrt(x)) creates a structure with components named 'm', 'n', and 'data'. You can also name components using keyword 'compnames' on structure(), strconcat() and split(). Str[NULL] is NULL. See topic 'NULL'. More generally, in an expression of the form Str[J], J may be a vector of positive integers, a vector of distinct negative integers, or a LOGICAL vector of length ncomps(Str). Str[J] is a structure whose components are the components of Str selected by J in the same way elements of a vector vec would be extracted by vec[J]. If J selects only one component, Str[J] is that component. If J selects no commponents (all F's or a full set of negative values), STR[J] is NULL. See topic 'subscripts' for how such a vector of subscripts is interpreted. An alternative way to extract components from a structure is Str[[J]], using double square brackets. This is equivalent to Str[J] when Str is a structure. However, when x is not a structure, the value of x[[1]] is x, not x[1], and x[[J]] is an error if J != 1. This feature can be useful in a macro when an argument can either be a non-structure variable or the first component of a structure. Examples: When Stats is as above, Stats[vector(2,1)] is equivalent to structure(var:Stats[2],mean:Stats[1]), and Stats[vector(F,T)] is equivalent to Stats[2] or Stats$var. You can replace one or more components of a structure by assigning to subscripts. For example, if Stats is as above, Stats[2] <- vector(1,3) will replace component 'var' by vector(3,10) without changing its name. Stats[[2]] <- vector(1,3) has the same effect. You can also change a single named component by assignment. For example, if Statist is as above, Stats$var <- vector(1,3) is equivalent to stats[2] <- vector(1,3). You can't assign to a sub component. For example, a$b$c <- x is illegal, even if component b os structure a is a structure with component c. See topic 'assignment' for details on assignment to structure components. You can use changestr() to modify a structure. See changestr() for details.

Gary Oehlert 2003-01-15