% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hatsurvey.R
\name{hatsurvey}
\alias{hatsurvey}
\title{hatsurvey}
\usage{
hatsurvey(
  x,
  y,
  denom = NULL,
  design,
  denom_value = NULL,
  success_value = NULL,
  data,
  survey.type
)
}
\arguments{
\item{x}{Character. Name of the target variable (numerator).}

\item{y}{Character. Name of the disaggregation (grouping) variable.}

\item{denom}{Character. Name of the denominator variable (only for \code{"prop"} and \code{"ratio"}).}

\item{design}{A survey design object created using \code{\link[survey]{svydesign}}.}

\item{denom_value}{A vector of values used to filter the denominator (optional).}

\item{success_value}{A vector of values considered as "success" in the numerator (optional).}

\item{data}{Original data frame used to preserve factor level ordering of \code{y}.}

\item{survey.type}{Character. Type of estimation:
\itemize{
\item \code{"mean"}
\item \code{"prop"}
\item \code{"ratio"}
}}
}
\value{
A data frame containing:
\itemize{
\item \code{Variable} : Name of the target variable
\item \code{Disaggregation} : Disaggregation category
\item \code{Estimation} : Estimated value
\item \code{SE} : Standard error
\item \code{RSE} : Relative standard error (\%)
\item \code{Lower Conf.Int} : Lower bound of confidence interval
\item \code{Upper Conf.Int} : Upper bound of confidence interval
\item \code{Variance} : Variance of the estimate
\item \code{DEFF} : Design effect
\item \code{n_denom} : Unweighted denominator count
\item \code{n_num} : Unweighted numerator count (for prop and ratio)
}
}
\description{
Computes survey indicator estimates using complex survey design
from the 'survey' package. It supports three types of estimation:
\itemize{
\item \code{"mean"}: mean or simple proportion (svymean)
\item \code{"prop"}: ratio-based proportion (svyratio, returned in percentage)
\item \code{"ratio"}: ratio of two variables (e.g., GER, NER, LFPR)
}
}
\details{
The output includes estimates, standard errors, relative standard errors, confidence intervals,
variance, design effect, and unweighted counts for numerator and denominator.

\strong{Important notes:}
\itemize{
\item For \code{"mean"}, the variable \code{x} should be numeric or binary (0/1).
\item For \code{"prop"} and \code{"ratio"}, ensure that \code{x} and \code{denom}
are properly defined (e.g., 1 = event, 0 = non-event).
\item The function uses \code{svyby}, so results follow the complex survey design.
\item Category ordering follows the factor levels in \code{data[[y]]}.
\item For \code{"prop"}, the estimate is computed as a ratio of totals,
not as a simple mean. This is useful for population-based indicators.
}
}
\examples{
# --- Simple toydata
df <- data.frame(
  x = c(100, 0, 100, 100, 0, 100),
  denom = c(100, 100, 100, 100, 100, 100),
  y = factor(c("Urban","Urban","Rural","Rural","Urban","Rural")),
  w = c(2,1,3,1,2,1)
)

# Build simple survey design
dsgn <- survey::svydesign(id = ~1, data = df, weights = ~w)

# --- Proportion using proportion estimator
hatsurvey(
  x = "x",
  y = "y",
  denom = "denom",
  design = dsgn,
  denom_value = 100,
  success_value = 100,
  data = df,
  survey.type = "prop"
)

# --- Full example (complex survey)
\donttest{
data("datause")

# Prepare data
datause$R101 <- as.factor(datause$R101)
options(survey.lonely.psu = "certainty")
# Build complex survey design (3-stage, stratified, with FPC)
snlik.design <- survey::svydesign(
  id = ~IDSUBSLS + IDRUTA + IDIDV,
  strata = ~STRATA,
  data = subset(datause, !is.na(CR509)),
  weights = ~W_FINAL,
  fpc = ~FPC1 + FPC2 + FPC3,
  nest = TRUE
)

# --- Proportion (percentage via ratio)
# Example: proportion of CR509 == 100 over total population
hatsurvey(
  x = "CR509",
  y = "R101",
  denom = "JMLH_PDDK",
  design = snlik.design,
  denom_value = NULL,
  success_value = 100,
  data = subset(datause, !is.na(CR509)),
  survey.type = "prop"
)

# --- Ratio (e.g., conditional rate)
# Example: CR509 == 100 over CRCOB == 1
hatsurvey(
  x = "CR509",
  y = "R101",
  denom = "CRCOB",
  design = snlik.design,
  denom_value = 1,
  success_value = 100,
  data = subset(datause, !is.na(CR509)),
  survey.type = "ratio"
)

# --- Mean
hatsurvey(
  x = "CR509",
  y = "R101",
  denom = NULL,
  design = snlik.design,
  denom_value = NULL,
  success_value = NULL,
  data = subset(datause, !is.na(CR509)),
  survey.type = "mean"
)
}

}
