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: 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: RasterSpec (read raster data - a catalogued layer, or a file that belongs to no dataset), 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 eight: Deactivate, Reactivate, SetLandCover, SetChange, AddAbundance, RemoveAbundance, AddAbundanceTable 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. Eight 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 two exponents that say how those rates respond to the environment. EqualPop, PopGrowth and NoGrowth are the concrete forms.

Every subtype carries the same four 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.

AbstractRecorder

A value that keeps something from a run each time a simulate! schedule fires - RecordAbundance, RecordDiversity or SaveAbundance. Pass one to simulate! in place of a callback, or call recorder(eco, occurrence) from a callback of your own to keep several things from one run. Each holds the Provenance of the run as it stood at its last write, which provenance returns.

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.

AbstractRunCalendar

How a run relates real dates to elapsed time - ExactDates or MeanMonths. Given as the calendar keyword of build_ecosystem, and used by everything in the run that turns a date into elapsed time or back: where each DatedSeries slice and the epoch fall, and the date simulationdate reports.

AbstractSchedule

When an Intervention fires - EveryStep, AtTime, AtTimes, BetweenTimes, EveryInterval, AtDates, EveryYear 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.

AbstractShapeRule

Abstract supertype of the rules that decide which cells a shape activates: AnyOverlap, FractionWithin, FullyWithin and WholeBoundingBox.

All but the last read one number - the share of the cell's own rectangle lying inside the shape - and admit a tolerance of one part in 100 000 of a cell, so a cell the shape meets only along an edge stays out while a cell covered to within rounding counts as covered.

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.

Which cells a shape activates is a question about rasterising rather than about geometry, so it is ShapeMaskSpec's: a shape used as a within mask on its own covers every cell at least half inside it, and ShapeMaskSpec(shape, rule) states any other rule.

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.

AddAbundanceTable(table)

Add individuals to cells as a table lists them, each row naming a species, a cell, a count and a time - a population seeded from dated records, for instance.

It goes in an Intervention of its own, with EveryStep. Its rows say when, so each step adds the rows whose time falls within it, and a row at or before the start of the run is added to the starting state. The intervention's region filters the rows: ActiveCells() drops those in an inactive cell, and CellMask(mask) those outside the mask.

The rows of one species and cell that fall in the same step are summed and then rounded to a whole number of individuals, ties to even. A date is placed through the run's epoch and calendar as AtDates places one, and must fall at the end of a step unless the steps are a day or shorter. build_abundance_table writes a table in this form from species names and grid positions.

The table may be streamed. One offering whole columns - a DataFrame, a NamedTuple of vectors, a memory-mapped Arrow file - is searched for the rows each step needs, so the operation holds no state and can serve any number of runs. One offering only rows, such as a CSV.Rows or a generator of named tuples, is read once, forwards, as the run proceeds: its rows must be in time order, and the operation serves a single run.

Arguments

• table: any Tables.jl source with the columns species (a species' name or its index in the species list), cell (a cell's linear index into the grid, which is its column in the abundance matrix, or its CartesianIndex (y, x)), time (an elapsed time from the start of the run, or a date) and, optionally, count (how many individuals, one per row without it).

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. A RecordAbundance writes into an array sized before the run starts, so a run that gains species needs RecordAbundance(eco, ntimes, maxspecies = ...), or storage from 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.

AnyOverlap()

Activate every cell the shape covers any part of.

The most inclusive rule: a coastal cell is simulated whatever share of it is land, so no ground the shape names is left out of the grid.

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.

AtDates(dates)

Fires once for each of dates, on the step that reaches each - AtTimes given real dates rather than elapsed times. A date becomes an elapsed time through the run's epoch and calendar (see build_ecosystem), so a run with no epoch refuses one before its first step. A date at or before the epoch acts on the starting state, before the first step, as an elapsed time at or before zero does. A date the run reaches must fall at the end of a step, or the step be no longer than a day: one falling inside a longer step would be acted on late, so the run is refused before its first step.

Arguments

