% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pit.R
\name{pareto_pit}
\alias{pareto_pit}
\alias{pareto_pit.default}
\alias{pareto_pit.draws_matrix}
\alias{pareto_pit.rvar}
\title{Pareto-smoothed probability integral transform}
\usage{
pareto_pit(x, y, ...)

\method{pareto_pit}{default}(x, y, weights = NULL, log = FALSE, ndraws_tail = NULL, ...)

\method{pareto_pit}{draws_matrix}(x, y, weights = NULL, log = FALSE, ndraws_tail = NULL, ...)

\method{pareto_pit}{rvar}(x, y, weights = NULL, log = FALSE, ndraws_tail = NULL, ...)
}
\arguments{
\item{x}{(draws) A \code{\link{draws_matrix}} object or one coercible to a
\code{draws_matrix} object, or an \code{\link{rvar}} object.}

\item{y}{(observations) A 1D vector, or an array of dim(x), if x is \code{rvar}.
Each element of \code{y} corresponds to a variable in \code{x}.}

\item{...}{Arguments passed to individual methods (if applicable).}

\item{weights}{A matrix of weights for each draw and variable. \code{weights}
should have one column per variable in \code{x}, and \code{ndraws(x)} rows.}

\item{log}{(logical) Are the weights passed already on the log scale? The
default is \code{FALSE}, that is, expecting \code{weights} to be on the standard
(non-log) scale.}

\item{ndraws_tail}{(integer) Number of tail draws to use for GPD
fitting. If \code{NULL} (the default), computed using \code{\link[=ps_tail_length]{ps_tail_length()}}.}
}
\value{
A numeric vector of length \code{length(y)} containing the PIT values, or
an array of shape \code{dim(y)}, if \code{x} is an \code{rvar}.
}
\description{
Compute PIT values using the empirical CDF, then refine values in
the tails by fitting a generalized Pareto distribution (GPD) to
the tail draws. This gives smoother, more accurate PIT values in
the tails where the ECDF is coarse, and avoids PIT values of 0 and 1.
Due to use of generalized Pareto distribution CDF in tails, the
PIT values are not anymore rank based and continuous uniformity
test is appropriate.
}
\details{
The function first computes raw PIT values identically to
\code{\link[=pit]{pit()}} (including support for weighted draws). It then fits a
GPD to both tails of the draws (using the same approach as
\code{\link[=pareto_smooth]{pareto_smooth()}}) and replaces PIT values for observations falling in
the tail regions:

For a right-tail observation \eqn{y_i > c_R} (where \eqn{c_R} is
the right-tail cutoff):

\deqn{PIT(y_i) = 1 - p_{tail}(1 - F_{GPD}(y_i; c_R, \sigma_R, k_R))}

For a left-tail observation \eqn{y_i < c_L}:

\deqn{PIT(y_i) = p_{tail}(1 - F_{GPD}(-y_i; -c_L, \sigma_L, k_L))}

where \eqn{p_{tail}} is the proportion of (weighted) mass in the
tail.

When (log-)weights in \code{weights} are provided, they are used for
the raw PIT computation (as in \code{\link[=pit]{pit()}}) and for GPD fit.
}
\examples{
x <- example_draws()
y <- rnorm(nvariables(x), 5, 5)
pareto_pit(x, y)

}
\seealso{
\code{\link[=pit]{pit()}} for the unsmoothed version, \code{\link[=pareto_smooth]{pareto_smooth()}} for
Pareto smoothing of draws.
}
