| Title: | Statistical tools for LPJmL data analysis |
|---|---|
| Description: | This package provides statistical tools for LPJmL data analysis to be used for benchmarking LPJmL outputs. |
| Authors: | David Hötten [aut, cre],
Jannes Breier [aut] |
| Maintainer: | David Hötten <[email protected]> |
| License: | AGPL-3 |
| Version: | 0.5.0 |
| Built: | 2024-10-18 08:19:12 UTC |
| Source: | https://github.com/PIK-LPJmL/lpjmlstats |
Subtract an LPJmLDataCalc object from another LPJmLDataCalc object
## S3 method for class 'LPJmLDataCalc' o1 - o2## S3 method for class 'LPJmLDataCalc' o1 - o2
o1 |
An |
o2 |
An |
An LPJmLDataCalc object.
Function to coerce (convert) an LPJmLData object into an
LPJmLDataCalc object with extended functionality.
.as_LPJmLDataCalc(obj).as_LPJmLDataCalc(obj)
obj |
LPJmLData object or an array with the following order of dimensions: 1. space, 2. time, 3. band. |
An LPJmLDataCalc object.
Multiply an LPJmLDataCalc object by another LPJmLDataCalc object
## S3 method for class 'LPJmLDataCalc' o1 * o2## S3 method for class 'LPJmLDataCalc' o1 * o2
o1 |
An |
o2 |
An |
An LPJmLDataCalc object.
Divide an LPJmLDataCalc object by another LPJmLDataCalc object
## S3 method for class 'LPJmLDataCalc' o1 / o2## S3 method for class 'LPJmLDataCalc' o1 / o2
o1 |
An |
o2 |
An |
An LPJmLDataCalc object.
Add an LPJmLDataCalc object to another LPJmLDataCalc object
## S3 method for class 'LPJmLDataCalc' o1 + o2## S3 method for class 'LPJmLDataCalc' o1 + o2
o1 |
An |
o2 |
An |
An LPJmLDataCalc object.
Function to aggregate the full data of an LPJmLDataCalc object by
applying summary statistics along the cell and/or time dimensions.
aggregate(x, ref_area = "terr_area", ...)aggregate(x, ref_area = "terr_area", ...)
x |
|
ref_area |
string either |
... |
one or several key-value pairs. Keys represent the dimension to be aggregated and values specify the target aggregation units and the desired summary statistic. Aggregation unit and statistic are given in a list,
by the syntax If only a string is given instead of a list it is used as
the aggregation unit and the summary statistic defualts to Options for the cell dimension The aggregation units for the cell dimension can be either an LPJmlRegionData object or a string with the following options
Options for the time dimension For the time dimension these aggregation units are available:
The only available aggregation method is |
An aggregated LPJmLDataCalc object.
## Not run: # Example 1 # Load an example LPJmLDataCalc object soiln <- load_soiln_calc() # Aggregate the data to countries of the world soiln_countries <- aggregate(soiln, cell = "countries") soiln_countries$data # look at country time series # Example 2 # Load an example LPJmLDataCalc object soiln <- load_soiln_calc() # Aggregate the to global region soiln <- aggregate(soiln, cell = list(to = "global", stat = "weighted_sum")) soiln$data # look at global time series # Example 3 # Load an example LPJmLDataCalc object soiln <- load_soiln_calc() # Take the mean of the data over the full simulation period # and a weighted mean over the cells soiln <- aggregate(soiln, time = "sim_period", cell = list(to = "global", stat = "weighted_mean")) # Look at the resulting value soiln$data ## End(Not run)## Not run: # Example 1 # Load an example LPJmLDataCalc object soiln <- load_soiln_calc() # Aggregate the data to countries of the world soiln_countries <- aggregate(soiln, cell = "countries") soiln_countries$data # look at country time series # Example 2 # Load an example LPJmLDataCalc object soiln <- load_soiln_calc() # Aggregate the to global region soiln <- aggregate(soiln, cell = list(to = "global", stat = "weighted_sum")) soiln$data # look at global time series # Example 3 # Load an example LPJmLDataCalc object soiln <- load_soiln_calc() # Take the mean of the data over the full simulation period # and a weighted mean over the cells soiln <- aggregate(soiln, time = "sim_period", cell = list(to = "global", stat = "weighted_mean")) # Look at the resulting value soiln$data ## End(Not run)
Function to benchmark one or several under test LPJmL runs against a baseline run.
benchmark( baseline_dir, under_test_dirs, settings = default_settings, metric_options = NULL, author = "", description = "", pdf_report = TRUE, ... )benchmark( baseline_dir, under_test_dirs, settings = default_settings, metric_options = NULL, author = "", description = "", pdf_report = TRUE, ... )
baseline_dir |
Path to directory containing the baseline run. |
under_test_dirs |
List of paths to directories containing the under test run results. |
settings |
List that defines for each output which metrics to use. The list has to have the following structure:
|
metric_options |
List that defines options for the metrics. The list has to have the following structure:
|
author |
Name of the author of the benchmark. |
description |
Description of the purpose of the benchmark. |
pdf_report |
Logical, if TRUE a pdf report will be created with the create_pdf_report function. |
... |
additional arguments to be passed to create_pdf_report |
In order for the benchmarking to work, all the output files specified in the settings have to be present in the baseline and all under test directories. All output files need to be with ".bin" extension and with meta files of ".bin.json" format. All output paths given to the function need to be distinct. In each output directory there must be a grid and a terr_area file corresponding to the outputs. For each variable the structure of the output files has to be same in each directory (i.e. same cells, same time steps, same bands).
The internal benchmarking process is structured as follows:
Create simulation table with meta information of all considered simulations and the short simulation identifiers.
Retrieve all summaries of outputs from the baseline and under test runs of the variable by applying the summary method of each metric to all lpjml outputs of variables that are designated to be evaluated with this metric, as specified in the settings. The results are organized in variable groups and stored in the var_grp_list attributes of the metrics. See Metric for details.
Add the comparison items to the variable groups, by applying the compare method of each metric to the combination of baseline summary with each under test summary of the variable groups stored in that metric.
Apply unit conversions to all data objects of the metrics, as specified in the unit conversion table. See set_lpjmlstats_settings.
A benchmarkResult object containing the numerical results of the benchmarking. This data object is basically a list of all metrics used in the benchmarking. See Metric for the way a metric structures benchmarking results. In addition the benchmarkResult object contains meta information. Of particular importance is the simulation table, which contains the simulation names, paths and the short simulation identifier that are used in the benchmarkResult object.
The function get_benchmark_meta_data can be used to retrieve the meta information.
The data structure of the benchmarkResult object is depicted here:
## Not run: # Example 1 # Most basic benchmarking with default settings benchmark("path_to_baseline_results", "path_to_under_test_results") # Example 2 # Specifying author and description, as well as filename for pdf report # is recommended. Also, it can make sense to store the benchmarkResult object # for later analysis. BM_resu <- benchmark("path_to_baseline_results", "path_to_under_test_results", author = "anonymous", description = "This is a test", output_file = "myBenchmark.pdf") saveRDS(BM_resu, "bm_results.rds") # Example 3 # Quick benchmarking that only looks at specific outputs with # specific metrics and doesn't generate pdf report. # In addition only the first 10 years are considered # which gives another significant speedup. settings <- list( vegc = c(GlobSumTimeAvgTable), soilc = c(GlobSumTimeAvgTable), # this give an aggregation to a single value for baseline and under test # and their comparison, displayed in a table mgpp = c(GlobSumTimeseries), # this gives a time series for baseline and under test # displayed as line plots mnpp = c(TimeAvgMap) # this gives a time average for baseline and under test # displayed as maps ) BM_data <- benchmark("path_to_baseline_results", "path_to_under_test_results", settings = settings, pdf_report = FALSE) # Example 4 # Benchmark soiltemp in addition to default settings # with a special metric settings <- c(default_settings, # use default settings list(msoiltemp1 = c(GlobAvgTimeAvgTable, TimeAvgMap)) # GlobAvgTimeAvgTable uses a weighted average over space # instead of the standard weighted sum ) BM_data <- benchmark("path_to_baseline_results", "path_to_under_test_results", settings = settings) # Example 5 # Benchmark multiple under test runs against the baseline BM_data <- benchmark("path_to_baseline_results", list("path_to_under_test_results1", "path_to_under_test_results2") ) # Example 6 # Benchmark with custom metric options metric_options <- list( GlobSumTimeAvgTable = list(font_size = 12), # use larger font size in table TimeAvgMap = list(highlight = "soilc") # plots a larger map for soilc ) BM_data <- benchmark("path_to_baseline_results", "path_to_under_test_results", metric_options = metric_options) # Example 7 # Benchmark only maize harvest # The benchmarking allows to select only specific bands of an output settings <- list(`pft_harvest.pft$rainfed maize; irrigated maize` = c(GlobSumTimeAvgTable)) benchmark("path_to_baseline_results", "path_to_under_test_results", settings) ## End(Not run)## Not run: # Example 1 # Most basic benchmarking with default settings benchmark("path_to_baseline_results", "path_to_under_test_results") # Example 2 # Specifying author and description, as well as filename for pdf report # is recommended. Also, it can make sense to store the benchmarkResult object # for later analysis. BM_resu <- benchmark("path_to_baseline_results", "path_to_under_test_results", author = "anonymous", description = "This is a test", output_file = "myBenchmark.pdf") saveRDS(BM_resu, "bm_results.rds") # Example 3 # Quick benchmarking that only looks at specific outputs with # specific metrics and doesn't generate pdf report. # In addition only the first 10 years are considered # which gives another significant speedup. settings <- list( vegc = c(GlobSumTimeAvgTable), soilc = c(GlobSumTimeAvgTable), # this give an aggregation to a single value for baseline and under test # and their comparison, displayed in a table mgpp = c(GlobSumTimeseries), # this gives a time series for baseline and under test # displayed as line plots mnpp = c(TimeAvgMap) # this gives a time average for baseline and under test # displayed as maps ) BM_data <- benchmark("path_to_baseline_results", "path_to_under_test_results", settings = settings, pdf_report = FALSE) # Example 4 # Benchmark soiltemp in addition to default settings # with a special metric settings <- c(default_settings, # use default settings list(msoiltemp1 = c(GlobAvgTimeAvgTable, TimeAvgMap)) # GlobAvgTimeAvgTable uses a weighted average over space # instead of the standard weighted sum ) BM_data <- benchmark("path_to_baseline_results", "path_to_under_test_results", settings = settings) # Example 5 # Benchmark multiple under test runs against the baseline BM_data <- benchmark("path_to_baseline_results", list("path_to_under_test_results1", "path_to_under_test_results2") ) # Example 6 # Benchmark with custom metric options metric_options <- list( GlobSumTimeAvgTable = list(font_size = 12), # use larger font size in table TimeAvgMap = list(highlight = "soilc") # plots a larger map for soilc ) BM_data <- benchmark("path_to_baseline_results", "path_to_under_test_results", metric_options = metric_options) # Example 7 # Benchmark only maize harvest # The benchmarking allows to select only specific bands of an output settings <- list(`pft_harvest.pft$rainfed maize; irrigated maize` = c(GlobSumTimeAvgTable)) benchmark("path_to_baseline_results", "path_to_under_test_results", settings) ## End(Not run)
Construct global region object that fully contains all cells given in a grid.
build_global_region(grid)build_global_region(grid)
grid |
An LPJmLGridData object containing the grid. |
An LPJmLRegionData object containing the global region.
CellSubsetAnnAvgTimeseries metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeseries -> lpjmlstats::GlobAvgTimeseries -> CellSubsetAnnAvgTimeseries
m_optionsList of metric options specific to this metric:
font_size: integer, font size of the plot (default 6)
year_subset: character vector, defines which calendar years the metric considers,
i.e., a data subset that the metric works with; e.g., c("1995", "1996") (default "1901" - "2019").
cell: cells to be subsetted (default 10000)
num_cols: integer, number of columns in the plot grid in the report (default 2)
var_subheading: logical, if TRUE, a linebreak and a subheading will
be inserted before plots for a new variable are added to the report.
with the name of the variable will be added. Both things are intended to visually seperate
the plots of different variables and to better organize the report,
especially if the metric generates many plots for each variable. (default FALSE)
band_subheading: analogous to var_subheading but for bands (default FALSE)
descriptionDescription used in the report
titleSection header used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeseries$arrange_plots()lpjmlstats::GlobSumTimeseries$plot()summarize()
Subset the cells and compute an annual average.
CellSubsetAnnAvgTimeseries$summarize(lpjml_data)
lpjml_dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
clone()
The objects of this class are cloneable with this method.
CellSubsetAnnAvgTimeseries$clone(deep = FALSE)
deepWhether to make a deep clone.
CellSubsetTimeseries metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeseries -> lpjmlstats::GlobAvgTimeseries -> lpjmlstats::CellSubsetAnnAvgTimeseries -> CellSubsetTimeseries
descriptionDescription used in the report
titleSection header used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeseries$arrange_plots()lpjmlstats::GlobSumTimeseries$plot()summarize()
Subset the cells.
CellSubsetTimeseries$summarize(lpjml_data)
lpjml_dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
clone()
The objects of this class are cloneable with this method.
CellSubsetTimeseries$clone(deep = FALSE)
deepWhether to make a deep clone.
Function to create a pdf with a table with literature values
create_literature_pdf(output_file = "literature_values.pdf", ...)create_literature_pdf(output_file = "literature_values.pdf", ...)
output_file |
filename of the output pdf, can include directory |
... |
additional parameters passed to rmarkdown::render |
Generate a pdf report from a benchmarkResult object.
create_pdf_report(benchmark_result, output_file = "benchmark.pdf", ...)create_pdf_report(benchmark_result, output_file = "benchmark.pdf", ...)
benchmark_result |
benchmarkResult object created by the |
output_file |
file of the output pdf, including filename and directory
|
... |
additional arguments passed to |
Each metric has its own section in the report. The content of the section is generated by the plot and plot_arrange function of the metric. The metric results are displayed in the same order as they were specified in the benchmark settings.
## Not run: create_pdf_report(BM_data, "myBenchmark.pdf") ## End(Not run)## Not run: create_pdf_report(BM_data, "myBenchmark.pdf") ## End(Not run)
Default settings for the Benchmarking
default_settingsdefault_settings
An object of class list of length 28.
Function that returns the meta data of a benchmarkResult object
get_benchmark_meta_data(benchmark_result)get_benchmark_meta_data(benchmark_result)
benchmark_result |
A benchmarkResult object |
A list with the meta data of the benchmarkResult object. The list contains the author, the description and a simulation identification table. The latter is a tibble with the columns sim_paths, lpjml_version, sim_names, sim_ident and sim_type.
GlobAvgAnnAvgTimeseries metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeseries -> GlobAvgAnnAvgTimeseries
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeseries$arrange_plots()lpjmlstats::GlobSumTimeseries$plot()summarize()
Take the mean for each year and then the global weighted mean over the cells.
GlobAvgAnnAvgTimeseries$summarize(data)
dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
clone()
The objects of this class are cloneable with this method.
GlobAvgAnnAvgTimeseries$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobAvgTimeAvgTable metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeAvgTable -> GlobAvgTimeAvgTable
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeAvgTable$arrange_plots()lpjmlstats::GlobSumTimeAvgTable$compare()lpjmlstats::GlobSumTimeAvgTable$plot()summarize()
First take global weighted mean, then average over all time steps.
GlobAvgTimeAvgTable$summarize(data)
dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
clone()
The objects of this class are cloneable with this method.
GlobAvgTimeAvgTable$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobAvgTimeseries metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeseries -> GlobAvgTimeseries
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeseries$arrange_plots()lpjmlstats::GlobSumTimeseries$plot()summarize()
Take the global weighted mean over the cells.
GlobAvgTimeseries$summarize(data)
dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
clone()
The objects of this class are cloneable with this method.
GlobAvgTimeseries$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobSumAnnAvgTimeseries metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeseries -> GlobSumAnnAvgTimeseries
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeseries$arrange_plots()lpjmlstats::GlobSumTimeseries$plot()summarize()
Take the mean for each year and then the global weighted sum over the cells.
GlobSumAnnAvgTimeseries$summarize(data)
dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
clone()
The objects of this class are cloneable with this method.
GlobSumAnnAvgTimeseries$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobSumAnnTimeseriesFPC metric
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeseries -> lpjmlstats::GlobSumAnnAvgTimeseries -> GlobSumAnnTimeseriesFPC
titleSection header used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeseries$arrange_plots()lpjmlstats::GlobSumTimeseries$plot()summarize()
Weigh by natural stand fraction and then do the same as GlobSumAnnAvgTimeseries
GlobSumAnnTimeseriesFPC$summarize(data)
dataLPJmLDataCalc object to be summarized
new()
initialize with an extended description
GlobSumAnnTimeseriesFPC$new()
clone()
The objects of this class are cloneable with this method.
GlobSumAnnTimeseriesFPC$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobSumAnnTimeseriesPFT_harvest metric
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeseries -> lpjmlstats::GlobSumAnnAvgTimeseries -> GlobSumAnnTimeseriesPFT_harvest
titleSection header used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeseries$arrange_plots()lpjmlstats::GlobSumTimeseries$plot()summarize()
Weigh by cft_frac and then do the same as GlobSumAnnAvgTimeseries
GlobSumAnnTimeseriesPFT_harvest$summarize(data)
dataLPJmLDataCalc object to be summarized
new()
initialize with an extended description
GlobSumAnnTimeseriesPFT_harvest$new()
clone()
The objects of this class are cloneable with this method.
GlobSumAnnTimeseriesPFT_harvest$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobSumTimeAvgTable metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> GlobSumTimeAvgTable
m_optionsList of metric options specific to this metric:
font_size: integer, font size of the table (default 7)
disp_digits: integer, number of significant digits to display (default 4)
year_subset: character vector, defines which calendar years the metric considers,
i.e., a data subset that the metric works with; e.g., c("1995", "1996") (default 1991:2000).
cell_subset: character vector, defines which cells to subset (default NULL)
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()summarize()
First take global weighted sum, then average over all time steps of the simulation period. The result is a scalar for each band.
GlobSumTimeAvgTable$summarize(data)
dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
compare()
Calculate difference and relative difference to the baseline.
GlobSumTimeAvgTable$compare(var_grp)
var_grpvariable group
plot()
Create a table of the results.
GlobSumTimeAvgTable$plot()
A tibble with the results
arrange_plots()
Style the table to be displayed in the report.
GlobSumTimeAvgTable$arrange_plots(table)
tableA tibble with the results
clone()
The objects of this class are cloneable with this method.
GlobSumTimeAvgTable$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobSumTimeAvgTableFPC metric
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeAvgTable -> GlobSumTimeAvgTableFPC
titleSection header used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeAvgTable$arrange_plots()lpjmlstats::GlobSumTimeAvgTable$compare()lpjmlstats::GlobSumTimeAvgTable$plot()summarize()
Weigh by natural stand fraction and then do the same as GlobSumTimeAvgTable
GlobSumTimeAvgTableFPC$summarize(data)
dataLPJmLDataCalc object to be summarized
new()
initialize with an extended description
GlobSumTimeAvgTableFPC$new()
clone()
The objects of this class are cloneable with this method.
GlobSumTimeAvgTableFPC$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobSumTimeAvgTablePFT_harvest metric
lpjmlstats::Metric -> lpjmlstats::GlobSumTimeAvgTable -> GlobSumTimeAvgTablePFT_harvest
titleSection header used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::GlobSumTimeAvgTable$arrange_plots()lpjmlstats::GlobSumTimeAvgTable$compare()lpjmlstats::GlobSumTimeAvgTable$plot()summarize()
Weigh by cft_frac and then do the same as GlobSumTimeAvgTable
GlobSumTimeAvgTablePFT_harvest$summarize(data)
dataLPJmLDataCalc object to be summarized
new()
initialize with an extended description
GlobSumTimeAvgTablePFT_harvest$new()
clone()
The objects of this class are cloneable with this method.
GlobSumTimeAvgTablePFT_harvest$clone(deep = FALSE)
deepWhether to make a deep clone.
GlobSumTimeseries metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> GlobSumTimeseries
m_optionsList of metric options specific to this metric:
font_size: integer, font size of the plot (default 6)
year_subset: character vector, defines which calendar years the metric considers,
i.e., a data subset that the metric works with; e.g., c("1995", "1996") (default "1901" - "2019").
cell_subset: character vector, defines which cells to subset (default NULL)
num_cols: integer, number of columns in the plot grid in the report (default 2)
var_subheading: logical, if TRUE, a linebreak and a subheading will
be inserted before plots for a new variable are added to the report.
Both things are intended to visually seperate
the plots of different variables and to better organize the report,
especially if the metric generates many plots for each variable. (default FALSE)
band_subheading: analogous to var_subheading but for bands (default FALSE)
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$compare()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()summarize()
Take a global weighted sum of the output.
GlobSumTimeseries$summarize(data)
dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
plot()
Create a time series plot of the results.
GlobSumTimeseries$plot()
A list of time series ggplots
arrange_plots()
Arrange the time series plots side by side with legends pooled together in the top left
GlobSumTimeseries$arrange_plots(plotlist)
plotlistList of time series ggplots
clone()
The objects of this class are cloneable with this method.
GlobSumTimeseries$clone(deep = FALSE)
deepWhether to make a deep clone.
An extended LPJmLData class that enables arithmetic and statistics.
lpjmlkit::LPJmLData -> LPJmLDataCalc
datathe data array
.data_with_unitReturns the internal enclosed unit object !Internal method only to be used for package development!
.metaReturns the actual LPJmLMetaDataCalc object !Internal method only to be used for package development!
lpjmlkit::LPJmLData$.__set_data__()lpjmlkit::LPJmLData$.__set_grid__()lpjmlkit::LPJmLData$as_array()lpjmlkit::LPJmLData$as_raster()lpjmlkit::LPJmLData$as_terra()lpjmlkit::LPJmLData$as_tibble()lpjmlkit::LPJmLData$dim()lpjmlkit::LPJmLData$dimnames()lpjmlkit::LPJmLData$length()lpjmlkit::LPJmLData$print()lpjmlkit::LPJmLData$subset()lpjmlkit::LPJmLData$summary()lpjmlkit::LPJmLData$transform()new()
Create a new LPJmLDataCalc object; to be used internally or explicitly !Internal method only to be used for package development!
LPJmLDataCalc$new(lpjml_data)
lpjml_dataan LPJmLData object.
aggregate()
See aggregate.
LPJmLDataCalc$aggregate(ref_area = "terr_area", ...)
add_band()
Add a band to the object by applying a function to the band vector for each spacial and temporal unit
LPJmLDataCalc$add_band(band_name, fun)
band_nameName of band
funfunction
get_ref_area()
Get the reference area of the LPJmLDataCalc object. For an area density variable the reference area should be the area of each cell on which the variable is defined.
LPJmLDataCalc$get_ref_area(ref_area)
ref_areaA string that can be
terr_area terrestrial area (land area including inland water bodies)
cell_area full area of each cell
An LPJmLDataCalc object with the reference area as variable.
plot()
Plot an LPJmLDataCalc object
The function acts a wrapper of plot.LPJmLData from lpjmlkit, but allows for plotting data in more formats.
In case of non-aggregated data plot.LPJmLData is directly called. In case of aggregated data the value for each region is assigned to all pixels that belong to the region. If a pixel belong to a region only partially, the value is multiplied by the fraction of that pixel belonging to the region. If a pixel belongs to multiple regions, the sum of all respective region values (multiplied by the fractions) is taken. The pixel values are then again plotted with plot.LPJmLData.
LPJmLDataCalc$plot(...)
...Arguments passed to LPJmLData plot method.
.check_internal_integrity()
Check consistency of data and meta data !Internal method only to be used for package development!
LPJmLDataCalc$.check_internal_integrity()
.plot_aggregated()
Plot aggregated data. Performs a very simple disaggregation to create LPJmLData obj that can be plotted with plot.LPJmLData. For each pixel the values of all regions that contain the pixel are multiplied by the fractions and summed up.
LPJmLDataCalc$.plot_aggregated(...)
...Arguments to be passed to plot.LPJmLData
.add()
Addition of two LPJmLDataCalc objects !Internal method only to be used for package development!
LPJmLDataCalc$.add(lpjml_calc_obj)
lpjml_calc_objAn LPJmLData object.
.subtract()
Subtraction of two LPJmLDataCalc objects !Internal method only to be used for package development!
LPJmLDataCalc$.subtract(lpjml_calc_obj)
lpjml_calc_objAn LPJmLData object.
.multiply()
Multiplication of two LPJmLDataCalc objects !Internal method only to be used for package development!
LPJmLDataCalc$.multiply(lpjml_calc_obj)
lpjml_calc_objAn LPJmLData object.
.divide()
Division of two LPJmLDataCalc objects !Internal method only to be used for package development!
LPJmLDataCalc$.divide(lpjml_calc_obj)
lpjml_calc_objAn LPJmLData object.
.convert_unit()
Unit conversion of LPJmLDataCalc object !Internal method only to be used for package development!
LPJmLDataCalc$.convert_unit(unit)
unitA string with the unit to convert to.
.set_unit()
Set unit of LPJmLDataCalc object !Internal method only to be used for package development!
LPJmLDataCalc$.set_unit(unit_str)
unit_strA string with the unit to be set.
apply_unit_conversion_table()
Apply unit conversion from conversion table
LPJmLDataCalc$apply_unit_conversion_table(path_to_table = NULL)
path_to_tableA string with the path to the conversion table.
add_grid()
Add a grid to the LPJmLDataCalc object
Wrapper for the add_grid method of the LPJmLData class.
LPJmLDataCalc$add_grid()
clone()
The objects of this class are cloneable with this method.
LPJmLDataCalc$clone(deep = FALSE)
deepWhether to make a deep clone.
A meta data container for the LPJmLDataCalc class that extends the LPJmLMetaData such that aggregation can be tracked.
lpjmlkit::LPJmLMetaData -> LPJmLMetaDataCalc
space_aggregationboolean, Indication weather the data has been subject to space aggregation.
time_aggregationboolean, Indication weather the data has been subject to time aggregation.
band_names_dispnamed vector, versions of band names used for display, usually shorter
pos_in_var_grplist, position of the lpjml_calc inside of its var_grp.
sim_identstring, simulation identifier
var_and_band_dispstring, variable name together with name of first band, e.g. soiln$200
lpjmlkit::LPJmLMetaData$.__init_grid__()lpjmlkit::LPJmLMetaData$.__set_attribute__()lpjmlkit::LPJmLMetaData$.__transform_space_format__()lpjmlkit::LPJmLMetaData$.__transform_time_format__()lpjmlkit::LPJmLMetaData$.__update_subset__()lpjmlkit::LPJmLMetaData$as_header()lpjmlkit::LPJmLMetaData$as_list()new()
Initialize the LPJmLMetaDataCalc object by copying all private attributes from an LPJmLMetaData object to private attributes of this object. !Internal method only to be used for package development!
LPJmLMetaDataCalc$new(lpjml_meta)
lpjml_metaan LPJmLMetaData object.
.__set_space_aggregation__()
Save in metadata that data is in space_aggregation format !Internal method only to be used for package development!
LPJmLMetaDataCalc$.__set_space_aggregation__(agg_method)
agg_methodstring indicating the aggregation method
.__set_time_aggregation__()
Save in metadata that data is in time_aggregation format !Internal method only to be used for package development!
LPJmLMetaDataCalc$.__set_time_aggregation__(agg_method)
agg_methodstring indicating the aggregation method
print()
Wrapper for LPJmLMetaData print method.
LPJmLMetaDataCalc$print(spaces = "", ...)
spacesstring of spaces to be printed as prefix
...additional arguments passed to LPJmLMetaData print method
.__set_sim_ident__()
Set the simulation identifier !Internal method only to be used for package development!
LPJmLMetaDataCalc$.__set_sim_ident__(sim_ident)
sim_identstring, simulation identifier
.__set_pos_in_var_grp__()
Set the position of the lpjml_calc inside of its var_grp. !Internal method only to be used for package development!
LPJmLMetaDataCalc$.__set_pos_in_var_grp__(pos_in_var_grp)
pos_in_var_grpA list with the position of the lpjml_calc inside of the var_grp. The first entry is the type; can be "baseline", "under_test" or "compare". The second entry is the compare item if of type "compare", e.g. "diff". E.g. list("under_test") or list("compare", "diff").
clone()
The objects of this class are cloneable with this method.
LPJmLMetaDataCalc$clone(deep = FALSE)
deepWhether to make a deep clone.
A class that represents one or several regions in LPJmL. Based on an LPJmL grid, a region is defined as set of grid cells together with fractions. The fractions indicate the share of each grid cell that is part of the region. (e.g. 1 = the cell belongs completely to the region, 0 = the cell does not belong to the region at all).\ The underlying data structure is a sparse matrix, where the rows represent the regions, the columns represent the grid cells and the values represent the fractions (cells not belonging to a region do not take memory as only nonzero entries are stored in a sparse matrix).
Create a new LPJmLRegionData object; only used internally.
region_matrixobject stores the region data as a sparse matrix.
gridLPJmLGridData object containing the underlying grid.
new()
!Internal method only to be used by the package itself!
LPJmLRegionData$new(grid, region_matrix)
gridLPJmLGridData object containing the underlying grid.
region_matrixobject stores the region data as a sparse matrix.
get_ncells_per_region()
Get number of cells per region.
LPJmLRegionData$get_ncells_per_region()
For partially belonging cells the fraction of the cell that belongs to the region is counted.
A vector of length nrow(region_matrix) containing the number of cells per region.
clone()
The objects of this class are cloneable with this method.
LPJmLRegionData$clone(deep = FALSE)
deepWhether to make a deep clone.
A metric is a) a structured, generic processing pipeline to calculate numerical indicators for sets of lpjml outputs as well as to display these indicators in a report, and b) a structured data container that stores the numerical indicators resulting from a).
a) A metric defines a procedure to
summarize a complex, multidimensional LPJmL output in a meaningfull, potentially opinionated way, typically involving the reduction of its time and or space dimension,
compare how this summary statistic of an output variable changes, when going from an established baseline LPJmL version or configuration to a new version or configuration currently under test,
plot the results of 1. and 2. as a figure or table and
arrange these plots in a report, (e.g. styling, side by side arrangement)
See benchmark on how these steps come into play in the benchmarking process.
b) The summarized outputs as well as comparisons that are stored a metric are grouped by the different lpjml variables. A so called variable group (var_grp) contains
the summary of the baseline output of that variable
a list of all summarized under test outputs of that variable
a list of compare items (e.g. difference, relative difference). Each compare item is a list of comparisons of the baseline summary with each under test summary using the specific method of that item.
All variable groups are stored in the var_grp_list attribute of the metric.
As the cornerstone of the benchmarking process, all metrics illuminate the change of LPJmL results from different angles, and should together provide a comprehensive picture of the effects of modifications in code or settings.
See GlobSumTimeAvgTable for a typical example of a metric.
m_optionsList of metric options Will be overwritten by the individual metric subclasses.
var_grp_listList of variable groups. Each variable group contains the summaries and the comparisons for one variable.
summarize()
Pipeline to summarize the raw data. Will be overwritten by the individual metric subclasses.
Metric$summarize(data)
dataRaw data to be summarized
compare()
Pipeline to compare the baseline summary with each under test summary stored in the metric. Will be overwritten by the individual metric subclasses.
Metric$compare(var_grp)
var_grpvariable group
plot()
Function to plot the results of the metric. Will be overwritten by the individual metric subclasses.
Metric$plot(var_grp)
var_grpvariable group
arrange_plots()
Function to arrange all plots of the metric in the respective section of the report. Will be overwritten by the individual metric subclasses.
Metric$arrange_plots(var_grp)
var_grpvariable group
capture_summary()
!Package internal method!
Metric$capture_summary(lpjml_calc, var, type)
lpjml_calcRaw data to be summarized
varVariable name
typeType of data ("baseline" or "under_test")
store_summary()
!Package internal method! Store the summary in the variable group
Metric$store_summary(summary, var, type)
summarySummary to be stored
varVariable name
typeType of data ("baseline" or "under_test")
add_comparisons()
!Package internal method! Compare and store the comparison in all variable groups
Metric$add_comparisons()
add_compare_meta()
!Package internal method! Add the position of the comparisons within the var_grp to meta
Metric$add_compare_meta(var_grp)
var_grpvariable group
transform_lpjml_calcs()
!Package internal method! Apply function to all lpjml_calcs in all eval groups and lists
Metric$transform_lpjml_calcs(fun, ...)
funFunction to apply
...Additional arguments passed to fun
generate_report_content()
!Package internal method! Generate the full report content of the metric.
Metric$generate_report_content()
print_metric_header()
!Package internal method! Function to print the metric header.
Metric$print_metric_header()
print_metric_description()
!Package internal method! Function to print the metric description.
Metric$print_metric_description()
print_year_subset()
!Package internal method! Function to print the year_subset metric option.
Metric$print_year_subset()
clone()
The objects of this class are cloneable with this method.
Metric$clone(deep = FALSE)
deepWhether to make a deep clone.
The function acts a wrapper of plot.LPJmLData from lpjmlkit, but allows for plotting data in more formats.
## S3 method for class 'LPJmLDataCalc' plot(x, ...)## S3 method for class 'LPJmLDataCalc' plot(x, ...)
x |
LPJmLDataCalc object. In case of non-aggregated data plot.LPJmLData is directly called. In case of aggregated data the value for each region is assigned to all pixels that belong to the region. If a pixel belong to a region only partially, the value is multiplied by the fraction of that pixel belonging to the region. If a pixel belongs to multiple regions, the sum of all respective region values (multiplied by the fractions) is taken. The pixel values are then again plotted with plot.LPJmLData. |
... |
Arguments passed to LPJmLData plot method. |
The COW = countries of the world data contains global country borders.
read_cow_regions()read_cow_regions()
An LPJmLRegionData object containing the cow regions.
The default grid is the standard global grid used in LPJmL.
read_def_grid()read_def_grid()
An LPJmLGridData object containing the default grid.
The function acts a wrapper of read_io from lpjmlkit,
but outputs an LPJmLDataCalc object.
read_io(..., output_type = "LPJmLDataCalc")read_io(..., output_type = "LPJmLDataCalc")
... |
Parameters that are passed to read_io |
output_type |
Can be either |
An LPJmLDataCalc object
This function configures various settings for the lpjmlstats package.
set_lpjmlstats_settings(...)set_lpjmlstats_settings(...)
... |
Variable arguments to specify settings. The function accepts the following options:
|
## Not run: set_lpjmlstats_settings(unit_table_path = "path/to/my_table.csv", pdf_plot_dpi = 300) ## End(Not run)## Not run: set_lpjmlstats_settings(unit_table_path = "path/to/my_table.csv", pdf_plot_dpi = 300) ## End(Not run)
Function to subset an LPJmLDataCalc object. The function acts as a wrapper
of subset.LPJmLData from lpjmlkit, but outputs an
LPJmLDataCalc object, in particular keeping its unit.
## S3 method for class 'LPJmLDataCalc' subset(x, ...)## S3 method for class 'LPJmLDataCalc' subset(x, ...)
x |
LPJmLDataCalc object. |
... |
Parameters that are passed to subset.LPJmLData. |
An LPJmLDataCalc object.
TimeAvgMap metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> TimeAvgMap
m_optionsList of metric options specific to this metric:
font_size: integer, font size of the map plot (default 6)
highlight: vector of strings, indicating which variables
should be highlighted in the report, that is receive a larger plot at the
beginning of report content of the metric.
All variables with a name that contains at least one these strings as a substring,
will not be plotted in the plotgrid (see num_cols) but before the plot grid starts.
These plots are allowed to extent to full page width. (default NULL)
quantiles: quantiles used to determine the lower and upper
limits for the values in the map plot (default c(0.05, 0.95))
n_breaks: number of breaks for each arm of the diverging
color scale (default 3)
year_subset: character vector, defines which calendar years the metric considers,
i.e., a data subset that the metric works with; e.g., c("1995", "1996") (default 1991:2000).
cell_subset: character vector, defines which cells to subset (default NULL)
num_cols: integer, number of columns in the plot grid in the report (default 2)
var_subheading: logical, if TRUE, a linebreak and a subheading will
be inserted before plots for a new variable are added to the report.
with the name of the variable will be added. Both things are intended to visually seperate
the plots of different variables and to better organize the report,
especially if the metric generates many plots for each variable. (default FALSE)
band_subheading: analogous to var_subheading but for bands (default FALSE)
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()summarize()
Take the mean over the simulation period for each cell.
TimeAvgMap$summarize(data)
dataLPJmLDataCalc object to be summarized
A summarized LPJmLDataCalc object
compare()
Compare the baseline summary with the under test summaries by subtracting the baseline from the under test.
TimeAvgMap$compare(var_grp)
var_grpvariable group
plot()
Create a map plot with country border overlay.
TimeAvgMap$plot()
A list of map ggplots
arrange_plots()
Arrange the map plots side by side
TimeAvgMap$arrange_plots(plotlist)
plotlistList of map ggplots
clone()
The objects of this class are cloneable with this method.
TimeAvgMap$clone(deep = FALSE)
deepWhether to make a deep clone.
TimeAvgMapWithAbs metric. See Metric for the documentation of metrics in general.
lpjmlstats::Metric -> lpjmlstats::TimeAvgMap -> TimeAvgMapWithAbs
m_optionsList of metric options specific to this metric:
font_size: integer, font size of the map plot (default 6)
highlight: vector of strings, indicating which variables
should be highlighted in the report, that is receive a larger plot at the
beginning of report content of the metric.
All variables with a name that contains at least one these strings as a substring,
will not be plotted in the plotgrid (see num_cols) but before the plot grid starts.
These plots are allowed to extent to full page width. (default NULL)
quantiles: quantiles used to determine the lower and upper
limits for the values in the map plot (default c(0.05, 0.95))
sep_cmp_lims: logical, if TRUE not all plots of a var_grp
will have the same limits anymore, but the compare plots
have their own separate limits (default TRUE)
n_breaks: number of breaks for each arm of the diverging
color scale (default 3)
year_subset: character vector, defines which calendar years the metric considers,
i.e., a data subset that the metric works with; e.g., c("1995", "1996") (default 1991:2000).
cell_subset: character vector, defines which cells to subset (default NULL)
num_cols: integer, number of columns in the plot grid in the report (default 3)
var_subheading: logical, if TRUE, a linebreak and a subheading will
be inserted before plots for a new variable are added to the report.
with the name of the variable will be added. Both things are intended to visually seperate
the plots of different variables and to better organize the report,
especially if the metric generates many plots for each variable. (default FALSE)
band_subheading: analogous to var_subheading but for bands (default FALSE)
titleSection header used in the report
descriptionDescription used in the report
lpjmlstats::Metric$add_compare_meta()lpjmlstats::Metric$add_comparisons()lpjmlstats::Metric$capture_summary()lpjmlstats::Metric$generate_report_content()lpjmlstats::Metric$print_metric_description()lpjmlstats::Metric$print_metric_header()lpjmlstats::Metric$print_year_subset()lpjmlstats::Metric$store_summary()lpjmlstats::Metric$transform_lpjml_calcs()lpjmlstats::TimeAvgMap$summarize()compare()
Compare the baseline summary with the under test summaries by subtracting the baseline from the under test.
TimeAvgMapWithAbs$compare(var_grp)
var_grpvariable group
plot()
Create a map plot with country border overlay.
TimeAvgMapWithAbs$plot()
A list of map ggplots
arrange_plots()
Arrange the map plots side by side
TimeAvgMapWithAbs$arrange_plots(plotlist)
plotlistList of map ggplots
clone()
The objects of this class are cloneable with this method.
TimeAvgMapWithAbs$clone(deep = FALSE)
deepWhether to make a deep clone.