Calculate credible intervals

Description

Calculate credible intervals for a DemographicArray. When the array consists of whole numbers the credible intervals, by default, also consist of whole numbers.

Usage

credibleInterval(
  object,
  width = 95,
  na.rm = FALSE,
  adjust = c("search", "expand", "none")
)

## S4 method for signature 'DemographicArray'
credibleInterval(
  object,
  width = 95,
  na.rm = FALSE,
  adjust = c("search", "expand", "none")
)

Arguments

Details

Credible intervals summarise variation across a posterior sample. To represent a posterior sample, a DemographicArray must have a dimension with dimtype "iteration". If object does not have a dimension with dimtype "iteration", credibleInterval throws an error.

width must be a percentage value. It can equal 100, but cannot equal 0.

When object consists of real numbers, credibleInterval returns intervals of the form (q/2, 1 - q/2) where q = 1 - width/100.

When object consists of whole numbers (ie if is.integer(object) is TRUE or if all(as.integer(object) == object)), the calculations are more complicated.

Step 1 is to calculate quantiles using the same formula as for real numbers. Intervals calculated in this way will, in general, be composed of real numbers. These intervals can, arguably, act as quick and dirty measures of uncertainty. They are, however, poorly defined. For instance, are the values 0 and 4 inside or outside the interval (0.1, 3.9)? Are they inside the interval (0.8, 3.2)? These ambiguities make non-whole-number intervals unsuitable for tasks such as assessing coverage rates involving whole numbers.

When adjust is "search" or "expand", credibleInterval adjusts credible intervals for whole numbers so that the credible intervals themselves consist of whole numbers and enclose at least as large a proportion of the posterior sample as the original intervals.

When adjust is "expand", the interval (l, u) is expanded to (floor(l), ceiling(u)).

When adjust is "search", credibleInterval calculates, for each cell, the four intervals

(floor(l), floor(u))

(ceiling(l), floor(u))

(floor(l), ceiling(u))

(ceiling(l), ceiling(u))

and selects the narrowest interval that encloses at least width percent of the posterior sample. The "search" approarchshould yield intervals that are, on average, slightly narrower than the "expand" approach, and is therefore the default.

Note that the adjust argument is only relevant when object consists entirely of integers. When object contains one or more non-integers, the credibleInterval ignores adjust.

When na.rm is TRUE (the default), missing values are removed before the credible interval is calculated.

Value

An object with the same class as object, in which the "iteration" dimension is replaced by a "quantiles" dimension of length 2.

See Also

credibleInterval calls function collapseIterations.

Examples

set.seed(0)

## 'object' contains fractions
object <- Values(array(runif(n = 20),
                       dim = c(2, 10),
                       dimnames = list(sex = c("F", "M"),
                                       iteration = 1:10)))
credibleInterval(object)
credibleInterval(object, width = 50)

## 'object' entirely whole numbers
object <- Values(array(rpois(n = 20, lambda = 10),
                       dim = c(2, 10),
                       dimnames = list(sex = c("F", "M"),
                                       iteration = 1:10)))
credibleInterval(object, width = 90, adjust = "none")
credibleInterval(object, width = 90, adjust = "expand")
credibleInterval(object, width = 90, adjust = "search")
credibleInterval(object, width = 90)
## 'na.rm' argument
object[1] <- NA
credibleInterval(object)
credibleInterval(object, na.rm = TRUE)