powerAnalysis: Conduct a power analysis for an unmarked model

In unmarked: Models for Data from Unmarked Animals

Conduct a power analysis for an unmarked model

Description

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.

Usage

  ## S4 method for signature 'unmarkedFrame'
powerAnalysis(object, model = NULL, effects = NULL,
    alpha=0.05, nsim = 100, parallel = FALSE, nulls=NULL, ...)
  ## S4 method for signature '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(s)

Ken Kellner [e-mail]

See Also

unmarkedPowerList

Examples

## Not run: 

# 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


## End(Not run)

unmarked documentation built on Sept. 11, 2024, 8:28 p.m.