get_index_sims: Calculate a population index via simulation from the joint...
In pbs-assess/sdmTMB: Spatial and Spatiotemporal SPDE-Based GLMMs with 'TMB'

get_index_sims

R Documentation

Calculate a population index via simulation from the joint precision matrix

Description

Calculate a population index via simulation from the joint precision matrix. Compared to get_index(), this version can be faster if bias correction was turned on in get_index() while being approximately equivalent. This is an experimental function. This function usually works reasonably well, but we make no guarantees. It is recommended to use get_index() with bias_correct = TRUE for final inference.

Usage

get_index_sims(
  obj,
  level = 0.95,
  return_sims = FALSE,
  area = rep(1, nrow(obj)),
  est_function = stats::median,
  area_function = function(x, area) x + log(area),
  agg_function = function(x) sum(exp(x))
)

Arguments

`obj`	`predict.sdmTMB()` output with `nsim > 0`.
`level`	The confidence level.
`return_sims`	Logical. Return simulation draws? The default (`FALSE`) is a quantile summary of those simulation draws.
`area`	A vector of grid cell/polyon areas for each year-grid cell (row of data) in `obj`. Adjust this if cells are not of unit area or not all the same area (e.g., some cells are partially over land/water). Note that the area vector is added as `log(area)` to the raw values in `obj`. In other words, the function assumes a log link, which typically makes sense.
`est_function`	Function to summarize the estimate (the expected value). `mean()` would be an alternative to `median()`.
`area_function`	Function to apply area weighting. Assuming a log link, the `function(x, area) x + log(area)` default makes sense. If in natural space, `function(x, area) x * area` makes sense.
`agg_function`	Function to aggregate samples within each time slice. Assuming a log link, the `function(x) sum(exp(x))` default makes sense. If in natural space, `function(x) sum(x)` makes sense.

Details

Can also be used to produce an index from a model fit with tmbstan.

This function does nothing more than summarize and reshape the matrix of simulation draws into a data frame.

Value

A data frame. If return_sims = FALSE:

name of column (e.g. year) that was supplied to sdmTMB() time argument
est: estimate
lwr: lower confidence interval value
upr: upper confidence interval value
log_est: log estimate
se: standard error on the log estimate

If return_sims = TRUE, samples from the index values in a long-format data frame:

name of column (e.g. year) that was supplied to sdmTMB() time argument
.value: sample value
.iteration: sample number

Examples


m <- sdmTMB(density ~ 0 + as.factor(year),
  data = pcod_2011, mesh = pcod_mesh_2011, family = tweedie(link = "log"),
  time = "year"
)
qcs_grid_2011 <- replicate_df(qcs_grid, "year", unique(pcod_2011$year))
p <- predict(m, newdata = qcs_grid_2011, nsim = 100)
x <- get_index_sims(p)
x_sims <- get_index_sims(p, return_sims = TRUE)

if (require("ggplot2", quietly = TRUE)) {
  ggplot(x, aes(year, est, ymin = lwr, ymax = upr)) +
    geom_line() +
    geom_ribbon(alpha = 0.4)
  ggplot(x_sims, aes(as.factor(year), .value)) +
    geom_violin()
}

# Demo custom functions if working in natural space:
ind <- get_index_sims(
  exp(p),
  agg_function = function(x) sum(x),
  area_function = function(x, area) x * area
)

pbs-assess/sdmTMB documentation built on Dec. 20, 2024, 1:51 p.m.