Skip to content

Commit

Permalink
updated extract_param documentation and vignettes to include normal e…
Browse files Browse the repository at this point in the history
…xtraction and allow negative vals for normal, relates #157
  • Loading branch information
joshwlambert committed Sep 5, 2023
1 parent a86b9d7 commit 1bf05cf
Show file tree
Hide file tree
Showing 6 changed files with 40 additions and 28 deletions.
33 changes: 20 additions & 13 deletions R/extract_param.R
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,25 @@
#'
#' Summary data of distributions, as provided by reports and meta-analyses, can
#' be used to extract the parameters of a chosen distribution. Currently
#' available distributions are: lognormal, gamma and Weibull. Extracting
#' from a lognormal returns the meanlog and sdlog parameters, and extracting
#' from the gamma and Weibull returns the shape and scale parameters.
#' available distributions are: lognormal, gamma, Weibull and normal.
#' Extracting from a lognormal returns the meanlog and sdlog parameters,
#' extracting from the gamma and Weibull returns the shape and scale parameters,
#' and extracting from the normal returns the mean and sd parameters.
#'
#' @details The `extract_param()` function works only for strictly positive
#' values at the percentiles of a distribution or the median and range of data
#' (numerics supplied to the `values` argument).
#' @details For `gamma`, `lnorm` and `weibull`, `extract_param()` works only
#' for strictly positive values at the percentiles of a distribution or the
#' median and range of data (numerics supplied to the `values` argument).
#' This means that negative values at the lower percentile or lower range
#' will not work with this function although they may present themselves in
#' epidemiological data (e.g. negative serial interval).
#'
#' epidemiological data (e.g. negative serial interval). For the `norm`
#' distribution negative values are allowed.
#'
#' @param type A `character` defining whether summary statistics based
#' around `percentiles` (default) or `range`
#' @param values A `vector`. If `type = percentiles`: `c(percentile_1,
#' percentile_2)`; and if `type = range`: `c(median, min, max)`
#' @param distribution A `character` specifying distribution to use.
#' Default is `lnorm`; also takes `gamma` and `weibull`.
#' Default is `lnorm`; also takes `gamma`, `weibull` and `norm`.
#' @param percentiles A `vector` with two elements specifying the
#' percentiles defined in `values` if using `type = "percentiles"`.
#' Percentiles should be specified between 0 and 1. For example 2.5th and 97.5th
Expand All @@ -39,7 +40,8 @@
#' @return A named `numeric` vector with the parameter values of the
#' distribution. If the `distribution = lnorm` then the parameters returned are
#' the meanlog and sdlog; if the `distribution = gamma` or `distribution =
#' weibull` then the parameters returned are the shape and scale.
#' weibull` then the parameters returned are the shape and scale; if
#' `distribution = norm` then the parameters returned are mean and sd.
#' @keywords extract
#' @author Adam Kucharski, Joshua W. Lambert
#' @export
Expand Down Expand Up @@ -76,7 +78,12 @@ extract_param <- function(type = c("percentiles", "range"),
distribution <- match.arg(arg = distribution, several.ok = FALSE)

# check numeric arguments
checkmate::assert_numeric(values)
if (distribution == "norm") {
checkmate::assert_numeric(values)
} else {
checkmate::assert_numeric(values, lower = 1e-10)
}

if (type == "percentiles") {
stopifnot(
"percentiles need to be given for type = 'percentiles'" =
Expand Down Expand Up @@ -277,8 +284,8 @@ check_optim_conv <- function(optim_params_list,
#' Function for extracting distribution parameters
#'
#' Set of functions that can be used to estimate the parameters of a
#' distribution (lognormal, gamma, Weibull) via optimisation from either the
#' percentiles or the median and ranges.
#' distribution (lognormal, gamma, Weibull, normal) via optimisation from
#' either the percentiles or the median and ranges.
#'
#' @param param Named numeric vector of the distribution parameters to be
#' optimised
Expand Down
2 changes: 1 addition & 1 deletion man/dot-extract_param.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

21 changes: 12 additions & 9 deletions man/extract_param.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions man/extraction_functions.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 4 additions & 2 deletions vignettes/extract-bias.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,10 @@ optimisation using least-squares.

The precision and bias of this approach needs to be explored across the parameter space
of the different distributions to understand potential erroneous inferences. This
vignette aims to explore this inference bias for the three distributions currently
supported in {epiparameter} for parameter extraction: gamma, lognormal and Weibull.
vignette aims to explore this inference bias for three distributions currently
supported in {epiparameter} for parameter extraction: gamma, lognormal and Weibull. Extraction
of parameters from a normal distribution is also supported in {epiparameter} but we
do not test that in this vignette.

::: {.alert .alert-warning}
This is not an in depth analysis of the estimation methods implemented in {epiparameter},
Expand Down
2 changes: 1 addition & 1 deletion vignettes/extract_convert.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ extract_param(
)
```

In the above example we estimate parameters of the gamma distribution, but extraction is also implemented for the lognormal and Weibull distributions, but specifying `"lnorm"` or `"weibull"`.
In the above example we estimate parameters of the gamma distribution, but extraction is also implemented for the lognormal, normal and Weibull distributions, but specifying `"lnorm"`, `"norm"` or `"weibull"`.

A message is shown when running `extract_param()` to make the user aware that the estimates are not completely reliable due to the use of numerical optimisation. Rerunning the function to and finding the same parameters are returned indicates that they have successfully converged. This issue is mostly overcome by the internal setup of the `extract_param()` function which searches for convergence to consistent parameter estimates before returning these to the user.

Expand Down

0 comments on commit 1bf05cf

Please sign in to comment.