Skip to contents

Base class for Distributions

Source: R/distribution_class.R
Distribution.Rd

Represents a modifiable Distribution family

See also

Other Distributions: dist_bdegp(), dist_beta(), dist_binomial(), dist_blended(), dist_dirac(), dist_discrete(), dist_empirical(), dist_erlangmix(), dist_exponential(), dist_gamma(), dist_genpareto(), dist_lognormal(), dist_mixture(), dist_negbinomial(), dist_normal(), dist_pareto(), dist_poisson(), dist_translate(), dist_trunc(), dist_uniform(), dist_weibull()

Active bindings

default_params

Get or set (non-recursive) default parameters of a Distribution

param_bounds

Get or set (non-recursive) parameter bounds (box constraints) of a Distribution

Methods

Public methods

Method new()

Usage

Distribution$new(type, caps, params, name, default_params)

Arguments

type

Type of distribution. This is a string constant for the default implementation. Distributions with non-constant type must override the get_type() function.

caps

Character vector of capabilities to fuel the default implementations of has_capability() and require_capability(). Distributions with dynamic capabilities must override the has_capability() function.

params

Initial parameter bounds structure, backing the param_bounds active binding (usually a list of intervals).

name

Name of the Distribution class. Should be CamelCase and end with "Distribution".

default_params

Initial fixed parameters backing the default_params active binding (usually a list of numeric / NULLs).

Details

Construct a Distribution instance

Used internally by the dist_* functions.

Method sample()

Usage

Distribution$sample(n, with_params = list())

Arguments

n

number of samples to draw.

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length n. In that case the i-th sample will use the i-th parameters.

Details

Sample from a Distribution

Returns

A length n vector of i.i.d. random samples from the Distribution with the specified parameters.

Examples

dist_exponential(rate = 2.0)$sample(10)

Method density()

Usage

Distribution$density(x, log = FALSE, with_params = list())

Arguments

x

Vector of points to evaluate the density at.

log

Flag. If TRUE, return the log-density instead.

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(x). In that case, the i-th density point will use the i-th parameters.

Details

Density of a Distribution

Returns

A numeric vector of (log-)densities

Examples

dist_exponential()$density(c(1.0, 2.0), with_params = list(rate = 2.0))

Method tf_logdensity()

Usage

Distribution$tf_logdensity()

Details

Compile a TensorFlow function for log-density evaluation

Returns

A tf_function taking arguments x and args returning the log-density of the Distribution evaluated at x with parameters args.

Method probability()

Usage

Distribution$probability(
  q,
  lower.tail = TRUE,
  log.p = FALSE,
  with_params = list()
)

Arguments

q

Vector of points to evaluate the probability function at.

lower.tail

If TRUE, return P(X <= q). Otherwise return P(X > q).

log.p

If TRUE, probabilities are returned as log(p).

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(q). In that case, the i-th probability point will use the i-th parameters.

Details

Cumulative probability of a Distribution

Returns

A numeric vector of (log-)probabilities

Examples

dist_exponential()$probability(
  c(1.0, 2.0),
  with_params = list(rate = 2.0)
)

Method tf_logprobability()

Usage

Distribution$tf_logprobability()

Details

Compile a TensorFlow function for log-probability evaluation

Returns

A tf_function taking arguments qmin, qmax and args returning the log-probability of the Distribution evaluated over the closed interval [qmin, qmax] with parameters args.

Method quantile()

Usage

Distribution$quantile(
  p,
  lower.tail = TRUE,
  log.p = FALSE,
  with_params = list()
)

Arguments

p

Vector of probabilities.

lower.tail

If TRUE, return P(X <= q). Otherwise return P(X > q).

log.p

If TRUE, probabilities are returned as log(p).

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(p). In that case, the i-th quantile will use the i-th parameters.

Details

Quantile function of a Distribution

Returns

A numeric vector of quantiles

Examples

dist_exponential()$quantile(c(0.1, 0.5), with_params = list(rate = 2.0))

Method hazard()

Usage

Distribution$hazard(x, log = FALSE, with_params = list())

Arguments

x

Vector of points.

log

Flag. If TRUE, return the log-hazard instead.

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(x). In that case, the i-th hazard point will use the i-th parameters.

Details

Hazard function of a Distribution

Returns

A numeric vector of (log-)hazards

Examples

dist_exponential(rate = 2.0)$hazard(c(1.0, 2.0))

