updateable: Make a function return updateable result

In MuMIn: Multi-Model Inference

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"))

## updateable wrapper for MASS::fitdistr
fitdistr2(x, densfun, start, ...)

Arguments

FUN	function to be modified, found via \lcodematch.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 if the result is an S4 object).
x	for get_call, an object from which the call should be extracted. For fitdistr2, a numeric vector passed to \lxcodefitdistrMASS.
formula, random	arguments to be passed to gamm or gamm4
lme4	if TRUE, gamm4 is called, gamm otherwise.
densfun, start	Arguments passed to \lxcodefitdistrMASS.
...	Arguments passed to respective wrapped functions.

Details

Most model fitting functions in R return an object that can be updated or re-fitted via \lcodeupdate. This is possible thanks to the function call stored in the object, which can be used (possibly modified) later on. It is also used by dredge to generate submodels. Some functions (such as mgcv::gamm or MCMCglmm::MCMCglmm) do not provide their result with the call element. To work around this, updateable can be used on such a 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 a call.

The eval.args argument specifies the names of the function arguments to be evaluated in the stored call. This is useful if, for example, the model object does not have a formula element or does not store the formula in any other way, and the modelling function has been called with the formula specified as the variable name. In this case, the default formula method will try to retrieve the formula from the stored call, which does not guarantee that the variable will be available at the time of retrieval, or that the value of that variable will be the same as that used to fit the model (this is demonstrated in the last ‘example’).

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 an S4 object).

Note

get_call is similar to \lcodegetCall (defined in package stats), but it can also extract the call when it is an \lxcodeattribute=attr (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

\lcode

update, \lcodegetCall, \lcodegetElement, \lcodeattributes

\lxcode

gammmgcv, \lxcodegamm4gamm4

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)

MuMIn documentation built on April 1, 2025, 3 a.m.