diff --git a/R/defaults.R b/R/defaults.R index f65437705..f9e61a5b3 100644 --- a/R/defaults.R +++ b/R/defaults.R @@ -1,7 +1,7 @@ #' Default method for data validation #' #' @inheritParams epidist_validate -#' @param ... Additional arguments for method. +#' @param ... Additional arguments passed to method. #' @family defaults #' @importFrom cli cli_abort #' @export @@ -15,7 +15,7 @@ epidist_validate.default <- function(data, ...) { #' Default method for defining a model specific formula #' #' @inheritParams epidist_formula -#' @param ... Additional arguments for method. +#' @param ... Additional arguments passed to method. #' @family defaults #' @importFrom cli cli_abort #' @export @@ -29,7 +29,7 @@ epidist_formula.default <- function(data, ...) { #' Default method for defining a model specific family #' #' @inheritParams epidist_family -#' @param ... Additional arguments for method. +#' @param ... Additional arguments passed to method. #' @family defaults #' @importFrom cli cli_abort #' @export @@ -43,7 +43,7 @@ epidist_family.default <- function(data, ...) { #' Default method for defining model specific Stan code #' #' @inheritParams epidist_stancode -#' @param ... Additional arguments for method. +#' @param ... Additional arguments passed to method. #' @family defaults #' @importFrom cli cli_abort #' @export @@ -56,8 +56,8 @@ epidist_stancode.default <- function(data, ...) { #' Default method used for interface using `brms` #' -#' @inheritParams epidist_formula #' @inheritParams epidist +#' @inheritParams epidist_formula #' @rdname epidist.default #' @method epidist default #' @family defaults diff --git a/R/generics.R b/R/generics.R index cdfc7242c..08787b7c4 100644 --- a/R/generics.R +++ b/R/generics.R @@ -1,6 +1,10 @@ -#' Validate +#' Validate a data object for use with [epidist()] #' -#' @param data A dataframe to be used for modelling. +#' This function validates that the provided `data` is suitable to run a +#' particular `epidist` model. This may include checking the class of `data`, +#' and that it contains suitable columns. +#' +#' @param data A `data.frame` to be used for modelling. #' @family generics #' @export epidist_validate <- function(data) { @@ -9,8 +13,13 @@ epidist_validate <- function(data) { #' Define a model specific formula #' +#' This function is used within [epidist()] to create the formula object passed +#' to `brms`. It is unlikely that as a user you will need this function, but we +#' export it nonetheless to be transparent about what exactly is happening +#' inside of a call to [epidist()]. +#' #' @inheritParams epidist_validate -#' @param ... Additional arguments for method. +#' @param ... Additional arguments passed to method. #' @family generics #' @export epidist_formula <- function(data, ...) { @@ -19,8 +28,13 @@ epidist_formula <- function(data, ...) { #' Define model specific family #' +#' This function is used within [epidist()] to create a model specific custom +#' `brms` family object. This object is passed to `brms`. It is unlikely that +#' as a user you will need this function, but we export it nonetheless to be +#' transparent about what exactly is happening inside of a call to [epidist()]. +#' #' @inheritParams epidist_validate -#' @param ... Additional arguments for method. +#' @param ... Additional arguments passed to method. #' @family generics #' @export epidist_family <- function(data, ...) { @@ -29,8 +43,13 @@ epidist_family <- function(data, ...) { #' Define model specific Stan code #' +#' This function is used within [epidist()] to create any custom Stan code which +#' is injected into `brms` via the `stanvars` argument. It is unlikely that +#' as a user you will need this function, but we export it nonetheless to be +#' transparent about what exactly is happening inside of a call to [epidist()]. +#' #' @inheritParams epidist_validate -#' @param ... Additional arguments for method. +#' @param ... Additional arguments passed to method. #' @rdname epidist_stancode #' @family generics #' @export @@ -38,15 +57,30 @@ epidist_stancode <- function(data, ...) { UseMethod("epidist_stancode") } -#' Interface using `brms` +#' Fit epidemiological delay distributions using a `brms` interface #' #' @inheritParams epidist_validate -#' @param formula ... -#' @param family ... -#' @param prior ... -#' @param backend ... -#' @param fn Likely `brms::brm`. Also possible to be `brms::make_stancode` or -#' `brms::make_standata`. +#' @param formula A formula object created using `brms::bf`. A formula must be +#' provided for the distributional parameter `mu` common to all `brms` families. +#' Optionally, formulas may also be provided for additional distributional +#' parameters. +#' @param 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 supported families +#' see [brmsfamily()]. +#' @param prior One or more `brmsprior` objects created by [brms::set_prior()] +#' or related functions. These priors are passed to [epidist_prior()] in the +#' `prior` argument. We recommend caution and the use of prior predictive checks +#' for specifying prior distributions. +#' @param backend Character string naming the package to use as the backend for +#' fitting the Stan model. Options are `"rstan"` and `"cmdstanr"` (the default). +#' This option is passed directly through to `fn`. +#' @param fn The internal function to be called. By default this is `brms::brm`, +#' which performs inference for the specified model. Other options +#' `brms::make_stancode`, which returns the Stan code for the specified model, +#' and `brms::make_standata` which returns the data passed to Stan. These +#' options may be useful for model debugging and extensions. #' @param ... Additional arguments for method. #' @family generics #' @export diff --git a/man/epidist.Rd b/man/epidist.Rd index 71f86a11c..36660f726 100644 --- a/man/epidist.Rd +++ b/man/epidist.Rd @@ -2,28 +2,43 @@ % Please edit documentation in R/generics.R \name{epidist} \alias{epidist} -\title{Interface using \code{brms}} +\title{Fit epidemiological delay distributions using a \code{brms} interface} \usage{ epidist(data, formula, family, prior, backend, fn, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{formula}{...} +\item{formula}{A formula object created using \code{brms::bf}. A formula must be +provided for the distributional parameter \code{mu} common to all \code{brms} families. +Optionally, formulas may also be provided for additional distributional +parameters.} -\item{family}{...} +\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 supported families +see \code{\link[=brmsfamily]{brmsfamily()}}.} -\item{prior}{...} +\item{prior}{One or more \code{brmsprior} objects created by \code{\link[brms:set_prior]{brms::set_prior()}} +or related functions. These priors are passed to \code{\link[=epidist_prior]{epidist_prior()}} in the +\code{prior} argument. We recommend caution and the use of prior predictive checks +for specifying prior distributions.} -\item{backend}{...} +\item{backend}{Character string naming the package to use as the backend for +fitting the Stan model. Options are \code{"rstan"} and \code{"cmdstanr"} (the default). +This option is passed directly through to \code{fn}.} -\item{fn}{Likely \code{brms::brm}. Also possible to be \code{brms::make_stancode} or -\code{brms::make_standata}.} +\item{fn}{The internal function to be called. By default this is \code{brms::brm}, +which performs inference for the specified model. Other options +\code{brms::make_stancode}, which returns the Stan code for the specified model, +and \code{brms::make_standata} which returns the data passed to Stan. These +options may be useful for model debugging and extensions.} \item{...}{Additional arguments for method.} } \description{ -Interface using \code{brms} +Fit epidemiological delay distributions using a \code{brms} interface } \seealso{ Other generics: diff --git a/man/epidist.default.Rd b/man/epidist.default.Rd index 330ee38df..e1a8ea3fd 100644 --- a/man/epidist.default.Rd +++ b/man/epidist.default.Rd @@ -15,18 +15,33 @@ ) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{formula}{...} +\item{formula}{A formula object created using \code{brms::bf}. A formula must be +provided for the distributional parameter \code{mu} common to all \code{brms} families. +Optionally, formulas may also be provided for additional distributional +parameters.} -\item{family}{...} +\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 supported families +see \code{\link[=brmsfamily]{brmsfamily()}}.} -\item{prior}{...} +\item{prior}{One or more \code{brmsprior} objects created by \code{\link[brms:set_prior]{brms::set_prior()}} +or related functions. These priors are passed to \code{\link[=epidist_prior]{epidist_prior()}} in the +\code{prior} argument. We recommend caution and the use of prior predictive checks +for specifying prior distributions.} -\item{backend}{...} +\item{backend}{Character string naming the package to use as the backend for +fitting the Stan model. Options are \code{"rstan"} and \code{"cmdstanr"} (the default). +This option is passed directly through to \code{fn}.} -\item{fn}{Likely \code{brms::brm}. Also possible to be \code{brms::make_stancode} or -\code{brms::make_standata}.} +\item{fn}{The internal function to be called. By default this is \code{brms::brm}, +which performs inference for the specified model. Other options +\code{brms::make_stancode}, which returns the Stan code for the specified model, +and \code{brms::make_standata} which returns the data passed to Stan. These +options may be useful for model debugging and extensions.} \item{...}{Additional arguments for method.} } diff --git a/man/epidist_family.Rd b/man/epidist_family.Rd index 756b01bbc..a0b25ad0d 100644 --- a/man/epidist_family.Rd +++ b/man/epidist_family.Rd @@ -7,12 +7,15 @@ epidist_family(data, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{...}{Additional arguments for method.} +\item{...}{Additional arguments passed to method.} } \description{ -Define model specific family +This function is used within \code{\link[=epidist]{epidist()}} to create a model specific custom +\code{brms} family object. This object is passed to \code{brms}. It is unlikely that +as a user you will need this function, but we export it nonetheless to be +transparent about what exactly is happening inside of a call to \code{\link[=epidist]{epidist()}}. } \seealso{ Other generics: diff --git a/man/epidist_family.default.Rd b/man/epidist_family.default.Rd index 612f5de19..3e26190fb 100644 --- a/man/epidist_family.default.Rd +++ b/man/epidist_family.default.Rd @@ -7,9 +7,9 @@ \method{epidist_family}{default}(data, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{...}{Additional arguments for method.} +\item{...}{Additional arguments passed to method.} } \description{ Default method for defining a model specific family diff --git a/man/epidist_formula.Rd b/man/epidist_formula.Rd index f8cbd3f73..19cadd60e 100644 --- a/man/epidist_formula.Rd +++ b/man/epidist_formula.Rd @@ -7,12 +7,15 @@ epidist_formula(data, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{...}{Additional arguments for method.} +\item{...}{Additional arguments passed to method.} } \description{ -Define a model specific formula +This function is used within \code{\link[=epidist]{epidist()}} to create the formula object passed +to \code{brms}. It is unlikely that as a user you will need this function, but we +export it nonetheless to be transparent about what exactly is happening +inside of a call to \code{\link[=epidist]{epidist()}}. } \seealso{ Other generics: diff --git a/man/epidist_formula.default.Rd b/man/epidist_formula.default.Rd index f5638a1e7..80f835c11 100644 --- a/man/epidist_formula.default.Rd +++ b/man/epidist_formula.default.Rd @@ -7,9 +7,9 @@ \method{epidist_formula}{default}(data, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{...}{Additional arguments for method.} +\item{...}{Additional arguments passed to method.} } \description{ Default method for defining a model specific formula diff --git a/man/epidist_stancode.Rd b/man/epidist_stancode.Rd index 35186588c..c6933d8fd 100644 --- a/man/epidist_stancode.Rd +++ b/man/epidist_stancode.Rd @@ -7,12 +7,15 @@ epidist_stancode(data, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{...}{Additional arguments for method.} +\item{...}{Additional arguments passed to method.} } \description{ -Define model specific Stan code +This function is used within \code{\link[=epidist]{epidist()}} to create any custom Stan code which +is injected into \code{brms} via the \code{stanvars} argument. It is unlikely that +as a user you will need this function, but we export it nonetheless to be +transparent about what exactly is happening inside of a call to \code{\link[=epidist]{epidist()}}. } \seealso{ Other generics: diff --git a/man/epidist_stancode.default.Rd b/man/epidist_stancode.default.Rd index 985e70f29..26b64ba94 100644 --- a/man/epidist_stancode.default.Rd +++ b/man/epidist_stancode.default.Rd @@ -7,9 +7,9 @@ \method{epidist_stancode}{default}(data, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{...}{Additional arguments for method.} +\item{...}{Additional arguments passed to method.} } \description{ Default method for defining model specific Stan code diff --git a/man/epidist_validate.Rd b/man/epidist_validate.Rd index ae4a1a9db..6f4697bd6 100644 --- a/man/epidist_validate.Rd +++ b/man/epidist_validate.Rd @@ -2,15 +2,17 @@ % Please edit documentation in R/generics.R \name{epidist_validate} \alias{epidist_validate} -\title{Validate} +\title{Validate a data object for use with \code{\link[=epidist]{epidist()}}} \usage{ epidist_validate(data) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} } \description{ -Validate +This function validates that the provided \code{data} is suitable to run a +particular \code{epidist} model. This may include checking the class of \code{data}, +and that it contains suitable columns. } \seealso{ Other generics: diff --git a/man/epidist_validate.default.Rd b/man/epidist_validate.default.Rd index 1c2ea593a..7149135bf 100644 --- a/man/epidist_validate.default.Rd +++ b/man/epidist_validate.default.Rd @@ -7,9 +7,9 @@ \method{epidist_validate}{default}(data, ...) } \arguments{ -\item{data}{A dataframe to be used for modelling.} +\item{data}{A \code{data.frame} to be used for modelling.} -\item{...}{Additional arguments for method.} +\item{...}{Additional arguments passed to method.} } \description{ Default method for data validation