spaMM: spaMM_boot – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

spaMM_boot

Parametric bootstrap

Description

This simulates samples from a fit object inheriting from class "HLfit", as produced by spaMM's fitting functions, and applies a given function to each simulated sample. Parallelization is supported (see Details). A typical usage of the parametric bootstrap is to fit by one model some samples simulated under another model (see Example).

Usage

spaMM_boot(object, simuland, nsim, nb_cores=NULL, seed=NULL,
           resp_testfn=NULL, control.foreach=list(),
           debug. = FALSE, type, fit_env=NULL, cluster_args=NULL,
           showpbar= eval(spaMM.getOption("barstyle")),
           ...)

Arguments

`object`	The fit object to simulate from.
`simuland`	The function to apply to each simulated sample. See Details for requirements of this function.
`nsim`	Number of samples to simulate and analyze.
`nb_cores`	Number of cores to use for parallel computation. The default is `spaMM.getOption("nb_cores")`, and 1 if the latter is NULL. `nb_cores=1` prevents the use of parallelisation procedures.
`seed`	Passed to `simulate.HLfit`
`resp_testfn`	Passed to `simulate.HLfit`; NULL, or a function that tests a condition which simulated samples should satisfy. This function takes a response vector as argument and return a boolean (TRUE indicating that the sample satisfies the condition).
`control.foreach`	list of control arguments for `foreach`. These include in particular `.combine` (with default value `"rbind"`), and `.errorhandling` (with default value `"remove"`, but `"pass"` is quite useful for debugging).
`debug.`	Boolean (or integer, interpreted as boolean). For debugging purposes, particularly from parallel computations. The effect of `debug.=TRUE` depends on what `simuland` does of it. The default `simuland` for likelihood ratio testing functions, `eval_replicate`, shows how `debug.` can be used.
`type`	Character: passed to `simulate.HLfit`. Defaults, with a warning, to `type="marginal"` in order to replicate the behaviour of previous versions. But this is not necessarily the appropriate `type` for all possible uses. See Details of `simulate.HLfit` for other implemented options.
`fit_env`	An environment or list containing variables necessary to evaluate `simuland` on each sample, and not included in the fit `object`. E.g., use `fit_env=list(phi_fix=phi_fix)` if the fit assumed `fixed=list(phi=phi_fix)`
`cluster_args`	`NULL` or a `list` of arguments, passed to `makeCluster`.
`showpbar`	Controls display of progress bar. See `barstyle` option for details.
`...`	Further arguments passed to the `simuland` function.

Details

spaMM_boot handles parallel backends with different features. pbapply::pbapply has a very simple interface (essentially equivalent to apply) and provides progress bars, but (in version 1.4.0, at least) does not have efficient load-balancing. doSNOW also provides a progress bar and allows more efficient load-balancing, but its requires foreach. foreach handles errors differently from pbapply (which will simply stop if fitting a model to a bootstrap replicate fails): see the foreach documentation.

spaMM_boot calls simulate.HLfit on the fit object and applies simuland on each column of the matrix returned by this call. simulate.HLfit uses the type argument, which must be explicitly provided.

The simuland function must take as first argument a vector of response values, and may have other arguments including ‘...’. When required, these additional arguments must be passed through the ‘...’ arguments of spaMM_boot. Variables needed to evaluate them must be available from within the simuland function or otherwise provided as elements of fit_env.

Value

A list, with two elements (unless debug. is TRUE):

bootreps: nsim return values in the format returned either by apply or parallel::parApply or by foreach::`%dopar%` as controlled by control.foreach$.combine (which is here "rbind" by default).
RNGstate: the state of .Random.seed at the beginning of the sample simulation

Examples

if (spaMM.getOption("example_maxtime")>7) {
 data("blackcap")
 
 # Generate fits of null and full models:
 lrt <- fixedLRT(null.formula=migStatus ~ 1 + Matern(1|longitude+latitude),
                 formula=migStatus ~ means + Matern(1|longitude+latitude), 
                 method='ML',data=blackcap)

 # The 'simuland' argument: 
 myfun <- function(y, what=NULL, lrt, ...) { 
    data <- lrt$fullfit$data
    data$migStatus <- y ## replaces original response (! more complicated for binomial fits)
    full_call <- getCall(lrt$fullfit) ## call for full fit
    full_call$data <- data
    res <- eval(full_call) ## fits the full model on the simulated response
    if (!is.null(what)) res <- eval(what)(res=res) ## post-process the fit
    return(res) ## the fit, or anything produced by evaluating 'what'
  }
  # where the 'what' argument (not required) of myfun() allows one to control 
  # what the function returns without redefining the function.
  
  # Call myfun() with no 'what' argument: returns a list of fits 
  spaMM_boot(lrt$nullfit, simuland = myfun, nsim=1, lrt=lrt, type ="marginal")[["bootreps"]] 
  
  # Return only a model coefficient for each fit: 
  spaMM_boot(lrt$nullfit, simuland = myfun, nsim=7,
               what=quote(function(res) fixef(res)[2L]), lrt=lrt, type ="marginal")[["bootreps"]]       
}

spaMM

Mixed-Effect Models, with or without Spatial Random Effects

v3.10.0

CeCILL-2

Authors

François Rousset [aut, cre, cph] (<https://orcid.org/0000-0003-4670-0371>), Jean-Baptiste Ferdy [aut, cph], Alexandre Courtiol [aut] (<https://orcid.org/0000-0003-0637-2959>), GSL authors [ctb] (src/gsl_bessel.*)

Initial release

2022-02-06