• dates: the Dates or DateTimes to fire at.

AtTime(time::Unitful.Time)

Fires on the single step that reaches time - the first step whose elapsed time is at or past it. A time at or before the start of the run acts on the starting state, before the first step.

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]. It acts over steps taken, so not at the start of the run even when from is zero.

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.

CDSRequest(dataset::AbstractString, request::AbstractDict, path::AbstractString)

A file fetched from the Copernicus Climate Data Store on first use and kept at path: the CDS dataset to ask ("reanalysis-era5-single-levels-monthly-means"), the request as the CDS takes it (product type, variable, years, months, area, format), and where the answer is written. Nothing is fetched at construction; assetpath fetches it through CDSAPI.jl when path does not yet exist, so a file already downloaded is never asked for twice, and writes a provenance record beside it holding the request and the CDS job. An entry of a RasterSpec's files. CDSRequest(ERA, code; years, path) builds one from a catalogued layer instead of the CDS's own names.

Fields

• dataset: the CDS dataset name.
• request: the request body, keys as the CDS documents them, values strings or vectors of strings.
• path: where the file lives once fetched.

CDSRequest(::Type{ERA}, code; years, path, months = 1:12, area = nothing)

Build the Climate Data Store request for one ERA5 monthly-means layer from its catalogue code, to be fetched into path on first use: CDSRequest(ERA, "t2m", years = 1990:1999, path = "era5_t2m_1990s.nc"). The CDS's own name for the variable comes from the ERA table's Request column, so a code with none is refused.

Arguments

• code: the layer, as the ERA table spells it.
• years: the years to ask for, a range or a vector.
• path: where the file lives once fetched.
• months: the months of each year, 1:12 by default.
• area: (north, west, south, east) in degrees to cut to, or nothing for the globe.

CERA <: EcoSISTEMSource

The CERA-20C reanalysis archive, as a data source: one netCDF file per decade, named as for ERA - SourceSpec(CERA, "t2m", files = decades), joined along time on read.

Fieldless, as ERA is.

CRUTS <: EcoSISTEMSource

The CRU TS archive, as a data source: a directory of monthly GeoTIFFs, named with SourceSpec(CRUTS, "tavg", directory = dir) and read as one series in file-name order.

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; path = nothing)

An immutable descriptor for a file downloaded from url on first use: into EcoSISTEM.assetdir(owner = owner) under the URL's own file name, or to path where one is given, which is how a project keeps a download under its own data directory. Nothing is downloaded at construction - call assetpath to get the local path, downloading it first if it is not there. The download is resumed from whatever an interrupted one left, and a provenance record is written beside the file (see provenance).

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, and the catalogue row its provenance record is filled from where the owner is a data source.
• url: where to fetch it from.
• path: where it lives once fetched, or nothing for the owner's cache directory.

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 study area is decided, so it narrows the grid the habitat is then built on.

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...; axis, combinestage = CombineOnTargetGrid(),
                      atend = RepeatAtEnd(), calendar = nothing)

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.
• atend, calendar: for a combine returning a raster with a time axis, what the series it becomes does past its last slice and what its coordinates mean, as on SourceSpec.

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())

Combine several shapes into one mask - the union of the United Kingdom, Ireland and the Isle of Man, a country with an island group cut out of it, or a study area of your own buffered by a distance - or transform one.

Shapes 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; read(spec) gives the pieces of ground the result is.

# 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, each wanting two or more members; or how one is transformed - ShapeBuffer, ShapeSimplify or ShapeConvexHull, each wanting exactly one; or a function handed one geometry per member and returning one.
• members: any shape specs - a ShapeSpec of your own, a NaturalEarthSpec, or a nested ConstructedShapeSpec - as many as the operation wants.
• 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.

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.

DatasetRecord

A dataset's row of the shipped datasets.csv: the fixed facts about a whole data source that no layer row carries, returned by datasetinfo.