Method diff_density()

Usage

Distribution$diff_density(x, log = FALSE, with_params = list())

Arguments

x

Vector of points.

log

Flag. If TRUE, return the gradient of the log-density instead.

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(x). In that case, the i-th density point will use the i-th parameters.

Details

Gradients of the density of a Distribution

Returns

A list structure containing the (log-)density gradients of all free parameters of the Distribution evaluated at x.

Examples

dist_exponential()$diff_density(
  c(1.0, 2.0),
  with_params = list(rate = 2.0)
)

Method diff_probability()

Usage

Distribution$diff_probability(
  q,
  lower.tail = TRUE,
  log.p = FALSE,
  with_params = list()
)

Arguments

q

Vector of points to evaluate the probability function at.

lower.tail

If TRUE, return P(X <= q). Otherwise return P(X > q).

log.p

If TRUE, probabilities are returned as log(p).

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(q). In that case, the i-th probability point will use the i-th parameters.

Details

Gradients of the cumulative probability of a Distribution

Returns

A list structure containing the cumulative (log-)probability gradients of all free parameters of the Distribution evaluated at q.

Examples

dist_exponential()$diff_probability(
  c(1.0, 2.0),
  with_params = list(rate = 2.0)
)

Method is_in_support()

Usage

Distribution$is_in_support(x, with_params = list())

Arguments

x

Vector of points

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(x). In that case, the i-th point will use the i-th parameters.

Details

Determine if a value is in the support of a Distribution

Returns

A logical vector with the same length as x indicating whether x is part of the support of the distribution given its parameters.

Examples

dist_exponential(rate = 1.0)$is_in_support(c(-1.0, 0.0, 1.0))

Method is_discrete_at()

Usage

Distribution$is_discrete_at(x, with_params = list())

Arguments

x

Vector of points

with_params

Distribution parameters to use. Each parameter value can also be a numeric vector of length length(x). In that case, the i-th point will use the i-th parameters.

Details

Determine if a value has positive probability

Returns

A logical vector with the same length as x indicating whether there is a positive probability mass at x given the Distribution parameters.

Examples

dist_dirac(point = 0.0)$is_discrete_at(c(0.0, 1.0))

Method tf_is_discrete_at()

Usage

Distribution$tf_is_discrete_at()

Details

Compile a TensorFlow function for discrete support checking

Returns

A tf_function taking arguments x and args returning whether the Distribution has a point mass at x given parameters args.

Method has_capability()

Usage

Distribution$has_capability(caps)

Arguments

caps

Character vector of capabilities

Details

Check if a capability is present

Returns

A logical vector the same length as caps.

Examples

dist_exponential()$has_capability("density")

Method get_type()

Usage

Distribution$get_type()

Details

Get the type of a Distribution. Type can be one of discrete, continuous or mixed.

Returns

A string representing the type of the Distribution.

Examples

dist_exponential()$get_type()
dist_dirac()$get_type()

dist_mixture(list(dist_dirac(), dist_exponential()))$get_type()
dist_mixture(list(dist_dirac(), dist_binomial()))$get_type()

Method get_components()

Usage

Distribution$get_components()

Details

Get the component Distributions of a transformed Distribution.

Returns

A possibly empty list of Distributions

Examples

dist_trunc(dist_exponential())$get_components()
dist_dirac()$get_components()
dist_mixture(list(dist_exponential(), dist_gamma()))$get_components()

Method is_discrete()

Usage

Distribution$is_discrete()

Details

Check if a Distribution is discrete, i.e. it has a density with respect to the counting measure.

Returns

TRUE if the Distribution is discrete, FALSE otherwise. Note that mixed distributions are not discrete but can have point masses.

Examples

dist_exponential()$is_discrete()
dist_dirac()$is_discrete()

Method is_continuous()

Usage

Distribution$is_continuous()

Details

Check if a Distribution is continuous, i.e. it has a density with respect to the Lebesgue measure.

Returns

TRUE if the Distribution is continuous, FALSE otherwise. Note that mixed distributions are not continuous.

Examples

dist_exponential()$is_continuous()
dist_dirac()$is_continuous()

Method require_capability()

Usage

Distribution$require_capability(
  caps,
  fun_name = paste0(sys.call(-1)[[1]], "()")
)

Arguments

caps

Character vector of Capabilities to require

fun_name

Frienly text to use for generating the error message in case of failure.

