From 03b95aa329e4fadb4fa679f62d55869577e7eb9b Mon Sep 17 00:00:00 2001
From: Sean Anderson <sean@seananderson.ca>
Date: Wed, 1 Nov 2023 10:25:38 -0700
Subject: [PATCH] Docs

---
 R/utils.R              | 41 +++++++++++++++++++++++++++++++++++----
 _pkgdown.yml           |  1 +
 man/set_delta_model.Rd | 44 ++++++++++++++++++++++++++++++++++++------
 3 files changed, 76 insertions(+), 10 deletions(-)

diff --git a/R/utils.R b/R/utils.R
index 77852f783..3896d3bc0 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -521,7 +521,9 @@ get_censored_upper <- function(
   round(high)
 }
 
-#' Set delta model for prediction/\pkg{ggeffects}
+#' Set delta model for [ggeffects::ggpredict()]
+#'
+#' Set a delta model component to predict from with [ggeffects::ggpredict()].
 #'
 #' @param x An [sdmTMB::sdmTMB()] model fit with a delta family such as
 #'   [sdmTMB::delta_gamma()].
@@ -529,8 +531,10 @@ get_censored_upper <- function(
 #'   `NA` does the combined prediction, `1` does the binomial part, and `2`
 #'   does the positive part.
 #'
-#' @export
-#' @examplesIf require("ggeffects", quietly = TRUE)
+#' @details
+#' A complete version of the examples below would be:
+#'
+#' ```
 #' fit <- sdmTMB(density ~ poly(depth_scaled, 2), data = pcod_2011,
 #'   spatial = "off", family = delta_gamma())
 #'
@@ -545,7 +549,36 @@ get_censored_upper <- function(
 #' # combined:
 #' set_delta_model(fit, model = NA) |>
 #'   ggeffects::ggpredict("depth_scaled [all]")
-
+#' ```
+#'
+#' But cannot be run on CRAN until a version of \pkg{ggeffects} > 1.3.2
+#' is on CRAN. For now, you can install the GitHub version of \pkg{ggeffects}.
+#' <https://github.com/strengejacke/ggeffects>.
+#'
+#' @returns
+#' The fitted model with a new attribute named `delta_model_predict`.
+#' We suggest you use `set_delta_model()` in a pipe (as in the examples)
+#' so that this attribute does not persist. Otherwise, [predict.sdmTMB()]
+#' will choose this model component by default. You can also remove the
+#' attribute yourself after:
+#'
+#' ```
+#' attr(fit, "delta_model_predict") <- NULL
+#' ```
+#'
+#' @examplesIf require("ggeffects", quietly = TRUE)
+#' fit <- sdmTMB(density ~ poly(depth_scaled, 2), data = pcod_2011,
+#'   spatial = "off", family = delta_gamma())
+#'
+#' # binomial part:
+#' set_delta_model(fit, model = 1)
+#'
+#' # gamma part:
+#' set_delta_model(fit, model = 2)
+#'
+#' # combined:
+#' set_delta_model(fit, model = NA)
+#' @export
 set_delta_model <- function(x, model = c(NA, 1, 2)) {
   assertthat::assert_that(model[[1]] %in% c(NA, 1, 2),
     msg = "`model` argument not valid; should be one of NA, 1, 2")
diff --git a/_pkgdown.yml b/_pkgdown.yml
index b92e27840..947bb1b9b 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -37,6 +37,7 @@ reference:
   - run_extra_optimization
   - residuals.sdmTMB
   - replicate_df
+  - set_delta_model
 
 - title: 'Families'
   desc: |
diff --git a/man/set_delta_model.Rd b/man/set_delta_model.Rd
index 7cf0e11fc..68b5c89a6 100644
--- a/man/set_delta_model.Rd
+++ b/man/set_delta_model.Rd
@@ -2,7 +2,7 @@
 % Please edit documentation in R/utils.R
 \name{set_delta_model}
 \alias{set_delta_model}
-\title{Set delta model for prediction/\pkg{ggeffects}}
+\title{Set delta model for \code{\link[ggeffects:ggpredict]{ggeffects::ggpredict()}}}
 \usage{
 set_delta_model(x, model = c(NA, 1, 2))
 }
@@ -10,14 +10,27 @@ set_delta_model(x, model = c(NA, 1, 2))
 \item{x}{An \code{\link[=sdmTMB]{sdmTMB()}} model fit with a delta family such as
 \code{\link[=delta_gamma]{delta_gamma()}}.}
 
-\item{model}{Which delta/hurdle model component to predict/plot with.}
+\item{model}{Which delta/hurdle model component to predict/plot with.
+\code{NA} does the combined prediction, \code{1} does the binomial part, and \code{2}
+does the positive part.}
+}
+\value{
+The fitted model with a new attribute named \code{delta_model_predict}.
+We suggest you use \code{set_delta_model()} in a pipe (as in the examples)
+so that this attribute does not persist. Otherwise, \code{\link[=predict.sdmTMB]{predict.sdmTMB()}}
+will choose this model component by default. You can also remove the
+attribute yourself after:
+
+\if{html}{\out{<div class="sourceCode">}}\preformatted{attr(fit, "delta_model_predict") <- NULL
+}\if{html}{\out{</div>}}
 }
 \description{
-Set delta model for prediction/\pkg{ggeffects}
+Set a delta model component to predict from with \code{\link[ggeffects:ggpredict]{ggeffects::ggpredict()}}.
 }
-\examples{
-\dontshow{if (require("ggeffects", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
-fit <- sdmTMB(density ~ poly(depth_scaled, 2), data = pcod_2011,
+\details{
+A complete version of the examples below would be:
+
+\if{html}{\out{<div class="sourceCode">}}\preformatted{fit <- sdmTMB(density ~ poly(depth_scaled, 2), data = pcod_2011,
   spatial = "off", family = delta_gamma())
 
 # binomial part:
@@ -31,5 +44,24 @@ set_delta_model(fit, model = 2) |>
 # combined:
 set_delta_model(fit, model = NA) |>
   ggeffects::ggpredict("depth_scaled [all]")
+}\if{html}{\out{</div>}}
+
+But cannot be run on CRAN until a version of \pkg{ggeffects} > 1.3.2
+is on CRAN. For now, you can install the GitHub version of \pkg{ggeffects}.
+\url{https://github.com/strengejacke/ggeffects}.
+}
+\examples{
+\dontshow{if (require("ggeffects", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+fit <- sdmTMB(density ~ poly(depth_scaled, 2), data = pcod_2011,
+  spatial = "off", family = delta_gamma())
+
+# binomial part:
+set_delta_model(fit, model = 1)
+
+# gamma part:
+set_delta_model(fit, model = 2)
+
+# combined:
+set_delta_model(fit, model = NA)
 \dontshow{\}) # examplesIf}
 }