--- title: "Getting Started with MLSurvey" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting Started with MLSurvey} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 6, fig.height = 4 ) ``` ## Overview `MLSurvey` fits machine learning models -- elastic net, XGBoost, and random forest -- to complex survey data, incorporating sampling weights, strata, and clusters via a replicate-weights approach. This vignette walks through the core elastic net workflow: 1. Fitting a single model with `wElnet()` 2. Searching across multiple `alpha` values in parallel with `par_wElnet()` 3. Visualizing results with both base R and `ggplot2` To keep this vignette fast and self-contained, we use a small synthetic survey-style data set rather than a real NHANES extract. The same workflow applies directly to real survey data with a `cluster`, `strata`, and `weights` column (or an equivalent `survey::svydesign()` object). ```{r setup} library(MLSurvey) ``` ## A small synthetic survey data set A complex survey data set typically includes: - A **cluster** identifier (primary sampling unit, PSU) - A **strata** identifier - A **sampling weight** - One or more **predictors** - A **response variable** ```{r make-data} set.seed(1) n <- 240 survey_data <- data.frame( psu = rep(rep(1:3, each = n / 12), times = 4), strata = rep(1:4, each = n / 4), weight = runif(n, 500, 5000), x1 = rnorm(n), x2 = rnorm(n), x3 = rnorm(n), x4 = rnorm(n), y = rep(c(0, 1), length.out = n) # binary outcome ) head(survey_data) ``` ## Fitting a single model with `wElnet()` `wElnet()` fits a weighted elastic net model for a single value of `alpha` (the mixing parameter between ridge and LASSO penalties), selecting the optimal `lambda` by replicate-weight cross-validation. ```{r fit-single} fit <- wElnet( data = survey_data, col.y = "y", col.x = c("x1", "x2", "x3", "x4"), family = "binomial", alpha = 0.5, cluster = "psu", strata = "strata", weights = "weight", method = "dCV", k = 4, R = 1 ) fit ``` Printing the fitted object (via `print.w.elnet()`) summarizes the key results: the alpha used, the selected `lambda.min`, its weighted error, and the number of nonzero coefficients at that lambda. ### Visualizing a single fit Two plotting interfaces are available for `w.elnet` objects: a base R `plot()` method, and a `ggplot2`-based `autoplot()` method. ```{r plot-single, fig.alt = "Weighted error vs. log(lambda) for a single alpha"} plot(fit) ``` ```{r autoplot-single, fig.alt = "ggplot2 version of the error profile for a single alpha"} library(ggplot2) autoplot(fit) ``` Both show the weighted error across the lambda grid, with the selected `lambda.min` marked. ## Searching across multiple alphas with `par_wElnet()` In practice, you'll usually want to compare several `alpha` values (e.g. a grid spanning ridge to LASSO) rather than fixing one in advance. `par_wElnet()` fits `wElnet()` once per alpha, in parallel across CPU cores, and reports the best (alpha, lambda) combination. ```{r fit-parallel, eval = FALSE} alpha_grid <- c(0, 0.25, 0.5, 0.75, 1) par_fit <- par_wElnet( alpha = alpha_grid, n.cores = 2, data = survey_data, col.y = "y", col.x = c("x1", "x2", "x3", "x4"), family = "binomial", cluster = "psu", strata = "strata", weights = "weight", method = "dCV", k = 4, R = 1 ) par_fit ``` ``` #> Parallel Weighted Elastic Net over 5 alpha value(s) #> #> alpha lambda.min min.error #> 1 0.00 0.0847 0.251 #> 2 0.25 0.0391 0.248 #> 3 0.50 0.0312 0.246 #> 4 0.75 0.0288 0.247 #> 5 1.00 0.0265 0.249 #> #> Best alpha: 0.5 ``` (This chunk is not evaluated when the vignette is built, since spawning a parallel cluster is best avoided in automated/non-interactive build environments such as `R CMD check`. It runs normally in an interactive R session or script.) ### Visualizing results across alphas `plot()` and `autoplot()` methods are also available for `par.w.elnet` objects, showing both the error profile for every alpha and a summary of the best error achieved by each: ```r plot(par_fit) # both panels: profile + summary plot(par_fit, type = "profile") # just the error-vs-lambda curves, one per alpha plot(par_fit, type = "summary") # just the best-error-vs-alpha curve autoplot(par_fit) # combined (requires patchwork) autoplot(par_fit, type = "profile", facet = TRUE) # one panel per alpha ``` ## Using a `survey::svydesign()` object instead If you already have a `survey.design` object, you can pass it directly via the `design` argument instead of specifying `cluster`/`strata`/`weights` separately: ```{r design-example} des <- survey::svydesign( ids = ~psu, strata = ~strata, weights = ~weight, nest = TRUE, data = survey_data ) fit_des <- wElnet( col.y = "y", col.x = c("x1", "x2", "x3", "x4"), design = des, family = "binomial", alpha = 0.5, method = "dCV", k = 4, R = 1 ) fit_des$alpha ``` ## Other replicate-weight methods `method` also accepts `"JKn"` (jackknife), `"BRR"`, `"bootstrap"`, `"subbootstrap"`, `"split"`, and `"extrapolation"`, each implemented via [replicate_weights()]. For example, a jackknife fit: ```{r jkn-example} fit_jkn <- wElnet( data = survey_data, col.y = "y", col.x = c("x1", "x2", "x3", "x4"), family = "binomial", alpha = 0.5, cluster = "psu", strata = "strata", weights = "weight", method = "JKn" ) fit_jkn ``` See `?replicate_weights` for details on each method and how its training/test replicate-weight columns are constructed. **Note:** Global options to avoid only one PSU in a stratum in a particular domain or subpopulation can be set at the beginning when getting errors with other methods: ``` #> options(survey.adjust.domain.lonely=TRUE) #> options(survey.lonely.psu="adjust") ``` ## Next steps - `?wXGBoost` and `?wRandomforest` extend the same replicate-weight framework to gradient boosting and random forests. - `?optim_wxgb_para` automates hyperparameter search for `wXGBoost()`. - See the function reference index for the complete list of available models, utilities, and plotting methods.