ExprModVar {rdecision}

A model variable constructed from an expression of other variables

Description

An R6 class representing a model variable constructed from an expression involving other variables.

Details

A class to support expressions involving objects of base class ModVar, which itself behaves like a model variable. For example, if A and B are variables with base class ModVar and c is a variable of type numeric, then it is not possible to write, for example, x <- 42*A/B + c, because R cannot manipulate class variables using the same operators as regular variables. But such forms of expression may be desirable in constructing a model and this class provides a mechanism for doing so. Inherits from class ModVar.

Super class

rdecision::ModVar -> ExprModVar

Methods

Public methods

• ExprModVar$new()

• ExprModVar$add_method()

• ExprModVar$is_probabilistic()

• ExprModVar$operands()

• ExprModVar$distribution()

• ExprModVar$mean()

• ExprModVar$mode()

• ExprModVar$SD()

• ExprModVar$quantile()

• ExprModVar$mu_hat()

• ExprModVar$sigma_hat()

• ExprModVar$q_hat()

• ExprModVar$set()

• ExprModVar$get()

• ExprModVar$clone()

Inherited methods

• rdecision::ModVar$description()
• rdecision::ModVar$is_expression()
• rdecision::ModVar$r()
• rdecision::ModVar$units()

Method new()

Create a ModVar formed from an expression involving other model variables.

Usage

ExprModVar$new(description, units, quo, nemp = 1000L)

Arguments

description

Name for the model variable expression. In a complex model it may help to tabulate how model variables are combined into costs, probabilities and rates.

units

Units in which the variable is expressed.

quo

A ⁠quosure⁠ (see package rlang), which contains an expression and its environment. The usage is quo(x+y) or rlang::quo(x+y).

nemp

sample size of the empirical distribution which will be associated with the expression, and used to estimate values for mu_hat, sigma_hat and q_hat.

Returns

An object of type ExprModVar

Method add_method()

Create a new ⁠quosure⁠ from that supplied in new() but with each ModVar operand appended with $x where x is the argument to this function.

Usage

ExprModVar$add_method(method = "mean()")

Arguments

method

A character string with the method, e.g. "mean()".

Details

This method is mostly intended for internal use within the class and will not generally be needed for normal use of ExprModVar objects. The returned expression is not syntactically checked or evaluated before it is returned.

Returns

A quosure whose expression is each ModVar v in the expression replaced with v$method and the same environment as specified in the quosure supplied in new().

Method is_probabilistic()

Tests whether the model variable is probabilistic, i.e. a random variable that follows a distribution, or an expression involving random variables, at least one of which follows a distribution.

Usage

ExprModVar$is_probabilistic()

Returns

TRUE if probabilistic

Method operands()

Return a list of operands.

Usage

ExprModVar$operands(recursive = TRUE)

Arguments

recursive

Whether to include nested variables in the list.

Details

Finds operands that are themselves ModVars in the expression. if recursive=TRUE, the list includes all ModVars that are operands of expression operands, recursively.

Returns

A list of model variables.

Method distribution()

Accessor function for the name of the expression model variable.

Usage

ExprModVar$distribution()

Returns

Expression as a character string with all control characters having been removed.

Method mean()

Return the value of the expression when its operands take their mean value (i.e. value returned by call to mean or their value, if numeric). See notes on this class for further explanation.

Usage

ExprModVar$mean()

Returns

Mean value as a numeric value.

Method mode()

Return the mode of the variable. By default returns NA, which will be the case for most ExprModVar variables, because an arbitrary expression is not guaranteed to be unimodal.

Usage

ExprModVar$mode()

Returns

Mode as a numeric value.

Method SD()

Return the standard deviation of the distribution as NA because the variance is not available as a closed form for all functions of distributions.

Usage

ExprModVar$SD()

Returns

Standard deviation as a numeric value

Method quantile()

Find quantiles of the uncertainty distribution. Not available as a closed form, and returned as NA.

Usage

ExprModVar$quantile(probs)

Arguments

probs

Numeric vector of probabilities, each in range [0,1].

Returns

Vector of numeric values of the same length as probs.

Method mu_hat()

Return the estimated expected value of the variable.

Usage

ExprModVar$mu_hat()

Details

