API

CODE_TYPE

The type of a single RasterDataSources layer code as a caller may write it: an Int layer number, a Symbol key or a String. All three name the same layer - layerinfo(4), layerinfo(:bio4) and layerinfo("bio4") return one record.

This is the input vocabulary, not what gets stored. A ClimateRaster resolves whatever it is given to that dataset's preferred spelling (_preferredcode), so two rasters of one layer cannot disagree about how it is named; SourceSpec's code field takes it for the same reason.

LayerInput

Type-union of everything a regime or supply keyword accepts: one AbstractSpec - which includes a Varying wrapping one - or a Tuple/NamedTuple of them for a multi-layer environment, a named tuple keeping the caller's names.

Written into the builders' signatures, not merely documented, so that methods(GridHabitat) and the rendered docs both show what a builder accepts, and a wrong kind of argument is rejected where it was passed rather than several calls later.

Deliberately not the same as LayerSpec, which is the union of spec types: this also admits the tuple forms and the Varying wrapper, because those are things a caller writes at a keyword rather than kinds of layer recipe. A Tuple here always means several layers, one spec per member; name a single data layer with a SourceSpec, which is where its axis, unit and read options live in any case.

Two costs, both accepted. Julia does not dispatch on keyword types, so a wrong argument is refused by a TypeError naming the keyword and printing this union expanded rather than by a message suggesting a remedy - and no fallback method can improve on that, since a second method with the same positional signature replaces the first instead of adding to it. And a signature cannot see inside a container, so an element of a tuple that is not a spec is caught later, by the resolvers.

LayerSpec

Type-union of everything accepted as a regime or supply layer: a synthetic layer spec (AbstractSyntheticLayerSpec) or any lazy data-backed spec (AbstractLazySpec).

MaskSpec

Type-union of everything accepted as an active mask: a synthetic mask spec (AbstractSyntheticMaskSpec) or any lazy data-backed spec (AbstractLazySpec).

NATURALEARTH_LEVELS

Every kind of named region the shipped region table covers, in the order they are reported.

The cultural levels come first, coarsest grouping to finest division, then the physical landform classes. A level's name is what the table's own Level column holds.

AbsoluteChange <: AbstractChangeMode - a position: the layer's value *is* this, in the layer's unit.

AbstractAccumulationPeriod

The interval a layer's value accumulated over - what turns a total into an honest rate. One of ConstantAccumulationPeriod, PerSliceAccumulationPeriod or PerCellAccumulationPeriod; nothing where no period applies.

A type family rather than a bare unit because the three cases are not interchangeable: a constant period is a fixed scale factor that a layer and a species tolerance both convert by, while a period that varies makes the two readings different biological claims, and the code must be able to tell which it is holding.

AbstractBoundaryCondition

What happens at one edge pair of a grid: Periodic (the edges join) or Bounded (they do not). A condition on a single axis, not on the grid as a whole.

AbstractCategoricalTolerance{A, V} <: AbstractTolerance{A, V}

A species' preference among class labels - the tolerances matched against a CategoricalRegime, where preference is membership rather than a distance.

Defined by what it answers rather than by what it stores: the suitability weight species sp gets in category c. SimpleCategoricalTolerance answers that sparsely, from a set of acceptable categories per species; a graded type could answer it densely, with a different weight for every species in every category.

Categorical, so iscontinuous is false: these are class labels, and nothing between two of them is meaningful. A species' response to how much of a class covers a cell is a continuous NicheTolerance on SurfaceArea instead.

AbstractChangeMode

How a change's values are to be read, and so which unit they must be in. The three that carry values differ in exactly that: AbsoluteChange is a position in the layer's own unit, RelativeChange an interval from the layer's captured values, and RateChange an interval per unit time. NoChange carries no values at all.

A mode is a type parameter of AbstractLayerChange, so every change declares one and changeunit always has an answer.

AbstractChangeSpec

Abstract supertype of the change recipes - a declared change that has not yet met a layer, and so has not yet been unit-checked. Materialised into an AbstractLayerChange at attach.

AbstractClimate

Abstract supertype of all climate data.

AbstractCombineStage

When a ConstructedRasterSpec's combine runs, relative to putting its layers on the study grid: on the target grid (CombineOnTargetGrid, the default) or on the layers' own (CombineOnSourceGrid). A type rather than a symbol, so an unrecognised stage is refused by the signature where it is written rather than by a check inside the constructor.

AbstractCoverage

How much of what a region name covers to take - AllTerritories or LargestLandmass.

A name almost never denotes one connected piece of ground. "France" includes Guadeloupe and Martinique, "Norway" includes Bouvet Island in the South Atlantic, and "Chile" includes Easter Island, so the extent of everything a name covers can be many times the extent of the ground most people mean by it. A coverage says which of the two is wanted, and is the same choice whether a bounding box or an actual shape is being asked for.

AbstractDecisionSource

Where a study area's crs or cellsize came from - GivenByUser if you supplied it, otherwise how it was derived. StudyAreaReport records one beside each of those two values, which is what lets the area announce what it guessed without also announcing what you gave it.

AbstractDemand{A, V}

A demand: how much of a Resource one individual of a species needs - the species-side mirror of AbstractSupply.

Demands are what make species compete. Summed over everything present in a cell and set against what that cell supplies, they regulate births and deaths, and so decide how many individuals the cell can hold.

This is a parametric alias for AbstractSpeciesRequirement with the role pinned to Resource, and pinning it is what keeps the constraint real: a tolerance is not an AbstractDemand, so every signature written against this name refuses one. V is the type the amount is stated in, and eltype is inherited from the shared supertype.

AbstractEcosystem{Part <: AbstractHabitat, SL <: AbstractSpecies,
    NF <: AbstractNicheFit} <: AbstractMetacommunity{Float64,
        Matrix{Int64}, Matrix{Float64}, SL, Part}

A community of species in a place, changing through time: an environment (Part), the species living in it (SL), and the rule scoring how well each species suits each place (NF).

This is the whole model. What it holds is an abundance for every species in every place, and what it does is let those abundances change: individuals are born, die and disperse to neighbouring places, step by step. Conditions decide where a species can persist at all, by making it die faster where its surroundings suit it poorly; resources decide how many can persist there, because the demands of everything present are set against what the place supplies. Nothing sets a carrying capacity - it is what those two pressures leave behind.

An ecosystem is a metacommunity: a set of local communities, one per place, drawn from a shared pool of species. Diversity can therefore be asked of it at either level - of a single place, or of the landscape as a whole, accounting for the fact that the same species appears in many of them.

AbstractHabitat{H <: AbstractRegime, B <: AbstractSupply,
                L <: EcoBase.AbstractLocationData} <: AbstractPartition

The physical world a simulation runs in, with nothing living in it yet: what each place is like (H, an AbstractRegime), what it provides (B, an AbstractSupply), and where those places are (L).

A habitat is the setting rather than the story. It says that this place is this warm and this wet and offers this much light, and that place is different - but it says nothing about who lives there or how they fare. An AbstractEcosystem is what results from putting species into one.

Its conditions and supplies need not be fixed. A habitat can warm, dry out or lose land cover as the simulation proceeds, which is how climate and land-use change enter the model; a species then experiences a different environment from one year to the next without itself having changed.

A habitat also knows where its places are, so that neighbours can be identified for dispersal and results can be put back on a map. Only that much is required: this package uses a regular grid of cells, but irregular areas or scattered points would serve equally well.

AbstractKernel

The shape of the probability distribution over where an individual's offspring lands, relative to its own cell. GaussianKernel and LongTailKernel are the concrete kernels.

A kernel says only how far and how likely. What happens when a draw crosses an edge is the grid's AbstractTopology, and what becomes of one aimed at a dead cell is disperse_safely on the movement - three separate questions, answered by three separate things.

AbstractLayer{R <: Role, A}

What the environment holds: one measured quantity, stated for every cell, in one of the two Roles - a regime if it is a Condition, a supply if it is a Resource.

This is the environment's half of the model. Its counterpart is AbstractSpeciesRequirement, which is what a species brings to the same axis; the two are matched role for role and axis for axis. Concrete kinds are ContinuousLayer, CategoricalLayer and the collection LayerCollection, which holds several layers over one set of cells.

The axis is carried in the type, not merely checked when an ecosystem is built, so that a signature can require a regime and the tolerance matched to it to be on the same axis.

Note that A is the axis structure rather than always a single axis: a single layer carries its own axis (Temperature), a collection a Tuple of its members' (Tuple{Temperature, Precipitation}). That is why the parameter carries no <: NicheAxis bound, and it is what lets a matched tolerance and regime be compared as one type whatever their arity. A collection's A is always read off its members rather than chosen.

AbstractLayerChange{M <: AbstractChangeMode}

Abstract supertype of the materialised per-timestep change rules a layer can hold, parameterised by the AbstractChangeMode that says how to read its values.

A change is applied as a pure function of (layer, elapsed, timestep) - never of the ecosystem - which is what lets MPI apply it redundantly on every rank without diverging.

AbstractLayerFate

What the chosen study grid costs one layer: LayerKeptExactly, LayerAggregated or LayerResampled. Each carries exactly the detail its own case has - the aggregation factor, or the reason for resampling - so a field can never be set for a case it means nothing to.

AbstractLazySpec <: AbstractSpec

Abstract supertype of the lazy, data-backed / derived specs. Resolved against the target grid at build time and usable in either role - a regime/supply layer or an active mask: SourceSpec (read a data source), ShapeSpec (a vector file), ConstructedRasterSpec (combine child specs by a function).

AbstractMovement

Which individuals disperse at all: BirthOnlyMovement (only the newly born, plant-like), AlwaysMovement (any individual, animal-like) or NoMovement (none).

A movement carries the per-species part of dispersal - one AbstractKernel per species, and one disperse_safely flag per species. The grid's own edges are not part of it: they belong to the GridHabitat, because two species on one grid cannot be on different topologies.

disperse_safely says what becomes of an individual dispersing into a dead cell - one off the grid, or an inactive one. true redistributes it among the reachable destinations as though it had never aimed there; false loses it, so the share of the kernel pointing at dead cells becomes mortality.

It is per species because it is a fact about the disperser, not about the map. A wind-dispersed seed blown out to sea is gone; an animal-dispersed one is carried to somewhere the animal can actually reach, so two species on one grid may legitimately differ. It cannot empty a cell outright: staying put is one of the kernel's own destinations, and a cell only disperses while it is active, so some share always survives.

AbstractNicheFit{A, V}

How well a species is suited to a cell: the rule that scores a species' AbstractSpeciesRequirement against the AbstractLayer it is matched to.

This closes the triangle. The environment states a value, the species states what it needs, and the fit says how well the two agree - a number that raises or lowers that species' birth and death rates in that cell. Where several axes are in play, a CombiningFit reduces their scores to one.

A sits in the same slot here as in AbstractLayer and AbstractSpeciesRequirement, so a single signature can require a layer, the requirement matched to it and the fit between them to be on the same axis. As there, it is the axis structure - a single axis for one fit, a Tuple of them for a combining one.

V is the value type the two sides are compared in - the same V the requirement carries - so the fit knows the frame it is working in and a layer's values can be brought into it before scoring.

AbstractOperation

What an Intervention does - a closed set of seven: Deactivate, Reactivate, SetLandCover, SetChange, AddAbundance, RemoveAbundance and AddSpecies.

Closed on purpose. A callback would let an intervention do anything, including the things that break reproducibility and MPI - writing a continuous layer's matrix directly, drawing from the global RNG, resizing the landscape mid-run. Seven named operations can each be checked once and then trusted.

A bound is not among them, and does not need to be. It is a property of the quantity rather than of an intervention - a supply cannot be negative because of what a resource is - so it is enforced on the layer automatically; see bounds and _enforcebounds!.

AbstractParams

The demographic rates a simulation runs on: a per-species birth rate and death rate, plus the three exponents and ceilings that say how those rates respond to the environment. EqualPop, PopGrowth and NoGrowth are the concrete forms.

Every subtype carries the same five fields, and two of them are what make the model a niche model:

• longevity is the exponent on a species' own resource demand, applied to birth and death alike. It therefore sets the tempo of turnover - a body-size proxy - and cancels out of the birth/death ratio, so it does not move where a species can persist.
• survival is the exponent on niche suitability, applied with opposite signs to birth and death. It does move the ratio, which is what makes it the niche.

Rates are Unitful quantities per unit time, so a run is timestep-independent: twelve one-month steps and one twelve-month step see the same rates.

AbstractProblemSeverity

How much a Problem matters: a ProblemNotice or a ProblemWarning. A type rather than a symbol, so an unrecognised severity is refused by the signature where it is written rather than by a check inside the constructor.

AbstractRegime{A}

A regime: what the environment is like, on one axis, in every cell - the Condition half of AbstractLayer.

A species meets a regime with its AbstractTolerance on the same axis, and how well the two agree is its suitability there. A regime is not divided between the species present: all of them experience the same value.

AbstractRegion

Where an Intervention applies - AllCells, ActiveCells, CellMask, RandomCells or SpreadingCells.

A region resolves to the linear cell indices an operation should touch. The two random regions draw from a counter-based stream keyed on the step (see Intervention), never from a species' stream and never from the global RNG, so a selection is identical on every rank and thread and a run replays exactly.

AbstractReportStage

Which of the two things a StudyAreaReport describes: an area as proposed (AsInvestigated) or as built (AsBuilt). Both are the same type with the same fields, so this is what says which question the numbers answer.

It matters because building can narrow the grid: a report's specs and constraints always say what was asked for, while a GridHabitat's layers may have removed cells the study area still lists.

It is therefore also what makes a built report safe to reuse. Any value carrying a report can be a StudyArea's base, and re-deriving from one would rebuild the proposed grid and discard that narrowing - so an AsBuilt base given no other keyword is copied verbatim instead, which is how build_habitat reseeds a habitat from the grid it is actually on.

AbstractSchedule

When an Intervention fires - EveryStep, AtTime, AtTimes, BetweenTimes or NeverScheduled.

A type rather than a predicate function, so that a schedule can be reported and checked rather than merely called, and so each rule is a method instead of a branch retaken every step.

AbstractSeriesCalendar

What kind of time coordinate a SeriesLayerChange's slices carry, and so what a simulation epoch is able to do with them - DatedSeries, MonthOfYearSeries or UndatedSeries. Written as the calendar keyword of SeriesChange.

A series has to say which kind it is; it cannot be inferred from the values. Coordinates of one, two and three months read equally well as the first three months of the year and as one, two and three months into my experiment, and phase-locking the second to January would be silently wrong. Only the two unambiguous cases are inferred: real dates in the lookup give a DatedSeries, and no time lookup at all gives an UndatedSeries. A climatology must say calendar = MonthOfYearSeries().

The set is extensible: a series subdivided some other way (day-of-year, say) is a new subtype supplying _calendarorigin, not a change to these.

AbstractSeriesEnd

What a SeriesLayerChange does once elapsed simulation time runs past its last stored slice - ErrorAtEnd, HoldAtEnd, RepeatAtEnd or RevertToLayer. Written as the atend keyword of SeriesChange, and a type rather than a name drawn from a list, so an unrecognised policy is refused by the signature where it is written and the behaviours are separate methods rather than a branch retaken every step.

There is no matching atstart, because before its first slice a series has only one sensible reading: it has not started, so it says nothing and the layer stands. A policy with one option is not a policy.

AbstractShapeOperation

How several named regions combine into one - ShapeUnion, ShapeIntersection or ShapeDifference.

Regions compose as geometries, not as rasters. A union of outlines is exact and independent of any grid, where combining rasterised masks would have to pick a resolution before the study grid was decided and would carry two sets of edge effects into the answer.

AbstractShapeSpec

