In r4atlantis/ratlantis: R package for developing, executing, and assessing Atlantis ecosystem models

Ecoystem modeling is a growing areas of specialization. Multiple models (e.g., Ecopath w/ Ecosim and Ecospace, INVITRO) exist, each having their own set of strengths and weaknesses. However, a shared issue among these models is the the time, data, and software needed to complete them. These models, by their very nature, are data- and computationally-intensive, with development times often leading to model construction taking years to complete. To begin to address this issue, we have developed ratlantis.

The ratlantis package is designed to allow Atlantis ecosystem models to be developed rapidly (3-6 months is the goal, vs the 2 years projected in other documents). It does this by

• providing access to software already designed by the Atlantis community via R, removing a learning curve and offering a single environment to design, execute, and analyze models
• using existing R packages that can pull biological, geographic, and other types of data from public repositories to provide data needed for Atlantis models
• offering a clear framework for developing a new model or modifying an existing one, where users supply data, modify output, and continue model development as needed

Atlantis, originally developed by Elizabeth Fulton at CSCIRO, is an ecosystem model designed to simulate long-term dynamics in marine systems. The model is spatially- and temporally-explicit, following the dynamics of numerous ecological groups in irregulary-shaped polygons of various depth. Groupings of organisms, polygon shapes, and depth levels are all determined by the user, and we leave the discussion of the implication of these decisions for other times. Here we will go through the basic use and development of an Atlantis model using the ratlantis package. While all steps could be completed in R, we will assume other pieces of software (table editors such as Excel or Sheets, GIS programs such as QGIS) are being used in the development workflow due to their common application. R users interested in fully developing models in this environment should be able to make small changes as needed.

This vignette and guide builds heavily on existing Atlantis documentation developed by Isaac Kaplan, Elizabeth Fulton, and Cameron Ainsworth ^[How to Build an Atlantis Model: A living document]. The CSIRO Atlantis wiki has also proved invaluable in model and package development.

Atlantis Steps: Model Development

Atlantis model development consists of several key task:

• map construction
• group assignment
• procuring and formatting environmental data
• creating input for files for C++ Atlantis software

The following guide walks users through these steps using the general setup

• short version: just what you need to provide the function
• example: example R code; files used here are available by emailing the author ([e-mail])
• longer version and explanations: lengthier overview of what Atlantis is doing and how the functoin works

Map Development with rbgmeriser

Short version

Map development is handled in ratlantis by the rbgmeriser function, to which users provide

• name of a wgs84 formatted shape file with the area you wish to model carved into polygons. The only other attribute/data you need is for each polygon to be labelled (box_id); start at 0 and go as high as needed.
• location of bgmeriser.jar, downloaded from Atlantis wiki; defaults to working directory
• name of a bathymetry file in wgs84 format that includes your map area and negative depths in a column named "Contour"
• depths you want to be used for Atlantis polygons (if Depth column not included in shape file)
• locations of all files; defaults to working directory

Function should return a .bgm file to be used in Atlantis models.

Example

rbgmeriser( map_name = "DeepCmap",
            boundary_boxes = c(0,52),
            get_bathymetry = TRUE,
            bathymetry_layer_name = "gom bath wgs84",
            bathymetry_cutoff = .9,
            bathymetry_levels = c(-10, -20,-50, -200,-1000, -2000,-4000)
)

Longer version with explanations

As previously noted, Atlantis models are spatially-explicit. Resolution depends on the size of the area being noted, but in general Atlantis most models have kept the number of areas (polygons) under 75. Polygons can be of any shape, but limiting sides and angles will help with computational time. Similarly, keeping polygons close to the same size is useful. Polygons can follow similar habitat areas, geographies, or areas of protection (reserves or fishing zones). Once developed in a mapping program, you must include a box_id column (going from 0 to the maximum number needed to number all boxes without skipping any numbers). You MAY also include a botz (set to the desired Atlantis depth for each polygon), horizmix, vertmix, and boundary column - all depths should be negative (below sea level) and boundary columns should be set to 1 unless a box is a adjacent to open water not included in the model (in which case it is set to 0).

