An R6 class representing a model variable constructed from an expression involving other variables.
Andrew J. Sims andrew.sims@newcastle.ac.uk
rdecision::ModVar -> ExprModVar
new()Create a ModVar formed from an expression involving
other model variables.
ExprModVar$new(description, units, quo, nemp = 1000)descriptionName for the model variable expression. In a complex model it may help to tabulate how model variables are combined into costs, probabilities and rates.
unitsUnits in which the variable is expressed.
quoA quosure (see package rlang), which contains an
expression and its environment. The usage is quo(x+y) or
rlang::quo(x+y).
nempsample 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()")methodA 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)recursiveWhether to include nested variables in the list.
Finds operands that are themselves ModVars in the
expression. if recursive=TRUE, the list includes all
ModVars 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)probsNumeric 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)probsVector 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)whatUntil 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.
valA 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)deepWhether to make a deep clone.
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.
Briggs A, Claxton K, Sculpher M. Decision modelling for health economic evaluation. Oxford, UK: Oxford University Press; 2006.