Next: subscripts Up: MacAnova Help File Previous: structure()   Contents

structures

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