improved documentation style and consistency, used imperative functio…

…n descriptions

R/accessors.R

@@ -1,16 +1,16 @@
-#' Parameters method for `epidist` object
+#' Get parameters from an `<epidist>` object
 #'
-#' Extracts the parameters of the distribution stored in an `epidist` object.
+#' Extract the parameters of the distribution stored in an `<epidist>` object.
 #'
-#' @details The <epidist> object can be unparameterised in which it lacks
+#' @details The `<epidist>` object can be unparameterised in which it lacks
 #' a probability distribution or parameters of a probability distribution.
 #' In this can the `parameters.epidist()` method with return `NA`.
 #'
-#' @param x An `epidist` object
+#' @inheritParams print.epidist
 #' @param ... Extra arguments to be passed to the method.
 #'
 #' @return A named vector of parameters or `NA` when the `<epidist>` object is
-#' unparameterised
+#' unparameterised.
 #' @export
 get_parameters <- function(x, ...) {
   UseMethod("get_parameters")
@@ -45,14 +45,13 @@ get_parameters.epidist <- function(x, ...) {
   params
 }
 
-#' Method for extracting citation information from `<epidist>` or
-#' `<epiparam>` objects.
+#' Extract citation information from `<epidist>` or `<epiparam>` objects
 #'
-#' @param x An `epidist` or `epiparam` object.
+#' @param x An `<epidist>` or `<epiparam>` object.
 #' @param ... Extra arguments to be passed to the method.
 #'
 #' @return A single character string or list of character string citations.
-#' Length of list output is equal to number of rows in the `epiparam` object
+#' Length of list output is equal to number of rows in the `<epiparam>` object
 #' passed to the function.
 #' @export
 #'

R/bind_epiparam.R

@@ -1,28 +1,28 @@
-#' Bind an epi object to an [`epiparam`] object
+#' Bind an epi object to an `<epiparam>` object
 #'
-#' Binds any epi data class in \pkg{epiparameter} ([`epidist`],
-#' [`vb_epidist`], [`epiparam`]) or data frame to an [`epiparam`] object.
+#' Bind any epi data class in \pkg{epiparameter} (`<epidist>`,
+#' `<vb_epidist>`, `<epiparam>`) or data frame to an `<epiparam>` object.
 #'
-#' @details The [`epiparam`] class holds the library of epidemiological
+#' @details The `<epiparam>` class holds the library of epidemiological
 #' parameters that is stored in the \pkg{epiparameter} R package and can be
 #' manipulated. The [bind_epiparam()] function allows users to add entries to
-#' the library by binding them to the bottom of an existing [`epiparam`] object
+#' the library by binding them to the bottom of an existing `<epiparam>` object
 #' loaded in R.
 #'
-#' The `<epiparam>` returned by `bind_epiparam()` contains the matching columns
-#' of the input objects. Therefore, if one of the input objects contains extra
-#' columns which are not present in the other input object these will be missing
-#' from the returned object. This also applies whether binding other
-#' `<epiparam>` objects or `<data.frames>`. When binding `<epidist>` objects
-#' missing data fields are given a default value before
+#' The `<epiparam>` returned by [bind_epiparam()] contains the matching
+#' columns of the input objects. Therefore, if one of the input objects
+#' contains extra columns which are not present in the other input object
+#' these will be missing from the returned object. This also applies whether
+#' binding other `<epiparam>` or `<data.frame>` objects. When binding
+#' `<epidist>` objects missing data fields are given a default value before
 #' binding.
 #'
-#' @param epiparam An `<epiparam>` object
+#' @inheritParams validate_epiparam
 #' @param epi_obj Either an `<epidist>`, `<vb_epidist>`, `<epiparam>` or list
 #' of `<epidist>` objects. It can also be a data frame as long as the columns
 #' conform to the columns of an `<epiparam>` object.
 #'
-#' @return An `<epiparam>` object
+#' @inherit epiparam return
 #' @export
 #'
 #' @examples

R/calc_dist_params.R

@@ -1,22 +1,21 @@
-#' Calculates the parameters of a probability distribution from a list of
-#' available summary statistics
+#' Calculate the parameters of a probability distribution from a list of
+#' summary statistics
 #'
-#' @description When the parameters of a probability distribution are not
+#' @description If parameters of a probability distribution are not
 #' provided (e.g. when describing the distribution in the literature) and
 #' instead summary statistics of a distribution are provided, the parameters
-#' can usually be calculated from the summary statistics. The
-#' `calc_dist_params()` function computes the parameters for the gamma,
-#' lognormal and Weibull distributions.
+#' can usually be calculated from the summary statistics.
 #'
-#' This function can provide a convenient wrapper around the conversion and
-#' extraction functions when it is not known which summary statistics can be
-#' used to calculate the parameters of a distribution.
+#' This function can provide a convenient wrapper around
+#' [convert_summary_stats_to_params()] and [extract_param()]
+#' when it is not known which summary statistics can be used to
+#' calculate the parameters of a distribution.
 #'
 #' @details The hierarchy of methods is:
 #'
 #' 1. Conversion is prioritised if the mean and standard deviation are
 #' available as these are mostly analytical conversions (except for one of the
-#' Weibull conversions)
+#' Weibull conversions).
 #' 2. Next method if possible is extraction from percentiles. This method
 #' requires a lower percentile (between(0-50]) and an upper percentile
 #' (between (50-100)). If multiple percentiles in each of these ranges is
@@ -28,7 +27,7 @@
 #' @param sample_size The sample size of the data. Only needed when falling back
 #' on using the median-range extraction calculation.
 #'
-#' @return A named vector with parameters
+#' @return A named `numeric` vector with parameters.
 #' @keywords internal
 #' @examples
 #' \dontrun{

R/check_epidist.R

@@ -1,5 +1,4 @@
-#' Checks the probability distribution name and parameters to be used in an
-#' `epidist` object
+#' Check the probability distribution name and parameters for `<epidist>` object
 #'
 #' @inheritParams new_epidist
 #'
@@ -27,7 +26,7 @@ check_epidist_params <- function(prob_dist, prob_dist_params) {
   invisible(prob_dist_params)
 }
 
-#' Checks the parameter uncertainty list in an `epidist` object
+#' Check the parameter uncertainty in an `<epidist>` object
 #'
 #' @inheritParams new_epidist
 #' @inheritParams epidist

R/checkers.R

@@ -1,16 +1,15 @@
-#' Checks whether <epidist> or <epiparam> object contains a distribution and
-#' parameters for that distribution.
+#' Check if `<epidist>` or `<epiparam>` object contain a distribution and
+#' distribution parameters
 #'
-#' @description If the <epidist> object or a row in the <epiparam> data frame
-#' is missing either a probability distribution or parameters for the
-#' probability distribution, `is_parameterised` returns `FALSE`, otherwise
-#' it returns `TRUE`.
 #'
-#' @param x An `epidist` or `epiparam` object.
-#' @param ... [`dots`] not used, extra arguments supplied will cause a warning.
+#' @param x An `<epidist>` or `<epiparam>` object.
+#' @param ... [dots] not used, extra arguments supplied will cause a warning.
 #'
-#' @return A boolean logical for <epidist> or vector of boolean for each entry
-#' in the <epiparam>.
+#' @return A single boolean `logical` for `<epidist>` or vector of boolean
+#' `logical`s with length equal to the number of rows in the `<epiparam>`.
+#' If the `<epidist>` object or a row in the `<epiparam>` is missing either
+#' a probability distribution or parameters for the probability distribution
+#' returns `FALSE`, otherwise it returns `TRUE`.
 #' @export
 #'
 #' @examples

R/convert_params.R

@@ -1,7 +1,7 @@
 #' Convert the summary statistics of a distribution to parameters
 #'
-#' @description Converts the summary statistics for a range of distributions to
-#' a distribution's parameters. Most summary statistics are calculated
+#' @description Convert the summary statistics for a range of distributions to
+#' the distribution's parameters. Most summary statistics are calculated
 #' analytically given the parameters. An exception is the Weibull distribution
 #' which uses a root finding numerical method.
 #'
@@ -21,10 +21,10 @@
 #' the parameters cannot be calculated from the given input.
 #'
 #' The distribution names and parameter names follow the style of
-#' distributions in R, for example the lognormal distribution is `lnorm`,
+#' distributions in \R, for example the lognormal distribution is `lnorm`,
 #' and its parameters are `meanlog` and `sdlog`.
 #'
-#' @param distribution A `character` specifying distribution to use.
+#' @param distribution A `character` string specifying distribution to use.
 #' Default is `lnorm`; also takes `gamma` and `weibull`, `nbinom` and `geom`.
 #' @param ... `Numeric` named summary statistics used to convert to
 #' parameter(s). An example is the meanlog and sdlog parameters of the
@@ -71,12 +71,12 @@ convert_summary_stats_to_params <- function(distribution = c( # nolint
 
 #' Convert the parameter(s) of a distribution to summary statistics
 #'
-#' @description Converts the parameters for a range of distributions to a
+#' @description Convert the parameters for a range of distributions to a
 #' number of summary statistics. All summary statistics are calculated
 #' analytically given the parameters.
 #'
 #' @details The distribution names and parameter names follow the style of
-#' distributions in R, for example the lognormal distribution is `lnorm`,
+#' distributions in \R, for example the lognormal distribution is `lnorm`,
 #' and its parameters are `meanlog` and `sdlog`.
 #'
 #' @inheritParams convert_summary_stats_to_params
@@ -228,14 +228,14 @@ convert_params_lnorm <- function(...) {
   )
 }
 
-#' Converts the summary statistics to parameters of the lognormal distribution
+#' Convert summary statistics to parameters of the lognormal distribution
 #'
-#' @description Converts the summary statistics input into the meanlog and sdlog
+#' @description Convert the summary statistics input into the meanlog and sdlog
 #' parameters of the lognormal distribution.
 #'
 #' @inheritParams convert_summary_stats_to_params
 #'
-#' @return A list of two elements, the meanlog and sdlog
+#' @return A list of two elements: meanlog and sdlog
 #' @keywords internal
 convert_summary_stats_lnorm <- function(...) {
   # capture input
@@ -271,12 +271,12 @@ convert_summary_stats_lnorm <- function(...) {
   )
 }
 
-#' Converts the parameters of the gamma distribution to summary statistics
+#' Convert parameters of the gamma distribution to summary statistics
 #'
-#' @description Converts the shape and scale parameters of the gamma
+#' @description Convert the shape and scale parameters of the gamma
 #' distribution to a number of summary statistics which can be calculated
 #' analytically given the gamma parameters. One exception is the median which
-#' is calculated using [`qgamma()`] as no analytical form is available.
+#' is calculated using [qgamma()] as no analytical form is available.
 #'
 #' @inheritParams convert_params_to_summary_stats
 #'
@@ -323,9 +323,9 @@ convert_params_gamma <- function(...) {
   )
 }
 
-#' Converts the summary statistics to parameters of the gamma distribution
+#' Convert summary statistics to parameters of the gamma distribution
 #'
-#' @description Converts the summary statistics input into the shape and scale
+#' @description Convert the summary statistics input into the shape and scale
 #' parameters of the gamma distribution.
 #'
 #' @inheritParams convert_summary_stats_to_params
@@ -355,12 +355,12 @@ convert_summary_stats_gamma <- function(...) {
   stop("Cannot calculate gamma parameters from given input")
 }
 
-#' Converts the parameters of the Weibull distribution to summary statistics
+#' Convert parameters of the Weibull distribution to summary statistics
 #'
-#' @description Converts the shape and scale parameters of the Weibull
+#' @description Convert the shape and scale parameters of the Weibull
 #' distribution to a number of summary statistics which can be calculated
 #' analytically given the Weibull parameters. Note the conversion uses the
-#' [`gamma()`] function.
+#' [gamma()] function.
 #'
 #' @inheritParams convert_params_to_summary_stats
 #'
@@ -413,14 +413,14 @@ convert_params_weibull <- function(...) {
   )
 }
 
