Character vector of variable names

Maximum interaction degree

Output from evppi or evsi. The argument check=TRUE must have been used when calling evppi or evsi, to allow the regression model objects from gam or earth to be preserved. (This is not done by default, since these objects can be large.). attr(x, "models") contains these objects.

Parameter (or parameter group) whose EVPPI calculation is to be checked. This should be in the pars component of the object returned by evppi. Only relevant if x is the result of an evppi calculation. By default, the first calculation shown in x is checked.

Sample size whose EVSI calculation is to be checked. This should be in the n component of the object returned by evsi. Only relevant if x is the result of an evsi calculation.

Only relevant if there are more than two treatments in the decision model. Different regression models are then used for the comparisons of different treatments with the baseline treatment. comparison is an integer identifying which of these models is checked.

"costs" or "effects". Only relevant if outputs was in cost-effectiveness format when calling evppi or evsi, hence different regressions are used for costs and effects. By default, outcome="costs" is used, so that the regression for costs is checked.

If FALSE, only numerical statistics are returned, and a plot is not made.

Number of samples to generate from the uncertainty distribution of the parameters in chemo_pars_fn.

Probability of side effects under treatment 1

Probability of side effects under treatment 2

Probability of hospitalisation in the year after receiving treatment

Probability of death in the year after receiving treatment

Recovery probability for someone treated at home

Recovery probability for someone treated in hospital who does not die

Cost of a yearly period under treatment at home

Cost of hospital treatment

Cost of death

Utility of a period in the recovery state

Utility of home care state

Utility of hospital state

Long term mortality rate

Log odds ratio of side effects for treatment 2 compared to 1

Data frame giving estimates of the expected value of sample information, as returned by evsi. This may contain multiple estimates, one for each sample size and willingness to pay.

Setup costs of the study. This can either be a constant, or a vector of two elements giving a 95% credible interval (with mean defined by the midpoint), or a vector of three elements assumed to define the mean and 95% credible interval.

Per-participant costs of the study, supplied in the same format as cost_setup.

Size of the population who would be affected by the decision.

Time horizon over which discounting will be applied.

Discount rate used when converting per-person to population EVSI.

If TRUE, then the maximum ENBS is determined after fitting a nonparametric regression to the data frame x, which estimates and smooths the ENBS for every integer sample size in the range of x$n. The regression is done using the default settings of gam from the mgcv package.

If this is FALSE, then no smoothing or interpolation is done, and the maximum is determined by searching over the values supplied in x.

Basis dimension for the smooth regression. Passed as the k argument to the s() term in gam. Defaults to 6, or the number of unique sample sizes minus 1 if this is lower. Set to a higher number if you think the smoother does not capture the relation of ENBS to sample size accurately enough.

Cut-off probability which defines a "near-optimal" sample size. The minimum and maximum sample size for which the ENBS is within pcut (by default 5%) of its maximum value will be determined.

Data frame containing a set of ENBS estimates for different sample sizes, which will be optimised over. Usually this is for a common willingness-to-pay. The required components are enbs and n.

Cut-off probability which defines a "near-optimal" sample size. The minimum and maximum sample size for which the ENBS is within pcut (by default 5%) of its maximum value will be determined.

If TRUE, then the maximum ENBS is determined after fitting a nonparametric regression to the data frame x, which estimates and smooths the ENBS for every integer sample size in the range of x$n. The regression is done using the default settings of gam from the mgcv package.

If this is FALSE, then no smoothing or interpolation is done, and the maximum is determined by searching over the values supplied in x.

Basis dimension for the smooth regression. Passed as the k argument to the s() term in gam. Defaults to 6, or the number of unique sample sizes minus 1 if this is lower. Set to a higher number if you think the smoother does not capture the relation of ENBS to sample size accurately enough.

If TRUE and smooth=TRUE then the data frame of predictions from the smooth regression model is stored in the "preds" attribute of the result.

This could take one of two forms

"net benefit" form: a matrix or data frame of samples from the uncertainty distribution of the expected net benefit. The number of rows should equal the number of samples, and the number of columns should equal the number of decision options.

"cost-effectiveness analysis" form: a list with the following named components:

"c": a matrix or data frame of samples from the distribution of costs. There should be one column for each decision option.

"e": a matrix or data frame of samples from the distribution of effects, likewise.

"k": a vector of willingness-to-pay values.

Objects of class "bcea", as created by the BCEA package, are in this "cost-effectiveness analysis" format, therefore they may be supplied as the outputs argument.

Users of heemod can create an object of this form, given an object produced by run_psa (obj, say), with import_heemod_outputs.

If outputs is a matrix or data frame, it is assumed to be of "net benefit" form. Otherwise if it is a list, it is assumed to be of "cost effectiveness analysis" form.

Number of simulations from the decision model to use for calculating EVPPI. The first nsim rows of the objects in inputs and outputs are used.

This could take one of two forms

"net benefit" form: a matrix or data frame of samples from the uncertainty distribution of the expected net benefit. The number of rows should equal the number of samples, and the number of columns should equal the number of decision options.

"cost-effectiveness analysis" form: a list with the following named components:

"c": a matrix or data frame of samples from the distribution of costs. There should be one column for each decision option.

"e": a matrix or data frame of samples from the distribution of effects, likewise.

"k": a vector of willingness-to-pay values.

Objects of class "bcea", as created by the BCEA package, are in this "cost-effectiveness analysis" format, therefore they may be supplied as the outputs argument.

Users of heemod can create an object of this form, given an object produced by run_psa (obj, say), with import_heemod_outputs.

If outputs is a matrix or data frame, it is assumed to be of "net benefit" form. Otherwise if it is a list, it is assumed to be of "cost effectiveness analysis" form.

Matrix or data frame of samples from the uncertainty distribution of the input parameters of the decision model. The number of columns should equal the number of parameters, and the columns should be named. This should have the same number of rows as there are samples in outputs, and each row of the samples in outputs should give the model output evaluated at the corresponding parameters.

Users of heemod can create an object of this form, given an object produced by run_psa (obj, say), with import_heemod_inputs.

Either a character vector, or a list of character vectors.

If a character vector is supplied, then a single, joint EVPPI calculation is done with for the parameters named in this vector.

If a list of character vectors is supplied, then multiple EVPPI calculations are performed, one for each list component defined in the above vector form.

pars must be specified if inputs is a matrix or data frame. This should then correspond to particular columns of inputs. If inputs is a vector, this is assumed to define the single parameter of interest, and then pars is not required.

Character string indicating the calculation method. If one string is supplied, this is used for all calculations. A vector of different strings can be supplied if a different method is desired for different list components of pars.

The default methods are based on nonparametric regression:

"gam" for a generalized additive model implemented in the gam function from the mgcv package. This is the default method for calculating the EVPPI of 4 or fewer parameters.

