| Title: | Probability Distributions with Certain or Uncertain Parameters |
|---|---|
| Description: | Represents probability distributions with fixed or potentially uncertain parameters, with tools to discretise, convolve, sample from and summarise them. |
| Authors: | Sebastian Funk [aut, cre] (ORCID: <https://orcid.org/0000-0002-2842-3406>), James M. Azam [aut] (ORCID: <https://orcid.org/0000-0001-5782-7330>), Sam Abbott [aut] (ORCID: <https://orcid.org/0000-0001-8057-8037>) |
| Maintainer: | Sebastian Funk <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.3.0 |
| Built: | 2026-10-12 23:24:35 UTC |
| Source: | https://github.com/epiforecasts/distspec |
Creates a delay distribution as the sum of two other delay distributions.
## S3 method for class 'dist_spec' e1 + e2## S3 method for class 'dist_spec' e1 + e2
e1 |
The first delay distribution (of type <dist_spec>) to combine. |
e2 |
The second delay distribution (of type <dist_spec>) to combine. |
A delay distribution representing the sum of the two delays
# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal( meanlog = 1.6, sdlog = 1, max = 20 ) dist1 + dist1 # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) dist1 + dist2# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal( meanlog = 1.6, sdlog = 1, max = 20 ) dist1 + dist1 # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) dist1 + dist2
Compares two delay distributions
## S3 method for class 'dist_spec' e1 == e2 ## S3 method for class 'dist_spec' e1 != e2## S3 method for class 'dist_spec' e1 == e2 ## S3 method for class 'dist_spec' e1 != e2
e1 |
The first delay distribution (of type <dist_spec>) to combine. |
e2 |
The second delay distribution (of type <dist_spec>) to combine. |
TRUE or FALSE
Fixed(1) == Normal(1, 0.5)Fixed(1) == Normal(1, 0.5)
<dist_spec>
Converts other representations of a probability distribution into a
<dist_spec>. A <dist_spec> is returned unchanged. A numeric vector is
interpreted as a probability mass function and becomes a NonParametric()
distribution; a single number becomes a Fixed() point mass at that value.
Other packages can provide methods for their own distribution classes by
registering an as_dist_spec.<class> method, without distspec depending on
them or them re-implementing the <dist_spec> format.
as_dist_spec(x, ...) ## S3 method for class 'dist_spec' as_dist_spec(x, ...) ## S3 method for class 'numeric' as_dist_spec(x, ...) ## Default S3 method: as_dist_spec(x, ...)as_dist_spec(x, ...) ## S3 method for class 'dist_spec' as_dist_spec(x, ...) ## S3 method for class 'numeric' as_dist_spec(x, ...) ## Default S3 method: as_dist_spec(x, ...)
x |
Object to convert: a |
... |
Additional arguments passed to methods. Every method forwards
them to |
A <dist_spec>.
Distributions for the constructors this converts to.
# a PMF vector becomes a nonparametric distribution as_dist_spec(c(0.1, 0.4, 0.3, 0.2)) # a single number becomes a fixed (point mass) distribution as_dist_spec(3) # a <dist_spec> is returned unchanged as_dist_spec(Gamma(mean = 4, sd = 1))# a PMF vector becomes a nonparametric distribution as_dist_spec(c(0.1, 0.4, 0.3, 0.2)) # a single number becomes a fixed (point mass) distribution as_dist_spec(3) # a <dist_spec> is returned unchanged as_dist_spec(Gamma(mean = 4, sd = 1))
A beta distribution as a <dist_spec>, given either by its shape parameters
shape1/shape2 or by its mean/sd. It is not discretised.
Beta(shape1, shape2, mean, sd, ...)Beta(shape1, shape2, mean, sd, ...)
shape1, shape2
|
Shape parameters of the beta distribution. |
mean, sd
|
Mean and standard deviation of the distribution, as an
alternative to |
... |
Limits of the distribution, passed to |
A <dist_spec>.
Distributions for an overview and the other distributions.
Beta(shape1 = 2, shape2 = 5) Beta(mean = 0.3, sd = 0.15)Beta(shape1 = 2, shape2 = 5) Beta(mean = 0.3, sd = 0.15)
<dist_spec>
Set the bounds that constrain a distribution: max truncates the support
at that value, while cdf_max trims the tail by keeping the distribution
only up to its cdf_max quantile. Either bound drops the mass beyond it
and renormalises what remains. discretise() applies the bounds when
producing a PMF, and sample_dist() draws from the bounded distribution.
A bound set on a composite distribution refers to the sum of its
components: sample_dist() rejects such a bound, and discretise() does
not apply it.
bound_dist(x, max = Inf, cdf_max = 1, cdf_cutoff = deprecated())bound_dist(x, max = Inf, cdf_max = 1, cdf_cutoff = deprecated())
x |
A |
max |
Numeric, maximum value of the distribution. The distribution will
be truncated at this value. Default: |
cdf_max |
Numeric in |
cdf_cutoff |
[Deprecated] Renamed to |
a <dist_spec> with relevant attributes set that define its bounds
discretise() and sample_dist(), which consume these bounds.
# Truncate a gamma distribution at 20 bound_dist(Gamma(mean = 5, sd = 1), max = 20) # Keep it up to its 99.9th percentile bound_dist(Gamma(mean = 5, sd = 1), cdf_max = 0.999)# Truncate a gamma distribution at 20 bound_dist(Gamma(mean = 5, sd = 1), max = 20) # Keep it up to its 99.9th percentile bound_dist(Gamma(mean = 5, sd = 1), cdf_max = 0.999)
This combines the given distributions into a single composite <dist_spec>
holding multiple delay distributions.
Note that distributions that already are combinations of other distributions cannot be combined with other combinations of distributions.
## S3 method for class 'dist_spec' c(...)## S3 method for class 'dist_spec' c(...)
... |
The delay distributions to combine |
Combined delay distributions (with class <dist_spec>)
# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal( meanlog = 1.6, sdlog = 1, max = 20 ) dist1 + dist1 # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) c(dist1, dist2)# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal( meanlog = 1.6, sdlog = 1, max = 20 ) dist1 + dist1 # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) c(dist1, dist2)
Evaluates the CDF of a <dist_spec> with fixed (non-uncertain) parameters
at the given values, respecting any max/cdf_max bound set with
bound_dist(): this is the CDF of the truncated distribution, not the
unbounded one, so it is 1 for any value at or beyond the bound. A
Fixed() (point-mass) distribution has a step-function CDF: 0 below its
value and 1 at or above it.
Only a distribution with fixed parameters can have its CDF evaluated. If
any parameter is itself a distribution (a prior), there is no single
distribution to evaluate and an error is raised; resolve it first with
fix_parameters().
A composite (multi-component) distribution returns one set of values per
component, in keeping with mean()/sd()/quantile.dist_spec(). A
max/cdf_max bound set on the composite itself (with bound_dist() on
the sum) refers to that combined distribution, which has no closed-form
CDF, so this raises an error. Bound the components individually to
evaluate their CDF under a bound.
cdf(x, ...) ## S3 method for class 'dist_spec' cdf(x, q, ...) ## S3 method for class 'multi_dist_spec' cdf(x, q, ...)cdf(x, ...) ## S3 method for class 'dist_spec' cdf(x, q, ...) ## S3 method for class 'multi_dist_spec' cdf(x, q, ...)
x |
A |
... |
Not used. |
q |
Numeric vector of values to evaluate the CDF at. |
For a single distribution, a numeric vector the same length as
q. For a composite distribution of k components, a length(q) by
k matrix, one column per component.
quantile.dist_spec() for the corresponding quantile function,
and fix_parameters() to resolve an uncertain distribution first.
# The CDF of a fixed-parameter gamma distribution cdf(Gamma(shape = 2, rate = 1), c(1, 2, 3)) # A `max` bound truncates the CDF accordingly: it reaches 1 at the bound cdf(Gamma(shape = 2, rate = 1, max = 3), c(1, 2, 3)) # A fixed (point-mass) distribution has a step-function CDF cdf(Fixed(3), c(2, 3, 4))# The CDF of a fixed-parameter gamma distribution cdf(Gamma(shape = 2, rate = 1), c(1, 2, 3)) # A `max` bound truncates the CDF accordingly: it reaches 1 at the bound cdf(Gamma(shape = 2, rate = 1, max = 3), c(1, 2, 3)) # A fixed (point-mass) distribution has a step-function CDF cdf(Fixed(3), c(2, 3, 4))
This convolves any consecutive nonparametric distributions contained in the <dist_spec>.
## S3 method for class 'dist_spec' collapse(x, ...)## S3 method for class 'dist_spec' collapse(x, ...)
x |
A |
... |
ignored |
A <dist_spec> where consecutive nonparametric distributions
have been convolved
discretise() to produce the nonparametric components this
convolves. The vignette("distspec") shows the full
get_pmf(collapse(discretise(d1 + d2))) pipeline.
# A fixed gamma distribution with mean 5 and sd 1. dist1 <- Gamma(mean = 5, sd = 1, max = 20) # An uncertain lognormal distribution with meanlog and sdlog normally # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) # The sum of two distributions collapse(discretise(dist1 + dist2, strict = FALSE))# A fixed gamma distribution with mean 5 and sd 1. dist1 <- Gamma(mean = 5, sd = 1, max = 20) # An uncertain lognormal distribution with meanlog and sdlog normally # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) # The sum of two distributions collapse(discretise(dist1 + dist2, strict = FALSE))
Convert from mean and standard deviation to the log mean of the
lognormal distribution. Useful for defining a LogNormal() distribution
from a mean and standard deviation on the natural scale.
convert_to_logmean(mean, sd)convert_to_logmean(mean, sd)
mean |
Numeric, mean of a distribution |
sd |
Numeric, standard deviation of a distribution |
The log mean of a lognormal distribution
convert_to_logmean(2, 1)convert_to_logmean(2, 1)
Convert from mean and standard deviation to the log standard deviation of the
lognormal distribution. Useful for defining a LogNormal() distribution
from a mean and standard deviation on the natural scale.
convert_to_logsd(mean, sd)convert_to_logsd(mean, sd)
mean |
Numeric, mean of a distribution |
sd |
Numeric, standard deviation of a distribution |
The log standard deviation of a lognormal distribution
convert_to_logsd(2, 1)convert_to_logsd(2, 1)
A Dirichlet prior over the weights of a nonparametric probability mass
function, used to specify an uncertain NonParametric() distribution whose
PMF is left uncertain given the Dirichlet prior. Give either alpha
directly, or a reference prior PMF together with a concentration.
Dirichlet(alpha, prior, concentration, ...)Dirichlet(alpha, prior, concentration, ...)
alpha |
A positive numeric vector of concentration parameters. |
prior |
Either a numeric PMF vector (zero-indexed, i.e. the
first entry represents probability mass at zero) or a
|
concentration |
A positive scalar controlling how tightly
the Dirichlet prior concentrates around the supplied PMF.
The Dirichlet alpha vector is computed as
|
... |
Not used. |
A <dist_spec>.
NonParametric() to use the prior, and Distributions for an
overview.
Dirichlet(c(1, 1, 1, 1)) Dirichlet(prior = c(0.1, 0.3, 0.4, 0.2), concentration = 10)Dirichlet(c(1, 1, 1, 1)) Dirichlet(prior = c(0.1, 0.3, 0.4, 0.2), concentration = 10)
Discretise a <dist_spec>
## S3 method for class 'dist_spec' discretise(x, strict = TRUE, remove_trailing_zeros = TRUE, ...) discretize(x, ...)## S3 method for class 'dist_spec' discretise(x, strict = TRUE, remove_trailing_zeros = TRUE, ...) discretize(x, ...)
x |
A |
strict |
Logical; If |
remove_trailing_zeros |
Logical; If |
... |
ignored |
A <dist_spec> where all distributions with constant parameters are
nonparametric. Extract the resulting PMF vector with get_pmf().
The probability mass function is computed using the {primarycensored}
package, which provides double censored PMF calculations. This correctly
represents the probability mass function of a double censored distribution
arising from the difference of two censored events.
The probability mass function of the discretised probability distribution is a vector where the first entry corresponds to the integral over the (0,1] interval of the corresponding continuous distribution (probability of integer 0), the second entry corresponds to the (0,2] interval (probability mass of integer 1), the third entry corresponds to the (1, 3] interval (probability mass of integer 2), etc.
The maximum value truncates the distribution: mass beyond it is dropped and
the remaining PMF is renormalised to sum to one. A cdf_max below 1
additionally trims the tail, keeping the distribution only up to its
cdf_max quantile.
A Fixed() (point-mass) distribution is not discretised through a CDF but by
its own method: an integer value places all of the mass on that integer,
while a fractional value splits the mass proportionally across the two
adjacent integers. For example Fixed(2.25) places 0.75 on 2 and 0.25 on 3.
Charniga, K., et al. “Best practices for estimating and reporting epidemiological delay distributions of infectious diseases using public health surveillance and healthcare data”, arXiv e-prints, 2024. doi:10.48550/arXiv.2405.08841 Park, S. W., et al., "Estimating epidemiological delay distributions for infectious diseases", medRxiv, 2024. doi:10.1101/2024.01.12.24301247 Abbott S., et al., "primarycensored: Primary Event Censored Distributions", 2025. doi:10.5281/zenodo.13632839
collapse() to convolve the discretised components of a composite
distribution into a single PMF, and sample_dist() to draw random samples.
The vignette("distspec") shows the full
get_pmf(collapse(discretise(d1 + d2))) pipeline.
# A fixed gamma distribution with mean 5 and sd 1, discretised to a PMF. dist1 <- Gamma(mean = 5, sd = 1, max = 20) get_pmf(discretise(dist1)) # An uncertain lognormal distribution cannot be discretised, so with # `strict = FALSE` it is returned unchanged. dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) discretise(dist2, strict = FALSE) # A fractional fixed value splits its mass across the two adjacent integers. get_pmf(discretise(Fixed(2.25)))# A fixed gamma distribution with mean 5 and sd 1, discretised to a PMF. dist1 <- Gamma(mean = 5, sd = 1, max = 20) get_pmf(discretise(dist1)) # An uncertain lognormal distribution cannot be discretised, so with # `strict = FALSE` it is returned unchanged. dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) discretise(dist2, strict = FALSE) # A fractional fixed value splits its mass across the two adjacent integers. get_pmf(discretise(Fixed(2.25)))
distspec represents probability distributions (typically epidemiological
delays, such as generation times or reporting delays) as <dist_spec>
objects. Each supported distribution has its own constructor: LogNormal(),
Gamma(), Normal(), Exponential(), Weibull(), Beta(), Fixed(),
NonParametric() and Dirichlet().
A parameter can be given either as a fixed numeric value or as an uncertain
value (another <dist_spec>); currently only normally distributed uncertain
parameters (from Normal()) are supported.
Each distribution has a "natural" (canonical) parameterisation, such as
shape and rate for Gamma() or meanlog and sdlog for LogNormal().
It can sometimes also be specified using other parameters, such as its mean
and standard deviation, which are then converted to the natural parameters
(propagating any uncertainty with a first-order delta-method approximation).
discretise() and collapse() to discretise and convolve
distributions, sample_dist() to draw samples, and get_parameters() /
get_pmf() to inspect them.
An exponential distribution as a <dist_spec>, given either by its rate or
by its mean.
Exponential(rate, mean, ...) Exp(...)Exponential(rate, mean, ...) Exp(...)
rate |
vector of rates. |
mean |
Mean of the distribution, as an alternative to |
... |
Limits of the distribution, passed to |
A <dist_spec>.
Distributions for an overview and the other distributions.
Exponential(rate = 1) Exponential(mean = 4)Exponential(rate = 1) Exponential(mean = 4)
<dist_spec>
If the given <dist_spec> has any uncertainty, it is removed and the
corresponding distribution converted into a fixed one.
Call this before sample_dist() or get_pmf() on an uncertain
distribution, as neither can operate on a distribution that still carries a
prior.
## S3 method for class 'dist_spec' fix_parameters(x, strategy = c("mean", "sample"), ...)## S3 method for class 'dist_spec' fix_parameters(x, strategy = c("mean", "sample"), ...)
x |
A |
strategy |
Character; either "mean" (use the mean estimates of the
mean and standard deviation) or "sample" (randomly sample mean and
standard deviation from uncertainty given in the |
... |
ignored |
A <dist_spec> object without uncertainty
# An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) fix_parameters(dist)# An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) fix_parameters(dist)
A fixed (delta) distribution as a <dist_spec>, placing all of its mass on a
single value.
Fixed(value, ...)Fixed(value, ...)
value |
Value of the fixed (delta) distribution. |
... |
Limits of the distribution, passed to |
A <dist_spec>.
Distributions for an overview and the other distributions.
Fixed(value = 3) Fixed(value = 3.5)Fixed(value = 3) Fixed(value = 3.5)
A gamma distribution as a <dist_spec>, given either by its natural
parameters shape/rate (or shape/scale) or by its mean/sd.
Gamma(shape, rate, scale, mean, sd, ...)Gamma(shape, rate, scale, mean, sd, ...)
shape, scale
|
shape and scale parameters. Must be positive,
|
rate |
an alternative way to specify the scale. |
mean, sd
|
Mean and standard deviation of the distribution, as an
alternative to |
... |
Limits of the distribution, passed to |
A <dist_spec>.
Distributions for an overview and the other distributions.
Gamma(mean = 4, sd = 1) Gamma(shape = 16, rate = 4) Gamma(shape = Normal(16, 2), rate = Normal(4, 1))Gamma(mean = 4, sd = 1) Gamma(shape = 16, rate = 4) Gamma(shape = Normal(16, 2), rate = Normal(4, 1))
<dist_spec>
Get the distribution of a <dist_spec>
get_distribution(x, id = NULL)get_distribution(x, id = NULL)
x |
A |
id |
Integer; the id of the distribution to use (if x is a composite
distribution). If |
A character string naming the distribution (or "nonparametric")
dist <- Gamma(shape = 3, rate = 2, max = 10) get_distribution(dist)dist <- Gamma(shape = 3, rate = 2, max = 10) get_distribution(dist)
Generic function to extract the distribution parameters (e.g. shape and
rate for Gamma) from a dist_spec object.
get_parameters(x, ...) ## S3 method for class 'dist_spec' get_parameters(x, id = NULL, ...)get_parameters(x, ...) ## S3 method for class 'dist_spec' get_parameters(x, id = NULL, ...)
x |
A |
... |
Additional arguments passed to methods |
id |
Integer; the id of the distribution to use (if x is a composite
distribution). If |
A list of parameters of the distribution.
dist <- Gamma(shape = 3, rate = 2) get_parameters(dist)dist <- Gamma(shape = 3, rate = 2) get_parameters(dist)
Get the probability mass function of a nonparametric distribution
get_pmf(x, id = NULL)get_pmf(x, id = NULL)
x |
A |
id |
Integer; the id of the distribution to use (if x is a composite
distribution). If |
An uncertain (Dirichlet-backed) nonparametric distribution has no concrete
PMF, so calling get_pmf() on one is an error. Resolve it to a fixed PMF
first with fix_parameters() (e.g. strategy = "mean").
The pmf of the distribution
dist <- discretise(Gamma(shape = 3, rate = 2, max = 10)) get_pmf(dist)dist <- discretise(Gamma(shape = 3, rate = 2, max = 10)) get_pmf(dist)
<dist_spec> is uncertainA distribution is uncertain when it carries a prior: a parametric
distribution with a <dist_spec> (rather than numeric) parameter, or a
nonparametric distribution whose PMF is given by a <dist_spec> (a
Dirichlet() prior) rather than a numeric vector.
has_uncertainty(x, id = NULL)has_uncertainty(x, id = NULL)
x |
A |
id |
Integer; the id of the distribution to use (if x is a composite
distribution). If |
TRUE if the (component) distribution is uncertain.
has_uncertainty(Gamma(shape = 1, rate = 1)) has_uncertainty(Gamma(shape = Normal(1, 0.5), rate = 1))has_uncertainty(Gamma(shape = 1, rate = 1)) has_uncertainty(Gamma(shape = Normal(1, 0.5), rate = 1))
Check if a <dist_spec> is constrained, i.e. has a finite maximum or nonzero CDF cutoff.
## S3 method for class 'dist_spec' is_constrained(x, ...)## S3 method for class 'dist_spec' is_constrained(x, ...)
x |
A |
... |
ignored |
Logical; TRUE if x is constrained
# A fixed gamma distribution with mean 5 and sd 1. dist1 <- Gamma(mean = 5, sd = 1, max = 20) # An uncertain lognormal distribution with meanlog and sdlog normally # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) # both distributions are constrained and therefore so is the sum is_constrained(dist1 + dist2)# A fixed gamma distribution with mean 5 and sd 1. dist1 <- Gamma(mean = 5, sd = 1, max = 20) # An uncertain lognormal distribution with meanlog and sdlog normally # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) # both distributions are constrained and therefore so is the sum is_constrained(dist1 + dist2)
A lognormal distribution as a <dist_spec>, given either by its natural
parameters meanlog/sdlog or by its mean/sd.
LogNormal(meanlog, sdlog, mean, sd, ...)LogNormal(meanlog, sdlog, mean, sd, ...)
meanlog, sdlog
|
mean and standard deviation of the distribution
on the log scale with default values of |
mean, sd
|
Mean and standard deviation of the distribution, as an
alternative to |
... |
Limits of the distribution, passed to |
A <dist_spec>.
Distributions for an overview and the other distributions.
LogNormal(mean = 4, sd = 1) LogNormal(mean = 4, sd = 1, max = 10) # Uncertain parameters must be given as the natural parameters LogNormal(meanlog = Normal(1.5, 0.5), sdlog = 0.25, max = 10)LogNormal(mean = 4, sd = 1) LogNormal(mean = 4, sd = 1, max = 10) # Uncertain parameters must be given as the natural parameters LogNormal(meanlog = Normal(1.5, 0.5), sdlog = 0.25, max = 10)
This works out the maximum of all the (parametric / nonparametric) delay distributions combined in the passed <dist_spec> (ignoring any uncertainty in parameters)
## S3 method for class 'dist_spec' max(x, ...)## S3 method for class 'dist_spec' max(x, ...)
x |
The <dist_spec> to use |
... |
Not used |
A numeric vector of maxima, one per component.
# A fixed gamma distribution with mean 5 and sd 1. dist1 <- Gamma(mean = 5, sd = 1, max = 20) max(dist1) # An uncertain lognormal distribution with meanlog and sdlog normally # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) max(dist2) # The max the sum of two distributions max(dist1 + dist2)# A fixed gamma distribution with mean 5 and sd 1. dist1 <- Gamma(mean = 5, sd = 1, max = 20) max(dist1) # An uncertain lognormal distribution with meanlog and sdlog normally # distributed as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- LogNormal( meanlog = Normal(3, 0.5), sdlog = Normal(2, 0.5), max = 20 ) max(dist2) # The max the sum of two distributions max(dist1 + dist2)
This works out the mean of all the (parametric / nonparametric) delay distributions combined in the passed <dist_spec>.
## S3 method for class 'dist_spec' mean(x, ..., ignore_uncertainty = FALSE)## S3 method for class 'dist_spec' mean(x, ..., ignore_uncertainty = FALSE)
x |
The |
... |
Not used |
ignore_uncertainty |
Logical; whether to ignore any uncertainty in parameters. If set to FALSE (the default) then the mean of any uncertain parameters will be returned as NA. |
A numeric vector of means, one per component of the <dist_spec>;
NA for any component with uncertain parameters unless
ignore_uncertainty = TRUE.
# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal(mean = 5, sd = 1, max = 20) mean(dist1) # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) mean(dist2) # The mean of the sum of two distributions mean(dist1 + dist2)# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal(mean = 5, sd = 1, max = 20) mean(dist1) # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) mean(dist2) # The mean of the sum of two distributions mean(dist1 + dist2)
dist_spec given parameters and a
distribution.This will convert all parameters to natural parameters before generating
a dist_spec. If they are uncertain the uncertainty is propagated to the
natural parameters with a first-order (delta-method) approximation (see
convert_to_natural()).
new_dist_spec( params, distribution, max = Inf, cdf_max = 1, cdf_cutoff = deprecated() )new_dist_spec( params, distribution, max = Inf, cdf_max = 1, cdf_cutoff = deprecated() )
params |
Parameters of the distribution (including |
distribution |
Character; the distribution type (e.g. |
max |
Numeric, maximum value of the distribution. The distribution will
be truncated at this value. Default: |
cdf_max |
Numeric in |
cdf_cutoff |
[Deprecated] Renamed to |
A dist_spec of the given specification.
new_dist_spec( params = list(mean = 2, sd = 1), distribution = "normal" )new_dist_spec( params = list(mean = 2, sd = 1), distribution = "normal" )
A nonparametric distribution as a <dist_spec>, defined directly by its
probability mass function. The PMF can instead be left uncertain by
passing a Dirichlet() prior.
NonParametric(pmf, ...)NonParametric(pmf, ...)
pmf |
Probability mass function, as a zero-indexed numeric vector (the
first entry is the mass at zero) or a |
... |
Limits of the distribution, passed to |
A distribution constructed with a Dirichlet() prior has no concrete PMF,
in the same way that Gamma(shape = Normal(3, 0.5), rate = 2) has an
uncertain shape in place of a fixed value. get_pmf() errors and
has_uncertainty() returns TRUE until fix_parameters() resolves the
prior into a PMF (e.g. with strategy = "mean").
A <dist_spec>.
Distributions for an overview and the other distributions.
NonParametric(c(0.1, 0.3, 0.2, 0.4)) # With a Dirichlet prior (PMF left uncertain) NonParametric(pmf = Dirichlet(c(1, 1, 1, 1)))NonParametric(c(0.1, 0.3, 0.2, 0.4)) # With a Dirichlet prior (PMF left uncertain) NonParametric(pmf = Dirichlet(c(1, 1, 1, 1)))
A normal distribution as a <dist_spec>, given by its mean and sd. Also
used to give an uncertain parameter of another distribution.
Normal(mean, sd, ...)Normal(mean, sd, ...)
mean, sd
|
Mean and standard deviation of the distribution. |
... |
Limits of the distribution, passed to |
A <dist_spec>.
Distributions for an overview and the other distributions.
Normal(mean = 4, sd = 1) Normal(mean = 4, sd = 1, max = 10)Normal(mean = 4, sd = 1) Normal(mean = 4, sd = 1, max = 10)
This function takes a <dist_spec> object and plots its probability mass
function (PMF) and cumulative distribution function (CDF) using {ggplot2}.
## S3 method for class 'dist_spec' plot(x, samples = 50L, res = 1, cumulative = TRUE, ...)## S3 method for class 'dist_spec' plot(x, samples = 50L, res = 1, cumulative = TRUE, ...)
x |
A |
samples |
Integer; Number of samples to generate for distributions with uncertain parameters (default: 50). |
res |
Numeric; Resolution of the PMF and CDF (default: 1, i.e. integer
discretisation). This applies only to components discretised from a
continuous distribution; a nonparametric component is already discretised
on its integer support and is unaffected by |
cumulative |
Logical; whether to plot the cumulative distribution in addition to the probability mass function |
... |
ignored |
A component must have a finite range to be plotted. One with no finite max
and no cdf_max of its own raises an error; bound it first (e.g. with
bound_dist()).
A {ggplot2} object showing the PMF (and, if cumulative = TRUE,
the CDF) of each component, faceted by distribution.
# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal(mean = 1.6, sd = 0.5, max = 20) # Plot discretised distribution with 1 day discretisation window plot(dist1) # Plot discretised distribution with 0.01 day discretisation window plot(dist1, res = 0.01, cumulative = FALSE) # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) plot(dist2) # Multiple distributions with 0.1 discretisation window and do not plot the # cumulative distribution plot(dist1 + dist2, res = 0.1, cumulative = FALSE)# A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal(mean = 1.6, sd = 0.5, max = 20) # Plot discretised distribution with 1 day discretisation window plot(dist1) # Plot discretised distribution with 0.01 day discretisation window plot(dist1, res = 0.01, cumulative = FALSE) # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) plot(dist2) # Multiple distributions with 0.1 discretisation window and do not plot the # cumulative distribution plot(dist1 + dist2, res = 0.1, cumulative = FALSE)
This displays the parameters of the uncertain and probability mass functions of fixed delay distributions combined in the passed <dist_spec>.
## S3 method for class 'dist_spec' print(x, ...)## S3 method for class 'dist_spec' print(x, ...)
x |
The |
... |
Not used |
invisible
#' # A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal(mean = 1.5, sd = 0.5, max = 20) print(dist1) # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) print(dist2)#' # A fixed lognormal distribution with mean 5 and sd 1. dist1 <- LogNormal(mean = 1.5, sd = 0.5, max = 20) print(dist1) # An uncertain gamma distribution with shape and rate normally distributed # as Normal(3, 0.5) and Normal(2, 0.5) respectively dist2 <- Gamma( shape = Normal(3, 0.5), rate = Normal(2, 0.5), max = 20 ) print(dist2)
Computes quantiles of a <dist_spec> with fixed (non-uncertain)
parameters, respecting any max/cdf_max bound set with bound_dist():
the quantiles are those of the truncated distribution, not the unbounded
one. A Fixed() (point-mass) distribution has every quantile equal to its
value.
Only a distribution with fixed parameters can have its quantiles computed.
If any parameter is itself a distribution (a prior), there is no single
distribution to compute quantiles of and an error is raised; resolve it
first with fix_parameters().
A composite (multi-component) distribution returns one set of quantiles per
component, in keeping with mean()/sd(), which also return one value per
component. A max/cdf_max bound set on the composite itself (with
bound_dist() on the sum) refers to that combined distribution, which has
no closed-form quantile function, so this raises an error. Bound the
components individually to get their quantiles under a bound.
## S3 method for class 'dist_spec' quantile(x, probs = seq(0, 1, 0.25), ...) ## S3 method for class 'multi_dist_spec' quantile(x, probs = seq(0, 1, 0.25), ...)## S3 method for class 'dist_spec' quantile(x, probs = seq(0, 1, 0.25), ...) ## S3 method for class 'multi_dist_spec' quantile(x, probs = seq(0, 1, 0.25), ...)
x |
A |
probs |
Numeric vector of probabilities in |
... |
Not used. |
For a single distribution, a numeric vector of quantiles the same
length as probs. For a composite distribution of k components, a
length(probs) by k matrix, one column per component.
cdf() for the corresponding cumulative distribution function,
and fix_parameters() to resolve an uncertain distribution first.
# Quantiles of a fixed-parameter gamma distribution quantile(Gamma(shape = 2, rate = 1), c(0.05, 0.5, 0.95)) # A `max` bound truncates the quantiles accordingly quantile(Gamma(shape = 2, rate = 1, max = 3), c(0.05, 0.5, 0.95)) # A fixed (point-mass) distribution: every quantile equals its value quantile(Fixed(3), c(0.1, 0.9))# Quantiles of a fixed-parameter gamma distribution quantile(Gamma(shape = 2, rate = 1), c(0.05, 0.5, 0.95)) # A `max` bound truncates the quantiles accordingly quantile(Gamma(shape = 2, rate = 1, max = 3), c(0.05, 0.5, 0.95)) # A fixed (point-mass) distribution: every quantile equals its value quantile(Fixed(3), c(0.1, 0.9))
Draws random samples from a <dist_spec> whose parameters are fixed
numbers. An unbounded distribution uses the base-R random-generation
function for its family (e.g. rgamma() for a gamma distribution). A
discretised distribution is sampled on its integer support.
A max/cdf_max set with bound_dist() on a parametric distribution is
respected: samples are drawn from the truncated distribution by inverse
CDF rather than by discarding draws beyond the bound, so the cost does not
depend on how much of the mass the bound cuts off.
Only distributions with fixed parameters can be sampled. If any parameter is itself a distribution (a prior), there is no single distribution to sample from and an error is raised.
A composite (multi-component) distribution is sampled per component, in
keeping with mean()/sd(), which also return one value per component. Use
rowSums() on the result to obtain samples of the combined (convolved)
distribution. A max/cdf_max set on the composite itself (with
bound_dist() on the sum) refers to that combined distribution, which has
no closed-form distribution to draw from, so sampling such a composite
raises an error. Bound the components individually to sample them under a
bound.
sample_dist(x, n, ...) ## S3 method for class 'dist_spec' sample_dist(x, n, ...) ## S3 method for class 'multi_dist_spec' sample_dist(x, n, ...)sample_dist(x, n, ...) ## S3 method for class 'dist_spec' sample_dist(x, n, ...) ## S3 method for class 'multi_dist_spec' sample_dist(x, n, ...)
x |
A |
n |
The number of samples to draw. |
... |
Not used. |
For a single distribution, a numeric vector of n samples. For a
composite distribution of k components, an n by k matrix, one column
of n samples per component (rowSums() gives n samples of the combined
distribution).
fix_parameters() to resolve an uncertain distribution to fixed
parameters before sampling, and discretise() to obtain a PMF instead.
# Samples from a fixed gamma distribution sample_dist(Gamma(shape = 2, rate = 1), 10) # Samples from a discretised distribution, drawn on its integer support sample_dist(discretise(Gamma(shape = 2, rate = 1, max = 20)), 10) # A fixed distribution always returns the same value sample_dist(Fixed(3), 5) # A composite: an n-by-k matrix, one column per component sample_dist(Gamma(shape = 2, rate = 1) + Gamma(shape = 3, rate = 1), 10)# Samples from a fixed gamma distribution sample_dist(Gamma(shape = 2, rate = 1), 10) # Samples from a discretised distribution, drawn on its integer support sample_dist(discretise(Gamma(shape = 2, rate = 1, max = 20)), 10) # A fixed distribution always returns the same value sample_dist(Fixed(3), 5) # A composite: an n-by-k matrix, one column per component sample_dist(Gamma(shape = 2, rate = 1) + Gamma(shape = 3, rate = 1), 10)
A Weibull distribution as a <dist_spec>, given either by its
shape/scale or by its mean/sd.
Weibull(shape, scale, mean, sd, ...)Weibull(shape, scale, mean, sd, ...)
shape, scale
|
shape and scale parameters, the latter defaulting to 1. |
mean, sd
|
Mean and standard deviation of the distribution, as an
alternative to |
... |
Limits of the distribution, passed to |
A <dist_spec>.
Distributions for an overview and the other distributions.
Weibull(shape = 1, scale = 1) Weibull(shape = 1, scale = 1, max = 10) Weibull(mean = 4, sd = 1)Weibull(shape = 1, scale = 1) Weibull(shape = 1, scale = 1, max = 10) Weibull(mean = 4, sd = 1)