directional-information: Directional information

In extras: Helper Functions for Bayesian Analyses

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)

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

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.

Value

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

Functions

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

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

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]

extras documentation built on July 16, 2026, 1:07 a.m.