Details

Ensure that a Distribution has all required capabilities. Will throw an error if any capability is missing.

Returns

Invisibly TRUE.

Examples

dist_exponential()$require_capability("diff_density")

Method get_dof()

Usage

Distribution$get_dof()

Details

Get the number of degrees of freedom of a Distribution family. Only parameters without a fixed default are considered free.

Returns

An integer representing the degrees of freedom suitable e.g. for AIC calculations.

Examples

dist_exponential()$get_dof()
dist_exponential(rate = 1.0)$get_dof()

Method get_placeholders()

Usage

Distribution$get_placeholders()

Details

Get Placeholders of a Distribution family. Returns a list of free parameters of the family. Their values will be NULL.

If the Distribution has Distributions as parameters, placeholders will be computed recursively.

Returns

A named list containing any combination of (named or unnamed) lists and NULLs.

Examples

dist_exponential()$get_placeholders()
dist_mixture(list(dist_dirac(), dist_exponential()))$get_placeholders()

Method get_params()

Usage

Distribution$get_params(with_params = list())

Arguments

with_params

Optional parameter overrides with the same structure as dist$get_params(). Given Parameter values are expected to be length 1.

Details

Get a full list of parameters, possibly including placeholders.

Returns

A list representing the (recursive) parameter structure of the Distribution with values for specified parameters and NULL for free parameters that are missing both in the Distributions parameters and in with_params.

Examples

dist_mixture(list(dist_dirac(), dist_exponential()))$get_params(
  with_params = list(probs = list(0.5, 0.5))
)

Method tf_make_constants()

Usage

Distribution$tf_make_constants(with_params = list())

Arguments

with_params

Optional parameter overrides with the same structure as dist$tf_make_constants(). Given Parameter values are expected to be length 1.

Details

Get a list of constant TensorFlow parameters

Returns

A list representing the (recursive) constant parameters of the Distribution with values sprecified by parameters. Each constant is a TensorFlow Tensor of dtype floatx.

Method tf_compile_params()

Usage

Distribution$tf_compile_params(input, name_prefix = "")

Arguments

input

A keras layer to bind all outputs to

name_prefix

Prefix to use for layer names

Details

Compile distribution parameters into tensorflow outputs

Returns

A list with two elements

  • outputs a flat list of keras output layers, one for each parameter.

  • output_inflater a function taking keras output layers and transforming them into a list structure suitable for passing to the loss function returned by tf_compile_model()

Method get_param_bounds()

Usage

Distribution$get_param_bounds()

Details

Get Interval bounds on all Distribution parameters

Returns

A list representing the free (recursive) parameter structure of the Distribution with Interval objects as values representing the bounds of the respective free parameters.

Examples

dist_mixture(
  list(dist_dirac(), dist_exponential()),
  probs = list(0.5, 0.5)
)$get_param_bounds()

dist_mixture(
  list(dist_dirac(), dist_exponential())
)$get_param_bounds()

dist_genpareto()$get_param_bounds()
dist_genpareto1()$get_param_bounds()

Method get_param_constraints()

Usage

Distribution$get_param_constraints()

Details

Get additional (non-linear) equality constraints on Distribution parameters

Returns

NULL if the box constraints specified by dist$get_param_bounds() are sufficient, or a function taking full Distribution parameters and returning either a numeric vector (which must be 0 for valid parameter combinations) or a list with elements

  • constraints: The numeric vector of constraints

  • jacobian: The Jacobi matrix of the constraints with respect to the parameters

Examples

dist_mixture(
  list(dist_dirac(), dist_exponential())
)$get_param_constraints()

Method export_functions()

Usage

Distribution$export_functions(
  name,
  envir = parent.frame(),
  with_params = list()
)

Arguments

name

common suffix of the exported functions

envir

Environment to export the functions to

with_params

Optional list of parameters to use as default values for the exported functions

Details

Export sampling, density, probability and quantile functions to plain R functions

Creates new functions in envir named {r,d,p,q}<name> which implement dist$sample, dist$density, dist$probability and dist$quantile as plain functions with default arguments specified by with_params or the fixed parameters.

The resulting functions will have signatures taking all parameters as separate arguments.

Returns

Invisibly NULL.

Examples