• dataset: the source type as it is written - WorldClim{BioClim}, CHELSA{Climate}, ERA.
• format: how the files are encoded, :GeoTIFF or :netCDF, which chooses the backend that opens them, or :Shapefile for a source of zipped vector outlines.
• longituderange: the longitude convention the files use, (-180°, 180°) or (0°, 360°), or nothing to read it off each file.
• crs: the coordinate reference system, an EPSG code or a WellKnownText, or nothing.
• resolution: the cell sizes the provider offers, each a length or an angle, or nothing.
• extent: the ground the dataset covers, an Extents.Extent of Y/X bounds in degrees, or nothing.
• fetch: how files are obtained - :getraster (through RasterDataSources), :cds (a Copernicus request), :https (a plain download) or :none (they must be given).
• url, doi, licence, version, citation, notes: provenance, blank where unknown; citation is the text a paper prints for the dataset, as the DOI resolves to it.

A blank cell means ask the file, so every field but dataset, format and fetch may be nothing. A recorded fact the file can contradict is checked on the first read of that dataset - longituderange, crs, resolution and extent are header facts, compared against the file's own and refused, naming the table, when they disagree. Provenance and format are not checked: a wrong format fails to open on its own.

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: monthly means on single levels, one netCDF file per variable per decade as the Climate Data Store serves them. Name a layer with SourceSpec(ERA, "t2m", file = path) - or files = decades in time order, or a EcoSISTEM.CDSRequest entry fetched on first use - and read it, or build on it, like any other; the ERA layer table supplies the unit, axis and accumulation period.

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, VectorData 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 - and calendar the AbstractRunCalendar its dates are placed by. inputs holds the InputRecords of published data belonging to the run as a whole - those given to build_ecosystem, and those of every intervention that has acted - which provenance lists.

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.

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.

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).

EveryInterval(interval::Unitful.Time)

Fires at every whole multiple of interval - 0, interval, 2interval and on - each on the step that reaches it, exactly as AtTimes would over that unending list. The multiples are counted from the start of the run, so the answer does not depend on the timestep; the multiple at zero acts on the starting state, before the first step.

Arguments

• interval: the elapsed simulation time between firings, which must be positive.

EveryStep() <: AbstractSchedule - fires after every timestep, and not at the start.

EveryYear(; month = 1, day = 1)

Fires on the step that reaches day of month in every year of the run, from the epoch on - an anniversary on the epoch acts on the starting state, and one before it does not fire. Its dates are placed through the run's epoch and calendar as AtDates's are, so a run with no epoch refuses it before its first step, and so is each anniversary checked against the steps as a date is: under ExactDates 1 January is 365 or 366 days after the one before, so no step of month_mean_duration or year ends on every one, while under MeanMonths every twelfth month_mean_duration does.

Arguments

• month: the month of the year, from 1 to 12.
• day: the day of that month, which must be one every year has - so 29 February is refused.

ExactDates()

Dates are placed by the real time between them, so a slice dated 1 March 2000 falls 60 days after one dated 1 January 2000. The default. Real months are 28 to 31 days long, so a timestep of month_mean_duration against a dated monthly series leaves some months never current, and simulate! refuses such a run before its first step.

FractionWithin(fraction)

Activate every cell the shape covers at least fraction of.

FractionWithin(0.5) is what a shape passed as within means on its own, and roughly keeps the region's area: the ground lost from the cells that are less than half covered is about the ground gained from the cells that are more.

Arguments

• fraction: the share of a cell that must be covered - greater than 0, and at most 1. Write AnyOverlap for any cover at all, which no positive threshold expresses.

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

FullyWithin()

Activate only the cells the shape covers completely.

The conservative rule, for a run that must put nothing on ground the shape does not name: a coastal cell with any water in it is dropped. It is the same test as FractionWithin(1.0).

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.

Under MPI with more than one rank this is a collective call, made on every rank in the same order; see Building is collective.

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.

InputRecord(; role, dataset, code = nothing, path = nothing, url = nothing, request = nothing,
            job = nothing, fetched = nothing, bytes = nothing, sha256 = nothing, doi = "",
            licence = "", version = "", citation = "")