-#' Converts the summary statistics to parameters of the Weibull distribution
+#' Convert summary statistics to parameters of the Weibull distribution
 #'
-#' @description Converts the summary statistics input into the shape and scale
+#' @description Convert summary statistics input into the shape and scale
 #' parameters of the Weibull distribution.
 #'
 #' @inheritParams convert_summary_stats_to_params
 #'
-#' @return A list of two elements, the shape and scale
+#' @return A list of two elements, the shape and scale.
 #' @keywords internal
 convert_summary_stats_weibull <- function(...) {
   # capture input
@@ -456,13 +456,13 @@ convert_summary_stats_weibull <- function(...) {
   stop("Cannot calculate Weibull parameters from given input")
 }
 
-#' Converts the parameters of the negative binomial distribution to summary
+#' Convert parameters of the negative binomial distribution to summary
 #' statistics
 #'
-#' @description Converts the probability (`prob`) and dispersion parameters of
+#' @description Convert the probability (`prob`) and dispersion parameters of
 #' the negative binomial distribution to a number of summary statistics which
 #' can be calculated analytically given the negative binomial parameters.
-#' One exception is the median which is calculated using [`qnbinom()`] as no
+#' One exception is the median which is calculated using [qnbinom()] as no
 #' analytical form is available.
 #'
 #' The parameters are `prob` and `dispersion` (which is also commonly
@@ -516,16 +516,16 @@ convert_params_nbinom <- function(...) {
   )
 }
 
