Cloning R objects
Description
Makes clones of R objects, that is values in the object are repeated n times, leaving the original structure of the object intact (in most of the cases).
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18  dclone(x, n.clones=1, ...)
## Default S3 method:
dclone(x, n.clones = 1, attrib=TRUE, ...)
## S3 method for class 'dcdim'
dclone(x, n.clones = 1, attrib=TRUE, ...)
## S3 method for class 'dciid'
dclone(x, n.clones = 1, attrib=TRUE, ...)
## S3 method for class 'dctr'
dclone(x, n.clones = 1, attrib=TRUE, ...)
## S3 method for class 'list'
dclone(x, n.clones = 1,
multiply = NULL, unchanged = NULL, attrib=TRUE, ...)
## S3 method for class 'environment'
dclone(x, n.clones = 1,
multiply = NULL, unchanged = NULL, attrib=TRUE, ...)
dcdim(x, drop = TRUE, perm = NULL)
dciid(x, iid=character(0))
dctr(x)

Arguments
x 
An R object to be cloned, or a cloned object to print. 
n.clones 
Number of clones. 
multiply 
Numeric or character index for list element(s) to be multiplied by

unchanged 
Numeric or character index for list element(s) to be left unchanged. 
attrib 
Logical, 
drop 
Logical, if 
perm 
The subscript permutation value, if the cloning dimension is not the last. 
iid 
Character (or optionally numeric or logical).
Column(s) to be treated as i.i.d. observations.
Ignored when 
... 
Other arguments passed to function. 
Details
dclone
is a generic function for cloning objects.
It is separate from rep
,
because there are different ways of cloning, depending on the
BUGS
code implementation:
(1) Unchanged: no cloning at all (fo e.g. constants).
(2) Repeat: this is the most often used cloning method,
repeating the observations rowwise as if there
were more samples. The dctr
option allows repeating
the data columnwise.
(3) Multiply: sometimes it is enough to multiply the numbers (e.g. for Binomial distribution).
(4) Add dimension: under specific circumstances, it is easier to
add another dimension for clones,
but otherwise repeat the observations (e.g. in case of time series,
or for addressing special
indexing conventions in the BUGS
code, see examples
dcdim
and dclone.dcdim
).
(5) Repeat pattern (i.i.d.): this is useful for example when
a grouping variable is considered, and more i.i.d. groups are to be
added to the data set. E.g. c(1, 1, 2, 2)
is to be cloned as
c(1, 1, 2, 2, 3, 3, 4, 4)
instead of
c(1, 1, 2, 2, 1, 1, 2, 2)
.
Value
An object with class attributes "dclone"
plus the original
one(s). Dimensions of the original object might change according to
n.clones
. The function tries to take care of names, sometimes
replacing those with the combination of the original names and an
integer for number of clones.
dcdim
sets the class attribute of an object to "dcdim"
,
thus dclone
will clone the object by adding an extra dimension
for the clones.
dciid
sets the class attribute of an object to "dciid"
,
thus dclone
will clone the object by treating columns
defined by the iid
argument as i.i.d. observations.
These columns must be numeric.
This aims to facilitates working with the INLA
package to generate approximate marginals based on DC.
Columns specified by iid
will be replaced by an increasing
sequence of values respecting possible grouping structure (see
Examples).
Lists (i.e. BUGS data objects) are handled differently to enable element
specific determination of the mode of cloning. This can be done via the
unchanged
and multiply
arguments, or by setting the
behaviour by the dcdim
function.
Environments are coerced into a list, and return value is identical to
dclone(as.list(x), ...)
.
Author(s)
Peter Solymos, solymos@ualberta.ca, implementation is based on many discussions with Khurram Nadeem and Subhash Lele.
References
Lele, S.R., B. Dennis and F. Lutscher, 2007. Data cloning: easy maximum likelihood estimation for complex ecological models using Bayesian Markov chain Monte Carlo methods. Ecology Letters 10, 551–563.
Lele, S. R., K. Nadeem and B. Schmuland, 2010. Estimability and likelihood inference for generalized linear mixed models using data cloning. Journal of the American Statistical Association 105, 1617–1625.
Solymos, P., 2010. dclone: Data Cloning in R. The R Journal 2(2), 29–37. URL: http://journal.rproject.org/archive/20102/RJournal_20102_Solymos.pdf
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  ## scalar
dclone(4, 2)
## vector
(x < 1:6)
dclone(x, 2)
## matrix
(m < matrix(x, 2, 3))
dclone(m, 2)
## data frame
(dfr < as.data.frame(t(m)))
dclone(dfr, 2)
## list
(l < list(n = 10, y = 1:10, x = 1:10, p = 1))
dclone(l, 2)
dclone(as.environment(l), 2)
dclone(l, 2, attrib = FALSE)
dclone(l, 2, multiply = "n", unchanged = "p")
## effect of dcdim
l$y < dcdim(l$y)
dclone(l, 2, multiply = "n", unchanged = "p")
## time series like usage of dcdim
z < data.matrix(rnorm(10))
dclone(dcdim(z), 2)
## usage if dciid
ll < dciid(data.frame(x=1:10, y=1:10), iid="y")
dclone(ll, 2)
## respecting grouping structure in iid
ll$y < rep(1:5, each=2)
(dci < dclone(ll, 2))
nclones(dci)
## repeating the data columnwise
dclone(dctr(m), 2)