The provenance of one published input to an experiment: a file this package fetched, or a dataset you handed it that it never fetched - an occurrence download, a trait table, a phylogeny. One shape for both, so that everything an ecosystem was built from can be listed together and a paper's references written from the list. provenance reads the records the package wrote; you write one for anything it could not have known about.

Fields

• role: which part of the system the input entered by - :habitat for a layer, :region for a shape or a named region's outline, :species, :phylogeny, :dispersal, :demography or :intervention for what you attached, :abundance for records a starting population was placed from, :state for a saved run a forward run starts from, :software for the package itself.
• dataset: the source's name - a catalogue key such as TwentyCR or WorldClim{BioClim}, or your own name for a dataset of yours.
• code: which layer of the source, where the input is one.
• path: the file's own name, or a path relative to wherever its record sits - never an absolute one, since a record is meant to be committed and shared.
• url: where it was fetched from, where it was.
• request: the request body sent to a service, as it was sent.
• job: the identifier a service gave the request.
• fetched: when it was fetched, in UTC.
• bytes, sha256: the file's size and checksum at fetch, which is what tells a truncated or replaced copy from the original.
• doi, licence, version, citation: the dataset's own, blank where unknown; citation is the text a paper prints.

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.

An intervention built from published data - a land-use scenario, the occurrence records a population is seeded from - says so with provenance, an InputRecord or a vector of them. The records join the ecosystem's own the first time the intervention acts, so provenance of the ecosystem lists an intervention that has acted and not one that never fired.

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.
• inputs: the files each read came from, an InputRecord per file under the read's own key - a file's provenance record where it has one, and otherwise its name and the catalogue's facts about its dataset.

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. documentedceiling is its companion: the largest value the layer's documented unit could plausibly reach, from the DocumentedCeiling column, or nothing where the table says none. It is what tells a layer that is still published at publishedscale from one that has since been corrected, and so is only set where publishedscale is.

verticalextent is where above or below the surface the layer is measured, from the VerticalExtent column: a single signed height (2m for a 2 metre air temperature) or a from..to pair for a layer of ground (-7cm..0cm for the top soil layer), heights positive upward, or nothing for a surface value. Every reanalysis has one. A range on a layer whose values are a fraction of the layer's volume is what turns that fraction into a depth on read, and on a file holding several soil layers it is what selects the one to take; otherwise it is recorded, not checked.

file is where the layer's file is fetched from, for a source whose datasets.csv row says its files come by plain https download - a URL from the File column - or nothing where the table has no such column or the cell is blank. request is the name the layer goes by in a request to the source's service - the Climate Data Store's 2m_temperature for ERA5's t2m, from the Request column - or nothing likewise; EcoSISTEM.CDSRequest builds a request from it.

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 aggregated onto the grid from the source cells covering each of its cells, weighted by how much of the cell each covers - not exact, because the grid's cells are not unions of the layer's, which is the thing the whole alignment story exists to avoid. reason says why it was unavoidable. Where the grid is at least twice as coarse as the layer, the layer is first aggregated exactly on its own lattice by the whole part of the ratio and only the residual is sampled; reason says so too.

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. Every rank takes the first rank's species list and seed when the ecosystem is built, so a species list or seed drawn at random on each rank still gives one ecosystem.

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.

MeanMonths()

Every calendar month counts as month_mean_duration (30.44 days). A dated slice falls at the number of whole calendar months since its series' first slice times that duration, whatever day of the month it is dated, and the epoch falls at its own month plus the fraction of that month it has reached - as a MonthOfYearSeries climatology is already placed. A monthly series stepped by month_mean_duration then makes every month current exactly once. A dated series with two slices in one calendar month is refused, since counting months says nothing about days.

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())

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.

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

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.
• seed: an integer fixing the layout. It is drawn from a stream of its own, so the same seed gives the same map in any process whatever else has used the global random generator; nothing, the default, draws from the global generator.

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.

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.

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.

Provenance