This is computed by numerical simulation because there is, in general, no closed form expressions for the mean of a function of distributions. It is derived from the empirical distribution associated with the object.

Returns

Expected value as a numeric value.

Method sigma_hat()

Return the estimated standard deviation of the distribution.

Usage

ExprModVar$sigma_hat()

Details

This is computed by numerical simulation because there is, in general, no closed form expressions for the SD of a function of distributions. It is derived from the empirical distribution associated with the object.

Returns

Standard deviation as a numeric value.

Method q_hat()

Return the estimated quantiles by sampling the variable.

Usage

ExprModVar$q_hat(probs)

Arguments

probs

Vector of probabilities, in range [0,1].

Details

This is computed by numerical simulation because there is, in general, no closed form expressions for the quantiles of a function of distributions. The quantiles are derived from the empirical distribution associated with the object.

Returns

Vector of quantiles.

Method set()

Sets the value of the ExprModVar.

Usage

ExprModVar$set(what = "random", val = NULL)

Arguments

what

Until set is called again, subsequent calls to get will return a value determined by the what parameter. as follows:

"random"

a random sample is derived by taking a random sample from each of the operands and evaluating the expression. It does not draw from the empirical distribution because of the possibility of nested autocorrelation. For example, if z=xy, where x is a model variable and y is an expression which involves x, then y and x are correlated and will produce a different distribution for z than if x and y were independent. However, if z was sampled from the empirical distribution of y and the uncertainty distribution of x independently, the effect of correlation would be lost;

"expected"

the value of the expression when each of its operands takes its expected value. This will not - in general - be the mean of the uncertainty distribution for the expression which can be estimated by calling mu_hat;

"q2.5"

the value of the expression when each of its operands is equal to the 2.5th centile of their own uncertainty distribution. In general, this will be a more extreme value than the 2.5th centile of the uncertainty distribution of the expression, which can be found by using q_hat(p=0.025);

"q50"

as per "q2.5" but for the 50th centile (median);

"q97.5"

as per "q2.5" but for the 97.5th centile;

"current"

leaves the what parameter of method set unchanged for each operand and causes the expression to be re-evaluated at subsequent calls to get. Thus, after calling set(what="current") for the expression, subsequent calls to get for the expression may not return the same value, if method set has been called for one or more operands in the meantime;

"value"

sets the value of the expression to be equal to parameter val. This is not recommended for normal usage because it allows the model variable to be set to an implausible value, based on its defined uncertainty. An example of where this may be needed is in threshold finding.

val

A numeric value, only used with what="value", ignored otherwise.

Details

The available options for parameter what are identical to those available for the set method of ModVar. However, because an ExprModVar represents the left hand side of an expression involving operands, the effect of some options is different from its effect on a non-expression ModVar.

Returns

Updated ExprModVar.

Method get()

Gets the value of the ExprModVar that was set by the most recent call to set().

Usage

ExprModVar$get()

Returns

Value determined by last set().

Method clone()

The objects of this class are cloneable with this method.

Usage

ExprModVar$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Note

For many expressions involving model variables there will be no closed form expressions for the mean, standard deviation and the quantiles. When an ExprModVar is created, an empirical distribution is generated by repeatedly drawing a random sample from each operand and evaluating the expression. The empirical distribution, which becomes associated with the object, is used to provide estimates of the mean, standard deviation and the quantiles via functions mu_hat, sigma_hat and q_hat.

For consistency with ModVars which are not expressions, the function mean returns the value of the expression when all its operands take their mean values. This will, in general, not be the mean of the expression distribution (which can be obtained via mu_hat), but is the value normally used in the base case of a model as the point estimate. As Briggs et al note (section 4.1.1) "in all but the most non-linear models, the difference between the expectation over the output of a probabilistic model and that model evaluated at the mean values of the input parameters, is likely to be modest."

Functions SD, mode and quantile return NA because they do not necessarily have a closed form. The standard deviation can be estimated by calling sigma_hat and the quantiles by q_hat. Because a unimodal distribution is not guaranteed, there is no estimator provided for the mode.

Method distribution returns the string representation of the expression used to create the model variable.

Author(s)

Andrew J. Sims [e-mail]

References

Briggs A, Claxton K, Sculpher M. Decision modelling for health economic evaluation. Oxford, UK: Oxford University Press; 2006.