% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/adjust_weights.R
\name{adjust_weights}
\alias{adjust_weights}
\title{Compute Pareto-smoothed Importance Weights for Alternative Model
Specifications}
\usage{
adjust_weights(spec, object, data = NULL, keep_bad = FALSE, incl_orig = TRUE)
}
\arguments{
\item{spec}{An object of class \code{adjustr_spec}, probably produced by
\code{\link{make_spec}}, containing the new sampling sampling statements
to replace their counterparts in the original Stan model, and the data,
if any, by which these sampling statements are parametrized.}

\item{object}{A model object, either of type \code{\link[rstan]{stanfit}},
\code{stanreg} (from \pkg{rstanarm}), \code{brmsfit} (from \pkg{brms}),
or a list with two elements: \code{model} containing a
\code{CmdStanModel}, and \code{fit} containing a
\code{CmdStanMCMC} object (both from the \pkg{cmdstanr} package).}

\item{data}{The data that was used to fit the model in \code{object}.
Required only if one of the new sampling specifications involves Stan data
variables.}

\item{keep_bad}{When \code{FALSE} (the strongly recommended default),
alternate specifications which deviate too much from the original
posterior, and which as a result cannot be reliably estimated using
importance sampling (i.e., if the Pareto shape parameter is larger than
0.7), have their weights discarded—weights are set to \code{NA_real_}.}

\item{incl_orig}{When \code{TRUE}, include a row for the original
model specification, with all weights equal. Can facilitate comparison
and plotting later.}
}
\value{
A tibble, produced by converting the provided \code{specs} to a
  tibble (see \code{\link{as.data.frame.adjustr_spec}}), and adding columns
  \code{.weights}, containing vectors of weights for each draw, and
  \code{.pareto_k}, containing the diagnostic Pareto shape parameters. Values
  greater than 0.7 indicate that importance sampling is not reliable.
  If \code{incl_orig} is \code{TRUE}, a row is added for the original model
  specification. Weights can be extracted with the
  \code{\link{pull.adjustr_weighted}} method. The returned object also
  includes the model sample draws, in the \code{draws} attribute.
}
\description{
Given a set of new sampling statements, which can be parametrized by a
data frame or list, compute Pareto-smoothed importance weights and attach
them to the specification object, for further calculation and plotting.
}
\details{
This function does the bulk of the sensitivity analysis work.  It operates
by parsing the model code from the provided Stan object, extracting the
parameters and their sampling statements.  It then uses R
metaprogramming/tidy evaluation tools to flexibly evaluate the log density
for each draw and each sampling statement, under the original and alternative
specifications. From these, the function computes the overall importance
weight for each draw and performs Pareto-smoothed importance sampling.  All
of the work is performed in R, without recompiling or refitting the Stan
model.
}
\examples{
spec = make_spec(eta ~ student_t(df, 0, 1), df=4:10)
adjust_weights(spec, eightschools_m, keep_bad=TRUE)

}
\references{
Vehtari, A., Simpson, D., Gelman, A., Yao, Y., & Gabry, J. (2024).
Pareto smoothed importance sampling.
\emph{Journal of Machine Learning Research}, 25(72), 1--58.
\doi{10.48550/arXiv.1507.02646}
}
\seealso{
\code{\link{make_spec}}, \code{\link{summarize.adjustr_weighted}}, \code{\link{spec_plot}}
}