If Depth is not set, you must provide the downloaded location of a bathymetry shape file that has a depth labeled as Contour (again, must be negative numbers), set get_bathymetry = T (default value), and list the desired depths for final model polygons (4-8 depths is recommended, for example in the Gulf of Mexico we set the max depth for each polygon to -10, -20,-50, -200,-1000, -2000,-4000 meters). The function overlays your polygon map on the bathymetry map to get depths for each site, and the bathymetry_cutoff functions instructs which quantile to take as the depth for each polygon (defaults to .9 to avoid a canyon overly influencing depths). The code then creates a botz column.

If boundary is not included, you must list the box_id values of the boundary boxes so a boundary column can be created.

If vertmix and horizmix are not defined, they are set to 0..00001 and 1, respectively, by default (standard for Atlantis models).

Atlantis input requires a .shp polygon file to be transformed to a .bgm format.
Map development is handled via the rbgmeriser function, which assumes you have downloaded the java applet bgmeriser.jar.

Comments

A common error following this function is that "java is not recognized as an internal command", etc. This means your workstation needs to have java added to it's PATH.
Also remember that the java path can't have any spaces in it.

Group Assignment and Biology PRM, NC development

Atlantis models consider a variety of marine life, moving from bacterial pools to fish and large marine mammals. However, this scale means that in order to make simulations tractable (both due to computing time and information needs) organisms are divied into functional (or focal) groups. These groups may range from single species to larger feeding or functional groups (e.g., reef sharks, large reef fish). Atlantis requires a .prm file giving data and an .nc file giving initial conditions (where they start in map) for each group. ratlantis helps create these groups and files using the following functions:

• Group creation
  • gather_group_for_species
  • gather_data_for_species
  • gather_interactions_for_species
  • gather_habitat_for_species
  • create_functional_groups
• Parameter creation
• create_atlantis_parameters
• Writing the prm
  • create_biology_prm

Group creation

In order to assign organisms to appropriate groups, we'd ideally like to use as much data as possible. However, we are always missing data and the time needed to find it For those reason, ratlantis automates 3 basic types of data that may be used iteratively to create functional groups.

• gather_group_for_species takes a basic scientific name (Genus species) and compiles data on higher classifications. These can be used to look for missing information needed for model or to supply Atlantis group types

• gather_data_for_species pulls data on basic life history and ecological traits (age, size, trophic level, harvested).

• gather_interactions_for_species uses rglobi to pull species interaction data from the Global Biotic Interaction Database.

• gather_habitat_for_species provides occurence data and notes on preferrered habitats.

• create_functional_groups uses data provided by user (via gather_ functions if needed)

These functions are separated as they have slightly different requirements and may be best run in different orders depending on existing data. If an external species list is present, you can use them in the order stated above. However, if an external list is not present, one option may be to run the gather_interactions_for_species function, which returns information on interactions (and thus species) documented for the area, and then use this list to run the gather_data and gather_habitat functions.

gather_group_for_species

Short version

Provide

• name and location (defaults to working directory) of a .csv file that has a list of species to be included. File needs to have columns labelled
  • Genus
  • species
  • common_name These may be blank for some speciesbut column must be included

Function should return a .csv file with information on species pulled from online sources.

Example

testgroup <- gather_group_for_species (species_list_csv = "species_test.csv")

Longer version with explanations

Knowing higher order groupings may aid in finding needed data (e.g., averaging trophic level across genus for missing species) or to build functional groupings.

gather_data_for_species

Short version

Provide

• name and location (defaults to working directory) of a .csv file that has a list of species to be included. File needs to have columns labelled
  • Genus
  • species
  • common_name These may be blank for some speciesbut column must be included

Function should return a .csv file with information on species pulled from online sources (Fishbase and Sealifebase currently, expanding to other sources)

Example

testdata <- gather_data_for_species (species_list_csv = "species_test.csv")

Longer version with explanations

Atlantis requires a variety of data for each group. The main traits models tend to focus on are those needed to model population growth and interactions. These include:

• Trophic level and consumption rate
• Diet composition
• Mortality rates (natural and fishing may be needed)
• Growth parameters (k, relationship between length and weight)
• Size and age parameters (maximum length, maximum age)
• developmental information (age/size at maturity)

