credibleInterval: Calculate credible intervals
In StatisticsNZ/dembase: Analysing Cross-Classified Data about Populations

Description Usage Arguments Details Value See Also Examples

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

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")
)

`object`	A `DemographicArray`. The array must have a dimension with `dimtype` `"iteration"`.
`width`	A percentage value.
`na.rm`	`TRUE` (the default) or `FALSE`.
`adjust`	`"search"` (the default), `"expand"`, or `"none"`. See the details for an explanation.

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.

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

credibleInterval calls function collapseIterations.

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)