% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gather_variables.R
\name{gather_variables}
\alias{gather_variables}
\title{Gather variables from a tidy data frame of draws from variables into a single column}
\usage{
gather_variables(data, exclude = c(".chain", ".iteration", ".draw", ".row"))
}
\arguments{
\item{data}{A data frame with variable names spread across columns, such as one returned by
\code{\link[=tidy_draws]{tidy_draws()}} or \code{\link[=spread_draws]{spread_draws()}}.}

\item{exclude}{A character vector of names of columns to be excluded from the gather. Default
ignores several meta-data column names used in tidybayes.}
}
\value{
A data frame.
}
\description{
Given a data frame such as might be returned by \code{\link[=tidy_draws]{tidy_draws()}} or \code{\link[=spread_draws]{spread_draws()}},
gather variables and their values from that data frame into a \code{".variable"} and \code{".value"} column.
}
\details{
This function gathers every column except grouping columns and those matching the expression
\code{exclude} into key/value columns \code{".variable"} and \code{".value"}.

Imagine a data frame \code{data} as returned by \code{spread_draws(fit, a[i], b[i,v])}, like this:
\itemize{
\item column \code{".chain"}: the chain number
\item column \code{".iteration"}: the iteration number
\item column \code{".draw"}: the draw number
\item column \code{"i"}: value in \code{1:5}
\item column \code{"v"}: value in \code{1:10}
\item column \code{"a"}: value of \code{"a[i]"} for draw number \code{".draw"}
\item column \code{"b"}: value of \code{"b[i,v]"} for draw number \code{".draw"}
}

\code{gather_variables(data)} on that data frame would return a grouped
data frame (grouped by \code{i} and \code{v}), with:
\itemize{
\item column \code{".chain"}: the chain number
\item column \code{".iteration"}: the iteration number
\item column \code{".draw"}: the draw number
\item column \code{"i"}: value in \code{1:5}
\item column \code{"v"}: value in \code{1:10}
\item column \code{".variable"}: value in \code{c("a", "b")}.
\item column \code{".value"}: value of \code{"a[i]"} (when \code{".variable"} is \code{"a"};
repeated for every value of \code{"v"}) or \code{"b[i,v]"} (when \code{".variable"} is
\code{"b"}) for draw number \code{".draw"}
}

In this example, this call:

\preformatted{gather_variables(data)}

Is roughly equivalent to:

\preformatted{data \%>\%
  gather(.variable, .value, -c(.chain, .iteration, .draw, i, v)) \%>\%
  group_by(.variable, .add = TRUE)
}
}
\examples{
\donttest{

library(dplyr)

data(RankCorr, package = "ggdist")

RankCorr \%>\%
  spread_draws(b[i,v], tau[i]) \%>\%
  gather_variables() \%>\%
  median_qi()

# the first three lines below are roughly equivalent to ggmcmc::ggs(RankCorr)
RankCorr \%>\%
  tidy_draws() \%>\%
  gather_variables() \%>\%
  median_qi()

}
}
\seealso{
\code{\link[=spread_draws]{spread_draws()}}, \code{\link[=tidy_draws]{tidy_draws()}}.
}
\author{
Matthew Kay
}
\keyword{manip}
