updateable {MuMIn}

Make a function return updateable result

Description

Creates a function wrapper that stores a call in the object returned by its argument FUN.

Usage

updateable(FUN, eval.args = NULL, Class)

get_call(x)

## updateable wrapper for mgcv::gamm and gamm4::gamm4
uGamm(formula, random = NULL, ..., lme4 = inherits(random, "formula"))

Arguments

FUN

function to be modified, found via match.fun.

eval.args

optionally a character vector of function arguments' names to be evaluated in the stored call. See ‘Details’.

Class

optional character vector naming class(es) to be set onto the result of FUN (not possible with formal S4 objects).

x

an object from which the call should be extracted.

formula, random, ...

arguments to be passed to gamm or gamm4

lme4

if TRUE, gamm4 is called, gamm otherwise.

Details

Most model fitting functions in R return an object that can be updated or re-fitted via update. This is thanks to the call stored in the object, which can be used (possibly modified) later on. It is also utilised by dredge to generate sub-models. Some functions (such as gamm or MCMCglmm) do not provide their result with the call element. To work that around, updateable can be used on that function to store the call. The resulting “wrapper” should be used in exactly the same way as the original function.

updateable can also be used to repair an existing call element, e.g. if it contains dotted names that prevent re-evaluation of such a call.

Argument eval.args specifies names of function arguments that should be evaluated in the stored call. This is useful when, for example, the model object does not have formula element. The default formula method tries to retrieve formula from the stored call, which works unless the formula has been given as a variable and value of that variable changed since the model was fitted (the last ‘example’ demonstrates this).

Value

updateable returns a function with the same arguments as FUN, wrapping a call to FUN and adding an element named call to its result if possible, otherwise an attribute "call" (if the returned value is atomic or a formal S4 object).

Note

get_call is similar to getCall (defined in package stats), but it can also extract the call when it is an attribute (and not an element of the object). Because the default getCall method cannot do that, the default update method will not work with atomic or S4 objects resulting from updateable wrappers.

uGamm sets also an appropriate class onto the result ("gamm4" and/or "gamm"), which is needed for some generics defined in MuMIn to work (note that unlike the functions created by updateable it has no formal arguments of the original function). As of version 1.9.2, MuMIn::gamm is no longer available.

Author(s)

Kamil Bartoń

See Also

update, getCall, getElement, attributes

gamm, gamm4

Examples

# Simple example with cor.test:

# From example(cor.test)
x <- c(44.4, 45.9, 41.9, 53.3, 44.7, 44.1, 50.7, 45.2, 60.1)
y <- c( 2.6,  3.1,  2.5,  5.0,  3.6,  4.0,  5.2,  2.8,  3.8)

ct1 <- cor.test(x, y, method = "kendall", alternative = "greater")

uCor.test <- updateable(cor.test)

ct2 <- uCor.test(x, y, method = "kendall", alternative = "greater")

getCall(ct1) # --> NULL
getCall(ct2)

#update(ct1, method = "pearson") --> Error
update(ct2, method = "pearson")
update(ct2, alternative = "two.sided")


## predefined wrapper for 'gamm':

set.seed(0)
dat <- gamSim(6, n = 100, scale = 5, dist = "normal")

fmm1 <- uGamm(y ~s(x0)+ s(x3) + s(x2), family = gaussian, data = dat, 
    random = list(fac = ~1))

getCall(fmm1)
class(fmm1)

###

## Not run: 
library(caper)
data(shorebird)
shorebird <- comparative.data(shorebird.tree, shorebird.data, Species)

fm1 <- crunch(Egg.Mass ~ F.Mass * M.Mass, data = shorebird)

uCrunch <- updateable(crunch)

fm2 <- uCrunch(Egg.Mass ~ F.Mass * M.Mass, data = shorebird)

getCall(fm1)
getCall(fm2)
update(fm2) # Error with 'fm1'
dredge(fm2)

## End(Not run)

###
## Not run: 
# "lmekin" does not store "formula" element 
library(coxme)
uLmekin <- updateable(lmekin, eval.args = "formula")

f <- effort ~ Type + (1|Subject)
fm1 <- lmekin(f, data = ergoStool)
fm2 <- uLmekin(f, data = ergoStool)

f <- wrong ~ formula # reassigning "f"

getCall(fm1) # formula is "f"
getCall(fm2) 

formula(fm1) # returns the current value of "f" 
formula(fm2)

## End(Not run)