A mask that is a piece of ground rather than data - ShapeSpec for one given as a vector file, NaturalEarthSpec for one given by name, ConstructedShapeSpec for several combined or one transformed.

What these share, and what the abstract type is for, is that they resolve to geometry before any grid exists. That is what lets them be combined exactly and at no resolution - a study area of your own, unioned with a country you named - where combining rasterised masks would have to fix a resolution before the study grid had been decided. It is the vector mirror of ConstructedRasterSpec, which composes rasters and so does need a grid.

AbstractSpatialRelation

How a named region may relate to something you have - Encloses, Overlaps or Within.

A relation carries the thing being asked about, so Encloses(mylayer) reads as what it means and there is no argument order to get the wrong way round. It is callable, taking a region's extent and answering whether the relation holds, which also makes it usable directly as a filter.

AbstractSpec

Abstract root of every build-time layer/mask recipe. A spec holds no grid array itself; materialise (or the data-driven resolvers) turns it into a real grid layer only at GridHabitat time. Two branches: AbstractLazySpec (data-backed, resolved against the target grid, usable as either a layer or a mask) and AbstractSyntheticSpec (self-contained generators, role-fixed).

AbstractSpecies

The species living in an ecosystem, and everything the model needs to know about them.

Species are what the simulation counts and moves. Each one brings a tolerance for every condition and a demand for every resource, so that it can be matched against the environment axis by axis; it disperses its offspring in its own way, and breeds and dies at its own rate. Those four things are what make one species behave differently from another in the same place.

Species do not currently interact directly. Two of them affect one another only by drawing on the same resource: their demands are summed against what a cell supplies, and everything present feels the result equally. There are currently no pairwise terms - no predation, no interference - so an assemblage is regulated entirely by what it collectively needs against what its surroundings provide.

AbstractSpeciesRequirement{R <: Role, A, V}

What a species brings to its environment on one axis: a tolerance for a Condition, or a demand for a Resource.

This is the species' half of the model, and the exact mirror of AbstractLayer. A species list holds the two requirements; a habitat holds the two layers; and they are matched role for role and axis for axis:

V is the species' own response type: the type of the values the requirement is stated in, so that it can be compared with the layer's. A temperature tolerance carries kelvin, a solar demand kilojoules per day, a land-cover tolerance the class codes it accepts. For a collection of requirements V is instead the members' NamedTuple, since there is no single one.

A follows AbstractLayer exactly, including that it is the axis structure rather than always a single axis. That symmetry is the point: a tolerance and the regime it is matched against carry the same A.

Write AbstractTolerance or AbstractDemand in preference to this. Each pins the role, so a demand cannot be used where a tolerance is meant. This name is for the rarer case of saying something true of both.

AbstractSupply{A}

A supply: what the environment provides, on one axis, in every cell - the Resource half of AbstractLayer.

A species meets a supply with its AbstractDemand on the same axis. Unlike a regime, a supply is shared: the demands of everything in the cell are summed against it, and that ratio is what regulates births and deaths.

AbstractSyntheticLayerSpec <: AbstractSyntheticSpec

Synthetic layer recipes - UniformSpec, GradientSpec, PeakedSpec, NicheSpec - used as a regime or supply, never as a mask.

AbstractSyntheticMaskSpec <: AbstractSyntheticSpec

Synthetic active-mask recipes - CircleMaskSpec - used only as an active mask.

AbstractSyntheticSpec <: AbstractSpec

Abstract supertype of the synthetic (generated, non-data) specs, split by role into AbstractSyntheticLayerSpec (regime/supply layers) and AbstractSyntheticMaskSpec (active masks).

AbstractTolerance{A, V}

A tolerance: how well a species copes with a Condition, across the range that condition can take - the species-side mirror of AbstractRegime.

A tolerance is what decides where a species can persist. Matched against the regime on the same axis, it yields that species' suitability in each cell, which raises its death rate where conditions suit it poorly and lowers it where they suit it well.

This is a parametric alias for AbstractSpeciesRequirement with the role pinned to Condition, and pinning it is what keeps the constraint real: a demand is not an AbstractTolerance, so every signature written against this name refuses one. eltype is inherited from the shared supertype.

AbstractTopology

The shape of the simulated world - how its edges join, if they join at all.

A property of the grid, held and set on GridHabitat, so every species on one grid shares it. The name promises no particular geometry: EdgeTopology is a rectangular lattice and is the only subtype at present, but a world that is not one can subtype this.

What becomes of an individual dispersing into a dead cell is a separate question, answered per species by disperse_safely on the movement rather than by the map.

ActiveCells() <: AbstractRegion - only the cells currently marked active.

AddAbundance(species, count)

Add individuals to each cell of the region - an invasion, or a reintroduction.

Arguments

• species: which species, by name or by index.
• count: how many per cell. An Integer is an exact number; a quantity per unit time is a mean rate, drawn afresh each step.

AddSpecies(tolerance = nothing, demand = nothing, dispersal = nothing,
           birth = nothing, death = nothing, abundance, name = nothing)

Introduce a new species - an invasion, a reintroduction, a crop sown for the first time - scattered across the intervention's region.

It carries the arrival's own traits, which is what it is for: an invader can be given a niche of its own rather than inheriting one. Any trait left as nothing clones the last species instead, which is what a plain reintroduction of something already present wants.

An existing species' dispersal can be handed straight over, since speciesdispersal returns exactly what dispersal takes:

AddSpecies(dispersal = EcoSISTEM.speciesdispersal(eco, 3), abundance = 500)

The recording has to have room. simulate_record! writes into an array sized before the run starts, so a run that gains species needs generate_storage(eco, times, reps, maxspecies = ...); see generate_storage. Not supported under MPI: species are partitioned across ranks, so adding one changes the partition itself, and unlike the abundance operations this is not rank-local.

Arguments

• abundance: how many individuals arrive in total, scattered over the region. The one required argument.
• tolerance, demand: the arrival's niche and its resource requirements. Cloned from the last species if omitted.
• dispersal: a dispersal kernel - a GaussianKernel or a LongTailKernel - matching build_species' keyword of the same name. Not an AbstractMovement: the movement type and the grid's edges belong to the whole assemblage, and only the kernel is per species.
• birth, death: the arrival's demographic rates.
• name: what to call it.

AdditiveFit{A, C} - a [`CombiningFit`](@ref) whose per-layer suitabilities are added.

AdditiveFit2{M1, M2} - two positional nichefits, added. Deprecated plumbing: use [`AdditiveFit`](@ref).

AdditiveFit3{M1, M2, M3} - three positional nichefits, added. Deprecated plumbing: use [`AdditiveFit`](@ref).

AdoptedFromLayers <: AbstractDecisionSource - a CRS adopted from the layers.

AgreedByAllLayers <: AbstractDecisionSource - a cell size every layer agrees on.

AllCells() <: AbstractRegion - every cell in the grid, active or not.

AllTerritories()

Take everything the name covers, however scattered.

This is faithful to the source and is what a political question usually wants: the territory of France really does include French Guiana. It is also what makes a selection able to span the antimeridian, since a country with territory either side of the date line has no single interval of longitude containing it.

Altitude <: NicheAxis - elevation above sea level (WorldClim Elevation; m).

AlwaysMovement{K <: AbstractKernel} <: AbstractMovement

Any individual may disperse, not only the newly born - animal-like.

Fields

• kernels: one AbstractKernel per species.
• disperse_safely: one flag per species, as described on AbstractMovement. Defaults to true for every species.

AsBuilt <: AbstractReportStage - an area as built: this describes a `GridHabitat` that exists.

AsInvestigated <: AbstractReportStage - an area as proposed: nothing has been built on it yet.

AtTime(time::Unitful.Time)

Fires on the single step that reaches time - the first step whose elapsed time is at or past it.

Reaches, not equals: elapsed time accumulates as a float and a run's steps need not land on time exactly, so an equality test would silently never fire. _current solves the same problem the same way for series slices.

Arguments

• time: the elapsed simulation time to fire at.

AtTimes(times)

Fires once for each of times, on the step that reaches each - AtTime repeated.

Arguments

• times: the elapsed simulation times to fire at.

AxisNode

One node of the layeraxes niche-axis tree: the axis type itself, the names of shipped layers that use it directly (an abstract grouping axis never carries a layer itself - only a concrete leaf does, so this is empty for every non-leaf node), and its children - the axis types immediately below it, each an AxisNode built the same way, recursively down to the concrete leaves.

BetweenTimes(from::Unitful.Time, to::Unitful.Time)

Fires on every step whose elapsed time lies in [from, to].

Arguments

• from, to: the inclusive elapsed-time bounds.

BirthOnlyMovement{K <: AbstractKernel} <: AbstractMovement

Only individuals that have just been born disperse - plant-like.

Fields

• kernels: one AbstractKernel per species.
• disperse_safely: one flag per species, as described on AbstractMovement. Defaults to true for every species.

Bounded <: AbstractBoundaryCondition - this axis does not wrap: it has real edges.

Brownian

A fitted Brownian-motion model of trait evolution, as returned by fitbrownian. Under it a trait wanders at random along every branch, so expected divergence grows with the time two lineages have been apart.

Fields of the concrete type EcoSISTEMPhyloExt.Brownian

• optimum: the maximum-likelihood parameters, [σ², z̄₀] - the diffusion rate and the inferred root state.
• se: their standard errors, from the Hessian; show prints each parameter with a ±2 SE interval.
• H: the Hessian of the negative log-likelihood at the optimum.
• LL: the log-likelihood there, for comparison against a competing model fitted to the same trait.

CERA <: EcoSISTEMSource

The CERA-20C reanalysis archive, as a data source. Read one with read(CERA, dir, file, param), which returns a ClimateRaster{CERA} - the archive is one file per decade, and the reader concatenates them along time.

Fieldless, as ERA is.

CRUTS <: EcoSISTEMSource

The CRU TS archive, as a data source. Read one with read(CRUTS, dir, var_name), which returns a ClimateRaster{CRUTS}.

CRU TS has no layer table of its own, so its variable codes and units are taken from WorldClim{Climate}'s.

Fieldless, as ERA is.

Cache

Cache houses an integer array of moves made by all species in a timestep for the update! function, netmigration.

CachedAsset(owner::Type, url::AbstractString)

An immutable descriptor for a file downloaded from url and cached under EcoSISTEM.assetdir(owner = owner). Nothing is downloaded at construction - call assetpath to get the local path, downloading it into the cache first if it is not there.

Fields

• owner: the type the download belongs to, which names its own subdirectory of the cache so that one type's downloads cannot collide with another's.
• url: where to fetch it from.

CachedEcosystem{Part <: AbstractHabitat, SL <: SpeciesList,
    NF <: AbstractNicheFit} <: AbstractEcosystem{Part, SL, NF}

CachedEcosystem houses the same information as Ecosystem (see ?Ecosystem), but holds the time period abundances as a CachedGridLandscape, so that they may be present or missing.

CachedEcosystem(eco::Ecosystem, outputfile::String, times::StepRangeLen;
                saveinterval::Unitful.Time = step(times))

Create a CachedEcosystem given an existing Ecosystem, eco, an output folder to which the simulations are saved, outputfile, and a range of times over which to simulate, times. The step of times is the simulation timestep; saveinterval controls how often checkpoints are written to disk (a multiple of the timestep, defaulting to every step). Because the simulation always advances by the timestep, results are independent of saveinterval.

CachedGridLandscape

A recorded run's abundances over time: one GridLandscape per timepoint, or missing where that point has not been computed yet.

How often checkpoints reach disk is separate from how often the simulation steps, and does not affect the answer: the run always advances by timestep, so saveinterval chooses only how much is kept.

Fields

• matrix: a DimArray over a Ti axis holding GridLandscapes and missings. Indexed by time value, which needs a selector - matrix[Ti(At(t))], not matrix[t], which is positional and an error for a Unitful.Time.
• outputfolder: where the JLD2 cache files are written.
• saveinterval: how often a checkpoint reaches disk. A multiple of timestep.
• timestep: the simulation step, and the granularity of the time axis.

CachedGridLandscape(file::String, times::StepRangeLen;
                    saveinterval::Unitful.Time = step(times))

Construct a CachedGridLandscape backed by a folder, with every timepoint still missing.

Arguments

• file: the folder the cache files are written to.
• times: every timepoint the run will cover. Its step size is the simulation timestep.
• saveinterval: how often a checkpoint reaches disk. Must be a multiple of the timestep, and defaults to saving every step.

CarbonAxis <: NicheAxis - carbon-cycle niche axes.

CarbonFlux <: CarbonAxis - net primary productivity, a carbon flux (BioClimPlus npp; g*m^-2*day^-1).

CategoricalLayer{A <: NicheAxis, V, Arr <: DimensionalData.AbstractDimArray{V, 2}, S <: Unitful.Quantity}

A categorical (class-code) grid layer on niche axis A - always a Condition (there is no categorical supply). matrix is a DimArray over (Y, X).

CategoricalRegime{V} - a categorical regime (a [`CategoricalLayer`](@ref), e.g. land cover), a `(Y, X)` `DimArray{V}`.

CategoricalSuitability{A, V} <: AbstractNicheFit{A, V}

The nichefit between a categorical trait on class labels of type V and its environment: it reports the weight the species' tolerance gives the cell's class.

Carries no fields, like every other leaf nichefit - the whole response, both the categories a species tolerates and the penalty it takes outside them, lives on the species side in an AbstractCategoricalTolerance. That is the same division as the continuous branch, where NicheTolerance holds the response distribution and NicheSuitability only evaluates it.

Soft and hard exclusion are therefore not different fits: they are different penalty values on the tolerance.

CellMask(mask::AbstractMatrix{Bool})

The cells where mask is true.

Arguments

• mask: a (Y, X) boolean grid, the same shape as the habitat's own.

CellNames{G} <: AbstractVector{String}

The names of a grid's cells - each the cell's own extent - computed on demand rather than stored.

Lazy because the eager form is what a grid this size cannot afford. Measured on a 1.2 million-cell grid: storing the names costs ~33 MB, against 8 bytes for this. That matters here specifically - a GridHabitat's active mask was deliberately squeezed from 10.3 MB to 0.14 MB for the same reason, and getspeciesstorage exists because these runs are bound by memory. Nothing in the simulation reads a cell's name; only output does.

Fields

• grid: the StudyGrid the names describe.

CircleMaskSpec(; radius, centre = nothing)

A circular active-area mask: the cells within a given distance of a point are simulated and the rest are not. Resolved onto the grid when the habitat is built.

Arguments

• radius: how far the circle reaches, as a physical distance (100.0km) rather than an angle.
• centre: where it is centred, as a LatLong. Defaults to the grid's own centre - and on a synthetic grid, which has no real-world coordinates, that default is the only thing supported, since a geographic centre could not be placed.

ClimateMoisture <: ClimateMoistureAxis - climate moisture index, precipitation minus potential evapotranspiration (Climate cmi, BioClimPlus cmi_max/mean/min; mm/day).

ClimateMoistureAxis <: WaterAxis - climate-moisture-index niche axes (level and range).

ClimateMoistureRange <: ClimateMoistureAxis - annual range of the monthly climate moisture index (BioClimPlus cmi_range; mm/day).

ClimateRaster{Source, Code, Array} <: AbstractClimate

Type for climate data derived from RasterDataSources.

Fields

array is the grid itself, a DimensionalData array over (Y, X) - plus a third dimension for a multi-layer or monthly read. Prefer to operate on the raster rather than reaching for this: a raster broadcasts and yields a raster, so lc .!= code and sum(bands) work directly, which is what lets a ConstructedRasterSpec combine avoid naming an array type at all.

