Conduct a power analysis for an unmarked model

This function uses a simulation-based approach to estimate power for parameters in unmarked models. At a minimum, users must provide an unmarkedFrame object describing the experimental design and a list of effect sizes for each parameter in the model. See the unmarkedPower vignette for more details and examples.

# S4 method for class 'unmarkedFrame'
powerAnalysis(object, model = NULL, effects = NULL,
    alpha=0.05, nsim = 100, parallel = FALSE, nulls=NULL, ...)
  # S4 method for class 'list'
powerAnalysis(object, model = NULL, effects = NULL,
    alpha=0.05, nsim = length(object), parallel = FALSE, nulls=NULL, ...)

Arguments

object

An unmarkedFrame object representing the desired study design. The values in the response (y) don't matter and can be missing. Alternatively, you can provide a list of such objects with the response data already simulated (such as the output from simulate).

model

The model to use when the unmarkedFrame type is used for multiple model types. For example, if the object is an unmarkedFrameOccu, model should be set to occu or occuRN.

effects

A list containing the desired effect sizes/parameter values for which you want to estimate power. This list must follow a specific format. There is one named entry in the list per submodel (e.g., occupancy, detection). Each list element should be a numeric vector with length equal to the number of parameters in that submodel. Parameter values are on the inverse link scale. You can leave effects=NULL, which will generate an error message with a template that you can fill in.

alpha

Desired Type I error rate.

nsim

Number of simulations to conduct.

parallel

Logical; run simulations in parallel?

nulls

If provided, a list matching the structure of effects which defines the null hypothesis value for each parameter. By default the null is 0 for all parameters.

...

Arguments to send to the fitting function for the model. Most importantly this will include formula argument(s), but could also include distributions, key functions, etc. For example, for simulating occupancy data, you must also supply the argument formula = ~1~1 for a no-covariate model, formula=~1~x for a covariate effect of x on occupancy, etc.

Value

unmarkedPower object containing the results of the power analysis. For information on interpretation of the output, see the power analysis vignette.

Author

Ken Kellner contact@kenkellner.com

Examples


if (FALSE) { # \dontrun{

# Create experimental design
M <- 50
J <- 3
y <- matrix(NA, M, J)
sc <- data.frame(x=rnorm(M))
umf <- unmarkedFrameOccu(y, siteCovs=sc)

# Power analysis
p <- powerAnalysis(umf, model=occu, formula=~1~x, 
                   effects = list(state = c(-0.2, 0.3), det = 0))

p
summary(p, alpha=0.3)
plot(p, ylim=c(-3, 3))
plot(p, ylim=c(-3, 3))

# Simulate your own datasets first and pass to power analysis
cf <- list(state=c(0,1), det=0)
s <- simulate(umf, model = occu, formula=~1~x, coefs=cf, nsim = 100)
p2 <- powerAnalysis(s, model=occu, formula=~1~x, effects=cf)
p2

} # }