-#' Converts the summary statistics to parameters of the negative binomial
+#' Convert summary statistics to parameters of the negative binomial
 #' distribution
 #'
-#' @description Converts the summary statistics of the negative binomial
+#' @description Convert summary statistics of the negative binomial
 #' distribution the parameters (`prob`) and (`dispersion`) of the negative
 #' binomial distribution.
 #'
 #' @inheritParams convert_summary_stats_to_params
 #'
-#' @return A list of two elements, the probability and dispersion parameters
+#' @return A list of two elements, the probability and dispersion parameters.
 #' @keywords internal
 convert_summary_stats_nbinom <- function(...) {
   # capture input
@@ -567,15 +567,15 @@ convert_summary_stats_nbinom <- function(...) {
   )
 }
 
-#' Converts the parameters of the geometric distribution to summary statistics
+#' Convert parameter of the geometric distribution to summary statistics
 #'
-#' @description Converts the probability (`prob`) of the geometric distribution
+#' @description Convert the probability (`prob`) of the geometric distribution
 #' to a number of summary statistics which can be calculated analytically given
 #' the geometric parameter.
 #'
 #' @details This conversion function assumes that distribution represents the
 #' number of failures before the first success (supported for zero). This is
-#' the same form as used by base R and `distributional::dist_geometric()`.
+#' the same form as used by base R and [distributional::dist_geometric()].
 #'
 #' @inheritParams convert_params_to_summary_stats
 #'
