refset: Create a reference to a subset of an object

Description

Create a refset - a reference to a subset of an object. When the object changes, the contents of the refset change, and when the refset is changed, the object is changed too.

Usage

refset(x, data, ..., drop = TRUE, dyn.idx = TRUE, read.only = FALSE,
  eval.env = parent.frame(), assign.env = parent.frame())
x %r% data

Arguments

name of the refset to create, as a bare name or character string

data

the object to refer to

...

indices to subset with

drop

passed to Extract

dyn.idx

update indices dynamically

read.only

create a read-only refset which throws an error if assigned to

eval.env

environment in which data and indices will be evaluated

assign.env

environment in which the variable named by x will be created

Value

refset returns NULL, but the x argument will be assigned to in the calling environment (or in env, if it is specified). x will have an attribute ".refset.".

Details

There are two ways to call refset. The two-argument form, e.g. refset(myref, mydata[rows,"column"]), creates a reference to the subset of mydata passed in the second argument.

The three-or-more argument form acts like the subset function: the indices in ... are applied to data. If data is a data.frame, then the indices are interpreted within it, so you can refer to columns directly: refset(myref, mydata, a>1 & b<a,). Bare column names must be quoted, however.

Empty arguments in ... are allowed and are treated as indexing the whole dimension, just as in Extract.

By default, the indices in subset are updated dynamically. For example, if you call refset(myref, mydata, x >= 3,) and then set mydata$x <- 3, the number of rows in myref will probably increase. To turn this behaviour off and make a reference to a "fixed" subset of your object, use dyn.idx=FALSE.

%r% is an infix version of the two-argument form.

Examples

Run this code

# NOT RUN {
dfr <- data.frame(a=1:4, b=1:4)
ss <- dfr[1:2,]
refset(rs, dfr[1:2,])
dfr$a <- 4:1
ss # 1:2
rs # 4:3

# same:
refset(rs, dfr, 1:2, )

# same:
rs %r% dfr[1:2,]

vec <- 1:10
refset(middle, vec[4:6])
vec[4:6] <- NA
middle 
middle <- 4:6 + 100
vec

# dynamic versus static indices:
dfr <- data.frame(a=rnorm(100), b=rnorm(100))
refset(ss, dfr, a>1,)
refset(ss.static, dfr, a>1,, dyn.idx=FALSE)
nrow(ss) == nrow(ss.static)
dfr$a <- dfr$a + 2 * dfr$b


precious.data <- rnorm(100)
refset(big, precious.data, precious.data>1, read.only=TRUE)
big
# }
# NOT RUN {
big <- big * 2 # throws an error
# }
# NOT RUN {
# Using refset with other functions:
# dynamically updated calculated column
dfr <- data.frame(a=rnorm(10), b=rnorm(10))
refset(rs, transform(dfr, x=a+2*b+rnorm(10)))
rs
rs # different

# Non-readonly refset with other functions. Works but gives a warning:
# }
# NOT RUN {
vec <- 1:5
refset(ssv, names(vec), read.only=FALSE)
ssv <- LETTERS[1:5]
vec
# }
# NOT RUN {
# }