Issue 216: Use [pkg::func()] in roxygen comments everywhere (#263)

* Improve documentation of priors

* Improve description of utils

* Use [pkg::func()] style for links everywhere

R/diagnostics.R

@@ -3,7 +3,6 @@
 #' This function computes diagnostics to assess the quality of a fitted model.
 #' When the fitting algorithm used is `"sampling"` (HMC) then the output of
 #' `epidist_diagnostics` is a `data.table` containing:
-#'
 #' * `time`: the total time taken to fit all chains
 #' * `samples`: the total number of samples across all chains
 #' * `max_rhat`: the highest value of the Gelman-Rubin statistic
@@ -15,8 +14,7 @@
 #' `max_treedepth`
 #' * `per_at_max_treedepth`: the proportion of samples which attained the
 #' `max_treedepth`
-#'
-#' When the fitting algorithm is not `"sampling"` (see `?brms::brm` for other
+#' When the fitting algorithm is not `"sampling"` (see [brms::brm()] for other
 #' possible algorithms) then diagnostics are yet to be implemented.
 #' @param fit A fitted model of class `epidist_fit`
 #' @family diagnostics

R/generics.R

@@ -44,8 +44,8 @@ epidist_stancode <- function(data, ...) {
 #' @param formula ...
 #' @param family ...
 #' @param prior ...
-#' @param fn Likely `brms::brm`. Also possible to be `brms::make_stancode` or
-#' `brms::make_standata`.
+#' @param fn Likely [brms::brm()]. Also possible to be [brms::make_stancode()]
+#' or [brms::make_standata()].
 #' @param ... Additional arguments for method.
 #' @family generics
 #' @export

R/latent_individual.R

@@ -32,7 +32,7 @@ assert_latent_individual_input <- function(data) {
 #' (positive, numeric) upper and lower bounds for the primary and secondary
 #' event times, as well as a (positive, numeric) time that observation takes
 #' place. The output of this function is a `epidist_latent_individual` class
-#' object, which may be passed to `epidist()` to perform inference for the
+#' object, which may be passed to [epidist()] to perform inference for the
 #' model.
 #'
 #' @param data A `data.frame` or `data.table` containing line list data
@@ -143,8 +143,8 @@ epidist_family.epidist_latent_individual <- function(data,
 #' Define a formula for the latent_individual model
 #'
 #' @param data ...
-#' @param family The output of `epidist_family()`
-#' @param formula As produced by `brms::brmsformula`
+#' @param family The output of [epidist_family()]
+#' @param formula As produced by [brms::brmsformula()]
 #' @param ... ...
 #' @method epidist_formula epidist_latent_individual
 #' @family latent_individual

R/latent_lognormal.R

@@ -1,9 +1,9 @@
 #' Draws from the posterior predictive distribution
 #'
-#' See [`brms::posterior_predict`].
+#' See [brms::posterior_predict()].
 #'
 #' @param i The index of the observation to predict
-#' @param prep The result of a call to [`brms::posterior_predict`]
+#' @param prep The result of a call to [brms::posterior_predict()]
 #' @param ... Additional arguments
 #' @family postprocess
 #' @autoglobal
@@ -32,7 +32,7 @@ posterior_predict_latent_lognormal <- function(i, prep, ...) { # nolint: object_
 
 #' Draws from the expected value of the posterior predictive distribution
 #'
-#' See [`brms::posterior_epred`].
+#' See [brms::posterior_epred()].
 #'
 #' @param prep The result of a call to [`brms::prepare_predictions`]
 #' @family postprocess

R/postprocess.R

@@ -1,8 +1,8 @@
 #' Extract samples of the delay distribution parameters
 #'
-#' @param fit A model fit with `epidist::epidist`
+#' @param fit A model fit with [epidist::epidist()]
 #' @inheritParams brms::prepare_predictions
-#' @param ... Additional arguments passed to `brms::prepare_predictions`
+#' @param ... Additional arguments passed to [brms::prepare_predictions()]
 #' @family postprocess
 #' @autoglobal
 #' @export

R/prior.R

@@ -1,4 +1,13 @@
-#' Define prior from defaults, model, family, user
+#' Define prior distributions using `brms` defaults, model specific priors,
+#' family specific priors, and user provided priors
+#'
+#' This function obtains the `brms` default prior distributions for a particular
+#' model, then uses [replace_prior()] to update the prior distributions using:
+#' 1. Model specific prior distributions from [epidist_model_prior()]
+#' 2. Family specific prior distributions from [epidist_family_prior()]
+#' 3. User provided prior distributions
+#' Each element of this list overwrites previous elements, such that user
+#' provided prior distribution have the highest priority.
 #'
 #' @param data ...
 #' @param family ...
@@ -17,7 +26,10 @@ epidist_prior <- function(data, family, formula, prior) {
   return(prior)
 }
 
-#' Model specific prior
+#' Model specific prior distributions
+#'
+#' This function contains `brms` prior distributions which are specific to
+#' particular `epidist` models e.g. the `latent_lognormal` model.
 #'
 #' @inheritParams epidist_prior
 #' @param ... ...
@@ -28,19 +40,22 @@ epidist_model_prior <- function(data, ...) {
   UseMethod("epidist_model_prior")
 }
 
-#' Default empty model specific prior
+#' Default model specific prior distributions
+#'
+#' By default, we do not return any model specific prior distributions.
 #'
 #' @inheritParams epidist_prior
 #' @param ... ...
 #' @family prior
 #' @export
 epidist_model_prior.default <- function(data, formula, ...) {
-  # Currently there are not model-specific priors
-  # In future there might be, but we need to be careful about Stan code
   return(NULL)
 }
 
-#' Family specific prior
+#' Family specific prior distributions
+#'
+#' This function contains `brms` prior distributions which are specific to
+#' particular likelihood families e.g. [brms::lognormal()].
 #'
 #' @inheritParams epidist_prior
 #' @param ... ...
@@ -51,7 +66,9 @@ epidist_family_prior <- function(family, ...) {
   UseMethod("epidist_family_prior")
 }
 
-#' Default empty family specific prior
+#' Default family specific prior distributions
+#'
+#' By default, we do not return any family specific prior distributions.
 #'
 #' @inheritParams epidist_prior
 #' @param ... ...
@@ -61,7 +78,9 @@ epidist_family_prior.default <- function(family, formula, ...) {
   return(NULL)
 }
 
-#' Family specific prior for lognormal
+#' Family specific prior distributions for the lognormal family
+#'
+#' We suggest priors to overwrite the `brms` defaults for the lognormal family.
 #'
 #' @inheritParams epidist_prior
 #' @param ... ...
@@ -76,10 +95,16 @@ epidist_family_prior.lognormal <- function(family, formula, ...) {
   return(prior)
 }
 
-#' Replace a brms prior only if it exists
+#' Replace `brms` prior distributions
+#'
+#' This function takes `old_prior` and replaces any prior distributions
+#' contained in it by the corresponding prior distribution in `new_prior`.
+#' If there is a prior distribution in `new_prior` with no match in `old_prior`
+#' then the function will error and give the name of the new prior distribution
+#' with no match.
 #'
 #' @param old_prior One or more prior distributions in the class `brmsprior`
-#' @param new_prior One prior distribution in the class `brmsprior`
+#' @param new_prior One or more prior distributions in the class `brmsprior`
 #' @family prior
 #' @importFrom cli cli_inform
 #' @importFrom utils capture.output

R/utils.R

@@ -1,6 +1,9 @@
-#' Read in a epidist Stan code chunk
+#' Read in an `epidist` Stan code chunk
 #'
-#' @param path The path within the "stan" folder of the installed epidist
+#' This function is used to obtain Stan code chunks from the `stan/` folder of
+#' the `epidist` package. It is used within the [epidist_stancode()] function.
+#'
+#' @param path The path within the `stan/` folder of the installed `epidist`
 #' package to the Stan code chunk of interest.
 #' @return A character string containing the Stan code chunk of interest.
 #' @family utils
@@ -10,10 +13,14 @@ epidist_stan_chunk <- function(path) {
   paste(readLines(local_path), collapse = "\n")
 }
 
-#' Label a epidist Stan model with a version indicator
+#' Label a `epidist` Stan model with a version indicator
+#'
+#' This function is used within [epidist_stancode()] to label the generated Stan
+#' code with the version of `epidist` used. To view the full Stan code for any
+#' particular `epidist` model, we recommend use of [brms::make_stancode()].
 #'
-#' @return A brms stanvar chunk containing the package version used to build
-#' the Stan code.
+#' @return A `brms` Stan chunk containing the `epidist` package version used to
+#' build the Stan code.
 #' @family utils
 #' @export
 epidist_version_stanvar <- function() {
@@ -26,7 +33,7 @@ epidist_version_stanvar <- function() {
 #'
 #' This function rounds an input `x` down to the nearest multiple of some number
 #' `f`. For example, if `f = 0.2` and `x = 1.5` then the output would be 1.4.
-#' Or, if `f = 1` then `floor_mult` behaves as `floor`.
+#' If `f = 1` then `floor_mult` behaves as `floor`.
 #'
 #' @param x A number to be rounded down
 #' @param f A number specifying the multiple to be rounded down to