tmp_env <- new.env(parent = globalenv())
dist_exponential()$export_functions(
  name = "exp",
  envir = tmp_env,
  with_params = list(rate = 2.0)
)
evalq(
  fitdistrplus::fitdist(rexp(100), "exp"),
  envir = tmp_env
)

Method clone()

The objects of this class are cloneable with this method.

Usage

Distribution$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# Example for param_bounds:

# Create an Exponential Distribution with rate constrained to (0, 2)
# instead of (0, Inf)
my_exp <- dist_exponential()
my_exp$param_bounds$rate <- interval(c(0, 2))
my_exp$get_param_bounds()
#> $rate
#> (0, 2)
#> 

fit_dist(my_exp, rexp(100, rate = 3), start = list(rate = 1))$params$rate
#> [1] 2


## ------------------------------------------------
## Method `Distribution$sample`
## ------------------------------------------------

dist_exponential(rate = 2.0)$sample(10)
#>  [1] 1.60965237 0.64341964 0.83093236 0.84142694 0.31550391 0.07872478
#>  [7] 0.04114154 0.08781801 0.34662483 0.91500172

## ------------------------------------------------
## Method `Distribution$density`
## ------------------------------------------------

dist_exponential()$density(c(1.0, 2.0), with_params = list(rate = 2.0))
#> [1] 0.27067057 0.03663128

## ------------------------------------------------
## Method `Distribution$probability`
## ------------------------------------------------

dist_exponential()$probability(
  c(1.0, 2.0),
  with_params = list(rate = 2.0)
)
#> [1] 0.8646647 0.9816844

## ------------------------------------------------
## Method `Distribution$quantile`
## ------------------------------------------------

dist_exponential()$quantile(c(0.1, 0.5), with_params = list(rate = 2.0))
#> [1] 0.05268026 0.34657359

## ------------------------------------------------
## Method `Distribution$hazard`
## ------------------------------------------------

dist_exponential(rate = 2.0)$hazard(c(1.0, 2.0))
#> [1] 2 2

## ------------------------------------------------
## Method `Distribution$diff_density`
## ------------------------------------------------

dist_exponential()$diff_density(
  c(1.0, 2.0),
  with_params = list(rate = 2.0)
)
#> $rate
#> [1] -0.13533528 -0.05494692
#> 

## ------------------------------------------------
## Method `Distribution$diff_probability`
## ------------------------------------------------

dist_exponential()$diff_probability(
  c(1.0, 2.0),
  with_params = list(rate = 2.0)
)
#> $rate
#> [1] 0.13533528 0.03663128
#> 

## ------------------------------------------------
## Method `Distribution$is_in_support`
## ------------------------------------------------

dist_exponential(rate = 1.0)$is_in_support(c(-1.0, 0.0, 1.0))
#> [1] FALSE FALSE  TRUE

## ------------------------------------------------
## Method `Distribution$is_discrete_at`
## ------------------------------------------------

dist_dirac(point = 0.0)$is_discrete_at(c(0.0, 1.0))
#> [1]  TRUE FALSE

## ------------------------------------------------
## Method `Distribution$has_capability`
## ------------------------------------------------

dist_exponential()$has_capability("density")
#> [1] TRUE

## ------------------------------------------------
## Method `Distribution$get_type`
## ------------------------------------------------

dist_exponential()$get_type()
#> [1] "continuous"
dist_dirac()$get_type()
#> [1] "discrete"

dist_mixture(list(dist_dirac(), dist_exponential()))$get_type()
#> [1] "mixed"
dist_mixture(list(dist_dirac(), dist_binomial()))$get_type()
#> [1] "discrete"

## ------------------------------------------------
## Method `Distribution$get_components`
## ------------------------------------------------

dist_trunc(dist_exponential())$get_components()
#> [[1]]
#> An ExponentialDistribution with 1 dof
#> 
dist_dirac()$get_components()
#> list()
dist_mixture(list(dist_exponential(), dist_gamma()))$get_components()
#> [[1]]
#> An ExponentialDistribution with 1 dof
#> 
#> [[2]]
#> A GammaDistribution with 2 dof
#> 

## ------------------------------------------------
## Method `Distribution$is_discrete`
## ------------------------------------------------

dist_exponential()$is_discrete()
#> [1] FALSE
dist_dirac()$is_discrete()
#> [1] TRUE

## ------------------------------------------------
## Method `Distribution$is_continuous`
## ------------------------------------------------

dist_exponential()$is_continuous()
#> [1] TRUE
dist_dirac()$is_continuous()
#> [1] FALSE