This function returns multiple of these files. Defaults (hard-coded in function) return

• mean reported M value
• maximum reported age
• maximum reported length

gather_interactions_for_species

Short version

Provide name and location (defaults to working directory) of a .csv file that has a list of species to be included. File needs to have columns labelled * Genus * species * common_name These may be blank for some speciesbut column must be included. A "functional_group" column may also be included name and location(defaults to working directory) of a .shp file that was used to build the .bgm file for Atlantis OR a bounding box for where interactions should be returned

Function should return a .csv file with information on species interactions pulled from online sources (Global Biotic Interaction database currently, expanding to other sources)

Example

testinteractions <- gather_interactions_for_species (species_list_csv = "species_test.csv")

Longer version with explanations

Atlantis requires a trophic model for all included functional groups (i.e., who eats who and how often). This function can be used to construct or check functional groups by ensuring major trophic pathways are included appropriately

gather_habitat_for_species

Short version

Provide name and location (defaults to working directory) of a .csv file that has a list of species to be included. File needs to have columns labelled * Genus * species * common_name These may be blank for some speciesbut column must be included. A "functional_group" column may also be included name and location of a .shp file that was used to build the .bgm file for Atlantis * (optional) list of key words to search for in Fishbase description

Function should return a .csv file with information on species occurrences pulled from online sources, including which species met certain depth parameters, keyword searches, and had been geotagged in each of your map polygons.

Example

testhabitat <- gather_habitat_for_species(species_list_csv = "species_test.csv")

Longer version with explanations

Understanding where each species occurs (depth and location) can be useful in determining functional groups and initial biomass starting locations. This function currently queries FishBase and several online sources of location data (gbif, iNaturalist and more using the spocc package).

Comments

The data.table package need to be installed independently (needed when message

there is no package called 'data.table'

appears)

create_functional_groups

Short version

Provide

• name and location (defaults to working directory) of a .csv file that has a list of species to be included and basic information. Columns that must be included are:
  • Phylogenetic information, specifically
    • Genus
    • species
    • family
    • order
    • class
    • superclass
    • phylum
  • Tropic level information, specifically at least one of the following
    • TrophicLevel
    • FoodTroph
    • DietTroph
  • Data on depth associations, specifically
    • Min_Depth
    • Max_Depth
• Information on bathymetry levels used in the Atlantis model. These can be directly provided (via bathymetry_levels argument) or pulled from an Atlantis model shape file for which users specify the location (map_location) and name (map_name)
• list of habitat types (habitat_list) to be included in the model

Example

test_groups <- create_functional_groups(species_info_csv = "test_combined.csv",
                          habitat_list = c("SeaGrassBeds", "CoralReefs", "Sand", "Mud" ))

Longer version with explanations

Like any ecosystem model, Atlantis must balance simplicity and the need for details. Once collected, species trait, interaction, and habitat data are used to divied species into groups with appropriate parameter (often averaged for the group). This function uses data on taxonomy, trophic level, and habitat and depth associations to suggest groupings.

File creation

Generating values for Atlantis groups

generate_group_parameters

Short version

Once data is collected for all species and groups are decided, the actual parameters needed for Atlantis groups are generated by the generate_group_parameters function. This is kept separate from creation of the biology prm file (handled by create_biology_prm) so that users may add data for groups (instead of species) and can check values before creating the prm file. Users provide:

• name and location (defaults to working directory) of a .csv file that has a list of species to be included and basic information. Columns that must be included are:
  • Phylogenetic information, specifically
    • Genus
    • species
    • family
    • order
    • class
    • superclass
    • phylum
    • kingdom
  • TL_final (Tropic level information supplied by create_functional_groups)
  • Data on depth associations, specifically
    • min_depth_bin
    • max_depth_bin
  • Growth information, specifically
    • mean_a
    • mean_b
    • mean_to
    • mean_K
    • max_age
    • mean_M
    • at least one of the following
    • max_length
    • mean_Loo
  • atlantis_type *for vertebrates, these can be: * fish * bird * mammal * shark
    • for invertebrates, a long list that can be found at https://wiki.csiro.au/display/Atlantis/AtlantisGroupTypes
  • group_name
  • group_code