What a study area, a habitat or an ecosystem can say about how it came to be, returned by provenance: the software, the published inputs, the grid and, for an ecosystem, the run.

Fields

• software: a named tuple of the package, its version, the doi every version of it is cited by, and the julia version.
• inputs: an InputRecord per input, one per file, in a fixed order.
• grid: a named tuple of the grid's crs (nothing for a synthetic grid), its cellsize, the extent its cells cover, and how many cells it has and how many of them are active.
• run: for an ecosystem, a named tuple of its seed, its epoch (nothing without one), the run calendar its dates were placed by and the time elapsed; nothing for a study area or a habitat.

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.

RasterSpec{A <: NicheAxis, U} <: AbstractLazySpec

Name raster data to be read, without reading it - a layer of a catalogued data source, written SourceSpec(source, code; ...), or a raster file that belongs to no dataset, written RasterFileSpec(path; axis, ...). It holds no grid array: the read, the cut and the resample happen only when it is materialised onto a decided grid, so a global file costs the window the study area needs rather than the globe, and refining an area re-reads nothing.

Four things say what is read. What the data is: the source type and the code of the layer, which is what the shipped catalogue is keyed on for a unit and an axis, and which the caller may override; a file that belongs to no dataset has no code, so it must be told both. Where the files are: an explicit list, or nothing for a source that resolves its own, as a catalogued dataset does. How it is read: cut windows the read to a box, scale coarsens by a whole number of cells a side, and fn says how a block is reduced. And how the files become one array in time: times labels the slices where the files cannot, atend says what the series does past its last slice, and calendar what its coordinates mean.

Fields

• source: the data source, a type marked EcoSISTEM.IsRasterData - a dataset such as WorldClim{BioClim}, or SyntheticData for a file that belongs to no dataset.
• code: which layer of the source, as one CODE_TYPE or a vector of them; nothing for a bare file, and never for a catalogued source, since a whole-dataset spec resolves the dataset's own code list at construction so that every layer's identity is known before anything is read and each can keep its own unit.
• files: the files to read, in time order, each a local path, the EcoSISTEM.CachedAsset a URL becomes, or a EcoSISTEM.CDSRequest fetched on first use; nothing where the source resolves them itself. Each file is opened by the backend its source's catalogue row names, so a netCDF file without an extension reads.
• unit: the physical unit attached on read. NoUnits where a multi-layer spec's layers disagree, as a neutral placeholder, and for a file given none.
• cut: an Extents.Extent of ° intervals to window the read to, or nothing for all of it. Applied before the pixels are fetched, so cutting a global layer to one country costs the country.
• scale: an integer factor to coarsen by on read, each block of scale × scale cells becoming one, or nothing where the study area may choose one to suit its grid. A stated scale, 1 included, stands. A coarsened read of a whole file is memoised on disk, so the cost is paid once per file rather than once per study area; a cut alongside skips the memo and the cost.
• fn: how a block is reduced to one cell, or nothing for the axis to decide - the most frequent class (ties to the smallest code) for a TypologyAxis, whose codes must not be averaged, and the mean for any other. On a grid much coarser than the layer the reduction runs in two stages, on the layer's own lattice and then onto the grid, so it must compose: a mean, a maximum or a minimum do exactly, the most frequent class approximately.
• times: the coordinates of the third axis, one per slice, replacing what the files say - for files carrying no time coordinate, or to label them in elapsed time rather than calendar dates; nothing to take the files' own, or monthly ordinals where they have none.
• atend: what the series the stack becomes does past its last slice, an AbstractSeriesEnd; RepeatAtEnd by default, which a climatology of even months cycles by. A series of real dates cannot cycle evenly and says HoldAtEnd or ErrorAtEnd.
• calendar: what the coordinates mean, an AbstractSeriesCalendar, or nothing to infer it: real dates give a DatedSeries, anything else an UndatedSeries; a monthly climatology says MonthOfYearSeries itself.
• readkw: keywords the source needs to resolve its files, kept for the eventual read - month = 1:12 for a monthly climatology, say. A spec nested inside a ConstructedRasterSpec can therefore carry its own read options.

