File: afill.Rd

package info (click to toggle)
abind 1.4-5-1
  • links: PTS
  • area: main
  • in suites: stretch
  • size: 180 kB
  • sloc: makefile: 1
file content (151 lines) | stat: -rw-r--r-- 5,104 bytes parent folder | download | duplicates (4)
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
\name{afill}
\alias{afill}
\alias{afill<-}
\alias{afill<-.default}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{ Fill an array with subarrays }
\description{
  Fill an array with subarrays.  \code{afill}
  uses the dimension names
  in the value in determining how to fill the LHS, unlike standard array
  assignment, which ignores dimension names in the value.
\code{afill()} is a S3 generic, with
one method, \code{afill.default}, supplied in the \code{abind} package.
}
\usage{
afill(x, ..., excess.ok = FALSE, local = TRUE) <- value
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{x}{ An array to be changed }
  \item{\dots}{ Arguments that specify indices for \code{x}.  If
    \code{length(dim(value)) < length(dim(x))}, then exactly \code{length(dim(x))}
    anonymous arguments must be supplied, with empty ones corresponding to
    dimensions of \code{x} that are supplied in \code{value}. }
  \item{excess.ok}{ If there are elements of the dimensions of
    \code{value} that are not found in the corresponding dimensions
     of x, they will be discarded if \code{excess.ok=TRUE}.}
  \item{local}{ Should the assignment be done in on a copy of x, and the
    result returned (normal behavior).  If \code{local=FALSE} the
    assignment will be done directly on the actual argument supplied as
    \code{x}, which can be more space efficient.}
  \item{value}{ A vector or array, with dimension names that match some dimensions of
    \code{x} }
}
\details{
  The simplest use of \code{afill} is to fill a sub-matrix. Here is an
  example of this usage:
  \preformatted{
> (x <- matrix(0, ncol=3, nrow=4, dimnames=list(letters[1:4], LETTERS[24:26])))
  X Y Z
a 0 0 0
b 0 0 0
c 0 0 0
d 0 0 0
> (y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26])))
  Y Z
b 1 3
c 2 4
> afill(x) <- y
> x
  X Y Z
a 0 0 0
b 0 1 3
c 0 2 4
d 0 0 0
>
}
The above usage is equivalent (when x and y have appropriately matching
dimnames) to
\preformatted{
> x[match(rownames(y), rownames(x)), match(colnames(y), colnames(x))] <- y
}

  A more complex usage of \code{afill} is to fill a sub-matrix in a
  slice of a higher-dimensional array.  In this case, indices for
  \code{x} must be supplied as arguments to \code{afill}, with the
  dimensions corresponding to those of \code{value} being empty, e.g.:
  \preformatted{
> x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
> y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
> afill(x, 1, , ) <- y
> x[1,,]
  X Y Z
a 0 0 0
b 0 1 3
c 0 2 4
d 0 0 0
> x[2,,]
  X Y Z
a 0 0 0
b 0 0 0
c 0 0 0
d 0 0 0
>
}

  The most complex usage of \code{afill} is to fill a sub-matrix in multiple
  slice of a higher-dimensional array.  Again, indices for
  \code{x} must be supplied as arguments to \code{afill}, with the
  dimensions corresponding to those of \code{value} being empty.
  Indices in which all slices should be filled can be supplied as
  \code{TRUE}.  E.g.:
  \preformatted{
> x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
> y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
> afill(x, TRUE, , ) <- y
> x[1,,]
  X Y Z
a 0 0 0
b 0 1 3
c 0 2 4
d 0 0 0
> x[2,,]
  X Y Z
a 0 0 0
b 0 1 3
c 0 2 4
d 0 0 0
>
}

In the above usage, \code{afill} takes care of replicating \code{value}
in the appropriate fashion (which is not straghtforward in some cases).
}
\value{
  The object \code{x} is changed.  The return value of the assignment is
  the parts of the object \code{x} that are changed.  This is similar to
  how regular subscript-replacement behaves, e.g., the expression
  \code{x[2:3] <- 1:2} returns the vector \code{1:2}, not the entire
  object \code{x}.  However, note that there can be differences
}
% \references{ ~put references to the literature/web site here ~ }
\author{Tony Plate \email{tplate@acm.org}}
% \note{ ~~further notes~~ }
\seealso{ \code{\link{Extract}} }
\examples{
# fill a submatrix defined by the dimnames on y
(x <- matrix(0, ncol=3, nrow=4, dimnames=list(letters[1:4], LETTERS[24:26])))
(y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26])))
afill(x) <- y
x
all.equal(asub(x, dimnames(y)), y) # TRUE
# fill a slice in a higher dimensional array
x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
afill(x, 1, , ) <- y
x[1,,]
x[2,,]
all.equal(asub(x, c(1,dimnames(y))), y) # TRUE
# fill multiple slices
x <- array(0, dim=c(2,4,3), dimnames=list(LETTERS[1:2], letters[1:4], LETTERS[24:26]))
y <- matrix(1:4, ncol=2, nrow=2, dimnames=list(letters[2:3], LETTERS[25:26]))
afill(x, TRUE, , ) <- y
x[1,,]
x[2,,]
all.equal(asub(x, c(1,dimnames(y))), y) # TRUE
all.equal(asub(x, c(2,dimnames(y))), y) # TRUE
}

\keyword{ manip }
\keyword{ array }