diff --git a/R/gen.R b/R/gen.R index abd86190f..ebef86b3b 100644 --- a/R/gen.R +++ b/R/gen.R @@ -3,15 +3,15 @@ #' #' This function creates a function that draws from the posterior predictive #' distribution for a latent model using [primarycensored::rpcens()] to handle -#' censoring and truncation. The returned function takes a prep argument from +#' censoring and truncation. The returned function takes a `prep` argument from #' `brms` and returns posterior predictions. This is used internally by #' [brms::posterior_predict()] to generate predictions for latent models. #' -#' @inheritParams epidist_family_model +#' @inheritParams epidist_family #' -#' @return A function that takes a prep argument from brms and returns a matrix -#' of posterior predictions, with one row per posterior draw and one column -#' per observation. The prep object must have the following variables: +#' @return A function that takes a `prep` argument from brms and returns a +#' matrix of posterior predictions, with one row per posterior draw and one +#' column per observation. The `prep` object must have the following variables: #' * `vreal1`: relative observation time #' * `vreal2`: primary event window #' * `vreal3`: secondary event window @@ -53,11 +53,11 @@ epidist_gen_posterior_predict <- function(family) { #' #' This function creates a function that calculates the expected value of the #' posterior predictive distribution for a latent model. The returned function -#' takes a prep argument (from brms) and returns posterior expected values. +#' takes a `prep` argument (from brms) and returns posterior expected values. #' This is used internally by [brms::posterior_epred()] to calculate expected #' values for latent models. #' -#' @inheritParams epidist_family_model +#' @inheritParams epidist_family #' #' @return A function that takes a prep argument from brms and returns a matrix #' of posterior expected values, with one row per posterior draw and one column diff --git a/R/latent_model.R b/R/latent_model.R index 6eba158d5..96215b971 100644 --- a/R/latent_model.R +++ b/R/latent_model.R @@ -109,7 +109,7 @@ epidist_family_model.epidist_latent_model <- function( #' #' @seealso [brms::log_lik()] for details on the brms log likelihood interface. #' -#' @inheritParams epidist_family_model +#' @inheritParams epidist_family #' #' @return A function that calculates the log likelihood for a single #' observation. The prep object must have the following variables: diff --git a/R/utils.R b/R/utils.R index ef2d3f73a..9fd6a419e 100644 --- a/R/utils.R +++ b/R/utils.R @@ -167,7 +167,7 @@ #' @param prefix Character string prefix of the brms function to get (e.g. #' "log_lik") #' -#' @param family A brms family object +#' @inheritParams epidist_family #' @return The requested brms function #' @keywords internal .get_brms_fn <- function(prefix, family) { diff --git a/man/dot-get_brms_fn.Rd b/man/dot-get_brms_fn.Rd index c1ad322e0..414c7a6e0 100644 --- a/man/dot-get_brms_fn.Rd +++ b/man/dot-get_brms_fn.Rd @@ -10,7 +10,12 @@ \item{prefix}{Character string prefix of the brms function to get (e.g. "log_lik")} -\item{family}{A brms family object} +\item{family}{A description of the response distribution and link function to +be used in the model. Every family function has a link argument allowing +users to specify the link function to be applied on the response variable. +If not specified, default links are used. For details of all supported +families see \code{\link[=brmsfamily]{brmsfamily()}}. Commonly used, such as \code{\link[=lognormal]{lognormal()}}, are also +reexported as part of \code{epidist}.} } \value{ The requested brms function diff --git a/man/epidist_gen_log_lik_latent.Rd b/man/epidist_gen_log_lik_latent.Rd index 289e96ab8..5fc1e1dee 100644 --- a/man/epidist_gen_log_lik_latent.Rd +++ b/man/epidist_gen_log_lik_latent.Rd @@ -8,8 +8,12 @@ model} epidist_gen_log_lik_latent(family) } \arguments{ -\item{family}{Output of a call to \code{brms::brmsfamily()} with additional -information as provided by \code{.add_dpar_info()}} +\item{family}{A description of the response distribution and link function to +be used in the model. Every family function has a link argument allowing +users to specify the link function to be applied on the response variable. +If not specified, default links are used. For details of all supported +families see \code{\link[=brmsfamily]{brmsfamily()}}. Commonly used, such as \code{\link[=lognormal]{lognormal()}}, are also +reexported as part of \code{epidist}.} } \value{ A function that calculates the log likelihood for a single diff --git a/man/epidist_gen_posterior_epred.Rd b/man/epidist_gen_posterior_epred.Rd index d385fe3f6..05d072457 100644 --- a/man/epidist_gen_posterior_epred.Rd +++ b/man/epidist_gen_posterior_epred.Rd @@ -8,8 +8,12 @@ distribution for a latent model} epidist_gen_posterior_epred(family) } \arguments{ -\item{family}{Output of a call to \code{brms::brmsfamily()} with additional -information as provided by \code{.add_dpar_info()}} +\item{family}{A description of the response distribution and link function to +be used in the model. Every family function has a link argument allowing +users to specify the link function to be applied on the response variable. +If not specified, default links are used. For details of all supported +families see \code{\link[=brmsfamily]{brmsfamily()}}. Commonly used, such as \code{\link[=lognormal]{lognormal()}}, are also +reexported as part of \code{epidist}.} } \value{ A function that takes a prep argument from brms and returns a matrix @@ -19,7 +23,7 @@ per observation. \description{ This function creates a function that calculates the expected value of the posterior predictive distribution for a latent model. The returned function -takes a prep argument (from brms) and returns posterior expected values. +takes a \code{prep} argument (from brms) and returns posterior expected values. This is used internally by \code{\link[brms:posterior_epred.brmsfit]{brms::posterior_epred()}} to calculate expected values for latent models. } diff --git a/man/epidist_gen_posterior_predict.Rd b/man/epidist_gen_posterior_predict.Rd index fb60d3bd0..b572d4c6e 100644 --- a/man/epidist_gen_posterior_predict.Rd +++ b/man/epidist_gen_posterior_predict.Rd @@ -8,13 +8,17 @@ latent model} epidist_gen_posterior_predict(family) } \arguments{ -\item{family}{Output of a call to \code{brms::brmsfamily()} with additional -information as provided by \code{.add_dpar_info()}} +\item{family}{A description of the response distribution and link function to +be used in the model. Every family function has a link argument allowing +users to specify the link function to be applied on the response variable. +If not specified, default links are used. For details of all supported +families see \code{\link[=brmsfamily]{brmsfamily()}}. Commonly used, such as \code{\link[=lognormal]{lognormal()}}, are also +reexported as part of \code{epidist}.} } \value{ -A function that takes a prep argument from brms and returns a matrix -of posterior predictions, with one row per posterior draw and one column -per observation. The prep object must have the following variables: +A function that takes a \code{prep} argument from brms and returns a +matrix of posterior predictions, with one row per posterior draw and one +column per observation. The \code{prep} object must have the following variables: \itemize{ \item \code{vreal1}: relative observation time \item \code{vreal2}: primary event window @@ -24,7 +28,7 @@ per observation. The prep object must have the following variables: \description{ This function creates a function that draws from the posterior predictive distribution for a latent model using \code{\link[primarycensored:rprimarycensored]{primarycensored::rpcens()}} to handle -censoring and truncation. The returned function takes a prep argument from +censoring and truncation. The returned function takes a \code{prep} argument from \code{brms} and returns posterior predictions. This is used internally by \code{\link[brms:posterior_predict.brmsfit]{brms::posterior_predict()}} to generate predictions for latent models. } diff --git a/vignettes/ebola.Rmd b/vignettes/ebola.Rmd index 1dbf76016..bd1c199fe 100644 --- a/vignettes/ebola.Rmd +++ b/vignettes/ebola.Rmd @@ -315,7 +315,7 @@ ranef(fit_sex_district) To go further than summaries of the fitted model, we recommend using the `tidybayes` package. For example, to obtain the posterior expectation of the delay distribution, under no censoring or truncation, we may use the `modelr::data_grid()` function in combination with the `tidybayes::add_epred_draws()` function. -The `tidybayes::add_epred_draws()` function uses the (internal) `posterior_epred_latent_lognormal()` function implemented in `epidist` for the `latent_lognormal` custom `brms` family. +The `tidybayes::add_epred_draws()` function uses the `epidist_gen_posterior_predict()` function to generate a posterior prediction function for the `lognormal()` distribution. In Figure \@ref(fig:epred) we show the posterior expectation of the delay distribution for each of the three fitted models. Figure \@ref(fig:epred)B illustrates the higher mean of men as compared with women. diff --git a/vignettes/epidist.Rmd b/vignettes/epidist.Rmd index 40a561d41..399652a84 100644 --- a/vignettes/epidist.Rmd +++ b/vignettes/epidist.Rmd @@ -290,6 +290,9 @@ fit <- epidist( ) ``` +**Note that here we use the default `rstan` backend but we generally recommend using the `cmdstanr` backend for faster sampling and additional features.** +**This can be set using `backend = "cmdstanr"` after following the installing CmdStan instructions in the README.** + The `fit` object is a `brmsfit` object containing MCMC samples from each of the parameters in the model, shown in the table below. Many of these parameters (e.g. `swindow` and `pwindow`) are the so called latent variables, and have lengths corresponding to the `sample_size`. @@ -307,9 +310,6 @@ data.frame( Users familiar with Stan and `brms`, can work with `fit` directly. Any tool that supports `brms` fitted model objects will be compatible with `fit`. -**Note that here we use the default `rstan` backend but we generally recommend using the `cmdstanr` backend for faster sampling and additional features.** -**This can be set using `backend = "cmdstanr"` after following the installing CmdStan instructions in the README.** - For example, we can use the built in `summary()` function ```{r} @@ -341,7 +341,7 @@ ggplot() + data = data.frame(x = c(0, 30)), aes(x = x), fun = dlnorm, - linewidth = 2, + linewidth = 1.5, args = list( meanlog = secondary_dist[["mu"]], sdlog = secondary_dist[["sigma"]]