credibleInterval {dembase} | R Documentation

## 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

`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.

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

[Package dembase version 0.0.0.119 Index]