Next: subscripts
Up: MacAnova Help File
Previous: structure()
Contents
Usage:
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]
|
Keywords:
structures, syntax, variables
Description of structure
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 Stats is structure(mean:xbar, var:s_sq), 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
Creating a structure
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 strconcat() to combine the components in two or more
structures into one larger structure, optionally including additional
variables as comnponents.
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().
You can use 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.
Functions used with structures
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.
equal(str1, str2) compares two structures, returning True only when all
their components and subcomponents are equal. See equal().
Assignment to components
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'.
Structure arguments to functions
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)).
Binary and unary operators with structures
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'.
Extracting components
You can extract components of structure Str using subscripts instead of
a name. For example, if Stats is structure(mean:xbar, var:s_sq),
'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.
Alternative subscript form
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, if J != 1, x[[J]] is an error. 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 structure(mean:xbar, var:s_sq),
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.
Replacing components
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 Stat is as above, Stats$var <- vector(1,3) is equivalent
to stats[2] <- vector(1,3).
You can change subcomponents at any depth <= 31 by assignment. For
example, x is structure(a:run(3),b:structure(A:1,B:2,C:3)), all of x$b$C
<- PI, x[[2]]$C <- PI, x$b[[3]] <- PI or x[[2]][[3]] <- PI are
equivalent.
See topic 'assignment' for details on assignment to structure
components.
You can use changestr() to modify a structure. See changestr() for
details.
Gary Oehlert
2005-08-12