Combine multidimensional arrays
Description
Combine multidimensional arrays. This is a generalization of cbind and rbind. Takes a sequence of vectors, matrices, or arrays and produces a single array of the same or higher dimension.
Usage
1 2 3 
Arguments
... 
Any number of vectors, matrices, arrays, or data frames.
The dimensions of all the arrays must match, except on one dimension
(specified by Alternatively, there can be one (and only one) list argument supplied, whose components are the objects to be bound together. Names of the list components are treated in the same way as argument names. 
along 
(optional) The dimension along which to bind the arrays.
The default is the last dimension, i.e., the maximum length of the dim
attribute of the supplied arrays. 
rev.along 
(optional)
Alternate way to specify the dimension along which to bind the arrays:

new.names 
(optional)
If new.names is a list, it is the first choice for the
dimnames attribute of the result. It should have the same
structure as a dimnames attribute. If the names for a
particular dimension are If 
force.array 
(optional) If 
make.names 
(optional)
If <p>The default is 
use.anon.names 
(optional)

use.first.dimnames 
(optional)
When dimension names are present on more than one
argument, should dimension names for the result be take from
the first available (the default is to take them from the
last available, which is the same behavior as

hier.names 
(optional)
If 
use.dnns 
(default 
Details
The dimensions of the supplied vectors or arrays do not need
to be identical, e.g., arguments can be a mixture of vectors
and matrices. abind
coerces arguments by the addition
of one dimension in order to make them consistent with other
arguments and along=
. The extra dimension is
added in the place specified by along=
.
The default action of abind is to concatenate on the last
dimension, rather than increase the number of dimensions.
For example, the result of calling abind with vectors is a
longer vector (see first example below). This differs from
the action of rbind
and cbind which is to return a matrix when
called with vectors. abind can be made to behave like cbind
on vectors by specifying along=2
, and like rbind by
specifying along=0
.
The dimnames of the returned object are pieced together
from the dimnames of the arguments, and the names of the
arguments. Names for each dimension are searched for in the
following order: new.names, argument name, dimnames (or
names) attribute of last argument, dimnames (or names)
attribute of second last argument, etc. (Supplying the
argument use.first.dimnames=TRUE
changes this to
cause abind
to use dimnames or names from the
first argument first. The default behavior is the same as
for rbind
and cbind
: use dimnames
from later arguments.) If some names are supplied for the
along dimension (either as argument names or dimnames in
arguments), names are constructed for anonymous arguments
unless use.anon.names=FALSE
.
Value
An array with a dim attribute calculated as follows.
Let rMin=min(sapply(list(...), function(x) length(dim(x))))
and
rMax=max(sapply(list(...), function(x) length(dim(x))))
(where
the length of the dimensions of a vector are taken to be 1). Then rMax
should be
equal to or one greater than rMin
.
If along
refers to an existing dimension, then the length of
the dim attribute of the result is rMax
. If along
does
not refer to an existing dimension, then rMax
should equal
rMin
and the length of the dim attribute of the result will be rMax+1
.
rbind
or cbind
are
called to compute the result if (a)
force.array=FALSE
; and (b) the result will be a
twodimensional object.
Note
It would be nice to make abind()
an S3 generic, but S3 generics
cannot dispatch off anonymous arguments.
The ability of abind()
to accept a single list argument removes
much of the need for constructs like do.call("abind",
list.of.arrays)
. Instead, just do abind(list.of.arrays)
. The
direct construct is preferred because do.call()
construct can
sometimes consume more memory during evaluation.
Author(s)
Tony Plate tplate@acm.org and Richard Heiberger
Examples
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  # Five different ways of binding together two matrices
x < matrix(1:12,3,4)
y < x+100
dim(abind(x,y,along=0)) # binds on new dimension before first
dim(abind(x,y,along=1)) # binds on first dimension
dim(abind(x,y,along=1.5))
dim(abind(x,y,along=2))
dim(abind(x,y,along=3))
dim(abind(x,y,rev.along=1)) # binds on last dimension
dim(abind(x,y,rev.along=0)) # binds on new dimension after last
# Unlike cbind or rbind in that the default is to bind
# along the last dimension of the inputs, which for vectors
# means the result is a vector (because a vector is
# treated as an array with length(dim(x))==1).
abind(x=1:4,y=5:8)
# Like cbind
abind(x=1:4,y=5:8,along=2)
abind(x=1:4,matrix(5:20,nrow=4),along=2)
abind(1:4,matrix(5:20,nrow=4),along=2)
# Like rbind
abind(x=1:4,matrix(5:20,nrow=4),along=1)
abind(1:4,matrix(5:20,nrow=4),along=1)
# Create a 3d array out of two matrices
abind(x=matrix(1:16,nrow=4),y=matrix(17:32,nrow=4),along=3)
# Use of hier.names
abind(x=cbind(a=1:3,b=4:6), y=cbind(a=7:9,b=10:12), hier.names=TRUE)
# Use a list argument
abind(list(x=x, y=x), along=3)
# Use lapply(..., get) to get the objects
an < c('x','y')
names(an) < an
abind(lapply(an, get), along=3)
