Input and Output

The crop models that can be used in the simulation.

The file that stores all default parameters: src/parameters.toml

flattenTOML(dict)

An internal utility function to convert the two-dimensional dict returned by TOML.parsefile() into a one-dimensional dict, so that instead of writing settings["domain"]["param"] one can use settings["domain.param"]. Can be reversed with prepareTOML.

getsettings(configfile, userparams=Dict())

Combines all configuration options to produce a single settings dict. Precedence: function arguments - commandline parameters - user config file - default values

loadmodelobject(fullfilename)

Deserialise a model object that was previously saved with [savemodelobject](@ref).

parsecommandline()

Certain software parameters can be set via the commandline.

preprocessparameters(settings)

Take the raw input parameters and process them where necessary (e.g. convert types or perform checks). This is a helper function for getsettings.

@param(domainparam)

Return a configuration parameter from the global settings. The argument should be in the form <domain>.<parameter>, for example @param(core.outdir). Possible values for <domain> are core, nature, farm, or crop. For a full list of parameters, see src/parameters.toml.

Note: this macro only works in a context where the model object is available!

Log output is saved to simulation.log in the output directory

All input data are copied to the inputs folder within the output directory

DataOutput

A struct for organising model output. This is used to collect model data in an in-memory dataframe or for CSV output. Submodels can register their own output functions using newdataoutput!.

Struct fields: - frequency: how often to call the output function (daily/monthly/yearly/end/never) - databuffer: a vector of vectors that temporarily saves data before it is stored permanently or written to file - datastore: a data frame that stores data until the end of the run - outputfunction: a function that takes a model object and returns data values to record (formatted as a vector of vectors) - plotfunction: a function that takes a model object and returns a Makie figure object (optional)

createdatadir(outdir, overwrite)

Creates the output directory, dealing with possible conflicts.

Retrieve the data stored in a DataOutput (assumes core.storedata is true).

modellogger(loglevel, outdir, output="both")

Create a logger object that writes output to screen and/or a logfile. This object is stored as model.logger and can then be used with with_logger(). Note: requires createdatadir to be run first.

newdataoutput!(model, name, header, frequency, outputfunction, plotfunction)

Create and register a new data output. This function must be called by all submodels that want to have their output functions called regularly.

outputdata(model, force=false)

Cycle through all registered data outputs and activate them according to their configured frequency. If force is true, activate all outputs regardless of their configuration.

prepareTOML(dict)

An internal utility function to re-convert the one-dimensional dict created by flattenTOML into the two-dimensional dict needed by TOML.print, and convert any data types into TOML-compatible types where necessary.

record!(model, outputname, data)

Append an observation vector to the given output.

saveinputfiles(model)

Copy all input files into the output directory, including the actual parameter settings used. This allows replicating a run in future.

savemodelobject(model, filename)

Serialise a model object and save it to file for later reference. Includes the current model and Julia versions for compatibility checking.

WARNING: produces large files (>100 MB) and takes a while to execute.

visualiseoutput(model)

Cycle through all data outputs and call their respective plot functions, saving each figure to file.

withtestlogger(model)

Replace the model logger with the currently active logger. This is intended to be used in the testsuite to circumvent a Julia issue, where @test_logs doesn't work with local loggers.

@data(outputname)

Return the data stored in the given output (assumes core.storedata is true). Only use in scopes where model is available.

@record(outputname, data)

Record an observation / data point. Only use in scopes where model is available.

croptrends(model)

Plot a dual line graph of cropped area and average plant height per crop over time. Returns a Makie figure object.

datetickmarks(dates)

Given a vector of dates, construct a selection to use as tick mark locations. Helper function for [populationtrends](@ref)

populationtrends(model)

Plot a line graph of population sizes of each species over time. Returns a Makie figure object.

skylarkpopulation(model)

Plot a line graph of total population size and individual demographics of skylarks over time. Returns a Makie figure object.

skylarkstats(model)

Plot various statistics from the skylark model: nesting habitat, territory size, mortality.

visualisemap(model, date, landcover)

Draw the model's land cover map and plot all individuals as points on it at the specified date. If no date is passed, use the last date for which data are available. Optionally, you can pass a landcover map image (this is needed to reduce the frequency of disk I/O for Persefone Desktop). Returns a Makie figure object.