Compute the **Shortest Probability Interval (SPI)** of posterior distributions.
The SPI is a more computationally stable HDI. The implementation is based on
the algorithm from the **SPIn** package.

## Usage

```
spi(x, ...)
# S3 method for class 'numeric'
spi(x, ci = 0.95, verbose = TRUE, ...)
# S3 method for class 'data.frame'
spi(x, ci = 0.95, rvar_col = NULL, verbose = TRUE, ...)
# S3 method for class 'stanreg'
spi(
x,
ci = 0.95,
effects = c("fixed", "random", "all"),
component = c("location", "all", "conditional", "smooth_terms", "sigma",
"distributional", "auxiliary"),
parameters = NULL,
verbose = TRUE,
...
)
# S3 method for class 'brmsfit'
spi(
x,
ci = 0.95,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
verbose = TRUE,
...
)
# S3 method for class 'get_predicted'
spi(x, ci = 0.95, use_iterations = FALSE, verbose = TRUE, ...)
```

## Arguments

- x
Vector representing a posterior distribution, or a data frame of such vectors. Can also be a Bayesian model.

**bayestestR**supports a wide range of models (see, for example,`methods("hdi")`

) and not all of those are documented in the 'Usage' section, because methods for other classes mostly resemble the arguments of the`.numeric`

or`.data.frame`

methods.- ...
Currently not used.

- ci
Value or vector of probability of the (credible) interval - CI (between 0 and 1) to be estimated. Default to

`.95`

(`95%`

).- verbose
Toggle off warnings.

- rvar_col
A single character - the name of an

`rvar`

column in the data frame to be processed. See example in`p_direction()`

.- effects
Should results for fixed effects, random effects or both be returned? Only applies to mixed models. May be abbreviated.

- component
Should results for all parameters, parameters for the conditional model or the zero-inflated part of the model be returned? May be abbreviated. Only applies to brms-models.

- parameters
Regular expression pattern that describes the parameters that should be returned. Meta-parameters (like

`lp__`

or`prior_`

) are filtered by default, so only parameters that typically appear in the`summary()`

are returned. Use`parameters`

to select specific parameters for the output.- use_iterations
Logical, if

`TRUE`

and`x`

is a`get_predicted`

object, (returned by`insight::get_predicted()`

), the function is applied to the iterations instead of the predictions. This only applies to models that return iterations for predicted values (e.g.,`brmsfit`

models).

## Value

A data frame with following columns:

`Parameter`

The model parameter(s), if`x`

is a model-object. If`x`

is a vector, this column is missing.`CI`

The probability of the credible interval.`CI_low`

,`CI_high`

The lower and upper credible interval limits for the parameters.

## Details

The SPI is an alternative method to the HDI (`hdi()`

) to quantify
uncertainty of (posterior) distributions. The SPI is said to be more stable
than the HDI, because, the *"HDI can be noisy (that is, have a high Monte Carlo error)"*
(Liu et al. 2015). Furthermore, the HDI is sensitive to additional assumptions,
in particular assumptions related to the different estimation methods, which
can make the HDI less accurate or reliable.

## Note

The code to compute the SPI was adapted from the **SPIn** package,
and slightly modified to be more robust for Stan models. Thus, credits go
to Ying Liu for the original SPI algorithm and R implementation.

## References

Liu, Y., Gelman, A., & Zheng, T. (2015). Simulation-efficient shortest probability intervals. Statistics and Computing, 25(4), 809–819. https://doi.org/10.1007/s11222-015-9563-8

## Examples

```
library(bayestestR)
posterior <- rnorm(1000)
spi(posterior)
#> 95% SPI: [-1.96, 1.96]
spi(posterior, ci = c(0.80, 0.89, 0.95))
#> Shortest Probability Interval
#>
#> 80% SPI | 89% SPI | 95% SPI
#> ---------------------------------------------
#> [-1.17, 1.34] | [-1.50, 1.70] | [-1.96, 1.96]
df <- data.frame(replicate(4, rnorm(100)))
spi(df)
#> Shortest Probability Interval
#>
#> Parameter | 95% SPI
#> -------------------------
#> X1 | [-2.04, 1.89]
#> X2 | [-1.65, 1.96]
#> X3 | [-2.09, 1.74]
#> X4 | [-2.11, 1.97]
spi(df, ci = c(0.80, 0.89, 0.95))
#> Shortest Probability Interval
#>
#> Parameter | 80% SPI | 89% SPI | 95% SPI
#> ---------------------------------------------------------
#> X1 | [-1.05, 1.49] | [-1.41, 1.76] | [-2.04, 1.89]
#> X2 | [-0.90, 1.09] | [-1.33, 1.41] | [-1.65, 1.96]
#> X3 | [-1.38, 1.44] | [-1.84, 1.49] | [-2.09, 1.74]
#> X4 | [-1.27, 1.40] | [-1.61, 1.56] | [-2.11, 1.97]
# \donttest{
library(rstanarm)
model <- suppressWarnings(
stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200, refresh = 0)
)
spi(model)
#> Shortest Probability Interval
#>
#> Parameter | 95% SPI
#> ----------------------------
#> (Intercept) | [29.08, 47.70]
#> wt | [-6.75, -4.12]
#> gear | [-1.74, 1.70]
# }
```