ExprModVar | R Documentation |

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

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`

.

`rdecision::ModVar`

-> `ExprModVar`

`new()`

Create a `ModVar`

formed from an expression involving
other model variables.

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

`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`

.

An object of type `ExprModVar`

`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.

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

`method`

A character string with the method, e.g.

`"mean()"`

.

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.

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().

`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.

ExprModVar$is_probabilistic()

`TRUE`

if probabilistic

`operands()`

Return a list of operands.

ExprModVar$operands(recursive = TRUE)

`recursive`

Whether to include nested variables in the list.

Finds operands that are themselves `ModVar`

s in the
expression. if `recursive=TRUE`

, the list includes all
`ModVar`

s that are operands of expression operands, recursively.

A list of model variables.

`distribution()`

Accessor function for the name of the expression model variable.

ExprModVar$distribution()

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

`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.

ExprModVar$mean()

Mean value as a numeric value.

`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.

ExprModVar$mode()

Mode as a numeric value.

`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.

ExprModVar$SD()

Standard deviation as a numeric value

`quantile()`

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

.

ExprModVar$quantile(probs)

`probs`

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

Vector of numeric values of the same length as `probs`

.

`mu_hat()`

Return the estimated expected value of the variable.

ExprModVar$mu_hat()

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.

Expected value as a numeric value.

`sigma_hat()`

Return the estimated standard deviation of the distribution.

ExprModVar$sigma_hat()

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.

Standard deviation as a numeric value.

`q_hat()`

Return the estimated quantiles by sampling the variable.

ExprModVar$q_hat(probs)

`probs`

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

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.

Vector of quantiles.

`set()`

Sets the value of the `ExprModVar`

.

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

`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.

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`

.

Updated `ExprModVar`

.

`get()`

Gets the value of the `ExprModVar`

that was set by the most recent
call to `set()`

.

ExprModVar$get()

Value determined by last `set()`

.

`clone()`

The objects of this class are cloneable with this method.

ExprModVar$clone(deep = FALSE)

`deep`

Whether to make a deep clone.

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 `ModVar`

s 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.

Andrew J. Sims andrew.sims@newcastle.ac.uk

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

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.