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

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.

Gary Oehlert 2003-01-15