Contents

labels

Usage:

This topic has information on coordinate labels.
Functions for working with labels are:
  setlabels(x, labs [,silent:T])
  setlabels(x, NULL) # remove labels
  labs <- getlabels(x [,silent:T])
  labs <- getlabels(x,vector(1,3,5) [,silent:T])
  if (haslabels(x)){..do something with labels...}
  y <- vector(x,labels:labs [, silent:T])
  y <- matrix(x,labels:structure(rowLabs,colLabs) [, silent:T])
  y <- array(x,labels:structure(lab1,lab2,...) [, silent:T])
  y <- structure(comp1, comp2, ..., labels:labs [, silent:T])
  y <- strconcat(var1, var2, ..., labels:labs [, silent:T])
  y <- hconcat(x1,x2,...,labels:structure(rowLabs,colLabs) [, silent:T])
  y <- vconcat(x1,x2,...,labels:structure(rowLabs,colLabs) [, silent:T])
  y <- matread(fileName,labels:structure(rowLabs,colLabs))

Keywords: general, variables, output

MacAnova vectors, matrices and arrays may have labels for each
dimension.  The label for dimension k is a CHARACTER vector with length
dim(x)[k].  When a variable x has any labels it has them for all
dimensions.

A structure Str may have a single vector of labels of length ncomps(Str)
to label the components.  This is distinct from labels the individual
components may have and distinct from the component names.

The primary function of the labels for a variable is to provide
informative identification of coordinates when the variable is printed.

Labels belonging to x are sometimes propagated to new variables computed
from x.  See below for details.

getlabels(x) retrieves all the labels, if any, associated with variable
x.  When x is a vector or a structure, the result is a CHARACTER vector;
otherwise the result is a structure with ndims(x) CHARACTER vector
components.

getlabels(x, 2), say, retrieves the labels for dimension 2 of x as a
CHARACTER vector.  getlabels(x,vector(1,3)), for example, retrieves as a
structure with two components the labels associated with dimensions 1
and 3 of x.  See getlabels().

haslabels(x) is True if and only if variable x has coordinate labels.

                            Removing Labels
setlabels(x, NULL), removes the labels from a scalar, vector, matrix,
array or structure x.

                            Attaching Labels
setlabels(x, Labs) adds coordinate labels to an existing variable.  When
x already has labels they are replaced.

In these usages, Labs is a CHARACTER vector or scalar, or a structure
with CHARACTER vector or scalar components, one for each dimension of
the variable to be labeled.

Examples:
  Cmd> setlabels(x, vector("MN","WI","IA","ND","SD","NE")) # x a vector

  Cmd> setlabels(w, structure(vector("M","F"),\
         vector("Urban","Suburban","rural"))) # w a 2 by 3 matrix

It is not an error when the number of vectors of labels supplied does
not match the number of dimensions.  Extra labels are ignored and
missing ones are assumed to be "@" which will be printed as numbers in
parentheses (see below).  In both cases a warning message is normally
printed.

You can use keyword 'labels' on vector(), matrix(), array(), hconcat(),
vconcat(), structure(), strconcat(), and matread() to create a labelled
variable.  The general usage
  xxxxxx(... , labels:Labs [,silent:T])
where xxxxxx() is one of these functions and Labs is as described for
setlabels().

Supplying a vector of coordinate labels of the wrong length to
setlabels() is an error.  On other commands on which you can set labels
using keyword 'labels' (matrix(), for example), providing labels of the
wrong length produces only a warning message that the labels will be
ignored.

On any of the commands which set labels, you can suppress warning
messages by keyword phrase 'silent:T'.

When variable x has labels, matprint(fileName, x) and matwrite(fileName,
x) write the labels to the file immediately following x in a format that
allows
  Cmd> x <- matread(fileName, "x")
to retrieve both data and labels for x from the file.  Topic
'matread_file' describes the file format of labeled variables.  See also
matread().

                        Expanding Scalar Labels
When you provide labels using keyword 'labels' on a command or as an
argument to setlabels(), any scalar labels (quoted strings or CHARACTER
vectors of length 1) are treated specially.

A scalar label, say "root", for a coordinate with length > 1 is expanded
to vector("root1","root2",...).  For example, labels:structure("A","B ")
generates labels vector("A1","A2",...) and vector("B 1","B 2",...).

This doesn't happen if a scalar label starts with '@' or is one of "",
"#", "(", "[", "{", "<", "/", or "\\".

Scalar label "" is expanded to rep("", length) resulting in its
dimension having no visible labels.

Scalar label "#" is expanded to vector("1","2",...).

Scalar label "(" is expanded to vector("(1)","(2)", ...) and similarly
for the other special characters, with the first element of the label
being "[1]", "{1}", "<1>", "/1/", or "\\1\\".

Scalar label "@" is expanded to rep("@", n) and a scalar label starting
with '@', say "@anything" is expanded to rep("@anything", n).  Such
labels are further expanded when they are printed.

      Expansion of labels starting with '@' when they are printed
A label of the form rep("@", n) or rep("@anything", n) is interpreted
specially when it is printed.  At that time, it is further expanded
similarly to the way scalar labels that do not start with '@' are
expanded when they are created.

rep("@#", n) prints as '1', '2', ... .

rep("@[", n) prints as '[1]', '[2]', ..., and similarly with "@(", "@{",
"@<", "@/",or "@\\".

rep("@", n) prints "bracketed" labels using the default labeling style,
usually using '(' and ')'.  This style can be changed by option
'labelstyle'.  For example, after setoptions(labelstyle:"["), "@" has
the same effect as "@[".  See topic setoptions(), subtopic
'options:"labelstyle"'.

