Example kittiwake: step 1 - seabORD inputs
C_KI_inputs.RmdLoad the seabORD package
library(seabORD)This vignette demonstrates how to prepare all inputs required for a seabORD simulation using the built-in example datasets.
Preparing the inputs
To run seabORD several inputs are needed:
| arguments | type | description |
|---|---|---|
| Par | List | The main parameters controlling/defining this run e.g., species and colony |
| modPar | List | Parameters relating to the model mode and computer environment |
| ordPar | List | Input parameters relating to the ORDs |
| switches | List | A set of switches/flags used to control optional features of the run and determine range of outptus |
| seamask | Raster | land/sea grid, 1km expected. |
| spadat1 | Tibble | Information relating to the colony/SPA |
| spadat2 | Tibble | Information relating to the colony/SPA |
| spdat | Dataframe | Species-specific parameters |
| BrdData | Raster | Bird distribution map - derived from GPS data or failing that, a distance-decay model |
| FrgCompData | Raster | Competition distribution map - derived from GPS data or failing that, a distance-decay model |
| fltdist_base | Raster | Flight distance by sea, without ORDs. See user guide for details. |
| FlightGridcorrection | Raster | Flight distance transition layer (gdistance) corrected for distortions relating to the CRS |
| ORDpoly | Multipolygon (simple features) | The ORD footprints |
The package comes with some example input data to run the model with. Here’s an example run of the model with detailed explanation for each input argument.
Par
List for biological parameters:
thisSpecies: The species being used. You can select from “KI” (kittiwake), “GU” (guillemot), “RA” (razorbill), or “PU” (puffin)
colonies: The code number for the colony/SPA being modelled
Nscalefactor: What proportion of the total population do you want to run the model for i.e., Nscalefactor = 1 is for 100% of the population, where 0.1 would represent 10% of the population which may be useful for test runs.
Prob_Displacement: The proportion of individual birds which will experience displacement effects if interacting with an ORD during a certain trip. E.g., if Prob_Displacement = 0.6, 60% of individuals will be displacement susceptible.
Prob_Barrier: The proportion of individuals which experience displacement effects, which will also experience barrier effects. E.g., if Prob_Barrier = 1, 100% of individuals which are displacement susceptible will also be barrier effect susceptible (i.e., 60% of total population)
PreyType: This dictates the type of prey layer used in the simulation, which is typically set to “uniform”, meaning all prey cells begin with the same prey value.
collision: Not currently used
SiteSelectionMethod: Set to “Map” currently, but options to add in a distance decay module.
MaxDistancekm: Not currently used in this version
PropInRange: Not currently used in this version
Npairspercol: The number of pairs of adult birds at the given colony/SPA
Pmedian: The value of prey in cells in this particular replicate. Prior to running the simulation with ORDs this must be determined in a calibration step.
Par_example <- seabORD::get_example_par()
#which looks like
str(Par_example)
#> List of 12
#> $ thisSpecies : chr "KI"
#> $ colonies : chr "UK9004171"
#> $ Nscalefactor : num 1
#> $ Prob_Displacement : num 0.6
#> $ Prob_Barrier : num 1
#> $ PreyType : chr "Uniform"
#> $ collision : chr "Off"
#> $ SiteSelectionMethod: chr "Map"
#> $ MaxDistancekm : num 0
#> $ PropInRange : num 0
#> $ Npairspercol : num 2898
#> $ Pmedian : num 158modPar
List for model parameters.
Nparallel: This is used for parallel runs only (i.e., set to “NA” for runs on local machine) to indicate which replicate is being run which will dictate the seed being so that reproducibility is conducted in the same fashion as for local runs.
initialseed: A seed for reproducibility.
reference: A name to be attached to folders and files emanating from this particular simulation which will be generated from other outputs in the order of: model environment; model mode (calibration/scenario); species, colony ID. E.g., “serial_scenario_KI_UK9004171”
outputdir: The file directory where outputs from your model will be saved to.
Nreplicates: The number of replicates being used
make a folder in the directory to store your output (you can place it wherever)
# Create the ouput folder "output_seabORD" if not existing already
if (!dir.exists("output_seabORD")) {
dir.create("output_seabORD")
}and then the list of modPar
modPar_example <- seabORD::get_example_modpar()
#which looks like
str(modPar_example)
#> List of 5
#> $ Nparallel : logi NA
#> $ initialseed: num 6598
#> $ reference : chr "serial_scenario_KI_UK9004171"
#> $ outputdir : chr "output_seabORD"
#> $ Nreplicates: num 1ordPar
List for wind farm parameters
include_ORDs: Code names of ORDs to be included in this run, e.g., “NEART” is Neart na Gaoithe
parnames: Further naming of wind farms to be included
FootprintBorder: The extension distance (km) of the buffer around the ORD which birds avoid
BufferZone: Also known as the displacement zone, this is the distance (km) extending beyond the FootprintBorder where displacement susceptible birds will be displaced to.
ordPar_example <- seabORD::get_example_ordPar()
#which looks like
str(ordPar_example)
#> List of 4
#> $ include_ORDs : chr [1:2] "NEART" "INCAP"
#> $ parnames : chr "NEART;INCAP"
#> $ FootprintBorder: num 2
#> $ BufferZone : num 5Switches
This parameter requires a llist() object that defines the optional features of the run. It accepts the following options:
environment : “serial” or “parallel”
modelmode: “scenario” or “calibration”
debugmode: 0, 1, or 2 - typically used during development so can be ignored
bycol: TRUE or FALSE
bysus: TRUE or FALSE
bych: TRUE or FALSE
printdaily: TRUE or FALSE - an option to print out daily outputs from each timestep for all modelled indiviudals
printseason: TRUE or FALSE - more detailed outputs from each season (baseline/scenario), as opposed to teh higher level summary issued as standard.
printpair: TRUE or FALSE - more detailed outputs from each pair.
minout: TRUE or FALSE - to be completed
silent: TRUE or FALSE - to be completed
saverds: TRUE or FALSE - This should nearly always be set to TRUE, as this is the standard output summary.
savebirdflightmap: TRUE or FALSE - an option to view a map of foraging locations from this simulation, which can be used as a visual check that the simulations are executing as intended i.e., have you run a simulation with the correct colony and wind farm set up.
There is an example list available in the package that can be accessed by simply call in the built-in list “example_switch_list”:
#get the example switches list
switches_example <- seabORD::get_example_switches()
#check the setting of this example
str(switches_example)
#> List of 14
#> $ environment : chr "serial"
#> $ modelmode : chr "scenario"
#> $ debugmode : num 0
#> $ bycol : logi FALSE
#> $ bysus : logi FALSE
#> $ bych : logi FALSE
#> $ printdaily : logi FALSE
#> $ printseason : logi FALSE
#> $ printpair : logi FALSE
#> $ printfinal : logi FALSE
#> $ minout : logi FALSE
#> $ silent : logi FALSE
#> $ saverds : logi FALSE
#> $ savebirdflightmap: logi FALSEIn this example seabORD will in serial and in scenario mode; without debugging and by saving the output as a .rds file.
seamask
Used to indicate where the sea is. Example data to be used as seamask can be found built in the package and can be accessed via the built in function get_example_seamask().
example_data_seamask <- seabORD::get_example_seamask()which looks like:
# You can use the built in plot function
seabORD::plot_seamask(seamask = example_data_seamask)
spadat1
For this example the values for spadat1 for the site “UK9004171” are taken from the built-in dataset “spacoordinates” which has data for 108 relevant SPA sites for the CEF. The package provides helper functions for extracting the example data used throughout this vignette.
#open the dataset provided with the pacakge
spadat1_example <- seabORD::get_example_spadat1()
#display the data for the example site
print(t(spadat1_example))
#> [,1]
#> SITECODE "UK9004171"
#> CEF.include "TRUE"
#> Marine "FALSE"
#> Longitude "-2.564"
#> Latitude "56.186"
#> dat.CELLNO "1658699"
#> dat.ATSEA "TRUE"
#> flt.LONG "-2.558333"
#> flt.LAT "56.18875"
#> flt.CELLNO "1658699"
#> flt.ATSEA "TRUE"
#> flt.DIST "0.4661833"
#> flt.near "TRUE"
#> datxy.E "3544920"
#> datxy.N "3743923"
#> datxy.CELLNO "1800240"
#> datxy.ATSEA "TRUE"
#> fltxy.E "3544466"
#> fltxy.N "3743659"
#> fltxy.CELLNO "1800240"
#> fltxy.ATSEA "TRUE"
#> fltxy.DIST "525.4244"
#> fltxy.near "TRUE"spadat2
Can be derived from the built in list dataset “spalist”, which contains information for all the SPA sites. The package provides helper functions for extracting the example data used throughout this vignette.
spadat2_example <- seabORD::get_example_spadat2()
#take a look
print(t(spadat2_example))
#> [,1]
#> SITE_CODE "UK9004171"
#> SITE_NAME "Forth Islands"
#> CEF.include "Y"
#> Marine.only NA
#> Altnames.sufficient NA
#> Altnames.SPApolys NA
#> Altnames.SMP NA
#> Altnames.Productivity NA
#> Altnames.BDMPS NA
#> Altnames.FR NAspdat
The species specific data for the Black-legged Kittiwake be derived from the built in dataset “energeticsandpreydata” that has data for all 4 species that seabORD models (“KI”, “GU”, “RA”, “PU”). The package provides helper functions for extracting the example data used throughout this vignette.
example_spdat <- seabORD::get_example_spdat()
#take a look
print(t(example_spdat))
#> [,1]
#> Code "KI"
#> Species "Black-legged Kittiwake"
#> BM_adult_mn "372.69"
#> BM_adult_sd "33.62"
#> BM_adult_mortf "0.6"
#> BM_adult_abdn "0.8"
#> BM_chick_mn "36"
#> BM_chick_sd "2.2"
#> BM_Chick_mortf "0.6"
#> daylength "36"
#> seasonlength "30"
#> unattend_max_hrs "18"
#> adult_DEE_mn "802"
#> adult_DEE_sd "196"
#> chick_DER "525.7"
#> IR_max "4.369"
#> IR_half_a "900"
#> IR_half_b "0.02"
#> flight_msec "13.1"
#> assim_eff "0.74"
#> energy_prey "6.52"
#> energy_nest "427.8"
#> energy_flight "1400.7"
#> energy_searest "400.6"
#> energy_forage "1400.7"
#> energy_warming "26"
#> chick_mass_a "11"
#> adult_mass_KG "38.5"
#> beta "0.038"
#> basesurv_poor "0.65"
#> basesurv_modr "0.8"
#> basesurv_good "0.9"
#> massloss_poor "20"
#> massloss_modr "10"
#> massloss_good "0"
#> chicksurv_poor "10"
#> chicksurv_modr "50"
#> chicksurv_good "100"The 4 species can be accessed via
spdat_all_species <- seabORD::get_spdat()BrdData
Bird distribution map. There is a built in example data-set for this run which is derived from GPS data and modeled with a GAM incorporating important factors known to drive space use in this species. The raster can be accessed with the built in function get_example_brddata()
example_brddata <- seabORD::get_example_brddata()Example:
seabORD::plot_brddata(brddata = example_brddata)
FrgCompData
Competition distribution map i.e., the distribution of conspecifics from surrounding colonies which may interact with the colony/SPA being simulated. This is used throughout the model to estimate how competition from other colonies influences intake rate at different foraging sites. It uses the built in dataset “frgcompdata_example”. The example raster can be accessed using the built in function frgcompdata_example().
example_frgcompdata <- seabORD::get_example_frgcompdata()Example:
seabORD::plot_frgcompdata(frgcompdata = example_frgcompdata)
fltdist_base
Flight distance by sea, without ORDs. See user guide for details.
example_fltdist_base <- seabORD::get_example_fltdist_base()Example:
seabORD::plot_fltdist_base(fltdist_base = example_fltdist_base)
FlightGridcorrection
It’s a TransitionLayer class object. One example provided that can be loaded
FlightGridcorrection <- seabORD::get_example_fgc_3035()ORDpoly
This is a set of polygons used to represent the ORDs that we are intending to predict the impact of.
ORDpoly_example <- seabORD::get_example_ORDpoly()which is a dataset with this multipolygon shapes:
seabORD::plot_ORDpoly(ORDpoly = ORDpoly_example)