R6 class to represent a manager for generating summary
metrics and/or matrices from simulation results, as well as optionally regenerating
values via generators.
Super classes
poems::GenericClass -> poems::GenericManager -> ResultsManager
Active bindings
sample_dataA data frame of sampled parameters for each simulation/result.
simulation_resultsAn object of a class inherited from the
SimulationResultsclass for encapsulating and dynamically generating simulation results.generatorsA list of generators (
Generatoror inherited class) objects for (optionally) regenerating simulation model values.result_attachment_functionsA list of functions for attaching intermediate values to the simulation results prior to generation.
summary_metricsAn array of names for summary metrics, each of which are calculated as single values for each simulation. These should refer to list names for the summary functions.
summary_matricesAn array of names for summary matrices, each of which are calculated as a single matrix row for each simulation. These should refer to list names for the summary functions.
summary_functionsA list of functions, result attributes, or constants for transforming individual simulation results to single summary metric values stored in the metric data frame, or to matrix rows stored in the summary matrix list.
summary_metric_dataA data frame of generated summary metrics (one row per simulation).
summary_matrix_listA list of generated matrices of summary results (each having one row per simulation).
summary_matrix_weighted_averagesA list of calculated weighted averages for each of the summary matrices (using the sample data weight column).
parallel_coresNumber of cores for running the simulations in parallel.
results_dirResults directory path.
results_extResult file extension (default is .RData).
results_filename_attributesA vector of: prefix (optional); attribute names (from the sample data frame); postfix (optional); utilized to construct results filenames.
error_messagesA vector of error messages encountered when setting model attributes.
warning_messagesA vector of warning messages encountered when setting model attributes.
Methods
Method new()
Initialization method optionally copies attributes from a simulation (results) manager, sets any included attributes (sample_data, simulation_results, generators, result_attachment_functions, summary_metrics, summary_functions, parallel_cores, results_dir, results_ext, results_filename_attributes), and attaches other attributes individually listed.
Usage
ResultsManager$new(simulation_manager = NULL, ...)Arguments
simulation_managerOptional
SimulationManagerobject (or an object inherited from theGenericManagerclass), from which simulation attributes can be copied....Parameters listed individually.
Method generate()
Generates the summary metric data and/or matrix list via the summary functions for each simulation sample, and creates/writes a generation log.
Method calculate_result_attachments()
Calculates and attaches intermediate values to the sample result model (via the result attachment functions).
Arguments
simulation_resultsThe sample simulation results, an object of a class inherited from
SimulationResults, to which the intermediate results are attached.
Method calculate_summaries()
Calculates the summary metrics and/or matrices for the results of a sample simulation (via the summary functions).
Arguments
simulation_resultsThe sample simulation results, an object of a class inherited from
SimulationResults.sample_indexIndex of sample from data frame.
Method log_generation()
Summarizes the log generated within the generate method and writes it to a text file in the results directory.
Method calculate_summary_weighted_averages()
Calculates the weighted averages for each of the summary matrices (providing the sample data has a weight column).
Examples
if (FALSE) { # interactive()
# U Island example region
coordinates <- data.frame(
x = rep(seq(177.01, 177.05, 0.01), 5),
y = rep(seq(-18.01, -18.05, -0.01), each = 5)
)
template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent
template_raster[][-c(7, 9, 12, 14, 17:19)] <- NA # make U Island
region <- Region$new(template_raster = template_raster)
raster::plot(region$region_raster,
main = "Example region (indices)",
xlab = "Longitude (degrees)", ylab = "Latitude (degrees)",
colNA = "blue"
)
# Results manager
results_manager <- ResultsManager$new(
sample_data = data.frame(index = 1:3),
simulation_results = PopulationResults$new(region = region),
summary_metrics = c("trend_n", "total_h"),
summary_matrices = c("n", "h"),
summary_functions = list(
trend_n = function(results) {
round(results$all$abundance_trend, 2)
},
total_h = function(results) {
sum(results$harvested)
},
n = "all$abundance", # string
h = "all$harvested"
),
parallel_cores = 2,
results_dir = tempdir()
)
# Write example result files
results <- list()
for (i in 1:3) {
results[[i]] <- list(abundance = t(apply(
matrix(11:17), 1,
function(n) round(n * exp(-(0:9) / i))
)))
results[[i]]$harvested <- round(results[[i]]$abundance * i / 7)
file_name <- paste0(results_manager$get_results_filename(i), ".RData")
saveRDS(results[[i]], file.path(tempdir(), file_name))
}
# Generate result metrics and matrices
gen_output <- results_manager$generate()
gen_output$summary
dir(tempdir(), "*.txt") # plus generation log
results_manager$summary_metric_data
results_manager$summary_matrix_list
}