4  R routines

DISPLACE requires input files in a specific format for the modeling framework to read them correctly. The previous sections described the contents and structure of the raw inputs, which must then be transformed to meet these requirements. In this section, we walk through the R routines needed to adapt the inputs.

The required DISPLACE inputs depend on the type of analysis being performed and the model modules being used. While other DISPLACE applications make use of additional routines to prepare such inputs (see the complete routines repository from François et al.), here we only include those relevant to our case study. These are divided into two main groups: routines for preparing data for the populations model and routines for preparing data for the fleet model. Additional routines are included to prepare the remaining data needed to run DISPLACE.

In this repository, the routines are located in the routines folder, and the code to execute them sequentially can be found in r/functions_routines.R. Here we use R 4.5.0, and the packages included in r/config.R. Be aware that as describerd in some of the previous sections, some model inputs are hardcoded within this routines, so modify the code as needed for your case study.

Routines for the population inputs located in raw_inputs/POPULATIONS are:

• 01_GeneratePopulationsFeatures.R
  
• 02_GeneratePopulationsConfigFiles.R
  
• 03_RunPopulationsConfigFiles.R
  
• 04_GeneratePopulationsPreferencesPerSpeciesMatrix.R
  
• 05_GeneratePopulationsVariousFiles.R

Routines for the fleet inputs in raw_inputs/FISHERIES are:

• 06_GenerateVesselsConfigFiles.R
  
• 07_RunVesselsConfigFiles.R
  
• 08_GenerateVesselsEconomicsFile.R
  
• 09_GenerateOtherCatchesOnNodes.R
  
• 10_GenerateMetiersSelectivityPerStockFiles.R
  
• 11_GenerateMetiersVariousFiles.R

The routine 09_GenerateOtherCatchesOnNodes.R assigns additional fixed catches to the nodes beyond those of our modeled fleet. For instance, if other nations or fleets not explicitly characterized in the model exert fishing pressure on the populations defined in the analysis, the catch from these can be indicated in the file OTHER/othercatchespercountry.csv as fixed removals (in tonnes per year). While recruits are proportionally assigned based on coverage and density from SDM inputs, this routine assigns other catches evenly across the species’ coverage area, without accounting for species density. The routine can, however, be updated to weight other catches according to species distribution.

Additional routines required to run DISPLACE are:

• 12_GenerateHarboursFiles.R: Prepares harbour files, including stock prices and fuel prices. Currently, the routine assigns the same prices across all ports, but it can be updated to reflect port-specific prices.

• 13_GenerateShippingFiles.R: Although we do not use this module (which models traffic lanes used by other vessels that might influence fishing vessel behavior), DISPLACE still requires two files with dummy data in the raw_inputs/SHIPPING folder and corresponding processed inputs, so the model can run even without using this feature.

• 14_GenerateFishfarmsFiles.R: Similarly, fish farm locations and features (defined by coordinates and size) can be included to condition vessel navigation and fishing. For this case study, we use dummy data in raw_inputs/FISHFARMS to allow DISPLACE to run, though this feature is not used in the analysis.

• 15_GenerateWindmillsFiles.R: Allows input of specific turbine distributions or single turbine positions. Dummy data are included in raw_inputs/WINDMILLS for this case study.

• 16_GenerateFirmsFiles.R: We do not use the firms feature. The input file in raw_inputs/FIRMS is populated with dummy data solely to satisfy DISPLACE requirements.

• 17_GenerateSimulationsConfigFiles.R: An important step, as it generates all files required to inform DISPLACE about the parameterization, characteristics, and inputs needed to execute a run. These files are stored in processed_inputs/simusspe_california_example after running all routines.

• 18_GenerateBenthosLandscapeOnNodes.R: DISPLACE includes an optional benthic module designed to evaluate fishing impacts on benthic habitats. This module is deactivated in our project, and the file in raw_inputs/HABITATS is filled with dummy data solely to prevent DISPLACE from crashing.

The execution of r/functions_routines.R runs these routines sequentially and generates the contents of the processed_inputs folder (initially empty in this repository). To create its contents, simply execute this script.

source(here::here("r/functions_routines.R"))

In addition to running the routines, functions_routines.R also:

• Updates config.dat to indicate the implicitly defined species.
  
• Updates the baseline.dat file to set the baseline scenario using the closer_port feature, ensuring vessels return to the closest port among those historically fished (as part of our case study parametrization; this may differ depending on the application of DISPLACE).

The script also includes the function generate_dis_run_files, which defines the .bat and .dsf files needed to run DISPLACE without using the GUI. This function allows the user to specify:

• The base directory for outputs.
  
• The scenario being run.
  
• The replicate name
• The number of replicates.
• The number of years analyzed.
• The number of years for which data are stored. By default, DISPLACE only saves 1 year of VMS-like data, but it can be set to save 7 or 10 years of simulated data.
  
• The number of threads to run the model, depending on the machine’s cores.

Once all processed inputs are generated (this can be done in Windows, macOS, or Linux using R), DISPLACE can be run from a Windows machine either via the GUI or by double-clicking the generated .bat file.