R/data.R

In saeproj.multilevel: Small Area Estimation Using a Projection Estimator with a Multilevel Regression Model

#' An Example Small-Survey Dataset for Fitting the Linear Multilevel Regression Model
#'
#' Simulated model-survey data for saeproj.multilevel.
#'
#' @description
#' A simulated small-survey dataset used to demonstrate projection-based small
#' area estimation with a linear multilevel regression model.
#'
#' The dataset is one fixed replication from the simulation design used in the
#' package examples. It contains the target variable and auxiliary variables,
#' and is intended to be used as \code{data_model} in \code{sae_ml_linear()}.
#'
#' @format
#' A data frame with 250 rows, 11 variables, and 50 domains.
#'
#' \describe{
#'   \item{prov}{Province identifier.}
#'   \item{kab_kota}{District or city identifier used as the domain variable.}
#'   \item{id_individu}{Unique sampled-unit identifier. It is not a PSU or cluster identifier.}
#'   \item{Z1}{First area-level auxiliary variable.}
#'   \item{Z2}{Second area-level auxiliary variable.}
#'   \item{X1}{First unit-level auxiliary variable.}
#'   \item{X2}{Binary unit-level auxiliary variable.}
#'   \item{X3}{Third unit-level auxiliary variable.}
#'   \item{X4}{Fourth unit-level auxiliary variable.}
#'   \item{Y}{Target variable.}
#'   \item{WEIND}{Survey sampling weight.}
#' }
#'
#' @details
#' The dataset contains five sampled units in each of 50 domains. The target
#' variable \code{Y} was generated from a random-intercept multilevel
#' population model.
#'
#' It is designed to be used together with \code{saeml_projsvy}.
#'
#' The simulated survey design does not include a separate PSU or cluster
#' identifier. Therefore, package examples use \code{cluster_ids = ~1}.
#'
#' @source
#' Simulated data generated from the package study-simulation design.
#'
#' @seealso
#' \code{\link{saeml_projsvy}} and \code{\link{sae_ml_linear}}.
#'
#' @examples
#' data(saeml_modelsvy)
#'
#' dim(saeml_modelsvy)
#' head(saeml_modelsvy)
#' table(saeml_modelsvy$kab_kota)
"saeml_modelsvy"

#' An Example Large-Survey Dataset for Producing Projection Estimates
#'
#' Simulated projection-survey data for saeproj.multilevel.
#'
#' @description
#' A simulated large-survey dataset used to demonstrate projection-based small
#' area estimation with a linear multilevel regression model.
#'
#' The dataset is one fixed replication from the simulation design used in the
#' package examples. It contains auxiliary variables and survey design
#' variables, but does not contain the target variable.
#'
#' It is intended to be used as \code{data_proj} in \code{sae_ml_linear()}.
#'
#' @format
#' A data frame with 15,000 rows, 10 variables, and 50 domains.
#'
#' \describe{
#'   \item{prov}{Province identifier.}
#'   \item{kab_kota}{District or city identifier used as the domain variable.}
#'   \item{id_individu}{Unique sampled-unit identifier. It is not a PSU or cluster identifier.}
#'   \item{Z1}{First area-level auxiliary variable.}
#'   \item{Z2}{Second area-level auxiliary variable.}
#'   \item{X1}{First unit-level auxiliary variable.}
#'   \item{X2}{Binary unit-level auxiliary variable.}
#'   \item{X3}{Third unit-level auxiliary variable.}
#'   \item{X4}{Fourth unit-level auxiliary variable.}
#'   \item{WEIND}{Survey sampling weight.}
#' }
#'
#' @details
#' The dataset contains 300 sampled units in each of 50 domains. It is drawn
#' from the same fixed simulated population as \code{saeml_modelsvy}, but does
#' not contain the target variable \code{Y}.
#'
#' It is used to generate unit-level predictions and domain-level synthetic
#' estimates.
#'
#' The simulated survey design does not include a separate PSU or cluster
#' identifier. Therefore, package examples use \code{cluster_ids = ~1}.
#'
#' @source
#' Simulated data generated from the package study-simulation design.
#'
#' @seealso
#' \code{\link{saeml_modelsvy}} and \code{\link{sae_ml_linear}}.
#'
#' @examples
#' data(saeml_projsvy)
#'
#' dim(saeml_projsvy)
#' head(saeml_projsvy)
#' table(saeml_projsvy$kab_kota)
#' "Y" %in% names(saeml_projsvy)
"saeml_projsvy"