% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stan.R
\name{hsstan}
\alias{hsstan}
\title{Hierarchical shrinkage models}
\usage{
hsstan(
  x,
  covs.model,
  penalized = NULL,
  family = gaussian,
  iter = 2000,
  warmup = floor(iter/2),
  scale.u = 2,
  regularized = TRUE,
  nu = ifelse(regularized, 1, 3),
  par.ratio = 0.05,
  global.df = 1,
  slab.scale = 2,
  slab.df = 4,
  qr = TRUE,
  seed = 123,
  adapt.delta = NULL,
  keep.hs.pars = FALSE,
  ...
)
}
\arguments{
\item{x}{Data frame containing outcome, covariates and penalized predictors.
Continuous predictors and outcome variable should be standardized
before fitting the models as priors assume them to have mean zero and
unit variance.}

\item{covs.model}{Formula containing the unpenalized covariates.}

\item{penalized}{Names of the variables to be used as penalized predictors.
Any variable that is already part of the \code{covs.model} formula will be
penalized. If \code{NULL} or an empty vector, a model with only unpenalized
covariates is fitted.}

\item{family}{Type of model fitted: either \code{gaussian()} for linear regression
(default) or \code{binomial()} for logistic regression.}

\item{iter}{Total number of iterations in each chain, including warmup
(2000 by default).}

\item{warmup}{Number of warmup iterations per chain (by default, half the
total number of iterations).}

\item{scale.u}{Prior scale (standard deviation) for the unpenalized
covariates.}

\item{regularized}{If \code{TRUE} (default), the regularized horseshoe prior
is used as opposed to the original horseshoe prior.}

\item{nu}{Number of degrees of freedom of the half-Student-t prior on the
local shrinkage parameters (by default, 1 if \code{regularized=TRUE}
and 3 otherwise).}

\item{par.ratio}{Expected ratio of non-zero to zero coefficients (ignored
if \code{regularized=FALSE}). The scale of the global shrinkage parameter
corresponds to \code{par.ratio} divided by the square root of the number of
observations; for linear regression only, it's further multiplied by
the residual standard deviation \code{sigma}.}

\item{global.df}{Number of degrees of freedom for the global shrinkage
parameter (ignored if \code{regularized=FALSE}). Larger values induce more
shrinkage.}

\item{slab.scale}{Scale of the regularization parameter (ignored if
\code{regularized=FALSE}).}

\item{slab.df}{Number of degrees of freedom of the regularization parameter
(ignored if \code{regularized=FALSE}).}

\item{qr}{Whether the thin QR decomposition should be used to decorrelate the
predictors (\code{TRUE} by default). This is silently set to \code{FALSE} if
there are more predictors than observations.}

\item{seed}{Optional integer defining the seed for the pseudo-random number
generator.}

\item{adapt.delta}{Target average proposal acceptance probability for
adaptation, a value between 0.8 and 1 (excluded). If unspecified,
it's set to 0.99 for hierarchical shrinkage models and to 0.95 for
base models.}

\item{keep.hs.pars}{Whether the parameters for the horseshoe prior should be
kept in the \code{stanfit} object returned (\code{FALSE} by default).}

\item{...}{Further arguments passed to \code{\link[rstan:stanmodel-method-sampling]{rstan::sampling()}},
such as \code{chains} (4 by default), \code{cores} (the value of
\code{options("mc.cores")} by default), \code{refresh} (\code{iter / 10} by default).}
}
\value{
An object of class \code{hsstan} containing the following fields:
\item{stanfit}{an object of class \code{stanfit} containing the output
produced by Stan, including posterior samples and diagnostic summaries.
It can be manipulated using methods from the \strong{rstan} package.}
\item{betas}{posterior means of the unpenalized and penalized regression
parameters.}
\item{call}{the matched call.}
\item{data}{the dataset used in fitting the model.}
\item{model.terms}{a list of names for the outcome variable, the unpenalized
covariates and the penalized predictors.}
\item{family}{the \code{family} object used.}
\item{hsstan.settings}{the optional settings used in the model.}
}
\description{
Run the No-U-Turn Sampler (NUTS) as implemented in Stan to fit a hierarchical
shrinkage model.
}
\examples{
\dontshow{oldopts <- options(mc.cores=2)}
data(diabetes)

# non-default settings for speed of the example
df <- diabetes[1:50, ]
hs.biom <- hsstan(df, Y ~ age + sex, penalized=colnames(df)[5:10],
                  chains=2, iter=250)
\dontshow{options(oldopts)}

}
\seealso{
\code{\link[=kfold]{kfold()}} for cross-validating a fitted object.
}