Summarize the results of a Monte Carlo Simulation run by future_mc() with
(optionally) user-defined summary functions.
Usage
# S3 method for mc
summary(object, sum_funs = NULL, which_path = "all", ...)Arguments
- object
An object of class
mc, for which holdssimple_output = TRUE. See value offuture_mc().- sum_funs
A named (nested) list containing summary functions. See details.
- which_path
A character vector containing the names of (some of) the named outputs (the names of the returned list of
funinfuture_mc()), for which to return a "path" of the stepwise calculation of the result of the summary function. Alternatively,"all"or"none"can be used to return either the path for all or none of the numeric outputs. Default:"all".- ...
Ignored
Value
A list of type summary.mc containing the
result of the summary functions of the simulation
results of a respective output and parameter combination.
If the provided summary functions return a single numeric value,
the path of the summarized output
(which are contained in which_path)
over all simulation repetitions is also returned.
Details
In order to use summary(),
the output of future_mc() has to be "simple",
which is the case if the return value of fun is a named list of scalars.
If the
returned value of fun is a named list of more complex data structures,
summary()
cannot be used.
With sum_funs the user can define (different) functions which summarize
the simulation results for each output
(return values of fun in future_mc())
and each parameter combination.
Thus, the functions inside sum_funs only take one argument,
which is the output vector (with length repetitions) of one output
of one specific parameter combination.
The default summary functions are base::mean() for numeric outputs and
base::summary() for outputs with non-numeric data types.
The user can define summary functions by supplying a named
(nested) list to sum_funs. When
the functions provided for each output return only one numeric value
the results are twofold:
first, a single scalar result of the
function evaluating the whole output vector.
Second, a "path" with length repetitions of the
stepwise calculation of the function's result
across the output vector
(assumed that the output is contained in which_path).
If the user wants to summarize the simulation results of a respective output
in the same way
for each parameter combination, a list whose components are named after the
outputs (the names of the returned
list of fun in future_mc()) is supplied and each component is
a function which only takes the vector of results
of one output as the main argument.
If the user wants to summarize the simulation
results of a respective output differently for
different parameter combinations, a nested list has to be supplied.
The components of the outer list
must be equal in length and naming to the nice_names of the parameter
combinations (see value of future_mc()) and each component is another
list (inner list). The components of the inner list are then defined the
same way as above
(components named after the outputs and each component is a function).
The provided summary functions are not restricted regarding the complexity
of their return value.
However, the path of the summarized output over all simulation repetitions
is only returned if the
provided summary functions return a single numeric value
(and the output is contained in which_path).
Thus, plot.summary.mc() will only work in this specific case.
Examples
test_func <- function(param = 0.1, n = 100, x1 = 1, x2 = 2){
data <- rnorm(n, mean = param) + x1 + x2
stat <- mean(data)
stat_2 <- var(data)
if (x2 == 5){
stop("x2 can't be 5!")
}
return(list(mean = stat, var = stat_2))
}
param_list <- list(param = seq(from = 0, to = 1, by = 0.5),
x1 = 1:2)
set.seed(101)
test_mc <- future_mc(
fun = test_func,
repetitions = 1000,
param_list = param_list,
n = 10,
x2 = 2
)
#> Running single test-iteration for each parameter combination...
#>
#> Test-run successfull: No errors occurred!
#> Running whole simulation: Overall 6 parameter combinations are simulated ...
#>
#> Simulation was successfull!
#> Running time: 00:00:00.974604
summary(test_mc)
#> Results for the output mean:
#> param=0, x1=1: 3.015575
#> param=0, x1=2: 4.003162
#> param=0.5, x1=1: 3.49393
#> param=0.5, x1=2: 4.480855
#> param=1, x1=1: 3.985815
#> param=1, x1=2: 4.994084
#>
#>
#> Results for the output var:
#> param=0, x1=1: 0.9968712
#> param=0, x1=2: 1.026523
#> param=0.5, x1=1: 0.9933278
#> param=0.5, x1=2: 0.9997529
#> param=1, x1=1: 0.9979682
#> param=1, x1=2: 1.005633
#>
#>
summary(test_mc, sum_funs = list(mean = mean, var = sd))
#> Results for the output mean:
#> param=0, x1=1: 3.015575
#> param=0, x1=2: 4.003162
#> param=0.5, x1=1: 3.49393
#> param=0.5, x1=2: 4.480855
#> param=1, x1=1: 3.985815
#> param=1, x1=2: 4.994084
#>
#>
#> Results for the output var:
#> param=0, x1=1: 0.4804107
#> param=0, x1=2: 0.4727596
#> param=0.5, x1=1: 0.456396
#> param=0.5, x1=2: 0.4759277
#> param=1, x1=1: 0.4799977
#> param=1, x1=2: 0.4821494
#>
#>
sum_funcs <- list(
list(
mean = mean, var = sd
),
list(
mean = mean, var = summary
),
list(
mean = max, var = min
),
list(
mean = mean, var = sd
),
list(
mean = mean, var = summary
),
list(
mean = max, var = min
)
)
names(sum_funcs) <- test_mc$nice_names
summary(test_mc, sum_funs = sum_funcs)
#> Results for the output mean:
#> param=0, x1=1: 3.015575
#> param=0, x1=2: 4.003162
#> param=0.5, x1=1: 4.517579
#> param=0.5, x1=2: 4.480855
#> param=1, x1=1: 3.985815
#> param=1, x1=2: 6.275247
#>
#>
#> Results for the output var:
#> param=0, x1=1: 0.4804107
#> param=0, x1=2:
#> Min. 1st Qu. Median Mean 3rd Qu. Max.
#> 0.1363 0.6783 0.9458 1.0265 1.2878 2.6312
#>
#> param=0.5, x1=1: 0.1521897
#> param=0.5, x1=2: 0.4759277
#> param=1, x1=1:
#> Min. 1st Qu. Median Mean 3rd Qu. Max.
#> 0.08217 0.64574 0.91530 0.99797 1.25562 3.45382
#>
#> param=1, x1=2: 0.1308038
#>
#>