code is the layer this holds, when it is one identifiable layer of its source - or nothing for a whole-dataset read or a raster derived by arbitrary arithmetic. It is what lets a materialised layer still be looked up in the shipped table, which iscategorical needs to know whether resampling it may interpolate: the answer lives in the ValueType column, per layer, and a source type alone cannot supply it (BioClimPlus holds all three value types at once).

Write it however reads best - 4, :bio4 or "bio4" - and it is stored as the one spelling that dataset prefers, via _preferredcode. So two rasters of one layer always compare equal, and a code naming no layer is refused here rather than surfacing later.

There is deliberately no valuetype field. Whether the values are class codes or measurements is a property of the layer's niche axis, and the axis lives on the spec that declares what the layer means - see iscategorical. A copy stored here could contradict it, which is the one thing a declaration must not be able to do.

ClimateTypology <: TypologyAxis - categorical climate-classification classes (BioClimPlus kg0-5: Köppen-Geiger, Wissmann, Thornthwaite, Troll-Pfaffen).

CloudCover <: CloudCoverAxis - total cloud cover (Climate clt, BioClimPlus clt_max/mean/min; dimensionless).

CloudCoverAxis <: NicheAxis - cloud-cover niche axes (level and range).

CloudCoverRange <: CloudCoverAxis - annual range of the monthly total cloud cover (BioClimPlus clt_range; dimensionless).

CombineOnSourceGrid <: AbstractCombineStage

Combine on the layers' own shared grid first, and sample the result onto the study grid.

Needed whenever the combine does not commute with regridding: one that looks beyond its own cell (a neighbourhood, a crop, an aggregation), and equally one that is cell-wise but nonlinear, since the ratio of two interpolations is not the interpolation of the ratio. Growing-season rainfall gsp / gsl is the case that matters: divided early it is a mean daily rate, divided late a total over a mean season length, and those are different quantities.

The layers must share one native grid, checked when they are read - combining across datasets of different resolutions has no meaning before either is resampled.

CombineOnTargetGrid <: AbstractCombineStage

Sample every layer onto the study grid first, and combine there - the default, and right whenever the combine commutes with regridding. It is what keeps compress_landcover interpolating the per-class percentages it is given rather than argmaxing them first and interpolating between the resulting class codes, which is meaningless.

spec1 + spec2
EcoSISTEM.CombinedChange(specs...)

Declare that a layer carries several changes at once, added together - a stored monthly series plus a multi-year trend, say, where the trend offsets the whole seasonal pattern.

Write it as a sum. That is the spelling this exists for, and the only one most callers need:

ReplaceWith(SeriesChange(monthly)) + IncrementBy(0.02K / year)

CombinedChange is the type a sum builds, and is supported (though unexported, so it needs qualifying) for the case a + chain cannot express - combining a collection whose length is not known when the code is written:

EcoSISTEM.CombinedChange(specs...)     # rather than `reduce(+, specs)`

Either way the parts are summed as functions of elapsed time, not applied one after another; see SumOfLayerChanges for which combinations are meaningful.

CombiningFit{A, F, C <: NamedTuple} <: AbstractNicheFit{A, C}

Several nichefits, one per environmental layer, together with the function that combines their per-layer suitabilities into the cell's one suitability. The fits are held by name in a NamedTuple, and must line up name for name with the regime and tolerance collections they are matched against; a Tuple is accepted and named by each member's own niche axis.

combine is handed the whole NamedTuple of results, not folded across them as a binary operator, so a rule that treats layers differently is expressible and reads by name:

CombiningFit((summer = ..., winter = ..., moisture = ...)) do s
    return (s.summer + s.winter) * s.moisture
end

MultiplicativeFit and AdditiveFit are the two everyone actually uses, and are aliases for combine = prod and combine = sum; over a tuple those are themselves unrolled folds, so they cost exactly what the */+ of the fixed-arity fit types cost.

Condition <: Role

What a cell is like - temperature, rainfall, land cover, elevation.

A condition is a state, not a stock. Every species in the cell experiences the same value; nothing is divided between them and nothing is used up. What varies is how well each species copes, which is what its AbstractTolerance says: a species with a narrow tolerance does well over a small range of the condition and poorly outside it.

Conditions therefore set where a species can persist. They do not, by themselves, limit how many individuals a cell can hold - that is what a Resource does.

ConstantAccumulationPeriod(duration)

One fixed interval for the whole layer - year for a heat sum, month_mean_duration for a layer whose month is unknowable. The stock->rate conversion is then a constant scale factor.

Fields

• duration: the interval itself, as a Unitful.Units - what an accumulated value is divided by to become a rate.

ConstructedRasterSpec(combine, layers...)

The universal lazy escape hatch: read each of layers onto the working grid, then apply combine to the resulting rasters. Because combine is the first argument it can be written as a do-block:

ConstructedRasterSpec(EarthEnv{LandCover}, :open_water) do water
    water .< 50   # a mask of cells less than half open water
end

layers are given as alternating dataset, code(s) - a RasterDataSources type followed by an Int/Symbol code, a vector/tuple of codes (several layers), or no code (a bare dataset => all its layers, e.g. every land-cover class band, passed to combine as one multi-band raster); a pre-built spec is also accepted directly - including a synthetic one, so a combine may mix generated layers with read ones. A bare dataset becomes a whole-dataset spec. With no layers, combine is a nullary thunk that produces the layer itself (reading a source directly, or wrapping a literal in-memory array).

combine takes rasters and must return a raster - one contract, whichever way the spec is later used, because that decision is made elsewhere and cannot be known where the combine is written. A mask is simply a raster whose element type is Bool, so the element type still distinguishes the two; only the container is fixed.

Nothing has to be wrapped or unwrapped to satisfy that: a raster broadcasts and yields a raster, as the example above shows, and sum(bands) over a multi-band combine does the same. So a combine names no array type at all, which is the point - the array type is an implementation detail, and a combine is user code.

Usable as a regime/supply layer or an active mask. Covers what the other specs don't: bespoke data, derived layers (anomalies, blends) and thresholded/combined masks. See hasdata and landcoverclass for ready-made combine building blocks. No data is read or downloaded at construction - only when materialised onto a grid (GridHabitat), mirroring SourceSpec; each layer's unit/axis is resolved from the shipped table eagerly, so an invalid code errors here rather than at materialise time.

combinestage says when combine runs - after its layers are put on the study grid (CombineOnTargetGrid, the default) or before (CombineOnSourceGrid). See AbstractCombineStage for which a given combine needs.

Fields

• combine: the rule itself - a function taking one raster per layer (none, for a thunk) and returning a raster.
• layers: the child specs to materialise and hand it, already normalised; empty for a thunk.
• combinestage: when the combine runs, as above.

axis is a type parameter rather than a field, as on SourceSpec - and on this type it is the only statement of what the result means, since a derived raster has no layer code to resolve one from. That includes whether the result holds class codes: there is no valuetype keyword, because a TypologyAxis says the values are class labels and so must be resampled by nearest class, while any other axis says they may be interpolated. A separate declaration could only agree with the axis or contradict it.

ConstructedShapeSpec(operation, members...; coverage = AllTerritories(), outline = true)

Combine several named regions into one mask - the union of the United Kingdom, Ireland and the Isle of Man, or a country with an island group cut out of it.

Regions combine as geometry, so the result is exact and carries no resolution of its own: the grid is still decided afterwards, and nothing is rasterised twice.

# The British Isles, including Shetland - which Natural Earth's own polygon of that name omits
ConstructedShapeSpec(ShapeUnion(),
                   NaturalEarthSpec("United Kingdom", coverage = AllTerritories()),
                   NaturalEarthSpec("Ireland", level = "ADMIN"),
                   NaturalEarthSpec("Isle of Man", level = "ADMIN"),
                   coverage = LandmassesAbove(1km^2))     # ...and without Rockall

Arguments

• operation: how they combine - ShapeUnion, ShapeIntersection or ShapeDifference, the last taking every later member away from the first.
• members: two or more region specs, either NaturalEarthSpecs or nested ConstructedShapeSpecs.
• coverage: which components of the result to keep, applied after the operation - AllTerritories by default, since a combination usually means all of what it built.
• outline: as NaturalEarthSpec - false activates the result's bounding box instead of its outline.

ContinuousLayer{R <: Role, A <: NicheAxis, V <: Number, Arr <: DimensionalData.AbstractDimArray{V, 2}, S <: Unitful.Quantity}

A continuous (numeric) grid layer of role R on niche axis A, holding a value matrix (eltype V) as a DimArray over (Y, X) - real Projected/Sampled lookups for a data-driven source, NoLookup for a synthetic one (see data/architecture.md).

A layer holds one grid of values, never a stack of them: a time-varying layer holds the values current now and carries a SeriesLayerChange as its change, which decides from elapsed time which stored slice that is. The array bound says 2 to keep it that way - the stack and the cursor that walked it were what made a layer's own state ambiguous.

ContinuousRegime{V} - a static continuous regime (a `Condition`-role [`ContinuousLayer`](@ref) over a `(Y, X)` `DimArray{V}`).

ContinuousTolerance{A, V <: Number} <: AbstractTolerance{A, V}

A species' preference along a continuous niche axis, where suitability falls off with distance from an optimum rather than being a matter of membership. NicheTolerance is the concrete type; the matching layer is a ContinuousRegime.

CumulativeHeat <: TemperatureAxis - accumulated growing degree-days above a threshold (BioClimPlus gdd0/gdd5/gdd10; K*day).

Cylinder = EdgeTopology{Bounded, Periodic}

A cylindrical grid: the east-west (X) edges join, the north-south ones do not. The parameter order is {Y, X}, so Bounded comes first - X is the axis that wraps.

On a grid with a real-world position a wrapping X is right only where the grid spans the whole longitude sweep, and is warned about otherwise. Where it does span it, Cylinder is exact rather than an approximation, and it is the only wrapping topology that can be: a wrapping Y is never right, because latitude does not wrap however wide the grid.

DatedSeries(start::Dates.TimeType)

Slices carry real dates, start being the first slice's. The epoch places the series directly: the slice current at elapsed zero is the one covering the epoch's own date.

Inferred from a source whose Ti lookup holds Dates values, so it is rarely written by hand.

DayAxis <: NicheAxis - day-based phenology niche axes (day-of-year positions and day counts; day).

DayCount <: DayAxis - a number of days: growing-season length, snow-cover days or days above a threshold (BioClimPlus gsl/scd/ngd*; day). Counts days rather than measuring a spread, so deliberately not named `*Range` as every genuine max-min axis is.

DayOfYear <: DayAxis - an ordinal day-of-year: first/last growing day or first/last day above a degree-day threshold (BioClimPlus fgd/lgd/gdgfgd*/gddlgd*; day).

Deactivate() <: AbstractOperation

Destroy the region's cells: everything living there dies, and nothing grows there again until the cells are reactivated.

Killing is the point, not a side effect. A deactivated cell is skipped entirely by the hot loop, so anything left in it would neither breed nor die - a frozen population with no ecological meaning. Left alive, stranded individuals come to outnumber the living, because they hold their numbers while the real population turns over around them.

Reactivate does not bring them back, and should not: it makes the cell habitable again so that dispersal can recolonise it, as vegetation returns to a slag heap once it stops being used.

DefaultEcosystem

Marker selecting opt-in defaults for the builders. build_habitat(DefaultEcosystem(); ...), build_species(DefaultEcosystem(); ...) and build_ecosystem(DefaultEcosystem(); ...) fill any omitted required input from a defaults table - announcing each choice with an @info - then delegate to the strict builder. Use it to spin up a fully-parameterised runnable toy ecosystem, or to fill in only the required inputs you do not care about while passing the rest explicitly.

Demand{A <: NicheAxis, V, X} <: AbstractDemand{A, V}

What each species takes from the shared pool on one niche axis - the Resource mirror of a tolerance, and one of the two halves that must line up with the environment.

Name the axis to build one, Demand{SolarRadiation}(values). The values are converted to that axis's own canonical resource unit - kJ/day for SolarRadiation, L/day for Precipitation, g/day for CarbonFlux - so any scale of the right dimension is accepted, while a wrong dimension, or an axis that declares no resource at all, is refused at the call rather than deep in the simulation loop.

Fields

• resource: one demand per species, in the axis's canonical unit.
• exchange_rate: what a demand is measured against. Defaults to 1/mean(resource), so a species' demand is read relative to the assemblage it is part of rather than as an absolute. It scales birth and death equally, so it sets the tempo of turnover without moving any equilibrium.

Type parameters

• A: the niche axis these demands are stated on.
• V: the value type, which follows from canonicalunit(Resource, A).
• X: the exchange rate's type, the inverse of V.

DemandCollection2{M1, M2} - two positional demands. Deprecated plumbing: use [`SpeciesRequirementCollection`](@ref).

DerivedData{S}

Source of a raster computed from S but no longer S - the result of a ConstructedRasterSpec combine, or of an operation like compress_landcover that turns a dataset's layers into a quantity that is none of them. Summing eight land-cover bands does not give land cover, and what the result means comes from the spec's declared axis rather than from its inputs, so DerivedData{EarthEnv{LandCover}} records the lineage without claiming to be it.

Never write this type out - call _derivedfrom(S), which is what collapses nesting. Deriving from derived data is still just derived data, and no consumer asks how many steps there were; but DerivedData{DerivedData{S}} stays constructible, so the collapse is that function's job and not the type's.

S is a phantom parameter, never instantiated: it appears only as ClimateRaster's first type argument.

DiversitySet

Diversity measurements recorded from a CachedEcosystem over a run, held alongside the folder its cached abundances were written to.

Fields

• data: the measurements so far, or missing before any have been taken.
• folder: where the cached abundances live, which is also where results are read back from.
• times: every timepoint diversity is wanted at. gettimes narrows this to the ones not yet computed.

DiversitySet(cache::CachedEcosystem, times::Vector{T}) where T <: Unitful.Time

Construct a DiversitySet from a CachedEcosystem, initialising it with the cache output folder and a vector of timepoints times for which diversity is to be recorded.

ERA <: EcoSISTEMSource

The ERA5 reanalysis archive, as a data source. Read one with read(ERA, file, param), which returns a ClimateRaster{ERA}.

Fieldless: a source names where data came from, and the data itself lives in the ClimateRaster that carries it.

EcoSISTEMSource

Abstract supertype of the sources this package defines itself, for rasters that come from no dataset - see SyntheticData and DerivedData.

Ecosystem{Part <: AbstractHabitat} <:
   AbstractEcosystem{Part, SL, NF}

Ecosystem houses information on species and their interaction with their environment. For species, it holds abundances and locations, as well as properties such as trait information, spplist, and movement types, lookup. For environments, it provides information on environmental conditions and available resources,habitat. Finally, there is a slot for the nichefit between the environment and the characteristics of the species, nichefit. elapsed is the simulation clock (see simulationtime) and seed the seed the per-species RNG streams were derived from. epoch is the real date elapsed time zero corresponds to, or nothing for a run with no calendar - see simulationdate.

```julia Ecosystem{Part <: AbstractHabitat} <: AbstractEcosystem{Part, SL, NF} ``` Ecosystem houses information on species and their interaction with their environment. For species, it holds abundances and locations, as well as properties such as trait information, `spplist`, and movement types, `lookup`. For environments, it provides information on environmental conditions and available resources,`habitat`. Finally, there is a slot for the nichefit between the environment and the characteristics of the species, `nichefit`. `elapsed` is the simulation clock (see [`simulationtime`](@ref)) and `seed` the seed the per-species RNG streams were derived from. `epoch` is the real date elapsed time zero corresponds to, or `nothing` for a run with no calendar - see [`simulationdate`](@ref).

