| summary.mc {tidyMC} | R Documentation |
Summarize the Results of a Monte Carlo Simulation
Description
Summarize the results of a Monte Carlo Simulation run by future_mc() with
(optionally) user-defined summary functions.
Usage
## S3 method for class 'mc'
summary(object, sum_funs = NULL, which_path = "all", ...)
Arguments
object |
An object of class |
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 |
... |
Ignored |
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.
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.
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
)
summary(test_mc)
summary(test_mc, sum_funs = list(mean = mean, var = sd))
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)