@@ -620,18 +620,18 @@ convert_params_geom <- function(...) {
   )
 }
 
-#' Converts the summary statistics to parameters of the geometric distribution
+#' Convert summary statistics to parameters of the geometric distribution
 #'
-#' @description Converts the summary statistics of the geometric
+#' @description Convert summary statistics of the geometric
 #' distribution the parameter (`prob`) of the geometric distribution.
 #'
 #' @details This conversion function assumes that distribution represents the
 #' number of failures before the first success (supported for zero). This is
-#' the same form as used by base R and `distributional::dist_geometric()`.
+#' the same form as used by base R and [distributional::dist_geometric()].
 #'
 #' @inheritParams convert_summary_stats_to_params
 #'
-#' @return A list of one element, the probability parameter
+#' @return A list of one element, the probability parameter.
 #' @keywords internal
 convert_summary_stats_geom <- function(...) {
   # capture input

R/create_prob_dist.R

@@ -1,12 +1,15 @@
-#' Creates an distribution object depending on input parameters and distribution
-#' settings
+#' Create a distribution object from distribution name and parameters
 #'
-#' @description This function converts the probability distribution name and its
-#' parameters into an S3 class holding the distribution and parameters. The
-#' class holding the distribution depends on whether it is a continuous or
-#' discrete distribution. For continuous distributions the `{distributional}`
-#' package and classes are used, for discrete distributions the `{distcrete}`
-#' package is used. For details on the properties of the distribution classes
+#' @description Creates an S3 class holding the distribution and parameters
+#' from the probability distribution name, its parameters and distribution
+#' truncation and discretisation.
+#'
+#' The class holding the distribution depends on whether it is a discretised
+#' distribution. For continuous and discrete distributions S3 classes from the
+#' `{distributional}` package are used, for discretised continuous
+#' distributions the an S3 class from the `{distcrete}` package is used.
+#'
+#' For details on the properties of the distribution classes
 #' from each respective package see their documentation (either
 #' `?distributional` or `?distcrete`)
 #'
@@ -15,7 +18,7 @@
 #'
 #' @inheritParams new_epidist
 #'
-#' @return An S3 class containing the probability distribution
+#' @return An S3 class containing the probability distribution.
 #' @keywords internal
 #'
 #' @examples