"gp" for a Gaussian process regression, as described by Strong et al. (2014) and implemented in the SAVI package (https://github.com/Sheffield-Accelerated-VoI/SAVI). This is the default method for calculating the EVPPI of more than 4 parameters.

"inla" for an INLA/SPDE Gaussian process regression method, from Heath et al. (2016).

"bart" for Bayesian additive regression trees, using the dbarts package. Particularly suited for joint EVPPI of many parameters.

"earth" for a multivariate adaptive regression spline with the earth package (Milborrow, 2019).

"so" for the method of Strong and Oakley (2013). Only supported for single parameter EVPPI.

"sal" for the method of Sadatsafavi et al. (2013). Only supported for single parameter EVPPI.

If this is TRUE, calculate a standard error for the EVPPI if possible. Currently only supported for methods "gam", "earth" and method="bart". (In the latter method it is more correctly called a posterior standard deviation). These represent uncertainty about the parameters of the fitted regression model, and will naturally be lower when more simulations from the decision model are used to fit it. They do not represent uncertainty about the structure of the regression model, and are also typically small in the context of uncertainties arising from converting individual-level to population VoI.

Number of parameter replicates for calculating the standard error. Only applicable to method="gam". For method="bart" the analogous quantity is the number of MCMC samples, which is controlled by the ndpost argument to bart, which can be passed as an argument to evppi.

Number of simulations from the decision model to use for calculating EVPPI. The first nsim rows of the objects in inputs and outputs are used.

If TRUE, then messages are printed describing each step of the calculation, if the method supplies these. Can be useful to see the progress of slow calculations.

If TRUE, then extra information about the estimation is saved inside the object that this function returns. This currently only applies to the regression-based methods "gam" and "earth" where the fitted regression model objects are saved. This allows use of the check_regression function, which produces some diagnostic checks of the regression models.

Other arguments to control specific methods.

For method="gam", the following arguments can be supplied:

• gam_formula: a character string giving the right hand side of the formula supplied to the gam() function. By default, this is a tensor product of all the parameters of interest, e.g. if pars = c("pi","rho"), then gam_formula defaults to t(pi, rho, bs="cr"). The option bs="cr" indicates a cubic spline regression basis, which is more computationally efficient than the default "thin plate" basis. If there are four or more parameters of interest, then the additional argument k=4 is supplied to te(), specifying a four-dimensional basis, which is currently the default in the SAVI package.

  If there are spaces in the variable names in inputs, then these should be converted to underscores before forming an explicit gam_formula.

For method="gp", the following arguments can be supplied:

• gp_hyper_n: number of samples to use to estimate the hyperparameters in the Gaussian process regression method. By default, this is the minimum of the following three quantities: 30 times the number of parameters of interest, 250, and the number of simulations being used for calculating EVPPI.

• maxSample: Maximum sample size to employ for method="gp". Only increase this from the default 5000 if your computer has sufficent memory to invert square matrices with this dimension.

For method="inla", the following arguments can be supplied, as described in detail in Baio, Berardi and Heath (2017):

• int.ord (integer) maximum order of interaction terms to include in the regression predictor, e.g. if int.ord=k then all k-way interactions are used. Currently this applies to both effects and costs.

• cutoff (default 0.3) controls the density of the points inside the mesh in the spatial part of the mode. Acceptable values are typically in the interval (0.1,0.5), with lower values implying more points (and thus better approximation and greatercomputational time).

• convex.inner (default = -0.4) and convex.outer (default = -0.7) control the boundaries for the mesh. These should be negative values and can be decreased (say to -0.7 and -1, respectively) to increase the distance between the points and the outer boundary, which also increases precision and computational time.

• robust. if TRUE then INLA will use a t prior distribution for the coefficients of the linear predictor, rather than the default normal distribution.

• h.value (default=0.00005) controls the accuracy of the INLA grid-search for the estimation of the hyperparameters. Lower values imply a more refined search (and hence better accuracy), at the expense of computational speed.

• plot_inla_mesh (default FALSE) Produce a plot of the mesh.

• max.edge Largest allowed triangle edge length when constructing the mesh, passed to inla.mesh.2d.

• pfc_struc Variance structure to pass to pfc in the ldr package for principal fitted components. The default "AIC" selects the one that fits best given two basis terms. Change this to, e.g. "iso", "aniso" or "unstr" if an "Error in eigen..." is obtained.

For any of the nonparametric regression methods:

• ref The reference decision option used to define the incremental net benefit, cost or effects before performing nonparametric regression. Either an integer column number, or the name of the column from outputs.

For method="so":

• n.blocks Number of blocks to split the sample into. Required.

For method="sal":

• n.seps Number of separators (default 1).

A function to evaluate a decision-analytic model at a given set of parameters. This should have one argument per parameter, and return either:

(net benefit format) a vector giving the net benefit for each decision option, or

(cost-effectiveness analysis format) a matrix or data frame with two rows, and one column for each decision option. If the rows have names "e" and "c" then these are assumed to be the effects and costs respectively.

Otherwise, the first row is assumed to be the effects, and the second the costs.

A function to generate a random sample of values for the parameters of model_fn. This should return a matrix or a data frame with named columns matching the arguments of model_fn.

If any required arguments to model_fn are not supplied in this return value, then evppi_mc looks for them in the list supplied as the mfargs argument.

If any required arguments are not found in the results of par_fn or mfargs, and if model_fn defines default values for those arguments, then those default values are used.

The first argument of par_fn should be an integer n denoting the number of random values to draw for each parameter. The object returned by par_fn should then have n rows, and one column for each parameter. If one value is drawn, then par_fn is also allowed to return a vector, but this should still be named.

The parameters may be correlated. If we wish to compute the EVPPI for a parameter which is correlated with a different parameter q, then par_fn must have an argument with the name of that parameter. If that argument is set to a fixed value, then par_fn should return a sample drawn conditionally on that value. If that argument is not supplied, then par_fn must return a sample drawn from the marginal distribution. See the vignette for an example.

A character vector giving the parameters of interest, for which the EVPPI is required. This should correspond to an explicit argument to model_fn.

The parameters of interest are assumed to have uncertainty distributions that are independent of those of the other parameters.

Number of outer samples

Number of inner samples

Vector of willingness-to-pay values. Only used if model_fn is in cost-effectiveness analyis format.

Named list of additional arguments to supply to model_fn.

Set to TRUE to print some additional messages to help with debugging.

a vector of values for the quantity of interest, sampled from the uncertainty distribution of this quantity that is induced by the uncertainty about the parameters. This can also be a data frame with one column.

Typically this will come from a Monte Carlo sample, where we first sample from the uncertainty distributions of the parameters, and then compute the quantity of interest as a function of the parameters. It might also be produced by a Markov Chain Monte Carlo sample from the joint distribution of parameters and outputs.

Matrix or data frame of samples from the uncertainty distribution of the input parameters of the decision model. The number of columns should equal the number of parameters, and the columns should be named. This should have the same number of rows as there are samples in outputs, and each row of the samples in outputs should give the model output evaluated at the corresponding parameters.

Users of heemod can create an object of this form, given an object produced by run_psa (obj, say), with import_heemod_inputs.

Either a character vector, or a list of character vectors.

If a character vector is supplied, then a single, joint EVPPI calculation is done with for the parameters named in this vector.

If a list of character vectors is supplied, then multiple EVPPI calculations are performed, one for each list component defined in the above vector form.

pars must be specified if inputs is a matrix or data frame. This should then correspond to particular columns of inputs. If inputs is a vector, this is assumed to define the single parameter of interest, and then pars is not required.

Character string indicating the calculation method. If one string is supplied, this is used for all calculations. A vector of different strings can be supplied if a different method is desired for different list components of pars.

The default methods are based on nonparametric regression:

"gam" for a generalized additive model implemented in the gam function from the mgcv package. This is the default method for calculating the EVPPI of 4 or fewer parameters.

"gp" for a Gaussian process regression, as described by Strong et al. (2014) and implemented in the SAVI package (https://github.com/Sheffield-Accelerated-VoI/SAVI). This is the default method for calculating the EVPPI of more than 4 parameters.

"inla" for an INLA/SPDE Gaussian process regression method, from Heath et al. (2016).

"bart" for Bayesian additive regression trees, using the dbarts package. Particularly suited for joint EVPPI of many parameters.

"earth" for a multivariate adaptive regression spline with the earth package (Milborrow, 2019).

"so" for the method of Strong and Oakley (2013). Only supported for single parameter EVPPI.

"sal" for the method of Sadatsafavi et al. (2013). Only supported for single parameter EVPPI.

Number of simulations from the decision model to use for calculating EVPPI. The first nsim rows of the objects in inputs and outputs are used.

If TRUE, then messages are printed describing each step of the calculation, if the method supplies these. Can be useful to see the progress of slow calculations.

Other arguments to control specific methods.

For method="gam", the following arguments can be supplied:

• gam_formula: a character string giving the right hand side of the formula supplied to the gam() function. By default, this is a tensor product of all the parameters of interest, e.g. if pars = c("pi","rho"), then gam_formula defaults to t(pi, rho, bs="cr"). The option bs="cr" indicates a cubic spline regression basis, which is more computationally efficient than the default "thin plate" basis. If there are four or more parameters of interest, then the additional argument k=4 is supplied to te(), specifying a four-dimensional basis, which is currently the default in the SAVI package.

  If there are spaces in the variable names in inputs, then these should be converted to underscores before forming an explicit gam_formula.

For method="gp", the following arguments can be supplied:

• gp_hyper_n: number of samples to use to estimate the hyperparameters in the Gaussian process regression method. By default, this is the minimum of the following three quantities: 30 times the number of parameters of interest, 250, and the number of simulations being used for calculating EVPPI.

• maxSample: Maximum sample size to employ for method="gp". Only increase this from the default 5000 if your computer has sufficent memory to invert square matrices with this dimension.

For method="inla", the following arguments can be supplied, as described in detail in Baio, Berardi and Heath (2017):

• int.ord (integer) maximum order of interaction terms to include in the regression predictor, e.g. if int.ord=k then all k-way interactions are used. Currently this applies to both effects and costs.

• cutoff (default 0.3) controls the density of the points inside the mesh in the spatial part of the mode. Acceptable values are typically in the interval (0.1,0.5), with lower values implying more points (and thus better approximation and greatercomputational time).

• convex.inner (default = -0.4) and convex.outer (default = -0.7) control the boundaries for the mesh. These should be negative values and can be decreased (say to -0.7 and -1, respectively) to increase the distance between the points and the outer boundary, which also increases precision and computational time.

• robust. if TRUE then INLA will use a t prior distribution for the coefficients of the linear predictor, rather than the default normal distribution.

• h.value (default=0.00005) controls the accuracy of the INLA grid-search for the estimation of the hyperparameters. Lower values imply a more refined search (and hence better accuracy), at the expense of computational speed.

• plot_inla_mesh (default FALSE) Produce a plot of the mesh.

• max.edge Largest allowed triangle edge length when constructing the mesh, passed to inla.mesh.2d.

• pfc_struc Variance structure to pass to pfc in the ldr package for principal fitted components. The default "AIC" selects the one that fits best given two basis terms. Change this to, e.g. "iso", "aniso" or "unstr" if an "Error in eigen..." is obtained.

For any of the nonparametric regression methods:

• ref The reference decision option used to define the incremental net benefit, cost or effects before performing nonparametric regression. Either an integer column number, or the name of the column from outputs.

For method="so":

• n.blocks Number of blocks to split the sample into. Required.

For method="sal":

• n.seps Number of separators (default 1).

This could take one of two forms

"net benefit" form: a matrix or data frame of samples from the uncertainty distribution of the expected net benefit. The number of rows should equal the number of samples, and the number of columns should equal the number of decision options.

"cost-effectiveness analysis" form: a list with the following named components:

"c": a matrix or data frame of samples from the distribution of costs. There should be one column for each decision option.

"e": a matrix or data frame of samples from the distribution of effects, likewise.

"k": a vector of willingness-to-pay values.

Objects of class "bcea", as created by the BCEA package, are in this "cost-effectiveness analysis" format, therefore they may be supplied as the outputs argument.

Users of heemod can create an object of this form, given an object produced by run_psa (obj, say), with import_heemod_outputs.

If outputs is a matrix or data frame, it is assumed to be of "net benefit" form. Otherwise if it is a list, it is assumed to be of "cost effectiveness analysis" form.

Matrix or data frame of samples from the uncertainty distribution of the input parameters of the decision model. The number of columns should equal the number of parameters, and the columns should be named. This should have the same number of rows as there are samples in outputs, and each row of the samples in outputs should give the model output evaluated at the corresponding parameters.

Users of heemod can create an object of this form, given an object produced by run_psa (obj, say), with import_heemod_inputs.

Name of one of the built-in study types supported by this package for EVSI calculation. If this is supplied, then the columns of inputs that correspond to the parameters governing the study data should be identified in pars.

Current built-in studies are

"binary" A study with a binary outcome observed on one sample of individuals. Requires one parameter: the probability of the outcome. The sample size is specifed in the n argument to evsi(), and the binomially-distributed outcome is named X1.

"trial_binary" Two-arm trial with a binary outcome. Requires two parameters: the probability of the outcome in arm 1 and 2 respectively. The sample size is the same in each arm, specifed in the n argument to evsi(), and the binomial outcomes are named X1 and X2 respectively.

"normal_known" A study of a normally-distributed outcome, with a known standard deviation, on one sample of individuals. Likewise the sample size is specified in the n argument to evsi(). The standard deviation defaults to 1, and can be changed by specifying sd as a component of the aux_pars argument, e.g. evsi(..., aux_pars=list(sd=2)).

Either study or datagen_fn should be supplied to evsi().

For the EVSI calculation methods where explicit Bayesian analyses of the simulated data are performed, the prior parameters for these built-in studies are supplied in the analysis_args argument to evsi(). These assume Beta priors for probabilities, and Normal priors for the mean of a normal outcome.

If the proposed study is not one of the built-in types supported, it can be specified in this argument as an R function to sample predicted data from the study. This function should have the following specification:

1. the function's first argument should be a data frame of parameter simulations, with one row per simulation and one column per parameter. The parameters in this data frame must all be found in inputs, but need not necessarily be in the same order or include all of them.

2. the function should return a data frame.

3. the returned data frame should have number of rows equal to the number of parameter simulations in inputs.

4. if inputs is considered as a sample from the posterior, then datagen_fn(inputs) returns a corresponding sample from the posterior predictive distribution, which includes two sources of uncertainty: (a) uncertainty about the parameters and (b) sampling variation in observed data given fixed parameter values.

5. the function can optionally have more than one argument. If so, these additional arguments should be given default values in the definition of datagen_fn. If there is an argument called n, then it is interpreted as the sample size for the proposed study.

Character vector identifying which parameters are learned from the proposed study. This is required for the moment matching and importance sampling methods, and these should be columns of inputs. This is not required for the nonparametric regression methods.

Character vector identifying which columns of inputs are the parameters required to generate data from the proposed study. These should be columns of inputs.

If pars_datagen is not supplied, then it is assumed to be the same as pars. Note that these can be different. Even if the study data are generated by a particular parameter, when analysing the data we could choose to ignore the information that the data provides about that parameter.

Sample size of future study, or vector of alternative sample sizes. This is understood by the built-in study designs. For studies specified by the user with datagen_fn, if datagen_fn has an argument n, then this is interpreted as the sample size. However if calling evsi for a user-specified design where datagen_fn does not have an n argument, then any n argument supplied to evsi will be ignored.

Currently this shortcut is not supported if more than one quantity is required to describe the sample size, for example, trials with unbalanced arms. In that case, you will have to hard-code the required sample sizes into datagen_fn.

For the nonparametric regression and importance sampling methods, the computation is simply repeated for each sample size supplied here.

The moment matching method uses a regression model to estimate the dependency of the EVSI on the sample size, hence to enable EVSI to be calculated efficiently for any number of sample sizes (Heath et al. 2019).

A list of additional fixed arguments to supply to the function to generate the data, whether that is a built-in study design or user-defined function supplied in datagen_fn. For example, evsi(..., aux_pars = list(sd=2)) defines the fixed standard deviation in the "normal_known" model.

Character string indicating the calculation method. Defaults to "gam".

All the nonparametric regression methods supported for evppi, that is "gam","gp","earth","inla", can also be used for EVSI calculation by regressing on a summary statistic of the predicted data (Strong et al 2015).

"is" for importance sampling (Menzies 2016)

"mm" for moment matching (Heath et al 2018)

Note that the "is" and "mm" methods are used in conjunction with nonparametric regression, and the gam_formula argument can be supplied to evsi to specify this regression - see evppi for documentation of this argument.

Likelihood function, required (and only required) for the importance sampling method when a study design other than one of the built-in ones is used. This should have two arguments, named as follows:

Y: a one-row data frame of predicted data. Columns are defined by different outcomes in the data, with names matching the names of the data frame returned by datagen_fn.

inputs. a data frame of simulated parameter values. Columns should correspond to different variables in inputs. The column names should all be found in the names of inputs, though they do not have to be in the same order, or include everything in inputs. The number or rows should be the same as the number of rows in inputs.

The function should return a vector whose length matches the number of rows of the parameters data frame given as the second argument. Each element of the vector gives the likelihood of the corresponding set of parameters, given the data in the first argument. An example is given in the vignette.

The likelihood can optionally have a n argument, which is interpreted as the sample size of the study. If the n argument to evsi is used then this is passed to the likelihood function. Conversely any n argument to evsi will be ignored by a likelihood function that does not have its own n argument.

Note the definition of the likelihood should agree with the definition of datagen_fn to define a consistent sampling distribution for the data. No automatic check is performed for this.

Function which fits a Bayesian model to the generated data. Required for method="mm" if a study design other than one of the built-in ones is used. This should be a function that takes the following arguments:

data: A data frame with names matching the output of datagen_fn

args: A list with constants required in the Bayesian analysis, e.g. prior parameters, or options for the analysis, e.g. number of MCMC simulations. The component of this list called n is assumed to contain the sample size of the study.

pars Names of the parameters whose posterior is being sampled.

The function should return a data frame with names matching pars, containing a sample from the posterior distribution of the parameters given data supplied through data.

analysis_fn is required to have all three of these arguments, but you do not need to use any elements of args or pars in the body of analysis_fn. Instead, sample sizes, prior parameters, MCMC options and parameter names can alternatively be hard-coded inside analysis_fn. Passing these through the function arguments (via the analysis_args argument to evsi) is only necessary if we want to use the same analysis_fn to do EVSI calculations with different sample sizes or other settings.

List of arguments required for the Bayesian analysis of the predicted data, e.g. definitions of the prior and options to control sampling. Only used in method="mm". This is required if the study design is one of the built-in ones specified in study. If a custom design is specifed through analysis_fn, then any constants needed in analysis_fn can either be supplied in analysis_args, or hard-coded in analysis_fn itself.

For the built-in designs, the lists should have the following named components. An optional component niter in each case defines the posterior sample size (default 1000).

study="binary": a and b: Beta shape parameters

study="trial_binary": a1 and b1: Beta shape parameters for the prior for the first arm, a2 and b2: Beta shape parameters for the prior for the second arm.

study="normal_known": prior_mean, prior_sd (mean and standard deviation deviation of the Normal prior) and sampling_sd (SD of an individual-level normal observation, so that the sampling SD of the mean outcome over the study is sampling_sd/sqrt(n).

Function which evaluates the decision-analytic model, given parameter values. Required for method="mm". See evppi_mc for full documentation of the required specification of this function.

Function to simulate values from the uncertainty distributions of parameters needed by the decision-analytic model. Should take one argument and return a data frame with one row for each simulated value, and one column for each parameter. See evppi_mc for full specification.

Number of quantiles to use in method="mm".

Method to use to calculate the EVPPI, for those methods that require it. This is passed to evppi as the method argument.

Number of simulations from the model to use for calculating EVPPI. The first nsim rows of the objects in inputs and outputs are used.

If TRUE, then messages are printed describing each step of the calculation, if the method supplies these. Can be useful to see the progress of slow calculations.

If TRUE, then extra information about the estimation is saved inside the object that this function returns. This currently only applies to the regression-based methods "gam" and "earth" where the fitted regression model objects are saved. This allows use of the check_regression function, which produces some diagnostic checks of the regression models.

Other arguments understood by specific methods, e.g. gam_formula and other controlling options (see evppi) can be passed to the nonparametric regression used inside the moment matching method.

a vector of values for the quantity of interest, sampled from the uncertainty distribution of this quantity that is induced by the uncertainty about the parameters.

Matrix or data frame of samples from the uncertainty distribution of the input parameters of the decision model. The number of columns should equal the number of parameters, and the columns should be named. This should have the same number of rows as there are samples in outputs, and each row of the samples in outputs should give the model output evaluated at the corresponding parameters.

Users of heemod can create an object of this form, given an object produced by run_psa (obj, say), with import_heemod_inputs.

Name of one of the built-in study types supported by this package for EVSI calculation. If this is supplied, then the columns of inputs that correspond to the parameters governing the study data should be identified in pars.

Current built-in studies are

"binary" A study with a binary outcome observed on one sample of individuals. Requires one parameter: the probability of the outcome. The sample size is specifed in the n argument to evsi(), and the binomially-distributed outcome is named X1.

"trial_binary" Two-arm trial with a binary outcome. Requires two parameters: the probability of the outcome in arm 1 and 2 respectively. The sample size is the same in each arm, specifed in the n argument to evsi(), and the binomial outcomes are named X1 and X2 respectively.

"normal_known" A study of a normally-distributed outcome, with a known standard deviation, on one sample of individuals. Likewise the sample size is specified in the n argument to evsi(). The standard deviation defaults to 1, and can be changed by specifying sd as a component of the aux_pars argument, e.g. evsi(..., aux_pars=list(sd=2)).

Either study or datagen_fn should be supplied to evsi().

For the EVSI calculation methods where explicit Bayesian analyses of the simulated data are performed, the prior parameters for these built-in studies are supplied in the analysis_args argument to evsi(). These assume Beta priors for probabilities, and Normal priors for the mean of a normal outcome.

If the proposed study is not one of the built-in types supported, it can be specified in this argument as an R function to sample predicted data from the study. This function should have the following specification:

1. the function's first argument should be a data frame of parameter simulations, with one row per simulation and one column per parameter. The parameters in this data frame must all be found in inputs, but need not necessarily be in the same order or include all of them.

2. the function should return a data frame.

3. the returned data frame should have number of rows equal to the number of parameter simulations in inputs.

4. if inputs is considered as a sample from the posterior, then datagen_fn(inputs) returns a corresponding sample from the posterior predictive distribution, which includes two sources of uncertainty: (a) uncertainty about the parameters and (b) sampling variation in observed data given fixed parameter values.

5. the function can optionally have more than one argument. If so, these additional arguments should be given default values in the definition of datagen_fn. If there is an argument called n, then it is interpreted as the sample size for the proposed study.

Character vector identifying which parameters are learned from the proposed study. This is required for the moment matching and importance sampling methods, and these should be columns of inputs. This is not required for the nonparametric regression methods.

Sample size of future study, or vector of alternative sample sizes. This is understood by the built-in study designs. For studies specified by the user with datagen_fn, if datagen_fn has an argument n, then this is interpreted as the sample size. However if calling evsi for a user-specified design where datagen_fn does not have an n argument, then any n argument supplied to evsi will be ignored.

Currently this shortcut is not supported if more than one quantity is required to describe the sample size, for example, trials with unbalanced arms. In that case, you will have to hard-code the required sample sizes into datagen_fn.

For the nonparametric regression and importance sampling methods, the computation is simply repeated for each sample size supplied here.

The moment matching method uses a regression model to estimate the dependency of the EVSI on the sample size, hence to enable EVSI to be calculated efficiently for any number of sample sizes (Heath et al. 2019).

A list of additional fixed arguments to supply to the function to generate the data, whether that is a built-in study design or user-defined function supplied in datagen_fn. For example, evsi(..., aux_pars = list(sd=2)) defines the fixed standard deviation in the "normal_known" model.

See evsi, only nonparametric regression methods are currently supported in evsivar.

Number of simulations from the model to use for calculating EVPPI. The first nsim rows of the objects in inputs and outputs are used.

If TRUE, then messages are printed describing each step of the calculation, if the method supplies these. Can be useful to see the progress of slow calculations.

Other arguments understood by specific methods, e.g. gam_formula and other controlling options (see evppi) can be passed to the nonparametric regression used inside the moment matching method.

Object returned by the run_psa function in heemod, containing samples from probabilistic analysis of a decision model.

Vector of willingness-to-pay values. The default is inherited from the bcea function from the BCEA package.

Object returned from evppi.

"dots" for a dot plot of the EVPPI by parameter. If x includes multiple willingness-to-pay values for the same parameter, these are shown as multiple dots.

"curves" for a plot of EVPPI against willingness-to-pay, with different parameters distinguished as different curves. This is only applicable if there are multiple willingness-to-pay values included in x.

For dot plots, order the plot with highest EVPPI values at the top.

A positive integer. If specified, for example as top=5 then only five parameters are included in the plot, those with the top five maximum EVPPI values by parameter.

Other arguments (currently unused).

Vector of estimates of any per-person value of information measure, e.g. the evsi column of the data frame returned by evsi or the correspondingly-named columns of the data frames returned by evppi or evpi.

Size of the population who would be affected by the decision.

Time horizon over which discounting will be applied.

Discount rate used when converting per-person to population EVSI.