rep("@anythingelse", n) prints as 'anythingelse1', 'anythingelse2', ....

Note: The use of '@' delays the substitution of numerical indices until
they are actually used in printing, so that the same value may have
different printed labels at different times.  See the paragraph on
propagation of labels below.

When successive coordinates have the same type of "bracket" label
starting with '@' created by, say, labels:structure("@[","@[","["), the
printed labels are combined to, say, '[1,2]'.

Examples
  Cmd> setlabels(x, structure("#","X"))
  x now has labels vector("1","2",...) and vector("X1","X2",...).

  Cmd> y <- vector(vecread(fileName),labels:structure("Case ","Y"),\
        silent:T)
  y has labels vector("Case 1","Case 2",...) and vector("Y1","Y2",...)

  Cmd> z <- matread("MacAnova.dat","irisdata",\
        labels:structure("",vector("Variety","Y1","Y2","Y3","Y3")))
  The first label of z is rep("",nrows(z)) which does not print.

  Cmd> logy <- matrix(log(y),labels:structure("@",log(getlabels(y,2))))
  The labels of logy y will be rep("@",nrows(y)) and vector("log(Y1)",
  "log(Y2)", ...).  When printed the row labels of logy or any subset of
  rows of logy will be '(1)', '(2)', ... .

                         Propagation of Labels
A variable created by extracting part of a labeled variable using
subscripts is labeled with the appropriate subsets of the labels.
Examples:
After
  Cmd> x <- matrix(run(9),3,labels:structure("[","A "))[-1,-1]
x has labels vector("[2]","[3]") and vector("A 2", "A 3").

After
  Cmd> x <- matrix(run(9),3,labels:structure("@[","@A "))[-1,-1]
has labels vector("@[","@[") and vector("@A ","@A ").  When x is
printed, the row labels will be '[1]', '[2]' and the column labels will
be 'A 1', 'A 2', even though these are rows 2 and 3 and columns 2 and 3
of matrix(run(9),3).  That is, the special expansion of labels starting
with '@' occurs when they are printed, not when they are created.

cos(x), sqrt(x), and other transformation of x have the same labels as
x.

ismissing(x), rank(x), rankits(x) and halfnorm(x), but not sort(x) or
grade(x) have the same labels as x.

x' has the same label vectors as x but in reverse order

When the result of sum(x), min(x) and other transformation that operate
along the first dimension of x is not a scalar, its label for the first
dimension is "@" and the remaining labels match those of x.

+x, -x and !x have the same labels as x.

If OP is a binary operator such as '+', '-', '*', '==', ..., but not a
matrix operator such as %*%, %c%, and %C%, then x OP y often has the
labels of x.  When x does not have labels, x OP y may have the labels of
y.  If both x and y are scalar variables, x OP y does not have labels,
even if one or both of x and y do have labels.

When matrices x and y both have labels, x %*% y, x %c% y, and x %C% y
have labels taken from the row and or column labels of x and y in the
obvious way.  When only one of x or y has labels, the result is labelled
as if the one without the labels had row and column labels of the form
rep("@",m).

In most cases, functions and operators that transform structures to
similar shaped structures propagate labels for structure components.
This includes max(), min(), sum(), prod(), sort(), rank(), grade(),
ismissing(), and mathematical transformations such as cos(), log() and
sqrt().

When x is a labelled matrix, eigen(x)$vectors and releigen(x,y)$vectors
have the same row labels as x and column labels of the form
vector("(1)", "(2)", ...).

When x is a labelled matrix, the matrices of left and right singular
vectors as computed by svd() have labels.  Their row vectors are the row
and column labels of x, respectively.  Their column labels are of the
form vector("(1)", "(2)", ...).

If a is a labelled square matrix, the row and column labels of solve(a)
are the column and row labels of a, respectively.

If a is a labelled square matrix, the row and column labels of solve(a,
b) (a %\% b) are the column labels of a and b, respectively; the row and
column labels of rsolve(a,b) (b %/% a) are the row labels of b and a,
respectively.  When b has no labels, they are assumed to have the form
rep("@",m).  See topics solve(), rsolve(), 'matrices'.

When x is a labelled matrix, cor(x) has row and column labels matching
the column labels of x.  cor(x1, x2, ...) has no labels, even if x1, x2,
... have lables.

When x is a labelled matrix, rft(x) and hft(x) have the same column
labels as x with row labels of the form rep("@", nrows(x)).  The same is
true for cft(x) when ncols(x) is even.

If y is a response variable in a GLM command, its labels are propagated
to side effect variables RESIDUALS, WTDRESIDUALS, and HII.

After regress(), COEF and XTXINV are labeled with the names of the
variables (including "CONSTANT" when appropriate).

After any GLM function producing side effect variables DF and SS, DF and
the first dimension of SS are labeled with TERMNAMES.  After manova(),
dimensions 2 and 3 of SS are labeled with the column labels of the
response variable, it if has labels, and with vector("(1)","(2)", ... ),
otherwise.  The actual brackets used in the default labelling are
determined by the value of option 'labelstyle'.  For example, if the
value of 'labelstyle' is "[", the default labels are vector("[1]",
"[2]"',...).  See subtopic 'options:"labelstyle"'.

After manova(), the column labels of the response variable are attached
to the last dimension of each vector, matrix, or array returned by
coefs() and secoefs().

When any term name is longer than 12 characters (the maximum size for a
structure component name), structure output of coefs() and secoefs() is
labeled with the full term names.

When a structure with component labels is printed, the labels are
printed instead of the component names.