```julia Ecosystem(spplist::SpeciesList, habitat::GridHabitat, nichefit::AbstractNicheFit) ``` Create an `Ecosystem` given a species list, an abiotic environment and trait nichefit. An optional population function can be added, `popfun`, which defaults to generic random filling of the ecosystem. A `seed` may be supplied to make the run reproducible: it deterministically seeds one random number generator per species (see [`makerngs`](@ref)), so results are identical regardless of the number of threads used. If no `seed` is given, one is drawn at random.

Ecosystem(spplist::SpeciesList, habitat::GridHabitat,
    nichefit::AbstractNicheFit)

Create an Ecosystem given a species list, an abiotic environment and trait nichefit. An optional population function can be added, popfun, which defaults to generic random filling of the ecosystem. A seed may be supplied to make the run reproducible: it deterministically seeds one random number generator per species (see makerngs), so results are identical regardless of the number of threads used. If no seed is given, one is drawn at random.

EdgeTopology{BCY, BCX} <: AbstractTopology
EdgeTopology(; y, x)

The topology of a rectangular grid: one AbstractBoundaryCondition per axis.

Three of the four combinations have names of their own - Torus, Cylinder and Island - and those are the usual way to write them. The keyword form is for the fourth, which has no ecological name.

Arguments

• y: the boundary condition for the rows - northing on a projected grid - given as a type, EdgeTopology(y = Periodic, x = Bounded).
• x: the same for the columns, easting.

Type parameters

• BCY, BCX: those two conditions, in that order. (y, x) throughout the package, matching DimensionalData's own Y/X dims.

Encloses(x)

Regions that completely contain x.

Answers "which named regions is my data inside?", and is the relation investigate_regions uses when none is named. It is the only one that accepts a point, since nothing can lie within a point and nothing overlaps one.

Arguments

• x: what to ask about - a study area or its report, a raster, a layer, a habitat, an ecosystem, an Extents.Extent, a LatLong, or a match from an earlier report.

EqualPop{U <: Unitful.Units} <: AbstractParams

Demographic rates shared by every species: one birth rate and one death rate for the whole assemblage. equalpop expands it into a PopGrowth once the number of species is known.

Fields

• birth, death: the rates, per unit time, the same for every species.
• longevity, survival: the two exponents described in AbstractParams.
• boost: the ceiling on the birth multiplier where resources are abundant.

ErrorAtEnd <: AbstractSeriesEnd - running past the last slice is an error. The default.

Evapotranspiration <: EvapotranspirationAxis - potential evapotranspiration (Climate pet, BioClimPlus pet_penman_max/mean/min; mm/day).

EvapotranspirationAxis <: WaterAxis - evapotranspiration niche axes (level and range).

EvapotranspirationRange <: EvapotranspirationAxis - annual range of the monthly potential evapotranspiration (BioClimPlus pet_penman_range; mm/day).

EveryStep() <: AbstractSchedule - fires on every timestep.

FrostChangeFrequency <: TemperatureAxis - frost change frequency, the number of days the temperature crosses 0 °C (BioClimPlus fcf; dimensionless).

Gauss{A, V} <: AbstractNicheFit{A, V}

GaussianKernel(dist::Unitful.Length, thresh::Float64)

A dispersal kernel whose distances are Rayleigh distributed - the two-dimensional case of dispersing a Gaussian displacement in each direction independently.

Fields

• dist: the species' dispersal distance, converted to kilometres on construction.
• thresh: the probability below which a destination is dropped, which is what bounds the lookup table to a finite neighbourhood.

GivenByUser <: AbstractDecisionSource - you supplied it.

GradientSpec{A <: NicheAxis, V}

A layer whose value runs linearly across the grid.

The pattern is fixed in space and does not change of itself; wrap the spec in Varying to give it a change in time.

Arguments

• low, high: the values at the two ends. low must be strictly less than high.
• axis: the niche axis this layer is on, as UniformSpec. Required.
• orientation: which way the gradient runs, as a compass bearing clockwise from North. 0°, the default, runs south to north; 90° west to east; 180° north to south; and so on for any bearing between. Must be a real angle Quantity - 90°, or (pi/2)rad - since a bare number would be read as radians by Unitful's own counter-intuitive convention. Stored in degrees, so the type is not parametric on the angle unit.

GridHabitat(; regime::Union{LayerInput, AbstractRegime},
    supply::Union{LayerInput, AbstractSupply}, area::StudyArea,
    topology::AbstractTopology = Island())

Build an abiotic environment on an already-decided grid.

All three inputs are required. regime (the environmental Condition layer) and supply (the Resource layer) are each an AbstractSpec - a synthetic layer (UniformSpec/GradientSpec/PeakedSpec/NicheSpec), a SourceSpec, a ConstructedRasterSpec, or a tuple of 2-3 of these for a multi-variable environment. area is the StudyArea that decided the grid - its CRS, extent, cell size and active mask - which is where every geometric choice lives:

area = StudyArea(regime = cultivated, within = coastline, crs = EPSG(27700), cellsize = 5km)
env  = GridHabitat(regime = cultivated, supply = sunlight, area = area)

Use investigate_study_area first to see the grid, what it costs each layer and what it warns about, before committing to it. Omitting a required input errors - use build_habitat to fill omissions with announced defaults.

The area fixes the frame; the layers can only shrink activity. Nothing here chooses a grid: this samples regime and supply onto the area's, and where a layer has no data the cell is marked inactive. A layer that was not named when the area was decided can therefore remove cells but never move or resize the grid - so the area you inspected is the area you get - and doing so warns. Name a layer in StudyArea(...) if you want it to shape the grid; omit it and it can only subtract.

This is the type's only constructor. A habitat is described by the layers it should have and the grid they sit on; there is no form taking already-assembled parts, so new is reachable from exactly one place.

Fields

• regime: the Condition layer(s) of type H - what each cell is like.
• supply: the Resource layer(s) of type B - what each cell provides.
• active: a boolean (Y, X) DimArray marking which cells are simulated.
• topology: how the grid's edges join - see EdgeTopology.
• area: the StudyArea this habitat sits on, carrying both the StudyAreaReport it was built from - stamped AsBuilt and refined by whatever the build changed - and the StudyGrid it was actually built on. The report's active is the mask the habitat started with, so comparing it against the live active above says what the simulation has done since.

GridLandscape

An ecosystem's abundances: how many individuals of each species are in each cell. The same numbers are held under two names, as two views of one block of memory, because the simulation asks two different questions of them - the hot loop walks species against flat cells, while inspecting or seeding a run wants to say where.

Immutable, and that is what makes the two views agree: the only way to change shape is to build a new GridLandscape and reassign the whole field holding it, so they cannot drift apart.

Fields

• matrix: species against flat grid cell, with no Y/X structure - the per-timestep access pattern, and a plain Matrix{Int64}.
• grid: species against Y and X, a plain Array{Int64, 3} sharing matrix's memory.
• dimmatrix: matrix as a (Dim{:species}, Dim{:location}) DimArray, carrying real species names and, for each flat cell, its extent - [0.0, 1.0) x [0.0, 1.0) km.
• dimgrid: grid as a (Dim{:species}, Y, X) DimArray, with Y and X the habitat's own dimensions - real coordinates as Unitful lengths, or degrees on a geographic grid.

dimmatrix's cell descriptors are computed on demand from the grid rather than stored: the lookup holds a grid reference and nothing else, so it costs the same few bytes whether the grid has a hundred cells or a million. Selecting by descriptor scans, so it suits inspection rather than bulk work; dimgrid's Y and X are Sampled and select directly.

The raw arrays and the labelled views are the same memory, and both are stored on purpose. The hot loop reads matrix; asking which species or where reads dimmatrix/dimgrid.

The raw fields are what make the hot loop free, and the reason is not obvious. Ecosystem declares abundances::GridLandscape - the bare UnionAll, an abstract field. Julia can still infer a field of that container concretely provided the field's declared type does not mention the type parameters, which is exactly why matrix::Matrix{Int64} is written out rather than left as one of the parameters. Measured: reaching the labelled view through the abstract field costs about 176 bytes per cell and grows with the grid; reading the raw field is 0. Declaring these two fields in terms of Am/Ag would silently undo that.

GridLandscape(sl::SavedLandscape, names::Vector{String}, grid::StudyGrid)

Restore a GridLandscape from a SavedLandscape, putting its bare abundance matrix back onto dimensions.

Arguments

• sl: the saved abundances.
• names: the species names, from the ecosystem being restored into.
• yx: that ecosystem's Y and X dimensions.

The saved random number streams are restored separately, by the caller that already holds the ecosystem to put them in.

GrowingSeasonPrecipitation <: WaterAxis - precipitation accumulated over the growing season (BioClimPlus gsp; L*m^-2).

Heterogeneity <: NicheAxis - spatial habitat-heterogeneity metrics of EVI (EarthEnv HabitatHeterogeneity; dimensionless).

HoldAtEnd <: AbstractSeriesEnd - the last slice persists for the rest of the simulation.

HumidityAxis <: WaterAxis - atmospheric-water niche axes (vapour pressure, its deficit, relative humidity).

IncrementBy(shape)

Declare that shape's values are rates: they are accumulated into the layer, in its unit per unit time.

Arguments

• shape: a rate, in the layer's unit per unit time. This is the one recipe that accepts a bare constant, which gives a steady drift.

Intervention(schedule, region, operations...)

A declared change to the ecosystem - as against an AbstractLayerChange, which changes a single layer. The parts answer when (AbstractSchedule), where (AbstractRegion) and what (AbstractOperation):

Intervention(AtTime(50year), RandomCells(20), Deactivate())
Intervention(EveryStep(), AllCells(), SetChange(:rainfall, IncrementBy(-0.1mm/day/year)))

Several operations share one resolved region, applied in the order written - clear an area and plant a crop on it, or reactivate a site and restock it:

Intervention(AtTime(10year), RandomCells(20), Deactivate(), AddAbundance(:wheat, 500))

That sharing is the whole reason for the varargs, and it cannot be had from two interventions in a set: each resolves its own region, and a random one draws its own cells from its own stream (k is its index in the set), so two RandomCells(20) would pick different cells. A region that must be acted on twice has to be resolved once.

Pass one, or an InterventionSet, as simulate!'s intervention keyword.

InterventionSet(interventions...)

Several Interventions applied in the order written, every step. Any number of them, of any kinds, including several of the same kind.

IsRasterData{X}

Trait marking a type as one that may name a raster's data source.

Marking an abstract type covers its whole subtree, so RasterDataSources' hierarchy and this package's own each take one line. A third party's raster type needs one @traitimpl line and no change here, which is the point of a trait rather than a supertype bound.

Island = EdgeTopology{Bounded, Bounded}

A grid with hard edges: neither pair joins. The default on every grid.

A step past an edge is treated exactly as a step into a dead cell, so what becomes of it is answered per species by disperse_safely. With its default of true the blocked weight is redistributed among the reachable destinations, making the edge reflecting rather than absorbing.

Isothermality <: TemperatureAxis - isothermality, 100 * (mean diurnal range / annual range) (BioClim 3; dimensionless).

LandCoverTypology <: TypologyAxis - categorical land-cover / land-use classes (EarthEnv LandCover 1-12).

LandmassesAbove(threshold)

Take every connected piece of ground the name covers that clears threshold.

This is the coverage for "everything except the specks": the United Kingdom without Rockall, which LargestLandmass can only express by counting components and so needs to know how many there are. Rockall is 0.031 km2 and the next smallest British component is 2.536 km2, an eighty-fold gap, so any threshold between them does the same thing.

Unlike the other coverages this one cannot be answered from the shipped region table, which records only the largest few components' sizes - so boundingbox refuses it, while a spec built onto a real grid has the geometry and can.

Arguments

• threshold: how big a component must be to be kept, either as an area (1km^2, 500u"m^2") or as a share of the region's own total (5percent, from Unitful). A share is the more portable of the two, since what counts as a speck depends on how big the region is: the same 1km^2 keeps every part of Great Britain and discards most of the Maldives.

  A share must be written as a percentage rather than as a bare number. 0.05 and 5percent are the same quantity, but only one of them says which it means when read beside 1km^2, and a bare number is refused for that reason.

LargestLandmass(count::Integer = 1)

Take only the count largest connected pieces of ground the name covers.

Dissolving a selection and keeping its largest connected component is what turns "France" into France continentale, "United Kingdom" into Great Britain and "Scotland" into the Scottish mainland, without an area threshold or a hand-written list of exceptions. It is the largest component rather than the largest part: components are measured after neighbouring features have been merged, so a continent comes out as its mainland rather than as its largest country.

A landmass selected this way cannot cross the antimeridian, because Natural Earth splits its polygons at the date line and so no single connected component spans it.

The count is a keyword rather than a positional argument, unlike the sibling RandomCells and SpreadingCells. Those name a plural, so a bare number attaches to it and RandomCells(20) reads as twenty cells; this one names a single landmass, so a bare number would attach to nothing and could as easily be read as an ordinal. Naming it at the call site is what says which was meant.

Arguments

• count: how many components to keep, largest first. A count beyond the number of components returns all of them, so LargestLandmass(count = 2) on a single-component region is the region.

LatLong(lat, long)
LatLong(; lat, long)

A geographic point in Unitful degrees, validated on construction: LatLong(50.0°, -3.0°). Latitude must lie in [-90°, 90°] and longitude in (-180°, 180°].

A region is an Extents.Extent rather than one of these - Extent(Y = (54.6°, 58.7°), X = (-6.2°, -1.8°)). That is the bounding-box vocabulary the whole Julia geo ecosystem shares, and reusing it beats a parallel type of our own.

Reach the components with getlat and getlong. It implements the GeoInterface PointTrait, with the usual X = longitude, Y = latitude order, stripped to plain degrees.

LayerAggregated(factor)

The layer is combined factor source cells to a target cell - still exact, no interpolation.

LayerCache()

Hold the raw source reads made while deciding a StudyArea, so that refining an area does not read the same layer twice.

Only raw reads are cached, never anything reprojected onto a grid, which would be wrong to reuse for a different area. Downloads are already cached on disk, so what this saves is decoding rather than fetching.

Fields

• reads: the reads so far, keyed by what determines their content.

LayerCollection{R <: Role, A, C <: NamedTuple}

Several layers of the same role R over one grid (e.g. temperature + rainfall) and over the axis structure A, held by name in a NamedTuple, (Temperature = ..., Precipitation = ...). Sub-layer types stay concrete in the backing's own type, so the hot loop is exactly as type-stable as the fixed-arity named fields it replaces, and the arity is limited only by what the caller writes.

Layers are named by their axis, so a Tuple is accepted and named for you; two layers on the same axis cannot be told apart that way and are refused, asking for explicit names.

Layers are reached through the standard container interface - lc.Precipitation, lc[1], lc[:Precipitation], keys, values, pairs, iterate, length, merge and NamedTuple(lc), all forwarded to the backing (src/collections.jl). A single layer answers identically, as a one-member container.

LayerKeptExactly <: AbstractLayerFate - the layer is copied onto the grid, cell for cell.

LayerPlan

One layer's place in a study area: where it is, and what the chosen grid costs it.

Fields

• name: the layer's name.
• crs, step, bounds: where the layer is, in its own coordinates. Stated that way so that the three agree with each other and are exact - an extent re-expressed in a distant CRS need be neither.
• kind: what the target grid does to it, as an AbstractLayerFate, which carries the aggregation factor or the reason for resampling along with it.

LayerRecord

A single layer's catalogue entry: its dataset (the table basename, e.g. :BioClim), code aliases (the ;-separated Code, e.g. ["1", "bio1"]), name, definition, physical unit (NoUnits if dimensionless), axis (a NicheAxis type, or nothing if unclassified), the sources that provide it (the full list of supporting RasterDataSources), the numslices the code expands to, its temporal native reporting period - a genuine Unitful.Units time unit (day/month_mean_duration/year), or nothing for a static/non-time-varying value - its valuetype, and its category. Returned by layerinfo / layersbyaxis.

