% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/table_helpers.R
\name{summarise_BRRAT}
\alias{summarise_BRRAT}
\title{Summarise population and site-level posterior summaries}
\usage{
summarise_BRRAT(fit_obj, level = 0.95)
}
\arguments{
\item{fit_obj}{A fitted object returned by \code{\link[=BRRAT]{BRRAT()}}, of class \code{BRRAT}.}

\item{level}{Credible interval level (default \code{0.95}). The lower and upper
intervals are computed as \code{(1 - level) / 2} and \code{1 - (1 - level) / 2}.}
}
\value{
A list with one or two data frames:
\itemize{
\item \code{global}: one row summarising the population slope \code{beta} (mean, sd,
lower/upper credible interval, \code{prob_gt0}, \code{prob_lt0}, and \code{p_nonzero}).
\item \code{per_id}: if applicable (more than one site \code{ID} in the data) one
row per site \code{ID} with posterior summaries for
\code{intercept_id} and \code{slope_id} (mean, sd, lower/upper credible intervals).
}
}
\description{
Computes tidy posterior summaries for the \strong{population slope} (\code{beta}) and
\strong{per-site intercepts and slopes} (from \code{intercept_id} and \code{slope_id} generated
quantities) returned by the Stan fit. The function reports posterior means,
standard deviations, equal-tail credible intervals at a chosen level, and a
two-sided tail probability for non-zero slope at the population level.
}
\details{
Summarise global slope and per-site coefficients into tidy tables

The two-sided tail probability is computed as:
\deqn{p_{\mathrm{nonzero}} = 2\min\{ \Pr(\beta > 0 \mid \mathrm{data}), \Pr(\beta < 0 \mid \mathrm{data}) \}}{
p_nonzero = 2 * min(Pr(beta > 0 | data), Pr(beta < 0 | data))}
which is analogous to a two-sided p-value in spirit, but is a \strong{Bayesian posterior tail
probability}. It shrinks toward 0 as the posterior mass concentrates away from zero.
}
\section{Notes}{

Assumes the Stan model emits \code{intercept_id} and \code{slope_id} in \verb{generated quantities},
i.e., per-site fully-composed coefficients:
\deqn{\mathrm{intercept\_id}_j = \alpha + b_{0j},\quad \mathrm{slope\_id}_j = \beta + b_{1j}}{
intercept_id[j] = alpha + b0[j]; slope_id[j] = beta + b1[j]}
}

\examples{
\donttest{
set.seed(1)
samples <- 30
Clim <- sort(pmax(0, rnorm(samples, 600, 100)))
observed <- pmax(0, (Clim - 150) - 450 * tanh((Clim - 150) / 450))
Obs <- data.frame(P = Clim, Q = observed, year = 1:samples)
Sim <- data.frame(Q = observed * rnorm(samples, 1, 0.05), year = 1:samples)
res <- BRRAT(Sim, Obs, chains = 1, iter = 500)
tabs <- summarise_BRRAT(res, level = 0.95)
tabs$global
head(tabs$per_id)
}

}
