# mcSimulation: Perform a Monte Carlo simulation. In decisionSupport: Quantitative Support of Decision Making under Uncertainty

## Description

This function generates a random sample of an output distribution defined as the transformation of an input distribution by a mathematical model, i.e. a mathematical function. This is called a Monte Carlo simulation. For details cf. below.

## Usage

 ```1 2 3``` ```mcSimulation(estimate, model_function, ..., numberOfModelRuns, randomMethod = "calculate", functionSyntax = "data.frameNames", relativeTolerance = 0.05, verbosity = 0) ```

## Arguments

 `estimate` `estimate`: estimate of the joint probability distribution of the input variables. `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 running the model function. `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

This method solves the following problem. Given a multivariate random variable x = (x_1,…,x_k) with joint probability distribution P, i.e.

x ~ P

Then the continuous function

f:R^k --> R^l, y = f(x)

defines another random variable with distribution

y ~ f(P).

Given a probability density ρ of x that defines P the problem is the determination of the probability density φ that defines f(P). This method samples the probability density φ of y as follows: The input distribution P is provided as `estimate`. From `estimate` a sample `x` with `numberOfModelRuns` is generated using `random.estimate`. Then the function values y=f(x) are calculated, where f is `model_function`.

`functionSyntax` defines the syntax of `model_function`, which has to be used, as follows:

`"data.frameNames"`

The model function is constructed, e.g. like this:

```         profit<-function(x){
x[["revenue"]]-x[["costs"]]
}
```

or like this:

```         profit<-function(x){
x\$revenue-x\$costs
}
```
`"matrixNames"`

The model function is constructed, e.g. like this:

```           profit<-function(x){
x[,"revenue"]-x[,"costs"]
}
```
`"plainNames"`

`model_function` is constructed, e.g. like this:

```         profit<-function(x){
revenue-costs
}
```

Note: this is the slowest of the possibilities for `functionSyntax`.

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

`\$y`

`data.frame` containing the simulated y - (output) values, i.e. the model function values for `x`.

`print.mcSimulation`, `summary.mcSimulation`, `hist.mcSimulation`, `estimate`, `random.estimate`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79``` ``` ############################################################# # Example 1 (Creating the estimate from the command line): ############################################################# # Create the estimate object: variable=c("revenue","costs") distribution=c("norm","norm") lower=c(10000, 5000) upper=c(100000, 50000) costBenefitEstimate<-as.estimate(variable, distribution, lower, upper) # (a) Define the model function without name for the return value: profit1<-function(x){ x\$revenue-x\$costs } # Perform the Monte Carlo simulation: predictionProfit1<-mcSimulation( estimate=costBenefitEstimate, model_function=profit1, numberOfModelRuns=10000, functionSyntax="data.frameNames") # Show the simulation results: print(summary(predictionProfit1)) hist(predictionProfit1,xlab="Profit") ############################################################# # (b) Define the model function with a name for the return value: profit1<-function(x){ list(Profit=x\$revenue-x\$costs) } # Perform the Monte Carlo simulation: predictionProfit1<-mcSimulation( estimate=costBenefitEstimate, model_function=profit1, numberOfModelRuns=10000, functionSyntax="data.frameNames") # Show the simulation results: print(summary(predictionProfit1, classicView=TRUE)) hist(predictionProfit1) ######################################################### # (c) Using plain names in the model function syntax profit1<-function(){ list(Profit=revenue-costs) } # Perform the Monte Carlo simulation: predictionProfit1<-mcSimulation( estimate=costBenefitEstimate, model_function=profit1, numberOfModelRuns=1000, functionSyntax="plainNames") # Show the simulation results: print(summary(predictionProfit1, probs=c(0.05,0.50,0.95))) hist(predictionProfit1) ######################################################### # (d) Using plain names in the model function syntax and # define the model function without name for the return value: profit1<-function() revenue-costs # Perform the Monte Carlo simulation: predictionProfit1<-mcSimulation( estimate=costBenefitEstimate, model_function=profit1, numberOfModelRuns=1000, functionSyntax="plainNames") # Show the simulation results: print(summary(predictionProfit1, probs=c(0.05,0.50,0.95))) hist(predictionProfit1, xlab="Profit") ############################################################# # Example 2(Reading the estimate from file): ############################################################# # Define the model function: profit2<-function(x){ Profit<-x[["sales"]]*(x[["productprice"]] - x[["costprice"]]) list(Profit=Profit) } # Read the estimate of sales, productprice and costprice from file: inputFileName=system.file("extdata","profit-4.csv",package="decisionSupport") parameterEstimate<-estimate_read_csv(fileName=inputFileName) print(parameterEstimate) # Perform the Monte Carlo simulation: predictionProfit2<-mcSimulation( estimate=parameterEstimate, model_function=profit2, numberOfModelRuns=10000, functionSyntax="data.frameNames") # Show the simulation results: print(summary(predictionProfit2)) hist(predictionProfit2) ```