% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ht.paired.R
\name{ht.paired}
\alias{ht.paired}
\title{Design-based hypothesis test for the comparison of two paired AUCs.}
\usage{
ht.paired(
  design,
  response.var,
  phat.var.1,
  phat.var.2,
  tag.event = NULL,
  tag.nonevent = NULL,
  alternative = c("two.sided", "greater", "less"),
  method = c("JKn", "subbootstrap"),
  boot.B = 1000
)
}
\arguments{
\item{design}{An object of class \code{survey.design} generated by
\code{survey::svydesign} indicating the complex sampling design of the data.}

\item{response.var}{A character string with the name of the column indicating the response variable in the data set.}

\item{phat.var.1}{A character string with the name of the column indicating the estimated probabilities obtained with model 1 in the data set.}

\item{phat.var.2}{A character string with the name of the column indicating the estimated probabilities obtained with model 2 in the data set.}

\item{tag.event}{A character string indicating the label used to indicate the event of interest in \code{response.var}.
The default option is \code{tag.event = NULL}, which selects the class with the lowest number of units as event.}

\item{tag.nonevent}{A character string indicating the label used for non-event in \code{response.var}.
The default option is \code{tag.nonevent = NULL}, which selects the class with the greatest number of units as non-event.}

\item{alternative}{A character string specifying the alternative hypothesis: \code{'two.sided'}, \code{greater}, or \code{less}.
Default is \code{alternative = 'two.sided'}.}

\item{method}{A character string indicating the method implemented to estimate the variance:
\code{method = 'JKn'} or \code{method = 'subbootstrap'}. Default is \code{method = 'JKn'}.}

\item{boot.B}{A numeric value indicating the number of bootstrap resamples to be considered. Default is \code{boot.B=1000}. Only for \code{method = 'subbootstrap'}.}
}
\value{
The output object of this function is a list of 5 elements containing the following information:
\itemize{
\item \code{wauc.1}: a numeric value indicating the weighted point estimate of the AUC for model 1.
\item \code{wauc.2}: a numeric value indicating the weighted point estimate of the AUC for model 2.
\item \code{sd}: a numeric value indicating the square root of the estimated variance.
\item \code{z}: a numeric value indicating the value of the statistic.
\item \code{pvalue}: a numeric value indicating the p-value of the test.
}
}
\description{
Design-based hypothesis test for the comparison of two paired AUCs.
}
\examples{
\donttest{
mydesign <- survey::svydesign(ids = ~cluster, strata = ~strata, weights=~weights,
data = example_variables_wroc, nest=TRUE)
model.1 <- survey::svyglm(y ~ x1 + x2 + x3, design = mydesign, family = quasibinomial())
model.2 <- survey::svyglm(y ~ x4 + x5 + x6, design = mydesign, family = quasibinomial())
phat.1 <- predict(model.1, newdata = example_variables_wroc, type = "response")
phat.2 <- predict(model.2, newdata = example_variables_wroc, type = "response")
example_variables_wroc$phat.1 <- phat.1
example_variables_wroc$phat.2 <- phat.2
mydesign <- survey::svydesign(ids = ~cluster, strata = ~strata, weights = ~weights,
data = example_variables_wroc, nest=TRUE)

# JKn-based hypothesis test:
ht.JKn <- ht.paired(design=mydesign, response.var = "y", phat.var.1 = "phat.1",
                    phat.var.2 = "phat.2", tag.event = 1, tag.nonevent = 0, 
                    method="JKn")
                    
# Bootstrap-based hypothesis test:
set.seed(123)
ht.boot <- ht.paired(design=mydesign, response.var = "y", phat.var.1 = "phat.1",
                     phat.var.2 = "phat.2", tag.event = 1, tag.nonevent = 0, 
                     method="subbootstrap")
}

}
\references{
Iparragirre, A., Lumley, T., & Barrio, I. (2026).
Design-Based Inference for the AUC with Complex Survey Data.
arXiv, 2603.28320.
(https://arxiv.org/abs/2603.28320)
}
