Calculate the expected value of sample information from a decision-analytic model

Calculate the expected value of sample information from a decision-analytic model

evsi.remote(
  outputs,
  inputs,
  study = NULL,
  datagen_fn = NULL,
  pars = NULL,
  n = 100,
  aux_pars = NULL,
  method = NULL,
  likelihood = NULL,
  analysis_model = NULL,
  analysis_options = NULL,
  decision_model = NULL,
  Q = 30,
  npreg_method = "gam",
  nsim = NULL,
  verbose = FALSE,
  ...
)

Arguments

outputs	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.
inputs	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.
study	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 poi. Currently supported 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().
datagen_fn	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: 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. the function should return a data frame. the returned data frame should have number of rows equal to the number of parameter simulations in inputs. 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. 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. These arguments might be used to define sample sizes for a proposed study.
pars	Character vector identifying which columns of inputs are the parameters required to generate data from the proposed study. Required if the proposed study is specified through the study argument, but not if it is specified through the datagen_fn argument. For example, if study = "trial_binary" is specified, then pars should be a vector of two elements naming the probability of the outcome in arm 1 and arm 2 respectively. The pars argument is also required for the methods which involve an intermediate EVPPI calculation, that is the "is" and "mm". It should consist of the variables used in the definition of datagen_fn (and likelihood if used TODO ALSO in analysis_model and model?) and only these variables.
n	Sample size of future study - optional argument to datagen_fn - facilitates calculating EVSI for multiple sample sizes. TODO if we want to design trials with multiple unbalanced arms, we'll need more than one argument.
aux_pars	A list of additional fixed arguments to supply to the function to generate the data, whether that is a built-in or user-defined function, e.g. evsi(..., aux_pars = list(sd=2)) to change the fixed standard deviation in the "normal_known" model.
method	haracter string indicating the calculation method. The default methods are based on nonparametric regression.
likelihood	Likelihood function, required (and only required) for the importance sampling method. This should have two arguments as follows: a data frame of predicted data. Columns are defined by the number of outcomes in the data, and names matching the data frame returned by datagen_fn. a data frame of parameter values, whose names should all correspond to variables 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. Examples of this are currently in tests/tests_slow and tests/testthat in the package directory. Note the definition of the likelihood should agree with the definition of datagen_fn to define a consistent sampling distribution for the data.
analysis_model	Function which fits a Bayesian model to the generated data. Under development (need to decide format, output, JAGS dependencies, etc.). Required for method="mm" (and Jalal method if n0 not given)
analysis_options	List of arguments required by analysis_model. Under development - for method="mm" and Jalal method.
decision_model	Function which evaluates the decision-analytic model, given parameter values. Under development - for method="mm" and Jalal method. Need to decide the required format for nb, c, e output.
Q	Number of quantiles to use in method="mm" (under development).
npreg_method	Method to use to calculate the EVPPI, for those methods that require it. This is passed to evppi as the method argument.
nsim	Number of simulations from the model to use for calculating EVPPI. The first nsim rows of the objects in inputs and outputs are used.
verbose	Set to TRUE to print some additional messages to help with debugging.
...	Other arguments required by specific methods

Value

Examples

set.seed(1)
nsam <- 10000
inputs <- data.frame(
  p1 = rnorm(nsam, 1, 1),
  p2 = rnorm(nsam, 0, 2)
)
outputs_nb <- data.frame(
  t1 = 0,
  t2 = inputs$p1 - inputs$p2
)

datagen_normal <- function(inputs, n=100, sd=1){
data.frame(xbar = rnorm(n = nrow(inputs),
                       mean = inputs[,"p1"],
                       sd = sd / sqrt(n)))
}
evsi.remote(outputs_nb, inputs, datagen_fn = datagen_normal, n=c(10,100,1000))
#> Calling server at https://prism.peermodelsnetwork.com/route/voi/run
#> $n
#> [1]   10  100 1000
#> 
#> $evsi
#> [1] 0.0687 0.0807 0.0817
#>