6. DEFINITIONS OF FUNCTIONAL GROUPS
6.1. Introduction to functional groups
Types of functional groups
Biological components are represented as biomass pools (most non-vertebrates), age-structured biomass pools (some invertebrates) or age-structured groups (vertebrates). These three group types are assigned according to the GroupType and NumCohorts parameters given in the functional_groups.csv file (Table 8). Group types FISH, FISH_INVERT, SHARK, MAMMAL, BIRD, REPTILE are assigned to the fully age-structured groups with the number of age groups given by NumCohorts. Other groups are assigned to biomass pools. If NumCohorts for a biomass pool is >1 they will be assigned to an age-structured biomass pool. The age-structured biomass pools are similar to stanzas used in, for example, Ecosim and are used to allow for different juvenile and adult behaviour and parameters. All non-vertebrates that have NumCohorts=1 are assigned to simple biomass pools.
Can a non-vertebrate be modelled as an age-structured group?
Six GroupTypes (FISH, FISH_INVERT, MAMMAL, SHARK, BIRD and REPTILE) are currently modelled as age-structured groups. If full age-structure is needed for a non-vertebrate, it should be set as one of these groups, most likely as FISH_INVERT or FISH. FISH_INVERT currently uses the same code as FISH, but the intent is to use it to represent a size rather than age-based model, which is a more typical representation for key invertebrates (such as exploited species). Note however that setting a group as FISH_INVERT or FISH would not call typical non-vertebrate routines (see below).
Atlantis does not explicitly model sex, but represents an average individual. This means that all individuals in a biomass pool and an age cohort (or a genotype in a cohort, if multiple genotypes are modelled) are considered identical in terms of their reproductive output. This may require some caution in parameterisation, e.g. number of offspring per mammal individual.
State variables tracked
Main model
In models that are based on N only (i.e. do not explicitly track P and C) the only state variable tracked for most biomass pools is N, but both N and Si fluxes are tracked for Si limited biomass pools, such as diatoms. The Si limited groups are identified from the functional_groups.csv file parameter IsSiliconDep (see below). In age-structured groups three variables are tracked for each age cohort: reserve N (RN), structural N (SN) and numbers (Num). In addition, fluxes in the water column and sediments are tracked through eight inanimate pools: ammonia (NH), nitrate (NO), dissolved silica (Si), detrital silica (DSi), dissolved oxygen (O2), dissolved organic nitrogen (DON), labile detritus (DL), and refractory detritus (DR). An additional inanimate pool, carrion (DC), is also required, though it is only dynamically used if the fisheries submodel is active; DC is then used to represent fisheries discards. State variables tracked for each group defined with the GroupType parameter in the functional_groups.csv file are listed in Table 8.
Extended models
If the model also includes tracking of P and C (trackAtomicRatio is set to 1 in run.prm), then P and C pools are tracked for each functional group, together with N pools. Additional inanimate pools are for C and P are also required. If the model is of an estuary (FlagIsEstuary=1 in run.prm file) a sediment (SED) inanimate pool is added for the water column. If the model tracks contaminants (track_contaminants=1 in run.prm) a separate pool is added for each contaminant for each nitrogen pool tracked, so that concentration of contaminants can be tracked throughout the entire food web. If the model spans polar regions (flagIsPolar=1 in run.prm) the model allows for 24 hours of night/daylight seasonally.
Allocation of pools throughout the vertical dimension: water column, epibenthos and sediment
Atlantis models 3-5 explicit distribution types of organisms and inanimate pools through the model domain – water column, epibenthic layer and sediments are tracked in all models and ice and land may also optionally be included. The water column and sediment are modelled as three dimensional spaces (units of variables are in m3), whereas the epibenthic layer is two-dimensional (units in m2). Most organisms are restricted to one type, such as sediments (infaunal invertebrates identified with INF in GroupType name), epibenthic layer (epibenthic organisms, identified with EP in the GroupType name) or water column (fully age-structured groups). Some of the smaller groups (e.g. microflora primary producers) and the inanimate pools can exist in both the sediments and water column (Table 8).
In the Atlantis code the water column, epibenthic, sediment, ice and land distributionns are referred to as “habitatType”. However, remember that they are not the same as the ecological epibenthic habitats modelled in Atlantis (e.g. seagrass, corals, sponges etc.).
| Group | State variables tracked | GroupType in CSV file or initial_conditions.nc |
|---|---|---|
| Biomass pools | ||
| pelagic bacteria | N in water column | PL_BACT |
| sediment bacteria | N in sediments | SED_BACT |
| Age-structured biomass pools | ||
| These groups can be age structured if NumCohorts set > 1 | ||
| non epibenthic primary producers | N in water column N in sediments Si in water column Si in sediments NOTE: Age-structure not recommended |
SM_PHY LG_PHY MICROPHTYBENTHOS DINOFLAG |
| epibenthic primary producers | N in epibenthic layer for each age group defined by NumCohorts parameter. If age-structure is selected for SEAGRASS it is not really age structure, but different parts of the plant – with “age 0” assumed to be the pool representing leaves, “age 1” the roots, and “age 2” the epiphytes on the leaves, see details here | PHYTOBEN SEAGRASS |
| infaunal invertebrates | N in sediments for each age group defined by the NumCohorts parameter. NOTE: Not typically age-structured |
SM_INF LG_INF |
| epibenthic invertebrates | N in epibenthic layer for each age group defined by the NumCohorts parameter | SED_EP_FF SED_EP_OTHER MOB_EP_OTHER CORAL SPONGE |
| water column invertebrates | N in water column for each age group defined by the NumCohorts parameter | SM_ZOO MED_ZOO LG_ZOO |
| land plants | N on land for each age group defined by the NumCohorts parameter | MARSH MANGROVE |
| large invertebrates | N in water column for each age group defined by NumCohorts parameter | CEP PWN |
| Age-structured groups | ||
| vertebrates | RN in water column SN in water column Num in water column for each cohort defined in NumCohorts parameter |
FISH SHARK MAMMAL BIRD REPTILE |
| size/age structured invertebrates of particular interest | RN in water column SN in water column Num in water column for each cohort defined in NumCohorts parameter |
FISH_INVERT |
| Inanimate pools | ||
| Ammonia | NH3 in water column NH3 in sediments |
NH |
| Nitrate | NO3 in water column NO3 in sediments |
NO |
| Oxygen | O2 in water column O2 in sediments |
O2 |
| Dissolved organic nitrogen | DON in water column DON in sediments |
DON |
| Dissolved silica | Si in water column | Si |
| Detrital silica | DSi in water column | DSi |
| Labile detritus | N in water column N in sediments |
LAB_DET |
| Refractory detritus | N in water column N in sediments |
REF_DET |
| Carrion (only dynamically tracked if fisheries are active) | N in water column N in sediments |
CARRION |
| Sediment (only if flagIsEstuary=1) | SED in water column | SED |
Timestep of the model
The timestep at which most processes are repeated is typically an adaptive daily (24h) or diurnal (12h) timestep, though tidal models with shorter timesteps (3h or 6h) also exist. This timestep is specified as dt in the run.prm file. Reproduction, recruitment and migration occur less frequently, typically once per year.
The adaptive timestep means that for most of the groups the processes are repeated once per timestep, but for small organisms, such as bacteria and phytoplankton the timestep is reduced to ensure that fluxes into and out of the component with the fastest turnover rates remain stable and numerical artifacts are not introduced into the mathematical solution scheme. The length of the adaptive timestep for such groups is determined to ensure that the relative change (flux) in any variable does not exceed a pre-specified proportion of the standing stock – this tolerance is set in the biology.prm file. The adaptive timestep changes through time, depending on the standing stock of these groups and the temperature, nutrient availability and other factors that affect the turnover rates in these “fast” variables.
Biological processes modelled
The modelled biological processes include primary production, bacterial processes, feeding, assimilation, waste production, explicit respiration (optional and not used in most models), growth, movement and migration, non-predation mortality, maturation, reproduction and recruitment. In biomass pools all processes are modelled through biomass (nitrogen) turnover. In age-structured groups, the state variables are numbers-at-age and weight-at-age (tracked as reserve and structural nitrogen) which can be converted to biomass.
6.2. Defining functional groups
The functional group input file sets all the biological groups in the model. It can be set in CSV or XML format (see examples here). The number of groups is entirely flexible, but each model must include three obligatory detritus groups: carrion (CARRION), labile detritus (LAB_DET) and refractory detritus (REF_DET).
The functional_groups.csv file defines the biological groups used in the model and some of their key characteristics. These characteristics are used throughout the code to apply different appropriate routines for the group. The number of groups in the functional_groups.csv file must match the number given in the K_num_tot_sp parameter in the run.prm file. The detritus groups must be defined as the last three groups in the file.
Currently each group must have the following parameters (characteristics). For new updates, check the Atlantis wiki functional group page
| Parameter name | Description |
|---|---|
| GroupCode | 2 or 3 letter code of upper case letters used to identify each functional group. Atlantis will display an error message and quit if the group codes are not the correct format. This code is very important and applied to all functional group specific parameters |
| Index | An index of the group. Atlantis doesn’t actually read this in but it is helpful for modellers to see as it defines the order of read-in for species vectors and the group ID number if you are trying to activate some of the debug/calibration fprintf statements using whichcheck in the run.prm file. The index must start form 0, as this is how the C programing language counts |
| IsTurnedOn | A boolean value (either 0 (false) or 1 (true)) to indicate if the group is active in the current model run. If the group is not active it will be excluded from the model. This option allows the user to exclude some groups from the model without having to setup new initial conditions and parameter files. |
| Name | Name of a group. This must match the tracer names in the initial_conditions.nc file as it used to find the tracers in the initial_conditions.nc input file. |
| LongName | The long name written to the NetCDF output files. This name can be a few words long and ideally should be informative. This is especially important when sharing the model with others. |
| NumCohorts | The number of cohorts in a functional group. If the value is > 1 the groups is assumed to be age-structured (either an age-structured biomass pool or age-structured group). In the earlier Atlantis versions age structured groups all had to have 10 cohorts. This is now relaxed and there is no upper limit on the number of age-groups to model (but remember, the more age groups the slower the model will run). |
| NumGeneTypes | Number of discrete phenotypes in each age group. This option is used when simulating evolution or multiple size-at-age representations and should only be set to >1 if flag_do_evolution is set to 1 in biology.prm file. If more than one phenotype is present, initial conditions will be have to be set up for each phenotype. |
| NumStages | This parameter describes the number of separate stages in a functional group, which are set to 1 or 2 if juvenile and adult stages have separate parameters for distribution, mortality, migration, feeding and others. In principle, more than 2 stages are possible, although this has not been tested. Typically all age-structured groups have 2 stages, but age-structured biomass pools can also have separate parameters for juvenile and adult stages and thus have 2 stages. |
| NumSpawns | Number of spawns in the year. Typically one per year, but more than one is possible (especially for ages structured biomass pool groups). The timing of spawn is given in Time_Spawn_XXX parameter in biology.prm file (if NumSpawns is 1 it expects a single value, otherwise it expects a vector of length NumSpawns). |
| NumAgeClassSize | Number of calendar years in one age group. This can be set to be anything between a few months to many years and allows simulation of different longevity organisms without having to setup too many age groups (which reduces simulation speed). Note, all individuals in an age group are considered identical (unless different phenotypes are set in NumGeneTypes, in which case all individuals in one phenotype of one age group are identical). However, the proportion of an age group per annual cohort is tracked so that recruitment variation is represented through time and not homogenized away (see chapter 10.9.6). |
| NumStocks | This sets the number of geographically distinct stocks for age-structured groups and age-structured biomass pools. The stocks must occupy different boxes or layers, i.e. they do not spatially overlap. Some biological parameters, like vulnerability to prey can be set as stock specific, which allows for better tuning. It has been applied to some groups that are known to include ecologically distinct stocks in different geographic areas. If NumStocks >1 then the corresponding number of stock specific parameters will be required in the biology.prm input file |
| VerticallyMigrates | If true then the group can move vertically through the water column. This should be set to 1 except for debugging purposes. If this is set to 0, no vertical movement will happen even if it is specified in the biology.prm file and the vertical distribution of individuals in the initial_conditions.nc file will be retained throughout the simulation. |
| HorizontallyMigrates | If true then the group can move horizontally throughout the model as well as migrate out of the model. No migration will happen if this is set to 0. Biomass pool groups which are marked as passive in the initial_conditions.nc will still be advected even if HorizontallyMigrates is set to 0. |
| NumMigrations | The number of migrations per calendar year |
| MultiYrMigrations | Whether any of the migrations are multi-year (1) or simply annual (0). While this column is always required in the groups definition file the associated code will not function unless flag_multiyr_migs is also set to 1 in the run.prm file |
| ExternalReproduction | This is whether the group reproduces outside the model (i.e. the value for Time_Spawn_XXX parameter in biology.prm file is set during a day of the year when the species should be outside the model) |
| RecruitType | This is where you set the recruitment typ: 0 = independent distribution (use recruit_hdistrib) 1 = at parental locations 2 = external (into Migration Array) 3 = using a forced larval dispersal matrix 4 = external reproducer who has parental care |
| IsFished | If set to 1 the group can be fished (targeted) by commercial or recreational fisheries and the catch will be reported in the output files, and is analysed in the assessment model. Note that if set to 0, dynamic fishing will still occur if parameters are given in the harvest.prm file. |
| IsImpacted | If true then the group can be impacted by fishing, bycatch or incidental fishing related mortality (e.g. destruction of living habitats). This parameter differentiates between targeted and accidental interactions; it is not reported in the landings. This means there must be values in the harvest files for this group. Note the group can be impacted by bycatch/incidental mortality even if no explicit targeted fishing is setup. This means the bycatch/incidental mortality parameters should be assessed carefully in the harvest.prm file. If both this value and IsFished are set to 0 then all fisheries related impacts on the group are disabled. |
| isTAC | If true, the group will be under total allowable catch (TAC) management. It will activate specific TAC related code in the Harvest submodel. |
| GroupType | The type of species. This is one of the most important parameters, as it tells Atlantis what kind of organism the functional group is representing and what kind of processes should be applied to it. Six group types are allowed for age-structured groups. A lot more group types are available to define invertebrate biomass pool types and these group types are used to dictate the adaptive timestep for simulating proceses, and all of them have some specialized ecological routines applied (see some details about their characteristics here). The main Atlantis model groups include: AGE STRUCTURED GROUPS 1) Standard fin-fish or generic vertebrate FISH 2) Size/age-structured invertebrate FISH_INVERT 3) Chondrichthyans SHARK 4) Birds BIRD 5) Marine mammanls (potentially terrestrial mammals in the future) MAMMAL 6) Reptiles (can be present in the water and on land) REPTILE. BIOMASS POOL GROUPS Phytoplankton 7) Small Phytoplankton SM_PHY 8) Large Phytoplankton LG_PHY (used in combination with IsSiliconDep to define diatoms) 9) Trichodesmium and Cyanobacteria TRICHO (N fixers) Other primary producers 10) Microphtybenthos MICROPHTYBENTHOS 11) Dinoflagellates DINOFLAG 12) Phytoben PHYTOBEN (typically used to represent macroalgae) 13) Seagrass SEAGRASS 14) Turf TURF Zooplankton 15) Small Zooplankton SM_ZOO 16) Medium Zooplankton MED_ZOO 17) Large Zooplankton LG_ZOO 18) Jellyfish JELLIES (in the past represented as LG_ZOO) Large pelagic invetebrates 19) Cephalopod CEP 20) Prawns PWN Infauna 21) Small Infauna SM_INF 22) Large Infauna LG_INF Epibenthic organisms 23) Sediment epibenthic filter feeders SED_EP_FF (often used for bivalves, sponges) 24) Benthic grazers SED_EP_OTHER 25) Mobile epibenthos MOB_EP_OTHER (often used for crabs, lobster, octopus) 26) Corals CORAL 27) Sponges SPONGE Bacteria 28) Pelagic Bacteria PL_BACT 29) Sediment Bacteria SED_BACT Obligatory detritus groups 30) Carrion CARRION 31) Labile detritus LAB_DET 32) Refractory detritus REF_DET 33) Additional ice and land based groups are also available. Ice dwelling 34) ICE_BACT 35) ICE_MIXOTROPHS 36) ICE_DIATOMS 37) ICE_ZOOBIOTA Land dwelling (vegetation only for now) 38) MARSH 39) MANGROVE |
| IsPredator | If true then the group is assumed to eat other groups by the assessment code (for the purposes of defining network indices etc), it does not affect the ecological model. |
| IsCover | If true the group is classified as a habitat. This means that the group becomes a unique habitat type, that can be used by other groups in the model for shelter etc, in addition to the general four geological habitat types included by default (reef, flat, soft, canyon). For example, if IsCover is set to 1 for three functional groups (e.g. BFS, BFF, and MA), the model has a total of seven habitat types. In this case the habitat dependency parameter habitat_XXX in the biology.prm file must have 7 values for each functional group. The living habitats are always the first entries and the geological classes always the last 4 entries. So in this example, the first three entries will refer to the IsCover groups in the order they are listed in the functional_groups.csv file and the last four entries will refer to reef, flat, soft, canyon habitats. |
| IsSiliconDep | If true, the group is assumed to be Si limited and its energy flows are tracked both through nitrogen and silicon. All Si limited groups must have separate Si tracers set in the initial_conditions.nc, in addition to the usual Nitrogen tracers. At present most models have this set to true for Diatoms and MicroPhytopbenthos. |
| IsAssessed | If true then this group will be assessed in the Assessment submodel. This submodel will generate a number of assessment indices. |
| IsCatchGrazer | If true, the group grazes on catch, for instance pinnipeds that eat fish from nets. If set to 1 for a functional group XXX, then availability of catch of each functional group should be given for this group in the pFCXXX parameter in the biology.prm file. The pFC parameters are not required for groups that are not catch grazers. |
| OverWinters | If true, this group will go into hiatus over winter. The overwintering can be triggered and ended by time of the year or temperature. This is set using overwinterStartTofY_XXX, overwinterEndTofY_XXX, overwinterStartTemp_XXX, overwinterEndTemp_XXX parameters in the biology.prm file. These parameters only have to be set for overwintering groups. |
| isCultured | This identifies aquaculture groups, and applies aquaculture processes to them. Parameters required for aquaculture groups are described here. |
| isHabDepend | Identifies groups that are habitat dependent. Note, this value takes precedence over habitat preference parameters in the biology.prm file. If isHabDepend is set to 0 then the group is not affected by habitats, even if appropriate parameters are given in the biology.prm |
| numMoveEntries | The number of movement time periods you would like the group to have. Historically this has been fixed at 4 to allow for seasonal movement, but currently any number of moves is allowed. See further details on parameters in biology.prm here |
| isBioEroder | Whether the group bioerodes corals (i.e. sponges). This allows for boring sponges and bioeroder activities in reef models including corals and sponges |
| isSupplemented | Whether the group feeds on material from outside the model. If this is set to 1, the group will be assumed to be eating insects or pellets or something from outside the model domain. The proportion of their diet gained in this way (per box) must be set using the Supp_XXX in the biology.prm file. |
| isExternal | Flag to indicate whether the group uses the external population model option (instead of simply holding individuals in hiatus when they have migrated out of the model). |
| isLandActive | Marks the group as able to be on land (for models with land and sea). Only required if flagAllowLand is set to 1 in the run.prm file. |
| isLightEffected | Marks the group as susceptible to light pollution. Only required if flag_pollutant_impacts is set to 1 in the run.prm file. |
| isNoiseEffected | Marks the group as susceptible to noise pollution. Only required if flag_pollutant_impacts is set to 1 in the run.prm file. |
What is the role of detritus in an ecosystem model? An excerpt from Murray and Parslow (1997) PPBIM report:
“The detrital pool acts as a store of fixed nutrient, which introduces a delay into nutrient recycling. Particulate detritus sinks and thereby transports nutrients out of the surface layer into deep water or to the sediment. Dissolved organic matter (DOM) does not sink, and very large pools of refractory DOM are found in the open ocean and in coastal waters. Horizontal transport of particulate detritus and DOM from regions of high production to more oligotrophic areas can also be important”
“Three forms of non-living organic matter are included in the model: labile particulate detritus, refractory particulate detritus and dissolved organic matter [NOTE – these same pools, plus Carrion, are included in Atlantis, which is based on the PPBIM]. These are represented by the symbols DL, DR and DON respectively. The particulate detrital pool [in nature] contains a wide variety of particles, with diverse sources, ages, sizes and chemical composition. The model includes two functional components: fresh labile detritus breaking down on time scales of a few days, and semi-refractory detritus turning over on time scales of a year. This allows the model to treat perturbations to the nutrient cycle on time scales of days to years.”
“[In nature] The pool of dissolved organic matter also contains a variety of compounds with diverse turnover rates. In oceanic waters there is a large pool of highly refractory DOM, whose average age has been estimated to be as much as 3400 years (Williams 1975). The bulk of this material is essentially irrelevant for the cycling of nutrients on the time scales of [model] interest. However the DOM pool also includes much more labile components. Highly labile sugars and amino acids released through cell lysis or messy feeding may be consumed by bacteria or break down on time scales of hours (Fuhrman 1987) to days (Holibaugh and Azam 1983). This material is not modelled explicitly, but is treated as though it was remineralised immediately to form dissolved inorganic nutrient. The model includes a single DOM pool with an assumed turnover time of the order of a hundred days. … Because it turns over on time scales, which are long compared with both phytoplankton uptake of inorganic N, and transport within the Bay, it plays a role in reducing N sequestration in coastal waters.”
6.3. Defining the GroupType correctly
The definition of a group is very important as it will determine the ecological routines and the adaptive timestep applied for the group (see timestep description in chapter 6.1). Table 10 shows routines that are called for different group types. The routines are further modified depending on whether consumers live in the water column or sediment.
| Routine name in Atlantis code | GroupType for which the routine is applied |
|---|---|
| Dinoflag_Process() | DINOFLAG ICE_MIXOTROPHS |
| Phytoplankton_Process() | LG_PHY SM_PHY PHYTOBEN SEAGRASS MICROPHTYBENTHOS TURF ICE_DIATOMS |
| Invert_Consumers_Process() | SM_INF LG_INF SM_ZOO MED_ZOO LG_ZOO CEP PWN ICE_ZOOBIOTA |
| Epibenthic_Invert_Process() | SED_EP_FF MOB_EP_OTHER |
| Sediment_Epi_Other_Process() | SED_EP_OTHER |
| Coral_Process() | CORAL SPONGE |
| Pelagic_Bacteria_Process() | PL_BACT |
| Ice_Bacteria_Process() | ICE_BACT |
| Sediment_Bacterica_Process() | SED_BACT |
| Labile_Detritus_Process() | LAB_DET |
| Refractory_Detritus_Process() | REF_DET |
| Carrion_Process() | CARRION |
6.4. Modifying functional groups in parameterised models
Details on how to add a new functional group into an existing model are given on the wiki here. This will require a significant effort and reparameterisation of the model.
Alternatively, if changes to functional groups are needed, it might be easier to use an existing group and change it into something new. You may not want to change the three letter code, as that would involve changing all the parameter names for the group.