Input and Output

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, seed=nothing)

Combines all configuration options to produce a single settings dict. Precedence: 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.

@chance(odds)

Return true if a random number is less than the odds (0.0 <= odds <= 1.0), using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.

@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!

@rand(args...)

Return a random number or element from the sample, using the model RNG. This is a utility wrapper that can only be used a context where the model object is available.

@shuffle!(collection)

Shuffle the given collection in place, using the model RNG. This is a utility wrapper that can only be used 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: - name: a string identifier for the data collection (used as file name) - header: a list of column names - outputfunction: a function that takes a model object and returns data values to record (formatted as a vector of vectors) - frequency: how often to call the output function (daily/monthly/yearly/end/never) - 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.

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, outputfunction, frequency)

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.

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.

gettickmarks(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.

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.