scenario_mc {decisionSupport}

Perform a Monte Carlo simulation for predefined scenarios.

Description

This function is a wrapper around the mc_Simulation function that facilitates implementation of scenarios. The standard mc_Simulation function only allows specifying one set of estimates (i.e. distribution, lower and upper bounds) for each random variable. This is inconvenient when we want to run simulations for heterogeneous populations that include subsets with particular characteristics, e.g. small and large farms. It may then make sense to specify separate distributions for input variables for each of the subsets. The scenario_mc function facilitates this.

Usage

scenario_mc(
  base_estimate,
  scenarios,
  model_function,
  ...,
  numberOfModelRuns = NA,
  randomMethod = "calculate",
  functionSyntax = "data.frameNames",
  relativeTolerance = 0.05,
  verbosity = 0
)

Arguments

base_estimate

estimate: this object corresponds to the estimate object in mc_Simulation. The distributions that are specified through base_estimate are used as default distributions in the simulation, but their parameters can be overridden by information in the scenarios data.frame. In brief, this is an estimate of the joint probability distribution of the input variables. This can be read from a csv file and calculated with the estimate_read_csv function. It can also be generated with the as.estimate function.

scenarios

data.frame: Specifies values that should be adjusted in each scenario. Must contain columns Variable and param and one column for each scenario. The Variable column can only contain variable names that appear in base_estimate, as well as a Runs element. The param column can only contain the strings distribution, lower and upper, except for the row corresponding to Runs in the Variable column (for this the entry doesn't matter). For each scenario column (whose name is the scenario name), the scenario-specific values must be specified. If the value in the Runs row is NA, the numberOfModelRuns object will be used instead (if that's also NA, you get an error). param can also be "both", in which case both lower and upper bounds are set to the respective number, and the distribution is set to "const".

model_function

function: The function that transforms the input distribution. It has to return a single numeric value or a list with named numeric values.

...

Optional arguments of model_function.

numberOfModelRuns

The number of times to run the model function. This doesn't need to be provided when the scenarios data.frame contains a Runs line that specifies a particular number of runs for each scenario.

randomMethod

character: The method to be used to sample the distribution representing the input estimate. For details see option method in random.estimate.

functionSyntax

character: The syntax which has to be used to implement the model function. Possible values are "data.frameNames", "matrixNames" or "plainNames". Details are given below.

relativeTolerance

numeric: the relative tolerance level of deviation of the generated confidence interval from the specified interval. If this deviation is greater than relativeTolerance a warning is given.

verbosity

integer: if 0 the function is silent; the larger the value the more verbose is output information.

Details

See documentation of the mc_Simulation function.

Value

An object of class mcSimulation, which is a list with elements:

$x

data.frame containing the sampled x - (input) values which are generated from base_estimate and possibly modified by scenarios. To identify the scenario, the scenario name is provided in the scenario column.

$y

data.frame containing the simulated y - (output) values, i.e. the model function values for x.The return of the decision model function may include the assignment of names for the output variables, e.g. like this:

           profit <- function(x){
            revenue - costs
            return(list(Revenue = revenue,
                   Costs = cost))
         }
       

See Also

mcSimulation, print.mcSimulation, summary.mcSimulation, hist.mcSimulation, estimate, random.estimate

Examples

 
 ### define a model_function
 
 profit<-function(x)
 {profit<-benefit_1+benefit_2-cost_1-cost_2
   return(Profit=profit)}
   
 ### define a base_estimate, to be used when no other information is provided
 # through the scenario data.frame
   
 base_estimate<-as.estimate(variable=c("cost_1","cost_2","benefit_1","benefit_2"),
                              distribution=c("norm","posnorm","norm","posnorm"),
                              lower=c(40,10,50,30),
                              upper=c(100,200,300,100))
            
 ### define a scenario data.frame, which will override values in the base_estimate
                                     
 scenarios<-data.frame(Variable=c("Runs","cost_1","cost_1","cost_1","cost_2","cost_2",
                                  "benefit_1","benefit_1","benefit_2"),
                       param=c("x","lower","upper","distribution","lower","upper",
                               "lower","upper","lower"),
                       Scenario_1=c(100,40,70,"posnorm",30,90,20,35,10),
                       Scenario_2=c(50,100,200,"norm",10,40,35,75,5),
                       Scenario_3=c(10,400,750,"norm",400,600,30,70,60))
                       
 ### run a simulation
              
 results<-scenario_mc(base_estimate, scenarios, model_function=profit,
                      functionSyntax="plainNames")
                      
 ### plot and inspect results
 
 hist(results)
 summary(results)
 print(results)