General utility

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.

resolve_input_dir(path; configdir=nothing)

Return an absolute path to a directory if it exists, trying common roots (pkgdir, the directory of the config file, and the current working directory) in that order. Returns nothing if the directory cannot be found.

@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, animal, 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. This can be any of: "daily", "monthly", "yearly", "end", "never", or a date (e.g. "15 June"). - 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.

AbstractCropState

The abstract supertype of all crop states in the model. Each crop model has to define a type CropState <: AbstractCropState.

AbstractCropType

The abstract supertype of all crop types in the model. Each crop model has to define a type CropType <: AbstractCropType.

ModelAgent

The supertype of all agents in the model (animal species, farmer types, landscape polygons).

SimulationModel

The supertype of AgricultureModel. This is needed to avoid circular dependencies (most types and functions depend on SimulationModel, but the definition of the model struct depends on these types).

Coord

Continuous 2D coordinate in projected map units (e.g. meters).

This is aliased to GeometryBasics.Point{2,Float64} for compatibility with GeoInterface-aware geometry types.

Extent2D

Axis-aligned extent with X/Y bounds, backed by Extents.Extent.

Extent2D(geom::Geom)

Compute the X/Y extent of a GDAL geometry.

Geom

Geometry handle returned by GDAL/ArchGDAL. For polygons this is typically an ArchGDAL.IGeometry of type wkbPolygon or wkbMultiPolygon.

areaof(geom)

Return the area of a geometry in square meters.

bearingfrompoint(origin, destination)

Get the distance and the bearing of the destination point as seen from the origin.

circle(center, radius, coarseness=10)

Return a quasi-circular geom with the given properties. Coarseness defines how many degrees lie between two points of the resulting polygon (i.e. if 10°, the "circle" will consist of 36 points).

fuzzyposition(pos, maxdist, rng=default_rng())

Return a random position that is at most maxdist away from pos.

geom_from_coords(coords)

Create a GDAL polygon geometry from a list of coordinates (outer ring only).

point_in_polygon(coord, geom)

Test whether the given point lies within the given geometry.

pointfrombearing(origin, bearing, distance)

Calculate the coordinates of the point at the given bearing (in °) and distance from the origin.

randompoint(geom, rng)

Return a random position that lies within the given geometry.

rectangle(center, width, height)

Return a rectangular geom with the given properties.

square(center, width)

Return a square geom with the given properties.

@fuzzyposition(pos, maxdist)

Return a random position that is at most maxdist away from pos. This is a utility wrapper that can only be used where model is available.

@randompoint(place)

Return a random point within a landscape element or a home range. This is a utility wrapper that can only be used where model is available.

birdpopulation(speciesname, model)

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

birdstats(speciesname, model)

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

butterflyabundanceplot(speciesname, model)

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

butterflylifestats(speciesname, model)

Plot various statistics from the marbled white model: fecundity, movement, habitat use

butterflytrendsplot(speciesname, model)

... Returns a Makie figure object.

croptrends(model)

Plot a dual line graph of cropped area and average plant height and cover 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.

visualisemap(model, date, landscape)

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 pre-loaded Landscape object. Returns a Makie figure object.