Modes of Objects
R objects exist within an object system. R has two object systems: S3 and S4. S4 is the newest version of R and contains a new way to approach R programming. S3 is the preceding version. Both versions run concurrently. S4 offers powerful new methods, but to use those methods a solid knowledge of S3 is necessary. This book focuses mainly on S3 methods, including S4 syntax where appropriate.
Overview of the Modes
Modes describe the type of information an object contains and are an S3-level classification. The mode of an object can be found by using the function mode(). The S4 level classification is by type and can be found using the function typeof(). Currently, R objects fall into one of the following modes: NULL, logical, numeric, complex, raw, character, list, expression, name, function, pairlist, language, char, ..., environment, externalptr, weakref, closure, bytecode, promise, and S4. Since R is constantly changing, the list of modes may change. With a few exceptions, the types and the modes are the same and most of the modes can be found under the list of types. The list of types can be found at the help page for typeof() and at http://svn.r-project.org/R/trunk/src/main/util.c, under the TypeTable. The instances for which mode() and typeof() give different results include the following: the function typeof() returns either integer or double where mode() returns numeric, typeof() returns either special or built-in where mode() returns function, and typeof() returns symbol where mode() returns name. The help page for mode() gives the cross reference between modes and types.
Commonly Used Modes
Most users will never use half of the modes. The commonly used modes are NULL, logical, numeric, complex, raw, character, list, function, call, name, expression, and S4. The mode NULL is the mode of an otherwise modeless empty object. Objects of mode logical contain elements that can take on the values TRUE, FALSE, or NA, where NA represents a missing value. Objects of mode numeric can take on integer or real numeric values or NAs. Objects of mode complex can take on complex numeric values or NAs. Objects of mode raw are made up of bytes. NAs are set to 00 for raw data.
Objects of mode character are made up of character strings or NAs. The elements of character objects are quoted, except for NAs. Objects of mode list are lists of other objects, which can be of any mode. Objects of mode function are functions. Objects of mode name are a simplified name of an object based on the first element of the object, assuming the first element is not missing. Objects of mode call are functions and arguments. Objects of mode expression are collections of objects such as calls and names. Objects of mode S4 are those S4 objects that are complex (referring to the structure of the object, not to complex numbers).
The sources for the preceding information are the help pages for mode() and typeof().
Atomic, Recursive, and Language Modes
Modes come in three kinds: atomic, recursive, and language. The atomic modes are NULL, logical, numeric, complex, raw, and character. Atomic refers to the elements of the objects being atomlike. For the atomic modes, all of the elements within the object are of the same atomic mode. Recursive modes are collections of objects and can contain objects of different modes. Two types of recursive modes are list and function. Most objects that are not atomic are recursive. The language modes are name, call, and expression. More information about the kinds of modes can be found under the help pages for the functions that test for the kind of mode of an object: is.atomic(), is.recursive(), and is.language().
Some Functions for Atomic Modes
Each of the atomic modes, except NULL, has three functions associated with the mode: the function named for the mode, name(); an as.name() function; and an is.name() function, where name is the name of the mode. The name() function creates a vector of the length given by the argument or arguments, if the argument(s) are of the correct mode and permissible value(s).
The as.name() function attempts to coerce the argument of the function to the named mode. If the coercion is not possible, the as.name() function returns a vector of NAs or gives an error. Note that if the argument is a matrix or array, a vector of the elements of the matrix or array will be returned, where the conversion to a vector proceeds down each dimension of the matrix or array in turn (in the case of a matrix, going down the rows of the first column, then the second column, and so on).
The is.name() function tests whether the argument of the function is of the named mode and returns TRUE or FALSE, depending on whether the argument is or is not.
The NULL Mode
NULL is a reserved object in R and is also a mode. While there is no function NULL() in R, as.null() and is.null() are functions. With any object used as an argument or with no argument, as.null() returns just one NULL. The function is.null() returns TRUE if the argument is equal to NULL; FALSE otherwise.
The function logical() with no argument or with zero for an argument returns logical(0), which is the logical empty set and has length zero. The function logical() with an integer greater than zero as an argument returns a vector of FALSEs of length equal to the integer. If the argument is a single double precision element, the element is rounded down and a vector of FALSEs of the length equal to the resulting integer is created. If the argument is a numeric object other than a single number or if the argument is a logical object, the function returns FALSE. If the argument is of mode NULL, character, complex, raw, or a nonatomic mode, then logical() gives an error.
The function as.logical() coerces the argument of the function to logical, if possible, and returns a vector containing TRUEs, FALSEs, and/or NAs. If there is no argument or the argument is zero or NULL, as.logical() returns logical(0), a logical empty set of length zero. If the argument is of mode numeric, zeroes will be returned as FALSEs and all other numbers will be returned as TRUEs.
If the argument is a complex object, the function returns FALSE for 0+0i and TRUE for any other complex number. If the mode is raw, 00s will return FALSE and any other value will return TRUE. If the argument is of mode character, the function returns a vector of NAs of length equal to the length of the argument. If the argument contains NAs, for any of the modes except raw, NAs will be returned for the elements containing NAs. For the raw mode, there are no NAs since NAs are interpreted as 00s in the raw mode. For any other mode, as.logical() gives an error.
The function is.logical() returns TRUE if the argument is a logical object and FALSE otherwise. The result of is.logical(logical(0)) is TRUE.
For more information about the logical mode, enter ?logical at the R prompt.
For the mode numeric, things get a bit complicated. Originally in S, numeric objects could be integer, real, or double (for double precision). The real option is deprecated and should not be used. In S3, the integer and double options are both under mode numeric. In S4, each has a separate type. The functions numeric(), is.numeric(), and as.numeric() ae covered here. The functions integer(), as.integer(), is.integer(), double(), as.double(), and is.double() behave similarly but are not covered here because they are at the S4 level.
The function numeric() takes a numeric object or NULL as an argument. If the argument equals zero or NULL or there is no argument, numeric() returns numeric(0), an empty object of mode numeric and length zero. If a numeric object of length greater than one or a logical object is the argument, only the first element is evaluated. For a logical argument, TRUE is coerced to one and FALSE is coerced to zero, while for a numeric argument, the first element is rounded down to an integer. The function then returns a vector on zeroes of length equal to the value of the first element. For arguments of modes other than numeric or logical, R returns an error.
The function as.numeric() attempts to coerce an object to double precision. The argument can be any atomic mode object. If the argument is NULL or no argument is given, numeric(0) is returned, where numeric(0) is an empty object of type numeric and length zero. If the object is logical, TRUEs are set to one and FALSEs are set to zero in the object. If the object is numeric, the values of the elements are returned as double precision numbers. If the object is complex, only the real parts are returned—as double precision numbers. If the object is of mode raw, as.numeric() converts the hexadecimal values to double precision. If the object is of mode character, the function returns NAs for the elements of the object. If the argument is not atomic, R gives an error. Elements with a value of NA are returned as NA.
The function is.numeric() tests an object to see if the object is a numeric object and works with objects of any mode. The value TRUE is returned if the object is numeric and FALSE otherwise.
More information about mode numeric objects can be found by entering ?numeric at the R prompt.
The complex mode is the mode of complex numbers. Complex numbers can be created using complex() or by simply typing in the numbers at the R prompt. For example:
> a = complex(real=1:5, imaginary=6:10)
> a
[1] 1+ 6i 2+ 7i 3+ 8i 4+ 9i 5+10i
> a = 1:5 + 1i*6:10
> a
[1] 1+ 6i 2+ 7i 3+ 8i 4+ 9i 5+10i
Note that for complex numbers there is always a number with no operator in front of the i, which lets R know that the i is the imaginary root of minus one.
For the function complex(), an argument of zero or no argument returns complex(0), an empty set of mode complex and length zero. If the argument is a single positive number, complex() returns a vector of complex zeroes of the length of the number rounded down to an integer. If the argument consists of a numeric object with more than one element or if the argument is logical either with one element or more than one element, only the first element of the argument is used, where for logical objects FALSE is coerced to zero and TRUE to one.
The function complex() also take the arguments real and imaginary or modulus and argument. The arguments real and imaginary or modulus and argument can be set equal to any numeric or logical objects. The objects do not have to be the same length and will cycle. The arguments real and imaginary are the real and imaginary parts of the numbers while the arguments modulus and argument are the polar coordinates of the numbers, with modulus equal to the lengths of the numbers and argument equal to the angles above the x axis of the numbers in radians.
Numbers of mode raw can be used for the real and imaginary arguments and will be changed to double precision, but they cannot be used for the modulus and argument arguments. For the real and imaginary pair, either one can be omitted, and the omitted argument will be set to zero. For the modulus and argument pair, if modulus is omitted, the value for modulus will be set to one, and if argument is omitted, the value for argument will be set to zero. Some examples of complex() include the following:
> complex(real=c(T,F), imaginary=1:5+0.5)
[1] 1+1.5i 0+2.5i 1+3.5i 0+4.5i 1+5.5i
> complex(modulus=c(1,2), argument=pi/4)
[1] 0.7071068+0.7071068i 1.4142136+1.4142136i
> as.raw(27:30)
[1] 1b 1c 1d 1e
> complex(real=as.raw(27:30))
[1] 27+0i 28+0i 29+0i 30+0i
> complex(ima=as.raw(27:30))
[1] 0+27i 0+28i 0+29i 0+30i
> complex(mod=as.raw(27:30))
Error in rep_len(modulus, n) * exp((0+1i) * rep_len(argument, n)) :
non-numeric argument to binary operator
> complex(mod=3:5)
[1] 3+0i 4+0i 5+0i
> complex(arg=3:5*pi/180)
[1] 0.9986295+0.0523360i 0.9975641+0.0697565i 0.9961947+0.0871557i
The function as.complex() will try to coerce an object to mode complex. If the object can be coerced to numeric (the atomic modes) but is not complex, then the result is a complex object with the coerced argument as the real part and with zeros for the imaginary part, except for NAs, which are returned simply as NAs. For nonatomic modes, as.complex() returns an error.
The function is.complex() tests whether the argument to the function is of mode complex. The function returns TRUE if the argument is of the complex mode and FALSE otherwise.
More information about the complex mode can be found by entering ?complex at the R prompt.
The raw mode is for bytewise analysis. The numbers in a raw object are in hexadecimal format, with each element consisting of two digits, either of which can take on any of the values zero through nine or a through f. Raw elements cannot have a decimal equivalent of greater than 255 (that is, be a hexadecimal number with more than two digits) or be negative.
The function raw() returns a vector of 00s of length specified by the argument. If no argument or an argument of zero is given, raw() returns raw(0), an raw empty set with length zero. If a single number is entered as the argument, raw() returns a vector of length equal to the number rounded down to an integer. If any other kind of object is entered as the argument, raw() gives an error.
The function as.raw() attempts to coerce the argument of the function to raw. If no argument is given, as.raw() returns an error. If the argument is NULL, as.raw() returns raw(0), the raw empty set. If the argument is zero, the function returns 00, the hexadecimal zero.
Objects of any of the atomic modes can be used as arguments for as.raw(). For logical mode objects, FALSEs are set to 00 and TRUEs are set to 01. For numeric mode objects, for values greater than or equal to zero and less than 256, the numbers are rounded down to an integer and converted to hexadecimal. Numbers outside the legal range are converted to 00. For objects of mode complex, the real portion is treated in the same way as numeric objects and the imaginary portion is discarded. For objects of mode character, all of the elements are converted to 00. Any element equal to NA will also be set to 00. Using objects of modes other than atomic modes for the argument gives an error.
The function is.raw() tests if an object is of mode raw. The function returns TRUE if the object is of mode raw and FALSE otherwise. Any object can be used as an argument to is.raw().
More information about the mode raw can be found by entering ?raw at the R prompt.
Character mode objects are made up of quoted strings. If an object is text, the text will be broken at each 500 characters to form a vector of strings. The three usual functions also apply to the character mode.
The function character() creates a vector of empty strings and only takes mode numeric, one-element arguments. If the argument is greater than or equal to one, the argument is rounded down to an integer and the function returns a vector of “”s of length equal to the integer. If the argument is less than one and greater than or equal to zero, the character empty set of length zero, character(0), is returned. Other arguments return an error.
The function as.character() tries to convert the argument to strings. For the atomic modes, the conversion is literal, but the elements are returned within quotes. For double precision numbers up to 15 significant digits are used. Unlike the other atomic modes—except NULL—the function as.character() also returns results for some of the recursive modes.
Objects of mode list are described under the next section. In this section, lists are collections of objects that can be of any mode. The function lm() used in the example below fits a linear regression model, with the value to the left of the tilde being the dependent variable and the value to the right the independent variable. The output from lm() is a list.
With an object of mode list as an argument, as.character() may return some strange things depending on the list. The function may return something different from what is returned if the argument is entered at the R prompt. Examples follow:
> a.list
[[1]]
a1 a2 a3 a4
[1,] 1 6 11 16
[2,] 2 7 12 17
[3,] 3 8 13 18
[4,] 4 9 14 19
[5,] 5 10 15 20
[[2]]
[1] 1 2 3 4 5 6 7 8 9 10
[[3]]
[1] "glh" "abc"
> as.character(a.list)
[1] "1:20" "1:10" "c("glh", "abc")"
> a.lm
Call:
lm(formula = y ~ x)
Coefficients:
(Intercept) x
1 1
> as.character(a.lm)
[1] "c(0.999999999999999, 1)"
[2] "c(0, 0, 0)"
[3] "c(-5.19615242270663, -1.41421356237309, 0)"
[4] "2"
[5] "c(2, 3, 4)"
[6] "0:1"
[7] "list(qr = c(-1.73205080756888, 0.577350269189626, 0.577350269189626, -3.46410161513776, -1.41421356237309, 0.965925826289068), qraux = c(1.57735026918963, 1.25881904510252), pivot = 1:2, tol = 1e-07, rank = 2)"
[8] "1"
[9] "list()"
[10] "lm(formula = y ~ x)"
[11] "y ~ x"
[12] "list(y = 2:4, x = 1:3)"
Play around with different kinds of lists to see how as.character() performs.
Objects of modes name, call, and expression can also be coerced to character. Objects of modes function and S4 cannot.
The function is.character() tests to see if the argument to the function is of mode character and returns TRUE if so and FALSE otherwise. Any object can be used as an argument.
For more information about the character mode, enter ?character at the R prompt.
The Common Recursive and Language Modes
The recursive and language modes covered in this book are list, function, call, expression, and name. The modes list, function, call, and expression are all recursive modes. The modes call and expression are also language modes. The mode name is a language mode but not a recursive mode.
The List Mode
Lists are collections of objects, which may be of any mode and which do not have to be of the same mode within the list. The list mode has the same three functions as the atomic modes; however, there are a few more. Creating an empty list differs from the atomic modes. To create a list of a given number of objects where the objects are NULLs, use
vector("list", n),
where n is the number of objects to be in the list. The variable, n, must be numeric, is rounded down to an integer, and can only contain one element.
The function unlist() removes the list property for some lists and, for those lists, returns a vector of the elements of the objects in the list.
The function alist() creates a list where the values of variables in the list do not have to be specified. The function alist() is most often used in evaluating functions, where some variables can be prespecified and others are assigned at each running of the function.
The function list() creates a list out of the arguments to the function. Within the parentheses, the arguments are separated by commas. The arguments can be any kind of object.
The function as.list() attempts to coerce the argument to mode list. If more than one argument is supplied, only the first argument is coerced. The other arguments are ignored.
The function is.list() tests if the argument is a list (or a pairwise list, which is not covered here). If the object is of mode list, TRUE is returned. Otherwise, FALSE is returned.
More information can be found by entering ?list at the R prompt, which brings up the help page for list().
Functions in R are of mode function. Of the functions listed for atomic modes, only is.function() and function() exist for the mode function. The function is.function() returns TRUE if the argument is a function and FALSE otherwise. The function function() creates functions, but the structure of functions is different from the atomic modes and the list mode, and the help page for function() is different from the help page for is.function(). We will cover the creation of functions in Chapter 7.
Another mode for functions is closure. The mode closure is for functions that are not primitive—that is, are written in R code. Note that functions of mode closure are also of mode function. The function is.primitive() exists to test if a function is primitive, but a function is.closure() does not exist.
More information about the function mode can be found by entering ?is.function at the R prompt, which will bring up the help page for is.function().
Objects of the call mode are unevaluated functions with arguments, if the function takes arguments. The same three functions that exist for the atomic modes exist for the call mode: call(), as.call(), and is.call().
The function call() creates an object of mode call. The first argument of call() is the name of the function in quotes. The rest of the arguments to call are the arguments to the function. Some examples include the following:
> a.call = call("lm", y~x)
> a.call
lm(y ~ x)
> b.call = call("ls")
> b.call
ls()
> c.call = call("ls", pattern="abc")
> c.call
ls(pattern = "abc")
Note that an object of mode call can be evaluated using the function eval(). If all of the variables in the call exist in the workspace, eval() will evaluate the function; otherwise eval() will give an error. For example:
> x
[1] 1 2 3
> y
[1] 2 3 4
> eval(a.call)
Call:
lm(formula = y ~ x)
Coefficients:
(Intercept) x
1 1
> a.call = call("lm", z~x)
>
> z
Error: object 'z' not found
>
> eval(a.call)
Error in eval(expr, envir, enclos) : object 'z' not found
The function as.call() tries to coerce the argument to an object of mode call. If the argument is a list, then the conversion takes place; otherwise an error is returned. However, if the list does not consist of the name of a function followed by the arguments of that function, the object cannot be evaluated.
The function is.call() tests the argument and returns TRUE if the argument is of mode call and FALSE otherwise.
Further information about the mode call can be found by entering ?call at the R prompt.
The mode name refers to objects that are names created for and from other objects. Only the functions as.name() and is.name() exist for the name mode. Names can be up to 10,000 bytes long.
The function as.name() takes arguments that can be logical, numeric, complex, raw, character, or name. Arguments of other modes give an error. The function uses the first element of the object to assign the name. For example:
> mat
one two
row1 1 6
row2 2 7
> as.name(mat)
`1`.
The function is.name() tests if the argument is of mode name and returns TRUE if so and FALSE otherwise.
Note that the mode name and the type symbol are the same so as.name() is the same as as.symbol() and is.name() is the same as is.symbol(). The mode name is the S3 convention and the type symbol is the S4 convention. More information can be found by entering ?name at the R prompt.
The expression mode is like the list mode, but mainly for objects of modes like class or name. Objects of mode expression can be subsetted like lists and are not evaluated when created. The expression mode uses the three functions that the atomic modes use: expression(), as.expression(), and is.expression().
The function expression() creates a listing of the objects entered into the function. The objects are separated by commas and can be of any mode. The function eval() can be used to evaluate the expression. Only the last object in an expression is evaluated under eval(). If the last argument is made up of primitive functions, eval() will return the result, while if the function or expression is not primitive, eval() will return the expression. A second eval() is then necessary to evaluate the function or expression. Examples follow:
> a.exp = expression(sin(1:5/180*pi))
> a.exp
expression(sin(1:5/180 * pi))
> eval(a.exp)
[1] 0.01745241 0.03489950 0.05233596 0.06975647 0.08715574
> a.exp = expression(sin(1:5/180*pi),a.call)
> a.exp
expression(sin(1:5/180 * pi), a.call)
> eval(a.exp)
lm(y ~ x)
> eval(eval(a.exp))
Call:
lm(formula = y ~ x)
Coefficients:
(Intercept) x
1 1
> a.exp = expression(a.call,sin(1:5/180*pi))
> eval(a.exp)
[1] 0.01745241 0.03489950 0.05233596 0.06975647 0.08715574
An object of name mode will give an error if placed as the last argument in an expression that is being evaluated.
The function as.expression() attempts to coerce the argument to mode expression. The modes NULL, call, name, and pairlist are coerced to a single element expression. Atomic modes other than NULL are coerced elementwise. Lists are coerced with no changes except the mode. Other modes of objects will give an error if coercion is attempted.
The function is.expression() tests the argument and will return TRUE if the argument is of mode expression and FALSE otherwise.
More information about the expression mode can be found by entering ?expression at the R prompt.
The mode S4 identifies objects that are used in the new S4 version of R, which uses a quite different syntax and is not covered in this book. The isS4() function returns TRUE if an object is of mode S4 and FALSE otherwise. The function mode() returns S4 if the argument is of mode S4.
You can find more information by entering ?S4 at the R prompt.