extras (version 0.10.0)

directional_information: Directional information

Description

The occurrence of an event (or lack thereof) transmits more or less information depending on the event's probability.

Usage

directional_information(
  x,
  ...,
  side = "median",
  threshold = 0,
  threshold_split = "proportional",
  skeptical = TRUE,
  na_rm = FALSE
)
p2info(p, n = Inf)

Value

A number indicating the directional information in bits. If x has NA values but na_rm is FALSE, returns NA_real.

Arguments

x

A numeric vector of MCMC values.

...

Unused.

side

A string indicating whether to calculate the directional information relative to the left side ("left"; x < threshold), or the right side ("right"; x > threshold). Positive information suggests greater evidence for the specified side. Defaults to "median", which uses the side of the median of x via direction().

threshold

A number of the threshold value.

threshold_split

A string indicating how to deal with threshold values:

• "left" to include them on the left side,

• "right" to include them on the right side,

• "equal" to split them equally between the left and side,

• "proportional" (default) to split them between the left and right sides proportionally to the values of x on the left and right sides,

• "exclude" to drop the values of x equal to threshold (identical to using "proportional").

skeptical

A flag specifying whether or not to add one sample to the empty side of the threshold when 100% of samples are on one side. Avoids zero p-values and infinite s-values, and also imposes stronger bounds on directional information than [-n, n], which assume the MCMC samples are independent and representative.

na_rm

A flag specifying whether to remove missing values.

p

A numeric vector of probabilities of direction.

n

A numeric vector of the number of posterior samples used to estimate each value of p. Used to limit the information to be within the interval \([-n, n]\).

Functions

• directional_information(): Calculate the directional information from a posterior distribution.

• p2info(): Calculate the information from a vector of probabilities.

Details

Quantifies the information about direction in a posterior distribution based on the directional probability. This function calculates such information using the difference in the probability of direction (see probability_direction()), after converting each probability to bits (also see svalue().

When skeptical = TRUE (default), one sample is added to the empty side, giving bounds of \(\pm \log_2(n)\) rather than \(\pm n\), to mimic the behaviour of pvalue() and svalue(). When skeptical = FALSE, information is instead clamped to \([-n, n]\), which is assumes the MCMC samples are independent and representative.

References

Kery, M., and Schaub, M. 2011. Bayesian population analysis using WinBUGS: a hierarchical perspective. Academic Press, Boston. Available from https://www.vogelwarte.ch/en/research/population-biology/book-bpa/.

See Also

Other summary: direction(), kurtosis(), lower(), probability_direction(), pvalue(), pzeros(), skewness(), svalue(), upper(), variance(), xtr_mean(), xtr_median(), xtr_sd(), zeros(), zscore()

Examples

directional_information(0)
directional_information(1) # one coin flip of information
directional_information(c(1, 1)) # two coin flips
directional_information(c(1, 1, -1)) # x[2] and x[3] cancel out
directional_information(c(1, 1, -1, -1)) # both sides cancel out
directional_information(rnorm(1e3, mean = 0))
directional_information(rnorm(1e3, mean = 1))
directional_information(rnorm(1e3, mean = 10)) # all coin flips are positive
directional_information(rnorm(1e3, mean = -10)) # all coin flips are negative
directional_information(rnorm(1e3, mean = 1e3)) # only quantiles matter
directional_information(rnorm(1e6, mean = 1e3)) # more `x` implies more info
directional_information(rep(1, 1000)) # skeptical = TRUE (default) gives log2(n)
directional_information(rep(1, 1000), skeptical = FALSE) # skeptical = FALSE gives n

p2info(seq(0, 1, by = 0.1))
p2info(seq(0, 1, by = 0.1), n = 10) # limit information to be in [-10, 10]