Type parameters

• A: the niche axis, which is what matches the layer to species niches. 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: the type of unit.

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.

RecordAbundance(storage::AbstractArray)
RecordAbundance(eco::Ecosystem, ntimes::Integer; maxspecies = length(eco.spplist.abun))

Record every species' abundance in every cell into storage, one slice per occurrence: storage[:, :, k] holds species by cells at occurrence k. Under MPI the ranks' abundances are gathered and the root writes them, every rank taking part in the gather.

The second form allocates the storage with generate_storage. A run reaching more occurrences than the storage has room for, or gaining more species, is refused when it tries to record them.

Arguments

• storage: an integer array of at least species × cells × occurrences, as from generate_storage.
• eco: the ecosystem whose species and cells size the storage.
• ntimes: how many occurrences to leave room for.
• maxspecies: how many species to leave room for, counting any an intervention adds.

RecordDiversity(storage::AbstractArray, measure, qs::AbstractVector)

Record a subcommunity diversity measure - such as Diversity's norm_sub_alpha - at each of the orders qs into storage, one slice per occurrence: storage[:, :, k] holds cells by orders at occurrence k. Under MPI each rank's cells are gathered with gatherdiversity, so every rank holds and writes the whole answer.

Arguments

• storage: a float array of at least cells × orders × occurrences, as from generate_storage(eco, length(qs), ntimes, reps).
• measure: the subcommunity diversity function, returning a DataFrame with a :diversity column. A metacommunity or individual measure is refused.
• qs: the orders to measure at.

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.

A supply is a per-cell capacity in whatever quantity measures it - a flux, such as light or rain per day, or a stock, such as ground or the water standing in the soil - and each is a proxy for the capacity along its axis rather than a thing that is used up: the model currently draws nothing down, so a stock and a flux regulate in exactly the same way, through the ratio of demand to supply. Both are therefore admissible, and an axis says which it provides in its resource unit.

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.

SaveAbundance(folder::AbstractString, name::AbstractString)

Save every species' abundance in every cell to a JLD2 file at each occurrence, in folder, named name followed by the occurrence's number counted from 00 - so <name>00.jld2 holds the first - with the run's provenance beside each as <name>00.provenance.toml. Under MPI the ranks' abundances are gathered and the root writes the files.

Arguments

• folder: the directory to write into, created if it does not exist.
• name: the start of each file's name.

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.

ShapeCoverage(shape; axis)

The share of each cell that a shape covers, as a layer: a coastline becomes the land area of every cell, with the water left out.

land = ShapeCoverage(NaturalEarthSpec("Scotland", coverage = LargestLandmass()),
                     axis = SurfaceArea)
GridHabitat(regime = ..., supply = land, area = area)

The value is a fraction, from 0 where the shape misses a cell to 1 where it covers one, measured as the area of the cell's own rectangle lying inside the shape. A cell the shape touches only along an edge shares no area with it, and gets nothing. As a supply on SurfaceArea that fraction becomes an area per cell, using each cell's true area, so it is land rather than ground; as a regime it stays the fraction itself.

Every other value is built from the fraction with a ConstructedRasterSpec - f -> f .> 0 for the cells with any land, (land, cover) -> land .* cover to take a land-cover share of it.

It adopts the grid it is built on, as a generated layer does, so it never decides a study area's extent, resolution or CRS; and it needs a positioned area, since geometry can only be placed where there is a coordinate system to place it in.

Arguments

• shape: any AbstractShapeSpec - a ShapeSpec of your own file, a NaturalEarthSpec, or a ConstructedShapeSpec combining them.
• axis: what the fraction means, as for every other layer spec. A categorical axis is refused: a covered share is a continuous quantity.

ShapeDifference() <: AbstractShapeOperation

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

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

ShapeMaskSpec(shape, rule = FractionWithin(0.5))

Mask a study area by a shape under a stated rule - how much of a cell the shape must cover for that cell to be simulated.

