model_test_case: Define BioCro model test cases

Description

BioCro models can be tested using test cases, which are sets of known outputs that correspond to particular inputs. The model_test_case function defines such a test case.

Note that model tests are distinct from the module tests described in module_testing.

Usage

model_test_case(
    test_case_name,
    model_definition,
    drivers,
    check_outputs,
    directory = '.',
    quantities_to_ignore = character(),
    row_interval = 24,
    digits = 5,
    relative_tolerance = 1e-3
  )

Value

A list that defines a model test case, which can be passed to

update_stored_model_results, compare_model_output, or run_model_test_cases.

Arguments

test_case_name: A string describing the test case.
model_definition: A list defining a model, as described in the documentation for crop_model_definitions.
drivers: A set of drivers to be passed to run_biocro along with the model_definition.
check_outputs: A logical value indicating whether to compare the simulation output against a stored result.
directory: A relative or absolute path to a directory containing a stored simulation result. Only used when check_outputs is TRUE.
quantities_to_ignore: A character vector of any quantities that should not be compared against the stored results. Only used when check_outputs is TRUE.
row_interval: Determines which rows are saved and compared when using update_stored_model_results, compare_model_output, or run_model_test_cases. Only used when check_outputs is TRUE.
digits: Passed to signif to round values when storing saved results. Only used when check_outputs is TRUE.
relative_tolerance: A relative tolerance to be used when comparing new values against stored ones. This value will be passed to all.equal as its tolerance input argument. Only used when check_outputs is TRUE.

Details

The model_test_case function forms the basis for the BioCro model testing system. See model_testing for more information.

With the default settings:

Every 24 rows of the simulation output will be stored and compared. When using drivers with an hourly time step, this corresponds to one row for each day.
Values in the stored simulation results will be rounded to five significant digits. This reduces the size of the stored result file.
The value of the relative tolerance was chosen to be the smallest value that enabled the tests to pass on all operating systems.

These default settings have proven useful for the BioCro miscanthus_x_giganteus, willow, and soybean models.

Examples

Run this code

# Define a test case for the miscanthus model
miscanthus_test_case <- model_test_case(
    'miscanthus_x_giganteus',
    miscanthus_x_giganteus,
    get_growing_season_climate(weather$'2005'),
    TRUE,
    tempdir(),
    'soil_evaporation_rate'
)

# The result is a specially formatted list
str(miscanthus_test_case)