## ------------------------------------------------
## Method `Distribution$require_capability`
## ------------------------------------------------

dist_exponential()$require_capability("diff_density")

## ------------------------------------------------
## Method `Distribution$get_dof`
## ------------------------------------------------

dist_exponential()$get_dof()
#> [1] 1
dist_exponential(rate = 1.0)$get_dof()
#> [1] 0

## ------------------------------------------------
## Method `Distribution$get_placeholders`
## ------------------------------------------------

dist_exponential()$get_placeholders()
#> $rate
#> NULL
#> 
dist_mixture(list(dist_dirac(), dist_exponential()))$get_placeholders()
#> $dists
#> $dists[[1]]
#> $dists[[1]]$point
#> NULL
#> 
#> 
#> $dists[[2]]
#> $dists[[2]]$rate
#> NULL
#> 
#> 
#> 
#> $probs
#> $probs[[1]]
#> NULL
#> 
#> $probs[[2]]
#> NULL
#> 
#> 

## ------------------------------------------------
## Method `Distribution$get_params`
## ------------------------------------------------

dist_mixture(list(dist_dirac(), dist_exponential()))$get_params(
  with_params = list(probs = list(0.5, 0.5))
)
#> $dists
#> $dists[[1]]
#> $dists[[1]]$point
#> NULL
#> 
#> 
#> $dists[[2]]
#> $dists[[2]]$rate
#> NULL
#> 
#> 
#> 
#> $probs
#> $probs[[1]]
#> [1] 0.5
#> 
#> $probs[[2]]
#> [1] 0.5
#> 
#> 

## ------------------------------------------------
## Method `Distribution$get_param_bounds`
## ------------------------------------------------

dist_mixture(
  list(dist_dirac(), dist_exponential()),
  probs = list(0.5, 0.5)
)$get_param_bounds()
#> $dists
#> $dists[[1]]
#> $dists[[1]]$point
#> (-Inf, Inf)
#> 
#> 
#> $dists[[2]]
#> $dists[[2]]$rate
#> (0, Inf)
#> 
#> 
#> 
#> $probs
#> list()
#> 

dist_mixture(
  list(dist_dirac(), dist_exponential())
)$get_param_bounds()
#> $dists
#> $dists[[1]]
#> $dists[[1]]$point
#> (-Inf, Inf)
#> 
#> 
#> $dists[[2]]
#> $dists[[2]]$rate
#> (0, Inf)
#> 
#> 
#> 
#> $probs
#> $probs[[1]]
#> [0, 1]
#> 
#> $probs[[2]]
#> [0, 1]
#> 
#> 

dist_genpareto()$get_param_bounds()
#> $u
#> (-Inf, Inf)
#> 
#> $sigmau
#> (0, Inf)
#> 
#> $xi
#> (-Inf, Inf)
#> 
dist_genpareto1()$get_param_bounds()
#> $u
#> (-Inf, Inf)
#> 
#> $sigmau
#> (0, Inf)
#> 
#> $xi
#> [0, 1]
#> 

## ------------------------------------------------
## Method `Distribution$get_param_constraints`
## ------------------------------------------------

dist_mixture(
  list(dist_dirac(), dist_exponential())
)$get_param_constraints()
#> function (params) 
#> {
#>     prob_mat <- do.call(cbind, params$probs)
#>     nms <- names(flatten_params(params))
#>     jac_full <- matrix(0, nrow = nrow(prob_mat), ncol = length(nms))
#>     jac_full[, grepl("^probs", nms)] <- 1
#>     list(constraints = rowSums(prob_mat) - 1, jacobian = jac_full)
#> }
#> <environment: 0x5571e8e11668>

## ------------------------------------------------
## Method `Distribution$export_functions`
## ------------------------------------------------

tmp_env <- new.env(parent = globalenv())
dist_exponential()$export_functions(
  name = "exp",
  envir = tmp_env,
  with_params = list(rate = 2.0)
)
#> Exported `dexp()`.
#> Exported `rexp()`.
#> Exported `pexp()`.
#> Exported `qexp()`.
evalq(
  fitdistrplus::fitdist(rexp(100), "exp"),
  envir = tmp_env
)
#> Fitting of the distribution ' exp ' by maximum likelihood 
#> Parameters:
#>      estimate Std. Error
#> rate 2.187126  0.2187125