category says what kind of quantity the layer is - :instantaneous, :range, :rate, :count, :stock, :balance or :categorical - which is a different question from valuetype and not derivable from it. It is the only machine-readable record of the rate-vs-level distinction, the one canonicalunit(::Type{<:Precipitation}) got wrong.

publishedscale is the factor a provider ships the layer at when that is not the documented one - 100 for bio4 and 10 000 for the fourteen HabitatHeterogeneity layers, blank everywhere else. It is divided out on read, so values arrive at the order of magnitude the source's own documentation claims. It lives in the catalogue rather than in code deliberately: the correction is then visible to layerinfo as documentation and applied as behaviour, instead of being buried in a reader. The test guarding it is inverted - it fires when the upstream data is repaired, since a test asserting the data is still broken is what tells us the workaround can go.

The remaining fields carry the rest of the shipped table so that no column is dead data: officialunit (the source's own documented unit string, against which unit is our Unitful reading), notes, and the file-specific group (BioClimPlus) and order (HabitatHeterogeneity), each nothing where the table has no such column. UnitDimension is deliberately validated rather than stored, because it duplicates dimension(unit) and could only drift.

Two columns have been removed from the shipped tables outright, on the same reasoning: a column that cannot disagree with what we already know is not a check, it is a second place to get wrong. IsRate said exactly category === :rate in all 139 rows. LandCover's Filename (full version)/(reduced version) held consensus_full_class_N.tif / Consensus_reduced_class_N.tif - precisely what RasterDataSources' own rastername computes from the class number, down to its odd lower/upper-case asymmetry, so we were duplicating another package's convention and would not have noticed it changing.

period is the interval the value accumulated over - an AbstractAccumulationPeriod, or nothing where none applies. It is a different question from temporal: temporal is how often the layer is sampled, twelve monthly slices, while period is what each value accumulated over. For prec those are both months and the difference does not show; for srad they differ, sampled monthly and accumulated per day; and for a single-slice layer such as bio13 there is no sampling at all.

valuetype is :categorical, :discrete or :continuous, and the distinction that matters is categorical against the other two, not the names' everyday senses: a :discrete layer (a day-of-year, or a count of growing-degree days) is an ordinary number that may be averaged, while a :categorical one is a class code - Köppen-Geiger and friends, kg0-kg5, the only six in the shipped tables - where the arithmetic mean of two classes is meaningless. Anything resampling a layer must therefore pick nearest-class (:mode) for :categorical and may interpolate the rest.

So :discrete is descriptive metadata, not a switch: every consumer in the package tests === :categorical, and nothing anywhere reads :discrete. It is kept because it is honest about the source data - gsl really does count whole days - but a three-way column is a two-way split in practice, and a layer marked :discrete becomes an ordinary ContinuousLayer that is interpolated like any other number. Do not add behaviour keyed on it without deciding that question first.

LayerResampled(reason)

The layer is interpolated onto the grid, introducing uncertainty - the thing the whole alignment story exists to avoid. reason says why it was unavoidable.

LegacyLoss{V} <: AbstractLayerChange{NoChange}

Carries the loss rate of the deprecated HabitatLoss change function. Its mode is NoChange: the rate is a plain per-time probability, in no way the layer's own unit.

Transitional, and not a layer change at all. Habitat loss mutates the ecosystem - supply and abundances - from a layer's change slot, and draws randomly while doing it, so it satisfies neither invariant the other changes do. It survives only to keep HabitatLoss callable, and is superseded by an explicit cell-deactivating intervention.

LongTailKernel(dist::Unitful.Length, shape::Float64, thresh::Float64)

A dispersal kernel with a heavier tail than GaussianKernel's, so that rare long-distance dispersal is not effectively impossible.

Fields

• dist: the species' dispersal distance, converted to kilometres on construction.
• shape: how heavy the tail is. Smaller values reach further.
• thresh: the probability below which a destination is dropped, which is what bounds the lookup table to a finite neighbourhood.

Lookup

One species' dispersal neighbourhood, precomputed once and read by the hot loop: every destination its kernel can reach, as an offset from the source cell, with the probability of landing there.

The last two fields are scratch, rewritten on every cell of every timestep. Holding them here rather than allocating them per call is what keeps the movement step allocation-free.

Fields

• y, x: the destination offsets, relative to the cell dispersing. In that order, as everywhere else in the package.
• p: the kernel's probability for each, fixed for the run.
• pnew: those probabilities renormalised over the destinations actually available from this cell.
• moves: how many individuals go to each destination this step.

MPIEcosystem{MPIGL, Part, SL, NF} <: AbstractEcosystem{Part, SL, NF}

An Ecosystem whose abundances are distributed across MPI ranks; EcoSISTEMMPIExt supplies the concrete MPIEcosystem.

Only the abundances are split. The habitat, species list and nichefit are held whole on every rank, and four extra fields record which slice of the work this rank owns.

Fields

• abundances: the distributed MPIGridLandscape, in place of a GridLandscape.
• sppcounts, firstsp: how many species each rank holds, and the first one this rank holds.
• sccounts, firstsc: the same two, for grid cells.
• spplist, habitat, nichefit, lookup, cache, rngs, elapsed, seed, epoch: as Ecosystem, and identical on every rank. The epoch must be, or layers built redundantly per rank could phase their series differently.

Type parameters

• MPIGL: the MPIGridLandscape type holding the abundances.
• Part, SL, NF: habitat, species list and nichefit, as AbstractEcosystem.

MPIGridLandscape

An MPIEcosystem's abundances, distributed across MPI ranks; EcoSISTEMMPIExt supplies the concrete MPIGridLandscape{RA, NT}.

The same abundances are held twice, partitioned two different ways, because the simulation needs a different split at different moments - demographics is per species, dispersal is per cell. The synchronise steps copy between the two views.

Fields

• rows_matrix: this rank's species over all grid cells.
• cols_vector: all species over this rank's grid cells, flattened.
• reshaped_cols: cols_vector seen as one species-by-cell view per MPI block, which is what the collective operations address.
• rows_tuple, cols_tuple: how each view is partitioned - total, first, last, and the per-rank counts.
• dimgrid: the species this rank owns, by name, against the habitat's real Y and X. rows_matrix covers every cell, so the map is complete and the coordinates mean what they say.
• dimcols: every species, by name, against the global indices of the cells this rank owns. cols_vector is stored one block per contributing rank, because that is what the collective produces; this presents those blocks as a single ordinary matrix without copying. Those cells are a run of the flat ordering rather than a rectangle, so there is no Y/X view of them.

One labelled view per partition, each in the shape that partition naturally has - there is no flat twin of dimgrid, because unlike a serial landscape, which has two raw arrays and gives each a counterpart, this side has only rows_matrix. They matter more here than they do serially, where the matrix simply is the whole run: a rank holds only a slice, and these say which one. They are views of the same memory, so a write through either is seen by the raw fields and vice versa.

The raw fields are what the simulation uses. A scalar index into dimcols has to find its block first, which is markedly slower than walking reshaped_cols, so it is for inspection rather than for the loop.

MeasuredAcrossProjection <: AbstractDecisionSource - a cell size measured across the projection, no layer being in the target CRS.

MonthOfYearSeries()

Slices are months of the year with the year unknown - a monthly climatology. The epoch selects the slice matching its own calendar month, so a run beginning in July starts on the July slice rather than on slice one.

Matching is by month number, never by elapsed duration into the year. The slices are spaced by month_mean_duration (30.44 d), so six of them reach day 182.6 while the real 1 July is day 181 - proportional matching would land a July epoch on the June slice.

MultiplicativeFit{A, C} - a [`CombiningFit`](@ref) whose per-layer suitabilities are multiplied.

MultiplicativeFit2{M1, M2} - two positional nichefits, multiplied. Deprecated plumbing: use [`MultiplicativeFit`](@ref).

MultiplicativeFit3{M1, M2, M3} - three positional nichefits, multiplied. Deprecated plumbing: use [`MultiplicativeFit`](@ref).

NaturalEarthLevel

One kind of named region: which Natural Earth file defines it, and which attribute of that file carries the name.

Levels are what make a name unambiguous. "Africa" is a cultural CONTINENT of 55 countries and a UN REGION_UN of 62, with different members and different extents, so a name is always looked up at a stated level.

Fields

• name: the level's own name, as it is written in the shipped region table.
• dataset: the Natural Earth file it comes from, without the .zip extension.
• category: "cultural" or "physical", the source's own division and the directory it publishes each file under.
• field: the attribute of that file whose values name a region at this level.
• kind: what sort of division it is - :political, :statistical, :physical or :code.
• description: what the level means, and where it is likely to surprise.
• within: an attribute and value restricting which features belong to this level, or nothing where the whole file does. The physical file holds every kind of landform in one layer, so its levels are distinguished this way.

NaturalEarthSpec(name::AbstractString; level = nothing, coverage = AllTerritories(),
                 outline = true)

Name an active-area mask as a named region - a country, a continent, an island - without reading anything. The polygons are fetched and cut to the grid when the spec is materialised, as for ShapeSpec.

The name is resolved against the shipped region table at construction, so a name that does not exist is an error where it was written rather than minutes later mid-build. It is resolved by exactly the rule boundingbox uses, which is what makes the box that function reports the box this spec's shape actually has.

Arguments

• name: the region's name, matched case-insensitively but otherwise as Natural Earth spells it.
• level: which kind of region the name means - "ADMIN" for a country, "Physical Island" for a landmass; EcoSISTEM.naturalearth_levels() lists them. Only needed where a name means genuinely different ground at different levels, and the error says so when it does.
• coverage: how much of what the name covers to take - AllTerritories, the default and what the source itself means by the name, or LargestLandmass for the principal landmass alone.
• outline: true, the default, activates only the cells whose centres fall inside the region. false activates every cell in the region's bounding box instead, which is the cheaper thing to want when the region is only being used to say where to work rather than to mask a coastline.

NaturalEarthSpec(match::EcoSISTEM.RegionMatch; coverage = AllTerritories(), outline = true)

Turn one match from investigate_regions into a spec, without naming it again.

A match already carries the level and the name, which is the whole of a spec's identity, so nothing is re-derived and the shape agrees with the box the report displayed.

A report cannot be converted, because it may hold several regions. Pick one first - only(report) asserts there was exactly one, first(report) takes the best by the report's own ordering, and report[i] takes a chosen one.

NeverScheduled() <: AbstractSchedule

Never fires. For disabling an intervention without removing it from a set, so a configuration can keep its shape while one part of it is turned off.

NicheAxis

The quantity being measured - Temperature, Precipitation, SolarRadiation - independent of the unit it arrives in and orthogonal to Role.

An axis is what makes a pairing meaningful: a species' tolerance for temperature is matched against the temperature regime and nothing else. Both sides of the model carry one, so an AbstractLayer and the AbstractSpeciesRequirement it is matched against name the same axis, and a mismatch is a type error rather than a silent comparison of unrelated quantities.

Paired axes must be identical, not merely compatible: a SoilTemperature tolerance does not meet a Temperature regime.

Extend it with @nicheaxis. Related axes are grouped under an abstract intermediate named ...Axis (TemperatureAxis, WaterAxis) that carries their shared interface.

NicheSpec{A <: NicheAxis}

A categorical layer of randomly assigned niche classes - the synthetic counterpart of a land cover map.

Arguments

• n: how many distinct classes to draw from.
• axis: the niche axis this layer is on. Required.

NicheSuitability{A, V} <: AbstractNicheFit{A, V}

The nichefit between a NicheTolerance continuous trait and its environment: the density of the trait's response distribution evaluated at the current regime value, parameterised on any V. Works for any Distributions.ContinuousUnivariateDistribution (e.g. Trapezoid or Uniform).

NicheTolerance{A <: NicheAxis, V, D} <: ContinuousTolerance{A, V}

One species' response along a continuous niche axis, as a built probability distribution: where on the axis it does best, and how sharply that falls away.

The distributions are built once, at construction, in a frame - the unit their support is measured in, which is also the tolerance's eltype and the unit the matching regime must be in. In the hot loop the NicheSuitability nichefit fetches one and evaluates its density at a bare number already in that frame, so there is no per-call conversion and no allocation.

Fields

• dists: one distribution per species. Reach them with getdist.

Type parameters

• A: the niche axis.
• V: the frame the distributions are built in.
• D: the concrete distribution type, a Distributions.ContinuousUnivariateDistribution such as Trapezoid{Float64} or Uniform{Float64}.

NicheTolerance(axis::Type{<:NicheAxis}, ::Type{D}, dist::Matrix; support = _defaultsupport(axis),
    offset = nothing, scale = nothing, probes = ...)

Build a NicheTolerance from a bare parameter matrix, one species per row.

Arguments

• axis: the niche axis the tolerance is on.
• D: the response distribution type to build.
• dist: the parameters, one row per species, as bare numbers read in the support frame.
• support: the frame the distributions are built in - the unit their support is measured in, the tolerance's eltype, and the unit the matching regime must be in. Defaults to the axis's canonical unit.
• offset, scale: references in support, which place a shape-only distribution such as Beta or LogNormal onto the dimensioned axis through a LocationScale.
• probes: how D's parameter roles are determined; see param_roles_resolved.

NicheTolerance(axis::Type{<:NicheAxis}, ::Type{D}, params::AbstractVector...; support = _defaultsupport(axis),
    offset = nothing, scale = nothing, probes = ...)

Build a NicheTolerance from one vector per parameter of the distribution - the programmatic counterpart of the matrix constructor:

NicheTolerance(Temperature, Normal, opts, vars)          # a mu and a sigma vector
NicheTolerance(Precipitation, Gamma, shape, scale_vec)

The vectors may carry units, and each is read according to its parameter's role - a location converted as a position, a scale as an interval, a shape left dimensionless. So support = K and support = °C build the same preference, expressed in each frame.

Arguments

• axis: the niche axis the tolerance is on.
• D: the response distribution type to build.
• params: one vector per parameter of D, each with one entry per species. All must share a unit, and all must be the same length.
• support: the frame the distributions are built in, as for the matrix constructor.
• offset, scale, probes: as for the matrix constructor.

NoChange <: AbstractChangeMode - no values, and so no `changeunit`.

NoFitCategorical{A, V} <: AbstractNicheFit{A, V}

The absence of a nichefit between a categorical trait and its environment, parameterised on its axis structure A and on any V. Returns the value 1.

NoFitContinuous{A, V} <: AbstractNicheFit{A, V}

The absence of a nichefit between a continuous trait and its environment, parameterised on its axis structure A and on any V. Returns the value 1.

NoGrowth{U <: Unitful.Units} <: AbstractParams

Demographic rates for a population that does not grow. The same fields as PopGrowth, but the resource adjustment is short-circuited to zero, so births and deaths are taken at their stated rates and the environment does not modulate them.

Fields

• birth, death: one rate per species, per unit time.
• longevity, survival: the two exponents described in AbstractParams. Carried so that the same parameters can be reused with a growing model, but not read while growth is off.
• boost: the ceiling on the birth multiplier where resources are abundant, likewise unread.

NoLayerChange <: AbstractLayerChange{NoChange} - the layer never changes.

NoMovement{K <: AbstractKernel} <: AbstractMovement

Nothing disperses: every individual stays in the cell it was born in.

Fields

• kernels: one AbstractKernel per species, carried but never drawn from, so that a model can be switched between movements without rebuilding its species.

NoMovement{K <: AbstractKernel} <: AbstractMovement

Nothing disperses: every individual stays in the cell it was born in.

Fields

• kernels: one AbstractKernel per species, carried but never drawn from, so that a model can be switched between movements without rebuilding its species.

NoRealWorldPosition <: AbstractDecisionSource - a synthetic area, with no real-world position for a CRS to describe.

OffsetBy(shape)

Declare that shape's values are offsets from the layer's values as they stand when the change is attached - an interval, so K rather than °C on a temperature layer.

Arguments

• shape: as ReplaceWith, something that differs from step to step. A bare constant is rejected: a fixed offset applied every step is idempotent after the first, so it too is a one-off operation rather than a change.

Overlaps(x)

Regions that share real ground with x.

Answers "which regions does my data reach into?". Sharing only a boundary does not count, which is the whole difference from a bare intersection test: a region touching your data along an edge contains none of it, and boundingbox(..., round = ...) snaps boxes onto a lattice, so that case is reachable rather than theoretical.

Arguments

• x: as Encloses, but not a point - a point has no area to share.

ParamRole

Abstract supertype for the conversion role a distribution's parameter plays, which decides how a unit is attached to it.

The distinction is Unitful's affine one, and getting it wrong is silent. A location is a position on the axis, so LocationRole converts 12 °C to 285.15 K; a scale or a rate is an interval, so ScaleRole and RateRole leave a width of 12 °C as a width of 12 K rather than 285.15. A ShapeRole parameter is dimensionless and takes no unit at all.

PatternedChange(amplitude, timescale; shape = sinusoidal)

A shape of elapsed simulation time: amplitude * shape(elapsed / timescale).

Arguments

• amplitude: what shape's output is scaled by, and where the unit comes from.
• timescale: the elapsed time that maps to one unit of shape's argument. The phase is not wrapped, so this is a period for a periodic shape and a transition width for a monotone one.
• shape: any function of a dimensionless phase - a sigmoid, a ramp, a step. Defaults to sinusoidal, one full cycle per timescale.

Like SeriesChange this is a shape rather than a change in itself: the recipe wrapping it says whether its values are absolute, an offset or a rate.

PatternedLayerChange{M <: AbstractChangeMode, F, V, B} <: AbstractLayerChange{M}

A change following an arbitrary shape of elapsed simulation time: the layer gets amplitude * shape(elapsed / timescale), read according to M. shape defaults to sinusoidal, one full cycle per timescale; a sigmoid, ramp or step function is equally valid.

The phase handed to shape is deliberately not wrapped into [0, 1). A sinusoid is periodic by itself so wrapping would gain nothing, while a sigmoid is not periodic at all and wrapping would destroy it. timescale is therefore the elapsed time mapping to one unit of shape's argument - a period for a sinusoid, a transition width for a sigmoid.

Under RelativeChange the pattern is added to baseline, captured from the layer when the change was attached so that the result stays a pure function of elapsed time rather than compounding on what the previous step wrote. The other modes leave baseline as nothing.

PeakedSpec{A <: NicheAxis, V}

A layer whose value peaks - or dips - in the middle of the grid: inside at the centre, falling off to outside at each end.

As GradientSpec, the pattern is fixed in space; wrap the spec in Varying to give it a change in time.

Arguments

• outside, inside: the values at the ends and at the centre. They must differ, or there is no peak.
• axis: the niche axis this layer is on. Required.
• orientation: which way the peak runs, with the same meaning and the same angle-Quantity requirement as GradientSpec's.

PerCellAccumulationPeriod(code)

The period is another layer, varying by cell - gsp (growing-season precipitation) accumulates over gsl (growing-season length). Written percell=gsl.

A trait cannot be converted without reading that layer, so a stock and a rate reading of such a value are genuinely different hypotheses rather than two spellings of one.

Fields

• code: the CODE_TYPE of the layer holding the period - :gsl for gsp. It names a layer of the same dataset, which is what makes the second read resolvable from the first.

PerSliceAccumulationPeriod()

Each time slice accumulated over its own calendar month, so slice 1 is January's 31 days and slice 2 February's. Written perslice=calendar_month in the shipped tables.

This is the case a single unit cannot express, and the reason the column is not simply a unit: a 12-slice monthly read has twelve different divisors, not one.

Periodic <: AbstractBoundaryCondition - this axis wraps: its two edges join.

PopGrowth{U <: Unitful.Units} <: AbstractParams

Demographic rates given per species: the general form, and what the hot loop reads.

Fields

• birth, death: one rate per species, per unit time.
• longevity, survival: the two exponents described in AbstractParams.
• boost: the ceiling on the birth multiplier where resources are abundant.

Precipitation <: PrecipitationAxis - a precipitation amount over a month, quarter or year (BioClim 12-19, Climate prec/pr; mm/day). Carries the unit and provides a water supply/demand.

PrecipitationAxis <: WaterAxis - precipitation niche axes. A topical group; the unit and the water supply/demand live on the [`Precipitation`](@ref) leaf.

PrecipitationSeasonality <: PrecipitationAxis - precipitation seasonality, the coefficient of variation of the monthly precipitation totals (BioClim 15; dimensionless).

Problem

One thing worth telling the user about a study area.

Fields

• severity: a ProblemNotice or a ProblemWarning.
• code: names the kind of problem, so that it can be tested for and filtered on without matching against the prose.
• message: the prose itself.

ProblemNotice <: AbstractProblemSeverity - something was guessed, or is lossy but expected.

ProblemWarning <: AbstractProblemSeverity - it will work, but is probably not what you want.

RainTolerance

A rainfall preference: a NicheTolerance on Precipitation, read in the mm/day frame, with a Uniform response.

The frame is a rate rather than a depth: every shipped precipitation layer is read per unit time.

An alias rather than a type of its own, so it has the fields NicheTolerance has. RainTolerance(matrix) is a shorthand for NicheTolerance(Precipitation, Uniform, matrix).

RandomCells(count::CELLCOUNT)

count cells drawn at random, without replacement, from the currently active ones.

Arguments

• count: how many cells, either exactly (RandomCells(20)) or as a per-time rate (RandomCells(0.05/year)). A rate is applied to each candidate cell independently over the step, so the number taken is a binomial draw and varies from one firing to the next.

RasterDataAcceptableCode{S, C}

Trait holding when C is a shape in which a layer of source S may be named - a scalar code, a vector of them, or Nothing.

This admits a spelling; it does not confirm a layer exists. Rejecting :not_a_layer needs the catalogue and happens there. C records the canonical type a code resolves to, never the shape the caller wrote - see CODE_TYPE.

RateChange <: AbstractChangeMode - an interval per unit time, accumulated each step.

Reactivate() <: AbstractOperation

Mark the region's cells active again.

A deactivated cell keeps its supply - _zerogaps zeroes data gaps only - so a reactivated cell has resource waiting. That matters: a cell whose supply had been zeroed would be lethal rather than merely barren, since the death term is E/K and K = 0 gives a death probability of exactly one.

It does not restock the cell, and that asymmetry with Deactivate is deliberate: the habitat becomes available again and dispersal recolonises it from the surviving neighbours, which is how a site actually recovers. Actively replanting is a different act - combine AddAbundance with this over the same region - and is a restoration scenario rather than a release of constraint.

RegimeCollection2{M1, M2} - two positional regimes over one grid. Deprecated plumbing: use [`LayerCollection`](@ref).

RegimeCollection3{M1, M2, M3} - three positional regimes over one grid. Deprecated plumbing: use [`LayerCollection`](@ref).

RegionMatch

One named region a query found, and enough of it to act on without looking anything else up.

Fields

• level: which kind of region it is, as NaturalEarthLevel.
• name: the source's own spelling of the name.
• extent: its bounding box, in degrees.
• area: the total area of the region, in km^2.
• parts: how many separate components it has.
• share: what fraction of the region's area its largest component holds. This is the number that says whether LargestLandmass is a sensible answer for the region at all: New Zealand's is 0.56, so asking for its principal landmass silently returns South Island alone, and the Solomon Islands' is 0.20.
• overlap: the area of the box it shares with whatever was asked about, in km^2, which is what an Overlaps report orders by. nothing for a listing, which asked about nothing.

RegionReport

What investigate_regions found: the matching regions, in order, and the question asked.

A report is a container - it iterates, indexes and has a length - so only(report) asserts that the answer was unique, first(report) takes the best one and report[i] takes a chosen one. Any of those gives a RegionMatch, which is what NaturalEarthSpec accepts.

Fields

• relation: the question that was asked, including what it was asked about.
• matches: the regions that answered it, ordered as described in investigate_regions.
• exact: whether the answer was checked against the regions' real outlines rather than their bounding boxes.
• refined: how many candidates had their geometry fetched to answer it. Zero unless exact.

RelativeChange <: AbstractChangeMode - an interval from the layer's captured values, so `K` rather than `°C`.

RelativeHumidity <: RelativeHumidityAxis - near-surface relative humidity (Climate hurs, BioClimPlus hurs_max/mean/min; dimensionless).

RelativeHumidityAxis <: HumidityAxis - relative-humidity niche axes (level and range).

RelativeHumidityRange <: RelativeHumidityAxis - annual range of the monthly relative humidity (BioClimPlus hurs_range; dimensionless).

RemoveAbundance(species, count)

Remove individuals from each cell of the region, never taking a cell below zero - a cull, or a harvest.

Arguments

• species: which species, by name or by index.
• count: at most how many per cell. An Integer is an exact number; a quantity per unit time is a mean rate, drawn afresh each step.

RepeatAtEnd <: AbstractSeriesEnd - the series cycles, by a true modulus of its own period.

ReplaceWith(shape)

Declare that shape's values are absolute: the layer's value is shape, in the layer's own unit.

Arguments

• shape: something that genuinely differs from step to step - a SeriesChange, or a PatternedChange whose shape returns the full value. A bare constant is rejected, because writing the same value every step is a one-off operation on the ecosystem rather than a change of the layer.

Resource <: Role

What a cell provides - solar radiation, available water, land.

A resource is a shared pool that species compete for, and it is what regulates abundance. Each species states how much it needs as an AbstractDemand; the demands of everything present are summed, and births fall and deaths rise as that total approaches what the cell supplies. Species therefore interact only through this total. Carrying capacity is not a parameter anywhere in the model - it emerges from supply divided by demand.

RevertToLayer <: AbstractSeriesEnd

Past its last slice the series stops driving the layer, which returns to the values it held before the series was attached - its own spec's, for a ReplaceWith series.

This is the not-yet-started rule of AbstractSeriesEnd applied at the far end, where the alternatives are genuine. It is also the only end policy for which the layer's own values are still needed: the other three keep the series in charge.

Role

The two ways a cell of the world bears on the species living in it: as a Condition it must tolerate, or as a Resource it competes for.

This distinction is the axis the whole model is built along, and it applies to both sides at once. The environment states each role as a layer (AbstractLayer) - a regime and a supply - and each species brings a matching requirement (AbstractSpeciesRequirement) - a tolerance and a demand. A role therefore names a relationship, not a kind of data: the same temperature grid is a condition because of how species meet it, not because of what it contains.

The two roles behave quite differently, which is why they are distinguished rather than merged: a condition is experienced identically by everything in the cell, while a resource is finite and shared, so what one species takes bears on the rest.

RoundedFromMeasurement <: AbstractDecisionSource - a [`MeasuredAcrossProjection`](@ref) cell size, floored to whole units.

SavedLandscape

A GridLandscape reduced to what has to survive a round trip through disk: the bare abundance matrix, without its dimensions, and a snapshot of the per-species random number streams.

The streams are what make a resumed run reproducible - a run draws from one generator per species rather than from a shared one, so restoring the abundances alone would restart every stream from wherever the loading process happened to be. The dimensions are not saved because the ecosystem being restored into already has them.

Fields

• matrix: the abundances, species by flat grid cell.
• rngs: one generator state per species, copied at the moment of saving.

SavedLandscape(gl::GridLandscape, rngs::Vector{Random.Xoshiro})

Reduce a GridLandscape to its serialisable form.

Arguments

• gl: the landscape whose abundances are to be kept.
• rngs: the ecosystem's per-species generators, copied rather than aliased so that continuing the run does not alter what was saved.

SeriesChange(source; times = nothing, origin = nothing, atend = ErrorAtEnd(),
             calendar = nothing)

A stack of stored slices to be indexed by elapsed simulation time - a read climate series, or any (Y, X, Ti) array of values.

Arguments

• source: the slices. Anything indexable by a time dimension.
• times: one time per slice. Taken from source's own Ti lookup by default, or assumed monthly for an array carrying no lookup at all.
• origin: the point in the series' own coordinate that elapsed time zero corresponds to. Defaults to the first stored time, so a series starts at its own beginning whatever its axis is anchored to.
• atend: what happens past the last slice - an AbstractSeriesEnd, one of ErrorAtEnd (the default), HoldAtEnd or RepeatAtEnd.
• calendar: what the coordinates mean - an AbstractSeriesCalendar. A source whose lookup holds real dates is inferred to be a DatedSeries and anything else an UndatedSeries. A monthly climatology has to say calendar = MonthOfYearSeries() for a run's epoch to start it in the right month, because month-of-year coordinates cannot be told from plain offsets by their values alone.

origin = 0 is not the same as leaving origin out, and the difference is a real one rather than a technicality. Omitting it means start at the first slice; zero means the coordinate zero, which on an ordinary monthly climatology - slices at 1 to 12 months - is a month before the first slice, and a series before its first slice says nothing, so the layer holds its own values for that month. Write the lead-in when you want one; leave origin out when you mean "from the beginning".

origin is accepted only for an UndatedSeries, the one case where nothing else can set the zero point: for the other two the epoch fixes the phase, and a second knob for the same thing could only contradict it. To say that an undated series really begins at a particular date, give it real times rather than an origin - that states what every slice is, rather than only where zero sits.

Like PatternedChange this is a shape, so the mode is named by the recipe wrapping it: ReplaceWith for stored values the layer takes on, OffsetBy for a stored deviation from the layer's own values, IncrementBy for a stored rate.

SeriesLayerChange{M <: AbstractChangeMode, E <: AbstractSeriesEnd, C <: AbstractSeriesCalendar, D, B} <: AbstractLayerChange{M}

A stack of stored slices, indexed by elapsed simulation time: a slice is current from its own stored time until the next slice's, so at elapsed the layer takes the last slice at or before origin + elapsed, read according to M. Under AbsoluteChange the layer is that slice (a read climate series); under RelativeChange the slice is added to the layer's captured values.

times holds one time per slice in the same order, and origin is the point in that coordinate which elapsed time is measured from - the first stored time unless the caller says otherwise, so that a series starts at its own beginning whatever its axis is anchored to.

calendar records what the coordinates mean - see AbstractSeriesCalendar. It is what build_ecosystem reads when it resolves a run's epoch, and what it re-points the series against: resolving an epoch rewrites origin, leaving the stored slices and the hot path untouched.

Outside its own span a series contributes nothing, and the layer is whatever it would be without it: before the first slice always, and past the last under RevertToLayer. baseline is what that costs - the layer's values as they stood when the change was attached, kept for the modes that need something to fall back to.

Indexing by time rather than by a step counter is the substance of this type: it makes the result independent of the timestep (one twelve-month step and twelve one-month steps land on the same slice), which a cursor advanced once per call can never be. atend decides what happens past the last slice - see AbstractSeriesEnd.

SetChange(target, spec)

Install a new change rule on one layer, part-way through a run:

SetChange(:rainfall, IncrementBy(-0.1mm / day / year))

Region-independent by nature - a layer's change applies to the whole layer - so an intervention carrying it should use AllCells. Any other region is accepted but ignored, and says so.

Arguments

• target: which layer, by name. This addresses a member of a collection, so a multi-variable environment can say which variable is the one that changes.
• spec: the new change, as an AbstractChangeSpec.

SetLandCover(class)

Set the region's cells to a land-cover class.

The only operation permitted to write a layer's matrix directly, and only a categorical one. A continuous layer's values are owned by its change rule, which is a pure function of elapsed time; writing them from outside would break that and desynchronise MPI ranks. A categorical layer has no such rule, so land cover is the one thing an intervention may set.

Arguments

• class: the class to set the cells to, by name (:open_water) or by its code.

ShapeBuffer(distance)

Grow the shape outwards by distance, or shrink it inwards where distance is negative.

This is how a study area becomes "within 50 km of this coastline", which no set operation can express. It takes one member: a buffer transforms a shape rather than combining several.

⚠️ The distance is applied in the shape's own coordinates, which for Natural Earth are degrees of latitude and longitude - so a buffer given as a length is converted at the equator and is narrower in east-west terms the further from it the shape lies. Give an angle to say exactly what is meant.

Arguments

• distance: how far to grow, as a length (50km) or an angle (0.5°).

ShapeConvexHull() <: AbstractShapeOperation

The smallest convex outline containing the shape, as a rubber band round it.

Takes one member. Useful for turning a scattered archipelago into the single area it occupies, and for smoothing away a coastline's detail without choosing a tolerance.

ShapeDifference() <: AbstractShapeOperation

The first member's ground with every later member's removed.

ShapeIntersection() <: AbstractShapeOperation - only ground common to every member.

ShapeSimplify(tolerance)

Replace the outline with a coarser one no further than tolerance from it.

Only 1:10m polygons ship, that being the one scale at which a name's box and its shape can agree, so this is how a coarser outline is had when a fine one is not wanted - a continent's coastline carries tens of thousands of vertices that no continental-resolution grid can use. It takes one member.

Arguments

• tolerance: how far the simplified outline may depart from the original, as a length or an angle, in the same coordinates ShapeBuffer uses.

ShapeSpec(path::AbstractString; layer = 0)

Name an active-area mask taken from the polygons of a vector file, without reading it. It holds no geometry: the read, any download, the per-feature reprojection into the target grid's own CRS and the cell-membership test all happen when it is materialised onto a decided grid, as for SourceSpec.

Arguments

• path: a shapefile, GeoJSON, GeoPackage, or any format GDAL reads. A path ending in .zip is read directly, with no need to unzip first, and a URL is downloaded into EcoSISTEM.assetdir(owner = ShapeSpec) as an EcoSISTEM.CachedAsset the first time it is needed.
• layer: which layer of the file, 0-indexed. Every polygon feature in it is used.

ShapeUnion() <: AbstractShapeOperation - every member's ground, merged.

SimpleCategoricalTolerance{A <: NicheAxis, V} <: AbstractCategoricalTolerance{A, V}
SimpleCategoricalTolerance(vals; axis, penalty = 0.0)

The categories each species tolerates on niche axis A - one set of acceptable class values per species - together with the weight a species gets outside its set.

Fields

• vals: vals[i] lists the class values species i tolerates. A species with a single preferred class simply has a one-element set, so pass a plain vector of classes (one per species) and each is wrapped for you.
• penalty: the suitability weight outside the set, in [0, 1]. Inside it the weight is always 1.

penalty is the whole soft-versus-hard distinction, and it is a number rather than a type. 0.0, the default, is hard exclusion: the species cannot persist outside its classes at all, because a zero suitability makes its death rate infinite. 0.5 is soft - it does worse there but survives. Anything between is available and means what it says.

penalty interacts with params.survival. Suitability enters the demographics as suitability^±survival, so at survival = 0 every penalty is ignored and the tolerance does nothing at all. That is a property of the model rather than of this type, and invisible from here, so it is worth stating: a categorical tolerance needs a non-zero survival to have any effect.

SiteWaterBalance <: WaterAxis - cumulative site water balance over the year, capped by soil water-holding capacity (BioClimPlus swb; L*m^-2).

SnowWaterEquivalent <: WaterAxis - snow water equivalent, the liquid-water amount of the snowpack (BioClimPlus swe; L*m^-2).

SolarRadiation <: SolarRadiationAxis - surface downwelling shortwave (solar) radiation flux (Climate srad/rsds, BioClimPlus rsds_max/mean/min). Provides a solar supply/demand.

SolarRadiationAxis <: NicheAxis - solar-radiation niche axes (level and range).

SolarRadiationRange <: SolarRadiationAxis - annual range of the monthly solar radiation flux (BioClimPlus rsds_range).

SourceSpec{A <: NicheAxis, U, K <: NamedTuple}

Name a layer of a catalogued data source, without reading it. It holds no grid array: the read, the cut and the resample happen only when it is materialised onto a decided grid.

Passing no code describes the whole dataset - every layer read into one multi-band raster, which is the form ConstructedRasterSpec uses for a bare dataset, such as all the land-cover class bands for compress_landcover.

Arguments

• source: the dataset type to read from, WorldClim{BioClim} and the like.

• code: which layer of it, as one CODE_TYPE or a vector of them. Omit it for the whole dataset.

• unit: the physical unit to attach on read. Defaults to the layer's own, from the shipped table.

• axis: the niche axis, which is what matches the layer to species niches. Defaults from the shipped table, and to NicheAxis where the table names none.

• any other keyword: kept as a pass-through argument for the eventual read, so SourceSpec(WorldClim{Climate}, :wind, month = 1:12) reads the twelve monthly layers and month = 1 just the one. A SourceSpec nested inside a ConstructedRasterSpec can therefore carry its own read options.

  Two of those keywords decide how much is read, and are worth knowing about together. cut windows the read, so only the cells inside a bounding box come off disk. scale coarsens by an integer factor, and on its own it coarsens the whole source file however small a result is wanted, because the aggregated form is memoised per file rather than per window: for a global dataset that first read can need many gigabytes. Give a scale a cut as well where the whole world is not needed, and the memo is skipped along with the cost.

Fields

• source, code, unit, readkw: as above. code is never nothing - a whole-dataset spec resolves the dataset's own code list at construction, so every layer's identity is known before anything is read and each can keep its own unit. unit falls back to NoUnits as a neutral placeholder where a multi-layer spec's layers disagree.

Type parameters

• A: the niche axis. A type parameter rather than a field because it is dispatched on, which is what lets a layer's meaning be checked at compile time rather than looked up.
• U, K: the types of unit and readkw.

SpaceAxis <: NicheAxis - the physical space niche axes: ground surface now, canopy and soil later.

Spatial2D{Kind, T}

A two-dimensional quantity in (y, x) order, with Kind saying whether it is a place or a separation and T the type of each component.

Write SpatialLocation or SpatialSize rather than this; both are aliases that pin Kind, so a method annotated with either refuses the other.

The order is y then x – north-south before east-west – matching every other pair in the package, and the field names are always y/x whatever the units. A degree quantity makes a geographic pair and a length quantity a projected one, so the units say which frame a value is in without a second type having to.

Fields

• y: the north-south component – a latitude for a geographic position, a northing otherwise.
• x: the east-west component – a longitude for a geographic position, an easting otherwise.

SpatialKind

Supertype of the tags that say what kind of two-dimensional quantity a Spatial2D is.

The two are AbsolutePosition (a place) and RelativeOffset (a separation between places). Both are internal: a caller names SpatialLocation or SpatialSize instead, and the tag appears only inside the type.

SpatialLocation(y, x)

A place, in (y, x) order: SpatialLocation(50.0°, -3.0°) geographically, or SpatialLocation(5000.0m, 3000.0m) on a projected grid.

Degrees are checked against the valid geographic range on construction; other units are not, because what counts as in range is a property of the coordinate reference system and is not known here.

SpatialSize(y, x)

A separation in (y, x) order – the extent of a cell, the size of a grid, the step between two coordinates: SpatialSize(1.0km, 1.0km).

Never range-checked, and signed: a displacement may run either way, and an angular separation may exceed the range a latitude is confined to.

SpeciesList{TL <: AbstractTolerance, DM <: AbstractDemand,
            MO <: AbstractMovement, T <: AbstractTypes,
            P <: AbstractParams} <: AbstractTypes

Everything the simulation knows about the species themselves - the species-side counterpart of a GridHabitat, and one of the two halves build_ecosystem checks against each other name for name.

It is itself a Diversity.AbstractTypes, but it holds the real types in types rather than being them, so every AbstractTypes question is forwarded there; see src/DiversityInterface.jl.

Fields

• names: one name per species.
• tolerance: the niche of each species, an AbstractTolerance matching the habitat's regime axis for axis.
• demand: what each species takes from the shared pool, an AbstractDemand matching the habitat's supply the same way.
• abun: the abundances a run starts from, before populate! scatters them.
• types: the similarity structure - a UniqueTypes where species are maximally distinct, or a PhyloBranches derived from a phylogeny.
• movement: which individuals disperse and how far, an AbstractMovement.
• params: the demographic rates, an AbstractParams.
• native: whether each species is native, one flag each.
• susceptible: optional per-species disease susceptibility, missing where unset.

Type parameters

• TL, DM, MO, T, P: the types of tolerance, demand, movement, types and params. T is what a method keys on to require a phylogeny, since Diversity's own Sim slot cannot carry that constraint.

SpeciesList(numspecies::Int64, numtraits::Int64, abun::Vector{Int64},
  demand::DM, movement::MO, params::P, native::Vector{Bool})
SpeciesList(numspecies::Int64, numtraits::Int64, abun::Vector{Int64},
  demand::DM, movement::MO, params::P, native::Vector{Bool},
  switch::Vector{Float64})
SpeciesList(numspecies::Int64, numtraits::Int64, abun::Vector{Int64},
  demand::DM, movement::MO, phy::T, params::P, native::Vector{Bool})

Create a SpeciesList whose categorical niche tolerances are evolved along a random ultrametric phylogeny, with a PhyloBranches similarity structure computed from that tree.

The third form takes a similarity structure explicitly instead of computing one from the tree; the tolerances are still evolved along a random ultrametric tree.

All three forms need Phylo - each builds the tree, or forwards to one that does - so using Phylo is required and without it the call is a MethodError. The implementation is in EcoSISTEMPhyloExt.

Arguments

• numspecies: how many species.
• numtraits: how many categorical niche classes the tolerances are drawn from.
• abun: the starting abundances.
• demand: what each species takes from the shared pool.
• movement: which individuals disperse and how far.
• params: the demographic rates.
• native: whether each species is native.
• switch: the rate of trait change along branches. Defaults to [0.5].
• phy: a similarity structure to use in place of the one the tree would give.

SpeciesList(numspecies::Int64, tolerance::TL, abun::Vector{Int64}, demand::DM,
  movement::MO, params::P, native::Vector{Bool})

Create a SpeciesList from tolerances supplied directly, rather than evolved along a phylogeny. Species are treated as maximally distinct, with a UniqueTypes similarity structure.

Arguments

• numspecies: how many species.
• tolerance: their niches, as an AbstractTolerance.
• abun: the starting abundances. Padded with zeros if shorter than numspecies.
• demand: what each species takes from the shared pool.
• movement: which individuals disperse and how far.
• params: the demographic rates.
• native: whether each species is native.

SpeciesRequirementCollection{R <: Role, A, C <: NamedTuple}

Several species requirements of the same role R - tolerances over several regime layers, or demands over several supplies - over the axis structure A, held by name in a NamedTuple, (Temperature = ..., Precipitation = ...). The species side's counterpart to LayerCollection: its members must line up, name for name and in the same order, with the layer collection they are matched against.

Members are named by their axis, so a Tuple of them is accepted and named for you. Two members on the same axis cannot be told apart that way, and are refused rather than silently numbered.

The role is read off the members rather than chosen, as LayerCollection does, so R cannot be got wrong and a collection mixing a tolerance with a demand is refused instead of being tagged with whichever role came first.

Members are reached through the standard container interface - sr.Precipitation, sr[1], sr[:Precipitation], keys, values, pairs, iterate, length, merge and NamedTuple(sr). A single requirement answers identically, as a one-member container.

Fields

• nt: the members, by name. Reach them through the interface above rather than directly, so that no member name is reserved.

SpreadingCells(count::CELLCOUNT)

count cells forming a contiguous cluster: a random active seed cell, then repeatedly a random active neighbour of the cells already chosen. Falls back to a fresh seed if the cluster is boxed in, so it always returns count cells where that many are available.

Arguments

• count: how many cells, exactly or as a per-time rate, as RandomCells.

SteadyLayerChange{V} <: AbstractLayerChange{RateChange}

A constant rate of change: the layer gains value * timestep every step. value is a scalar or a per-cell matrix, already converted to the layer's changeunit when the change was attached.

The mode is fixed to RateChange because only a rate accumulates. A constant value - absolute or relative - writes the same thing every step and is idempotent after the first, which makes it a one-off operation on the ecosystem rather than a per-timestep change of the layer.

StudyArea(base = missing; regime::Union{LayerInput, Missing, Nothing} = missing,
    supply::Union{LayerInput, Missing, Nothing} = missing, within = missing,
          crs = missing, cellsize = missing, extent = missing, align = missing,
          simulate_safely = missing, verbosity = :normal)

Decide the grid a simulation will run on, before anything is built on it.

Nothing is compulsory: the grid is decided from whatever is given, so naming only regime means only the regime shapes it. A layer that is not named here can never move or resize the grid - when GridHabitat later samples it, it can only mark cells inactive (and says so). Name a layer to let it shape the grid; omit it and it can only subtract.

The optional positional base refines an existing area - StudyArea(area, cellsize = 1km) - keeping everything not overridden, including its cache of reads, so trying several grids does not re-read the data. A StudyAreaReport or a GridHabitat may be given in its place.

A habitat's grid is copied rather than re-derived. A habitat can end up narrower than the area it was built on, because a layer named only to GridHabitat can cost cells the area listed as active - and nothing but the habitat's own report records that. So a base whose report is AsBuilt, with no other keyword given, is taken verbatim: StudyArea(habitat) is the grid the habitat is actually on, not the one originally investigated. Naming any grid keyword alongside re-derives instead, which loses the narrowing; that is deliberate, and not warned about, because overriding is an explicit act.

What is copied is the report, not the built grid. StudyArea(habitat) describes the habitat's grid but is itself a fresh area with nothing built on it, so its builtgrid is nothing while its report stays AsBuilt. The two say different things - the report's stage describes what the report is, builtgrid what has been done to this area - which is why neither can be derived from the other.

Keywords are tri-state: missing (the default) means "not specified - derive it, or take it from base", nothing means "explicitly cleared, ignore any inherited value", and any other value is used as given.

Arguments

• regime, supply: the layers the simulation will use. Naming one here lets it shape the grid - its extent, its CRS and its resolution all become candidates. A layer not named here can still be used later, but can only mark cells inactive, never move or resize the grid.
• within: what positions the area - a ShapeSpec, a CircleMaskSpec, a LatLong box, or EcoSISTEM.boundingbox("Scotland"). It both restricts which cells are active and, where it can state an extent, sets the grid's. This is the argument to reach for when a global dataset would otherwise give you the globe.
• crs: the coordinate reference system to work in. A projected CRS is required to simulate: dispersal is expressed against one cell size, which only a projected grid has. Omitted, it is adopted from the layers, and a geographic result is warned about.
• cellsize: the length of a cell's side. Omitted, it is taken from the align layer's own step.
• extent: a size, not a bounding box - how big the area is, never where it is, given as a (y, x) tuple of lengths: north-south first, then east-west, the dimension order used throughout the package. It is therefore only meaningful for a synthetic area, and combining it with data layers is an error: those already carry their own extent, and a second unanchored size cannot be reconciled with it. Use within to position and limit an area built from data.
• align: names the layer whose own grid is preserved exactly. By default whichever layer is already in the target CRS (finest first), since that one needs no reprojection.
• simulate_safely: whether a cell must be wholly inside every layer's data to be simulated. true (the default) is the safe reading - a cell the data only partly describes is dropped, and the grid crops inwards rather than carrying it - since nothing can put data where a file has none. false restores the older rule, under which a cell survives if its centre has a value (i.e. if it is more than half covered) and is then given a whole cell's worth of supply over ground that is partly missing; that is announced, with a count. The same rule applies to layers named only later, at GridHabitat.
• verbosity: see below.

With no layers that can shape a grid, extent and cellsize build a synthetic one with no CRS - which is also what a synthetic layer (UniformSpec, GradientSpec, ...) needs, since it is generated at whatever shape it is handed and so has no CRS, extent or resolution to contribute. Naming one here is harmless but decides nothing.

verbosity is :silent (errors only), :normal (announce every guessed value and every lossy step, and warn about grids that will work but are probably not what you want) or :verbose (aliases :full/:debug; show the whole investigate_study_area report).

Fields

• report: the StudyAreaReport recording how this grid was decided - the CRS, cell size and extent it settled on, which layer decided each, and every Problem raised on the way.
• builtgrid: the StudyGrid a GridHabitat was built on here, or nothing until one has been. nothing does not mean the grid is undecided - an investigated area has decided one; that is what investigation is. It means nothing has been built on it yet, so the cells it lists are a prediction: a layer named only to GridHabitat can still narrow them.

StudyAreaReport

Everything decided about a study area, and what it costs.

Returned by investigate_study_area and held by every StudyArea. The two share one analysis, so a report can never describe a grid other than the one that would be built.

Fields

• crs, cellsize, align: the grid that was chosen.
• crssource, cellsizesource: where each of those decisions came from - an AbstractDecisionSource, GivenByUser if you supplied it, otherwise how it was derived. This is what lets the constructor announce everything it guessed.
• active: one array answering two questions. Its coordinates say where the cells are - units, CRS, span, locus - and its values say which of them are simulated.
• simulate_safely: the resolved rule active was decided by.
• layers: a LayerPlan each, saying what the chosen grid costs that layer.
• footprint: how much memory a run on this grid needs.
• problems: the Problems found on the way.
• specs, constraints: enough to use this report as the base of another - the specs it was decided from, and the constraints as given rather than as resolved.
• cache: the LayerCache of reads, or nothing on an as-built report, where it has been discarded.
• stage: which of the two kinds of report this is - see AbstractReportStage.

StudyGrid{C, YD, XD} <: EcoBase.AbstractGrid

The geometry of the grid a GridHabitat was built on: where its cells are, how big they are and what coordinate reference system they are stated in.

This is the package's EcoBase location data, so anything that speaks that interface - EcoBase, SpatialEcology, the plot recipes - can ask a habitat where its cells are. Every answer is unitful, in the grid's own units: a projected grid answers in km (or whatever it was built in) and a geographic one in degrees, neither converted into the other.

It is never constructed by hand and never carries its own copy of the coordinates: it holds the very Y and X dimensions the habitat's active mask is indexed by, so the two cannot drift apart. Reach it through the habitat's StudyArea.

Fields

• crs: the coordinate reference system the coordinates are stated in, or nothing for a synthetic grid, which has none.
• y: the grid's Y dimension - the first array dimension throughout this package.
• x: the grid's X dimension.

SumOfLayerChanges{M <: AbstractChangeMode, P <: Tuple, B} <: AbstractLayerChange{M}

Several changes driving one layer, added together - a stored monthly series plus a multi-year warming trend, say, where the trend offsets the whole seasonal pattern rather than contradicting it.

Composition is a sum of values as functions of elapsed time, evaluated once per step, never a sequence of mutations. Chaining the applications instead would silently fail: an absolute write each step erases whatever a rate had accumulated by then.

M follows from the parts. A part that is a position (a read series) makes the whole an AbsoluteChange - there can be at most one, since two positions cannot be added - and parts keeps it first so the fold adds intervals to it in an order affine units accept. With no such part the whole is a RelativeChange over the layer's captured baseline. A RateChange part contributes its integral, so it must have one in closed form: a steady rate does (value × elapsed), a patterned one would need the integral of its own shape and is refused rather than approximated.

Supply{A}

A supply of the resource measured on niche axis A - a Resource-role ContinuousLayer over a (Y, X) grid: Supply{SolarRadiation} (kJ/day per cell), Supply{Precipitation} (L/day), Supply{CarbonFlux} (g/day).

The axis is the only declaration of what a supply measures: its unit comes from canonicalunit(Resource, A), and an axis that declares no resource cannot be built as a supply at all. Construct one from a matrix of per-cell rates, Supply{SolarRadiation}(fill(200.0kJ/day, 10, 10)), or let GridHabitat do it from a spec that names the axis.

A supply that varies in time is the same type, carrying a SeriesLayerChange.

SupplyCollection2{M1, M2} - two positional supplies over one grid. Deprecated plumbing: use [`LayerCollection`](@ref).

SurfaceArea <: SpaceAxis - ground surface, as a fraction of a cell (EarthEnv LandCover 1-12, or a `SurfaceSpec`).

SyntheticData

Source of a raster that was generated, not read: a synthetic supply or regime field built from a spec. It has no dataset, no layer codes and no catalogue row, and says so rather than borrowing a real dataset's name.

TakenFromAlignedLayer <: AbstractDecisionSource - a cell size taken from the layer being aligned to.

TempTolerance

A temperature preference: a NicheTolerance on Temperature, read in the kelvin frame, with a Trapezoid response.

An alias rather than a type of its own, so it has the fields NicheTolerance has. TempTolerance(matrix) is a shorthand for NicheTolerance(Temperature, Trapezoid, matrix).

Temperature <: TemperatureAxis - an absolute temperature (annual/monthly/quarter mean, min, max, or growing-season mean; BioClim 1/5/6/8-11, Climate tavg/tmin/tmax/tas/tasmin/tasmax, BioClimPlus gst; K).

TemperatureAxis <: NicheAxis - temperature-related niche axes. A pure grouping node: each leaf states its own unit, because they do not share one.

TemperatureRange <: TemperatureAxis - a temperature range (max - min): mean diurnal range or annual range (BioClim 2 and 7; K interval).

TemperatureSeasonality <: TemperatureAxis - temperature seasonality, the standard deviation of the monthly mean temperatures (BioClim 4; K).

ToleranceCollection2{M1, M2} - two positional tolerances. Deprecated plumbing: use [`SpeciesRequirementCollection`](@ref).

ToleranceCollection3{M1, M2, M3} - three positional tolerances. Deprecated plumbing: use [`SpeciesRequirementCollection`](@ref).

Torus = EdgeTopology{Periodic, Periodic}

A toroidal grid: both pairs of edges join, so nothing ever leaves.

True of a synthetic grid. On one with a real-world position it asserts something false - a study area is a window on a globe, not a world that wraps - so it is accepted with a warning.

Trapeze{A, V} <: AbstractNicheFit{A, V}

Trapezoid{T<:Real} <: ContinuousUnivariateDistribution

Trapezoidal distribution as described at https://en.wikipedia.org/wiki/Trapezoidal_distribution.

TypologyAxis <: NicheAxis - categorical classification niche axes (class labels; dimensionless, used with a `CategoricalRegime`).

UndatedSeries()

No calendar identity at all - a synthetic stack, or any series whose coordinates are simply offsets. There is nothing for an epoch to bind to, so elapsed zero is the first slice unless the series' origin says otherwise. This is the only calendar for which origin is meaningful, and the default for any source that does not carry real dates.

Unif{A, V} <: AbstractNicheFit{A, V}

UniformSpec{A <: NicheAxis, V}

A layer with a single constant value in every cell.

Arguments

• value: what every cell holds - a Unitful quantity, or a bare number.
• axis: the niche axis this layer is on. Required: it is what makes the layer matchable against a species' tolerances, and no default could be right for every model. Pass NicheAxis itself for data whose meaning is genuinely not being claimed, such as a mask.

VapourPressure <: HumidityAxis - near-surface water-vapour partial pressure (Climate vapr; kPa).

VapourPressureDeficit <: VapourPressureDeficitAxis - near-surface vapour pressure deficit (Climate vpd, BioClimPlus vpd_max/mean/min; Pa).

VapourPressureDeficitAxis <: HumidityAxis - vapour-pressure-deficit niche axes (level and range).

VapourPressureDeficitRange <: VapourPressureDeficitAxis - annual range of the monthly vapour pressure deficit (BioClimPlus vpd_range; Pa).

Varying(spec, change)

Declare that the layer built from spec carries change. change is a change recipe (ReplaceWith, OffsetBy, IncrementBy) or an already materialised AbstractLayerChange.

Pass it to GridHabitat's regime or supply keyword. A StudyArea ignores the wrapper entirely - a change has no meaning until there is a grid to apply it to, so the area is decided from the spec alone.

GridHabitat(regime = Varying(SourceSpec(WorldClim{BioClim}, :bio1),
                                   IncrementBy(0.02K/yr)),
                  supply = GradientSpec(...), area = area)

Each layer names its own change, so a multi-variable regime wraps its elements, never the tuple: (Varying(temp, ...), rain), not Varying((temp, rain), ...).

WaterAxis <: NicheAxis - umbrella for all water-measuring niche axes (precipitation, humidity, evapotranspiration, moisture, water stocks). A pure grouping node with no unit or resource of its own.

WindSpeed <: WindSpeedAxis - near-surface (10 m) wind speed (Climate wind/sfcWind, BioClimPlus sfcWind_max/mean/min; m*s^-1).

WindSpeedAxis <: NicheAxis - wind-speed niche axes (level and range).

WindSpeedRange <: WindSpeedAxis - annual range of the monthly near-surface wind speed (BioClimPlus sfcWind_range; m*s^-1).

Within(x)

Regions that lie completely inside x.

Answers "which regions can I simulate in full with the data I have?" - the converse of Encloses, and what walks down a hierarchy where that walks up.

Arguments

• x: as Encloses, but not a point - no region fits inside a point.

append!(diversityset::DiversitySet, dat::DataFrame)

Append a DataFrame of diversity results to the data a DiversitySet already holds.

Arguments

• diversityset: the set to append to.
• dat: the results, one row per subcommunity per timepoint.

read(::Type{CERA}, dir::String, file::String, param::String; cut = nothing)

Read one variable out of the CERA-20C netCDF files in a directory - the archive is one file per decade - concatenate them along time, and return a ClimateRaster{CERA}.

Unlike the ERA readers this needs no dim: the monthly time coordinate for each decade is generated here, because the archive's layout is known. Longitudes are wrapped onto (-180°, 180°] as for ERA.

Arguments

• dir: the directory to search.
• file: matched against each filename.
• param: the name of the variable to take out of each.
• cut: an optional region to crop to.

read(::Type{ERA}, dir::String, file::String, param::String,
     dim::Vector{<:AbstractVector{<:Unitful.Time}}; cut = nothing)

Read one variable out of every matching ERA netCDF file in a directory, concatenating them along time, and return a ClimateRaster{ERA}. The multi-file wrapper over the three-argument method above.

Arguments

• dir: the directory to search.
• file: matched against each filename; every file containing it is read, in readdir order.
• param: the name of the variable to take out of each.
• dim: the time coordinate per file - a vector of time vectors, one per matched file.
• cut: an optional region to crop to.

read(::Type{ERA}, file::String, param::String, dim::Vector{<:Unitful.Time}; cut = nothing)

As the two-argument method, but with the file's own time coordinate overridden. Returns a ClimateRaster{ERA}.

Arguments

• file, param: as above.
• dim: one time per layer, replacing what the file says. For files whose CF time metadata is missing or wrong, or which are to be labelled in elapsed time rather than calendar dates.
• cut: an optional region to crop to.

read(::Type{ERA}, file::String, param::String; cut = nothing)

Read one variable out of a single ERA netCDF file, returning a ClimateRaster{ERA} - ERA names the source, and the raster carries the data.

The file's own time coordinate is used as it stands - a genuine Dates.DateTime per layer, decoded from its CF metadata - and its longitudes are wrapped onto (-180°, 180°] to match every other reader. Use the three-argument method to override the time coordinate instead of trusting it, and the four-argument one to read and concatenate a whole directory.

Arguments

• file: the netCDF file to read.
• param: the name of the variable to take out of it.
• cut: an optional region to crop to.

GaussTrait(mean, sd)
GaussTrait(::Type{A}, mean, sd)

HabitatLoss(eco::AbstractEcosystem, regime::AbstractRegime, timestep::Unitful.Time)

Destroy regime for one timestep of the ecosystem. The regime's change carries a loss rate (per unit time); over timestep it gives the per-cell probability that an active cell is lost. That many active cells are drawn at random and have their supply and abundances zeroed.

Deprecated: habitat loss changes the ecosystem, not a layer - it never marks the lost cells inactive, so they stay dispersal targets and can be lost again, and it draws from the global RNG, so it neither replays reproducibly nor agrees across MPI ranks. It is superseded by an explicit cell-deactivating intervention.

LayerUpdate(changefun, rate)
LayerUpdate(changefun, rate, ::Type{<:Unitful.Dimensions})

Construct the AbstractLayerChange that replaces the v0.4.0 change function changefun. The third argument, a dimension to check rate against, is accepted and ignored - a change is now checked against the layer it is attached to instead.

RainfallChange(eco::AbstractEcosystem, layer::AbstractLayer, timestep::Unitful.Time)

Apply one timestep of layer's own change. Deprecated: a rainfall change is now declared as IncrementBy(rate), in the layer's unit per unit time, rather than named as a change function that hard-codes mm - which stopped being precipitation's unit when it became the rate mm/d.

SurfaceSpec(fraction = 1.0; axis = SurfaceArea)

A uniform space layer: the fraction of each cell that is available, from 0.0 to all of it (1.0, the default).

A thin convenience over UniformSpec: it fixes the axis to a space one and checks the fraction is not negative, and nothing more. SurfaceSpec() is the whole-cell case, which is what makes a space supply easy to ask for without its being automatic.

Not capped at 1.0. A cover fraction cannot exceed a whole cell, but a canopy legitimately can, since crowns overlap, so the ceiling belongs to the axis's own bounds rather than here.

Arguments

• fraction: the share of each cell that is available, 1.0 by default.
• axis: which stratum, for when more than one is declared. SurfaceArea is the only SpaceAxis leaf today.

TempChange(eco::AbstractEcosystem, layer::AbstractLayer, timestep::Unitful.Time)

Apply one timestep of layer's own change. Deprecated: a temperature increase is now declared as IncrementBy(rate), in the layer's unit per unit time, rather than named as a change function that hard-codes K.

TempFluct(eco::AbstractEcosystem, layer::AbstractLayer, timestep::Unitful.Time)

Apply one timestep of layer's own change. Deprecated: an oscillation is now declared as IncrementBy(PatternedChange(amplitude, timescale)).

abundances(cache::CachedEcosystem, tm::Unitful.Time)

Extract abundances for an ecosystem, cache, at a certain point in time, tm. If the abundances for that time are missing from the ecosystem, then the function checks on disk for the last saved version and simulates forward.

applyinterventions!(eco::AbstractEcosystem, intervention, elapsed, timestep, step)

Apply every scheduled Intervention for the step that has just reached elapsed. Called by update! - after the population dynamics and before the layer update, so that a SetChange takes effect in the same step rather than one step late.

This is also the supported imperative route: it is the way to act on a running ecosystem without having declared anything in advance, and it takes any operation, not just some privileged subset. To add a species mid-run, having passed no intervention to simulate!:

simulate!(eco, 1year, 1month_mean_duration)
applyinterventions!(eco,
                     Intervention(EveryStep(), AllCells(),
                                  AddSpecies(tolerance = Normal(298.0, 2.0),
                                             abundance = 500)),
                     simulationtime(eco), 1month_mean_duration, 12)
simulate!(eco, 1year, 1month_mean_duration)     # carries on with the new species