ResultsManager: R6 class representing a results manager.
In poems: Pattern-Oriented Ensemble Modeling System
ResultsManager R Documentation
R6 class representing a results manager.
Description
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
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
Active bindings
sample_dataA data frame of sampled parameters for each simulation/result.
simulation_resultsAn object of a class inherited from the SimulationResults class for encapsulating and dynamically generating simulation results.
generatorsA list of generators (Generator or 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
Public methods
-
-
-
-
-
-
-
Inherited 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 SimulationManager object (or an object inherited from the GenericManager class), 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.
Usage
ResultsManager$generate(results_dir = NULL)
Arguments
results_dirResults directory path (must be present if not already set within manager class object).
Returns
Generation log as a list.
Method calculate_result_attachments()
Calculates and attaches intermediate values to the sample result model (via the result attachment functions).
Usage
ResultsManager$calculate_result_attachments(simulation_results)
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).
Usage
ResultsManager$calculate_summaries(simulation_results, sample_index)
Arguments
simulation_resultsThe sample simulation results, an object of a class inherited from SimulationResults.
sample_indexIndex of sample from data frame.
Returns
Generation log entry as a (nested) list, including generated summary metric data and (optionally) matrices.
Method log_generation()
Summarizes the log generated within the generate method and writes it to a text file in the results directory.
Usage
ResultsManager$log_generation(generation_log)
Arguments
generation_logNested list of log entries generated via the generate method.
Returns
Extended generation log as a nested with added summary and failure/warning indices.
Method calculate_summary_weighted_averages()
Calculates the weighted averages for each of the summary matrices (providing the sample data has a weight column).
Usage
ResultsManager$calculate_summary_weighted_averages(na_replacements = NULL)
Arguments
na_replacementsList of values or functions (form: modified_matrix <- function(matrix)) for dealing with NA values in each summary matrix (default NULL will ignore NAs).
Method clone()
The objects of this class are cloneable with this method.
Usage
ResultsManager$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
# 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
poems documentation built on Oct. 7, 2023, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| ResultsManager | R Documentation |
R6 class representing a results manager.
Description
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
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
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
Public methods
Inherited 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.
Usage
ResultsManager$generate(results_dir = NULL)
Arguments
results_dirResults directory path (must be present if not already set within manager class object).
Returns
Generation log as a list.
Method calculate_result_attachments()
Calculates and attaches intermediate values to the sample result model (via the result attachment functions).
Usage
ResultsManager$calculate_result_attachments(simulation_results)
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).
Usage
ResultsManager$calculate_summaries(simulation_results, sample_index)
Arguments
simulation_resultsThe sample simulation results, an object of a class inherited from
SimulationResults.sample_indexIndex of sample from data frame.
Returns
Generation log entry as a (nested) list, including generated summary metric data and (optionally) matrices.
Method log_generation()
Summarizes the log generated within the generate method and writes it to a text file in the results directory.
Usage
ResultsManager$log_generation(generation_log)
Arguments
generation_logNested list of log entries generated via the generate method.
Returns
Extended generation log as a nested with added summary and failure/warning indices.
Method calculate_summary_weighted_averages()
Calculates the weighted averages for each of the summary matrices (providing the sample data has a weight column).
Usage
ResultsManager$calculate_summary_weighted_averages(na_replacements = NULL)
Arguments
na_replacementsList of values or functions (form:
modified_matrix <- function(matrix)) for dealing with NA values in each summary matrix (default NULL will ignore NAs).
Method clone()
The objects of this class are cloneable with this method.
Usage
ResultsManager$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
# 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
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.