1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
\name{StructureClasses}
\alias{structure-class}
\alias{matrix-class}
\alias{array-class}
\alias{ts-class}
\alias{Math,structure-method}
\alias{Ops,structure,vector-method}
\alias{Ops,structure,structure-method}
\alias{Ops,structure,array-method}
\alias{Ops,vector,structure-method}
\alias{Ops,array,structure-method}
\alias{Ops,array,array-method}
\alias{initialize,array-method}
\alias{initialize,matrix-method}
\alias{initialize,ts-method}
\alias{initialize,mts-method}
\alias{show,ts-method}
\alias{matrix}
\alias{array}
\alias{ts}
\alias{structure}
\title{Classes Corresponding to Basic Structures}
\description{
The virtual class \code{structure} and classes that
extend it are formal classes analogous to S language structures such
as arrays and time-series.
}
\usage{
data matrix nrow matrix ncol matrix byrow matrix dimnames
data array dim array dimnames
data ts start ts end ts frequency ts deltat ts ts.eps ts class ts names
.Data structure ...
}
\arguments{ \item{data}{~~ TODO: describe this argument. ~~}
\item{nrow}{~~ TODO: describe this argument. ~~}
\item{ncol}{~~ TODO: describe this argument. ~~}
\item{byrow}{~~ TODO: describe this argument. ~~}
\item{dimnames}{~~ TODO: describe this argument. ~~}
\item{dim}{~~ TODO: describe this argument. ~~}
\item{start}{~~ TODO: describe this argument. ~~}
\item{end}{~~ TODO: describe this argument. ~~}
\item{frequency}{~~ TODO: describe this argument. ~~}
\item{deltat}{~~ TODO: describe this argument. ~~}
\item{ts.eps}{~~ TODO: describe this argument. ~~}
\item{class}{~~ TODO: describe this argument. ~~}
\item{names}{~~ TODO: describe this argument. ~~}
\item{.Data}{~~ TODO: describe this argument. ~~}
\item{...}{~~ TODO: describe this argument. ~~}
}
\references{
Chambers, John M. (2008)
\emph{Software for Data Analysis: Programming with R}
Springer. (For the R version.)
Chambers, John M. (1998)
\emph{Programming with Data}
Springer (For the original S4 version.)
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth & Brooks/Cole (for the original vector structures).
}
\section{Objects from the Classes}{
Objects can be created by calls of the form \code{new(Class, ...)},
where \code{Class} is the quoted name of the specific class (e.g.,
\code{"matrix"}), and the other arguments, if any, are interpreted as
arguments to the corresponding function, e.g., to function
\code{matrix()}. There is no particular advantage over calling those
functions directly, unless you are writing software designed to work
for multiple classes, perhaps with the class name and the arguments
passed in.
Objects created from the classes \code{"matrix"} and \code{"array"}
are unusual, to put it mildly, and have been for some time. Although
they may appear to be objects from these classes, they do not have the
internal structure of either an S3 or S4 class object. In particular,
they have no \code{"class"} attribute and are not recognized as
objects with classes (that is, both \code{\link{is.object}} and
\code{\link{isS4}} will return \code{FALSE} for such objects).
However, methods (both S4 and S3) can be defined for these
pseudo-classes and new classes (both S4 and S3) can inherit from them.
That the objects still behave as if they came from the corresponding
class (most of the time, anyway) results from special code
recognizing such objects being built into the base code of \R.
For most purposes, treating the classes in the usual way will work,
fortunately. One consequence of the special treatment is that these
two classes\emph{may} be used as the data part of an S4 class; for
example, you can get away with \code{contains = "matrix"} in a call
to \code{\link{setGeneric}} to create an S4 class that is a subclass
of \code{"matrix"}. There is no guarantee that everything will work
perfectly, but a number of classes have been written in this form
successfully.
Note that a class containing \code{"matrix"} or \code{"array"} will
have a \code{.Data} slot with that class. This is the only use of
\code{.Data} other than as a pseudo-class indicating the type of the
object. In this case the type of the object will be the type of the
contained matrix or array. See \code{\link{Classes_Details}} for a general
discussion.
The class \code{"ts"} is basically an S3 class
that has been registered with S4, using the
\code{\link{setOldClass}} mechanism. Versions of \R through 2.7.0
treated this class as a pure S4 class, which was in principal a good
idea, but in practice did not allow subclasses to be defined and had
other intrinsic problems. (For example, setting the
\code{"tsp"} parameters as a slot often fails because the built-in
implementation does not allow the slot to be temporarily
inconsistent with the length of the data. Also, the S4 class
prevented the correct specification of the S3 inheritance for class
\code{"mts"}.)
Time-series objects, in contrast to matrices and arrays, have a valid
S3 class, \code{"ts"}, registered using an S4-style definition (see the
documentation for \code{\link{setOldClass}} in the examples section
for an abbreviated listing of how this is done). The S3
inheritance of \code{"mts"} in package \pkg{stats} is also
registered.
These classes, as well as \code{"matrix"} and \code{"array"} should
be valid in most examples as superclasses for new S4 class
definitions.
All of these classes have special S4 methods for
\code{\link{initialize}} that accept the same arguments as the basic
generator functions, \code{\link{matrix}},
\code{\link{array}}, and \code{\link{ts}}, in so far as possible.
The limitation is that a class that has more than one non-virtual
superclass must accept objects from that superclass in the call to
\code{\link{new}}; therefore, a such a class (what is called a
\dQuote{mixin} in some languages) uses the default method for
\code{\link{initialize}}, with no special arguments.
}
\section{Extends}{
The specific classes all extend class \code{"structure"}, directly, and
class \code{"vector"}, by class \code{"structure"}.
}
\section{Methods}{
\describe{
\item{coerce}{Methods are defined to coerce arbitrary objects to
these classes, by calling the corresponding basic function, for
example, \code{as(x, "matrix")} calls \code{as.matrix(x)}.
If \code{strict = TRUE} in the call to \code{as()}, the method
goes on to delete all other slots and attributes other than the
\code{dim} and \code{dimnames}.
}
\item{Ops}{Group methods (see, e.g., \code{\link{S4groupGeneric}})
are defined for combinations of structures and vectors (including
special cases for array and matrix), implementing the concept of
vector structures as in the reference. Essentially, structures
combined with vectors retain the structure as long as the
resulting object has the same length. Structures combined with
other structures remove the structure, since there is no
automatic way to determine what should happen to the slots
defining the structure.
Note that these methods will be activated when a package is loaded
containing a class that inherits from any of the structure
classes or class \code{"vector"}.
}
}
}
\seealso{Class \linkS4class{nonStructure}, which enforces the
alternative model, in which all slots are dropped if any math
transformation or operation is applied to an object from a class
extending one of the basic classes.
}
\examples{
showClass("structure")
## explore a bit :
showClass("ts")
(ts0 <- new("ts"))
str(ts0)
showMethods("Ops") # six methods from these classes, but maybe many more
}
\keyword{classes}
|