StudyArea(regime = temperature, cellsize = 1km, crs = EPSG(27700),
          within = ShapeMaskSpec(NaturalEarthSpec("Scotland"), AnyOverlap()))

A shape passed as within on its own means FractionWithin(0.5), so this is what to write when a different rule is wanted: AnyOverlap to keep every cell with any land in it, FullyWithin to keep only whole cells, WholeBoundingBox to take the box and rasterise nothing.

The rule belongs here rather than on the shape because it is a question about rasterising - it has an answer only once there is a grid - while a shape is geometry, and composes with other geometry exactly and at no resolution.

Arguments

• shape: the ground, as any AbstractShapeSpec - a ShapeSpec of your own file, a NaturalEarthSpec, or a ConstructedShapeSpec combining them.
• rule: which cells that ground activates, as an AbstractShapeRule.

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, coverage = AllTerritories())

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 dissolve of its features into connected pieces of ground, the 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; read(spec) gives the pieces themselves.

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. A URL must name a self-contained file - a .zip, a GeoJSON or a GeoPackage. Only the one named file is fetched, so a bare remote .shp cannot be read: its .shx, .dbf and .prj companions never arrive and GDAL refuses the result. Point at the zip the shapefile is published in instead, or download the set by hand and give the local .shp path.
• layer: which layer of the file, 0-indexed. Every polygon feature in it is used.
• coverage: how much of the ground the file covers to take, once its features are dissolved into connected pieces - AllTerritories, the default and everything the file holds, LargestLandmass for the principal piece, or LandmassesAbove for every piece clearing a threshold.

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).

SoilVolume <: SpaceAxis - the soil available for rooting, as a depth of soil over a cell (m); a supply of m^3 per cell.

SoilWaterVolume <: WaterAxis - the water standing in a soil layer, as a depth over the cell (mm; ERA5 swvl1, 20CRv3 soilw); a supply of m^3 per cell.

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(source, code = nothing, unit = nothing; axis, files = nothing, file = nothing,
           directory = nothing, cut = nothing, scale = nothing, fn = nothing,
           times = nothing, atend = RepeatAtEnd(), calendar = nothing, readkw...)

Name a layer of a catalogued data source, without reading it, as a RasterSpec - one whose files the source resolves for itself, or one reading files you name, which the catalogue still describes: SourceSpec(ERA, "t2m", file = path) reads variable t2m out of an ERA5 netCDF file with the unit, axis and accumulation period the ERA table gives it, and SourceSpec(CRUTS, "tavg", directory = dir) reads a directory of monthly GeoTIFFs as one series.

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.
• files, file, directory: where the data is, when the source does not fetch it itself - a vector of files in time order, one file, or a directory whose raster files are taken in name order; each a local path, a URL, or a EcoSISTEM.CDSRequest. At most one of the three. Required for a source whose catalogue row says its files are not fetched for it (ERA, CERA, CRUTS), and refused for none. A source whose row says its files come by plain download (TwentyCR) fetches the layer's own file into the asset cache on first use unless one of the three names a copy already held.
• cut, scale, fn: the read options, as the RasterSpec fields of those names. Give a scale a cut as well where the whole world is not needed: on its own a scale coarsens the whole source file however small a result is wanted, because the aggregated form is memoised per file, and for a global dataset that first read can need many gigabytes.
• times, atend, calendar: how the files become one series, as the RasterSpec fields of those names. A netCDF file's own dates are kept unless times replaces them.
• 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.

SpaceAxis <: NicheAxis - the physical space niche axes: ground surface and soil; canopy 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.
• inputs: the InputRecords of the published data the species were built from - occurrence records, trait tables, parameters from the literature - as given with provenance.

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}; names = nothing, provenance = InputRecord[])

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.
• names: one name per species, unique, as a vector of strings. Left unset, the species are named "1" to "numspecies". The names label the species' Diversity types as well, so a diversity measure reports them.
• provenance: an InputRecord, or a vector of them, for the published data the species were built from; provenance of an ecosystem built from them lists these.

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.