ALL OF THE ABOVE ARE PROVIDED IN THE OUTPUT OF THE create_functional_group function except for

• group_name and group_code (these are modified forms of the "group" column returned by that function)
• atlantis_type for invertebrates (to be handled in future revision)

Example

group_parameters <- generate_group_parameters(species_info_groups_csv = 
    "group_recommendations_added.csv")

Longer version with explanations

This files calculated parameters needed for the Atlantis model by taking the mean of provided values. All of this data may be entirely provided by the user or (much more commonly) pulled from existing datasets and amended as needed. The suite of functions we just documented (gather_data_for_species, gather_habitat_for species, gather_interactions_for_data) all pull together this data, BUT IT IS UP TO THE USER TO VERIFY IT AND DETERMINE HOW TO USE IT. We recommend a workflow of:

• initial classification of species into focal groups based on model needs
  • this may be assisted using the create_functional_groups function, which creates groups based on trophic level, basic biological group, and depth usage
• review this initial list by considering interactions and habitat usage *this can be considered by merging data you've acquired by focus group to make sure the groups make sense
• generate the averaged traits for each functional groups and actual parameters used in Atlantis bio.prm file and create the bio.prm and groups.csv input files
  • the create_biology_prm function carries out both these tasks
• reiterate this process (create groups, check values) until you are pleased

One of the major benefits of the ratlantis package is the ability to consider multiple focus group considerations for one model (since much of the calibration and model creation will be automated), allowing models to be quickly reconfigured. The same perspective should apply for changing model areas (downscaling a model or changing polygons).

Atlantis notes

Before setting groups, a few specific Atlantis model properties should be understood. Groups are categorized as: Vertebrates FISH BIRD MAMMAL SHARK Invertebrates *a long list that can be found at https://wiki.csiro.au/display/Atlantis/AtlantisGroupTypes

