% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Wdiag.R
\name{W.diag}
\alias{W.diag}
\title{Wadsworth's univariate and bivariate exponential threshold diagnostics}
\usage{
W.diag(
  xdat,
  model = c("nhpp", "exp", "invexp"),
  u = NULL,
  k,
  q1 = 0,
  q2 = 1,
  par = NULL,
  M = NULL,
  nbs = 1000,
  alpha = 0.05,
  plots = c("LRT", "WN", "PS"),
  UseQuantiles = FALSE,
  changepar = TRUE,
  ...
)
}
\arguments{
\item{xdat}{a numeric vector of data to be fitted.}

\item{model}{string specifying whether the univariate or bivariate diagnostic should be used. Either \code{nhpp}
for the univariate model, \code{exp} (\code{invexp}) for the bivariate exponential model with rate (inverse rate) parametrization. See details.}

\item{u}{optional; vector of candidate thresholds.}

\item{k}{number of thresholds to consider (if \code{u} unspecified).}

\item{q1}{lowest quantile for the threshold sequence.}

\item{q2}{upper quantile limit for the threshold sequence (\code{q2} itself is not used as a threshold,
but rather the uppermost threshold will be at the \eqn{(q_2-1/k): q2-1/k} quantile).}

\item{par}{parameters of the NHPP likelihood. If \code{missing}, the \code{\link[mev]{fit.pp}} routine will be run to obtain values}

\item{M}{number of superpositions or 'blocks' / 'years' the process corresponds to (can affect the optimization)}

\item{nbs}{number of simulations used to assess the null distribution of the LRT, and produce the p-value}

\item{alpha}{significance level of the LRT}

\item{plots}{vector of strings indicating which plots to produce; \code{LRT}= likelihood ratio test, \code{WN} = white noise, \code{PS} = parameter stability. Use \code{NULL} if you do not want plots to be produced}

\item{UseQuantiles}{logical; use quantiles as the thresholds in the plot?}

\item{changepar}{logical; if \code{TRUE}, the graphical parameters (via a call to \code{par}) are modified.}

\item{...}{additional parameters passed to \code{plot}, overriding defaults including}
}
\value{
plots of the requested diagnostics and an invisible list with components
\itemize{
\item \code{MLE}: maximum likelihood estimates from all thresholds
\item \code{Cov}: joint asymptotic covariance matrix for \eqn{\xi}, \eqn{\eta} or \eqn{1/\eta}.
\item \code{WN}: values of the white noise process
\item \code{LRT}: values of the likelihood ratio test statistic vs threshold
\item \code{pval}: \emph{P}-value of the likelihood ratio test
\item \code{k}: final number of thresholds used
\item \code{thresh}: threshold selected by the likelihood ratio procedure
\item \code{qthresh}: quantile level of threshold selected by the likelihood ratio procedure
\item \code{cthresh}: vector of candidate thresholds
\item \code{qcthresh}: quantile level of candidate thresholds
\item \code{mle.u}: maximum likelihood estimates for the selected threshold
\item \code{model}: model fitted
}
}
\description{
Function to produce diagnostic plots and test statistics for the
threshold diagnostics exploiting structure of maximum likelihood estimators
based on the non-homogeneous Poisson process likelihood
}
\details{
The function is a wrapper for the univariate (non-homogeneous Poisson process model) and bivariate exponential dependence model.
For the latter, the user can select either the rate or inverse rate parameter  (the inverse rate parametrization  works better for uniformity
of the p-value distribution under the \code{LR} test.

There are two options for the bivariate diagnostic: either provide pairwise minimum of marginally
exponentially distributed margins or provide a \code{n} times 2 matrix with the original data, which
is transformed to exponential margins using the empirical distribution function.
}
\examples{
\dontrun{
set.seed(123)
# Parameter stability only
W.diag(xdat = abs(rnorm(5000)), model = 'nhpp',
       k = 30, q1 = 0, plots = "PS")
W.diag(rexp(1000), model = 'nhpp', k = 20, q1 = 0)
xbvn <- mvrnorm(n = 6000,
                mu = rep(0, 2),
                Sigma = cbind(c(1, 0.7), c(0.7, 1)))
# Transform margins to exponential manually
xbvn.exp <- -log(1 - pnorm(xbvn))
#rate parametrization
W.diag(xdat = apply(xbvn.exp, 1, min), model = 'exp',
       k = 30, q1 = 0)
W.diag(xdat = xbvn, model = 'exp', k = 30, q1 = 0)
#inverse rate parametrization
W.diag(xdat = apply(xbvn.exp, 1, min), model = 'invexp',
       k = 30, q1 = 0)
}
}
\references{
Wadsworth, J.L. (2016). Exploiting Structure of Maximum Likelihood Estimators for Extreme Value Threshold Selection, \emph{Technometrics}, \bold{58}(1), 116-126, \code{http://dx.doi.org/10.1080/00401706.2014.998345}.
}
\author{
Jennifer L. Wadsworth
}