Group type determines where organisms are found (in sediment, in water column, epibenthic) and how often they are processed. Focal groups are also either composed of singe pools or some number of structured size classes. These two concepts are tied together in the model code; vertebrates can have multiple (unlimited, formerly 10) age classes, while invertebrates can only have pools or two age classes. FOR THIS REASON, YOU MAY SEE INVERTEBRATES CLASSIFIED AS VERTEBRATS IN THE MODEL (e.g., if you need to model 3+ size classes for shrimp, crabs, etc, you'll have to tell the model they are a vertebrate). Similarly, the group.csv file (one of the required input files) has an invert_type column where you label the group type (so some rows will say FISH or other non-invertebrate groups).

ratlantis deals with this by asking how many cohorts you want to include for a species and then attempting to classify it into the right Atlantis group for you. You should note you are required to have one (and only one) of the following groups in each model: CARRION, carrion LAB_DET, labile detritus REF_DET, refractory detritus PL_BACT - Pelagic Bacteria *SED_BACT - Sediment Bacteria

These respresent the detrital and bacterial components of the ecosystem.

create_biology_prm

Short version

Creation of the bio.prm file is handled in ratlantis by the create_biology_prm function, to which users provide:

• name and location (defaults to working directory) of a .csv file that has a list of species to be included and basic information. Columns that must be included are:

• group_name

• group_code
• TL_final
• mean_M
• max_age
• min_age_reprod
• mean_a
• mean_b
• mean_Loo
• mean_K
• larval_duration

ALL OF THE ABOVE ARE PROVIDED IN THE OUTPUT OF THE generate_atlantis_parameters function except for

• larval_duration

Example

Comments

Key models and related assumptions that are commonly used include the Von Bertalannfy Growth Equation:

$Length_t = Length_{max}^{(1-e^k(t-t_0))}$

and related weight equation, and the relationship between length and weight

$W=aL^b$

Mortality can be hard to calculate, so a few simplifiying assumptions allow us to get:

$$M = {ln(.01)\over-{age_{max}}}$$

(this is assuming that the age of the oldest fish corresponds to a time when 1% of the fish from a given cohort survive )

where $age_{max}$ is the age of oldest individual.

Mum is the maxi"mum" daily production (consumption * efficiency)rate of a predator, while clearance is the feeding efficiency when prey are scarce. Maximum production "mum" rates are calculated using

$G = caWeight^cb$

, and clearance was set as a tenth of this maximum rate following estimates from Horne et al 2009 and direction from Ainsworth 2011.

All effiency values default to .1.

$S_{j}$ is assumed to be $$.3 * {growth rate\over{efficiency}}$$

Local recruitment (1 = demersal and piscivorous fish recruit at parental locations, 0 = independent distribution) defaults to 0 for all species.

Proportion of each class spawning defaults to .2 for the last juvenile stage, .8 for first adult, and 1 for all others.

Vertebrate reproduction related flags. The flagrecruit entries refer to the recruitment function used.
1=const, 2=dependent on prim producers (Chla), 3=Beverton-Holt, 4=lognormal, 5=dependent on all plankton groups not just Chla, 6=Bev-Holt with lognormal variation added, 7=Bev-Holt with encourage recovery
8=Bev-Holt with perscribed recovery, 9=Ricker, 10=Standard Bev-Holt (no explict use of spawn included)
11=pupping/calving linearly dependent on maternal condition, 12=pupping/calving a fixed number per adult spawning, 13=forced timeseries of recruitment. Defaults to 12 for mammals, birds, and turtles, 10 for all other vertebrates (fish, shark, and mislabeled invertebrates)

Vertebrate reproduction strength flags (1=very strong year classes possible, relative strength set using recruitRange and 0=only moderate variation in year class strength possible, mainly for top predators with few young per reproductive event, relative strength set using recruitRangeFlat). Defautlts to 1 for fish and sharks and 0 for all other vertebrates.

Some flags only apply to vertebrates

{planktivore} {bear_live_young} {parental_care} {feed_while_spawning} #flagq10 (vertsonly, default set to 1) #flagtempsensitive (vertsonly, default set to 0) #flaghabdepend (verts only, default set to 0) #flagchannel (verts only, default set to 0)

flagdem (default set to 1 for all living groups (not detritus)

Longer version with explanations

Atlantis Steps: Model Execution

Short version

Provide -This code assumes you have downloaded and compiled the C++ Atlantis code and requires --the location of the compliled Atlantis code --the name of the .exe file created by Atlanits code (e.g., atlantismain) --the names of files you have created to run Atlantis (which are stored in same folder at the .exe file) ---biology_nc, the biology initial conditions file ---run_file_prm, the initial conditions run file ---forcing_time_series_prm, the file detailing initial forcings ---physics_prm, the initial physics file detailing eddies and scaling ---biology_prm, the biology parameter file ---harvest_prm, the harvest file ---functional_group_csv, the list of functional groups ---fisheries_csv, the list delimiting targeted fisheries

The above are all created via code in ratlantis. You must also provide -output_file_nc, desired name for output file -output_folder, folder where should results be stored

Function will call the system shell and execute Atlantis

Example

execute_atlantis(atlantis_location = "C:/exampleatlantis", atlantis_exe = "atlantismain",
                              biology_nc ="init_VMPA_setas_25032013.nc",
                              output_file_nc = "outputSETAS.nc", run_file_prm =
                                "VMPA_setas_run_fishing_F_New.prm",
                              forcing_time_series_prm = "VMPA_setas_force_fish.prm",
                              physics_prm = "VMPA_setas_physics.prm", biology_prm
                              = "VMPA_setas_biol_fishing_New.prm",harvest_prm =
                                "VMPA_setas_harvest_F_New.prm",
                              functional_group_csv = "SETasGroups.csv",
                              fisheries_csv = "SETasFisheries.csv",
                              output_folder = "Outputfoldertest")

Longer version with explanations

Atlantis is a C++ program. This code does not recreate Atlantis in R, it simply acts as a wrapper for the program.

Atlantis Steps: Model Calibration

Work in progress planned for completion fall 2015

Atlantis Steps: Model Analysis

Work in progress planned for completion fall 2015

r4atlantis/ratlantis documentation built on May 26, 2019, 6:40 p.m.