Creates a folder with basic files for a running. Then, run the model and read the outputs.

Yunne-Jai Shin, Criscely Lujan, Wencheng Lau-Maudrano, Philippe Verley, Ricardo Oliveros-Ramos, Nicolas Barrier & Laure Velez (2020)

2020-04-28

Introduction

osmose (Object Oriented Simulator of Marine Ecosystems) is a multispecies and individual-based model (IBM) (Y.-J. Shin and Cury 2001; Y.-J. Shin and Cury 2004) focuses on fish species. This model assumes opportunistic predation based on spatial co-occurrence and size adequacy between a predator and its prey (size-based opportunistic predation). It represents fish individuals grouped into schools, which are characterized by their size, weight, age, taxonomy and geographical location (2D model), and which undergo major processes of fish life cycle (growth, explicit predation, natural and starvation mortalities, reproduction and migration) and fishing exploitation. The model needs basic biological parameters that are often available for a wide range of species, and which can be found in ‘FishBase’ for instance (see http://www.fishbase.org/search.php), and fish spatial distribution data. This package provides tools to build and run simulations using the ‘OSMOSE’ model.

Installation

For installing osmose, as follows:

# From CRAN
install.packages("osmose")

# From Github
devtools::install_github("osmose-model/osmose")

Jar files will be automatically downloaded in a temporary directory. However in order to set its location you will need to set up the OSMOSE_DIR environment variable. This is done by editing the .Renviron file, as shown here.

Other way to edit the .Renviron file is by using the usethis package and the following code:

# To open the .Renviron file
usethis::edit_r_environ()

# Then you should copy the directory where Jar files will be donwloaded. For example:
OSMOSE_DIR = Copy/a/path/here  #Don't use quotation marks

# Then save and close the .Renviron file

Note that in Linux/Mac OS X, the file must be put into the ${HOME} directory, while in Windows, it must be in the user’s Documents folder. Below is provided an example of OSMOSE_DIR for Linux/Mac Os X and Windows:

If you set upped OSMOSE_DIR variable you can re-use the same directory to download the files related to the demostration of the package.

About OSMOSE

OSMOSE is a multispecies and Individual-based model (IBM) which focuses on fish species. This model assumes opportunistic predation based on spatial co-occurrence and size adequacy between a predator and its prey (size-based opportunistic predation). It represents fish individuals grouped into schools, which are characterized by their size, weight, age, taxonomy and geographical location (2D model), and which undergo major processes of fish life cycle (growth, explicit predation, natural and starvation mortalities, reproduction and migration) and a fishing mortality distinct for each species (Y.-J. Shin and Cury 2001; Y.-J. Shin and Cury 2004). OSMOSE, uncoupled version, has been first applied to the Benguela upwelling ecosystem for which 12 fish species have been specified, from small pelagic fish to large demersal species (Y.-J. Shin and Cury 2004; Travers et al. 2006). The model needs basic parameters that are often available for a wide range of species, and which can be found in FishBase for instance.

Main functions

osmose package performs three main functions (read_osmose, run_osmose and get_var) and several methods for the outputs (plot, print, summary and report).

Create example files

osmose includes a function that allows to create basic example files in a selected folder. The files corresponds to a case study provided by Halouani et al. (2016). osmose_demo uses two main arguments: (1) path will be the folder path where the files will be copied and (2) config which indicates the configuration example to be copied. To indicate Halouani et al. (2016) case study, config = "gog".

# Define a folder to copy files (for the example: a temporary folder)
# Here you can also select the same directory than in OSMOSE_DIR 
exampleFolder <- tempdir()

cat(exampleFolder)
#> /var/folders/3c/807k30_50mv_53hr_lqb6q0c0000gn/T//Rtmp1DrbUl
# Copy files
demoPaths <- osmose_demo(path = exampleFolder, config = "gog")
#> Your file gog has been download and/or deziped in this folder : /var/folders/3c/807k30_50mv_53hr_lqb6q0c0000gn/T//Rtmp1DrbUl/gog
#> Copied files:
#>  [1] "Maps/corr_grid2_DIPANN.csv"           
#>  [2] "Maps/corr_grid2_ENGENC.csv"           
#>  [3] "Maps/corr_grid2_MELKER.csv"           
#>  [4] "Maps/corr_grid2_MERMER.csv"           
#>  [5] "Maps/corr_grid2_METMON.csv"           
#>  [6] "Maps/corr_grid2_MUSMUS.csv"           
#>  [7] "Maps/corr_grid2_OCTVUL.csv"           
#>  [8] "Maps/corr_grid2_PAGERY.csv"           
#>  [9] "Maps/corr_grid2_SARAUR.csv"           
#> [10] "Maps/corr_grid2_SARPIL.csv"           
#> [11] "Maps/corr_grid2_TRATRA.csv"           
#> [12] "Maps/grid2_DIPANN.csv"                
#> [13] "Maps/grid2_ENGENC.csv"                
#> [14] "Maps/grid2_MELKER.csv"                
#> [15] "Maps/grid2_MERMER.csv"                
#> [16] "Maps/grid2_METMON.csv"                
#> [17] "Maps/grid2_MUSMUS.csv"                
#> [18] "Maps/grid2_OCTVUL.csv"                
#> [19] "Maps/grid2_PAGERY.csv"                
#> [20] "Maps/grid2_SARAUR.csv"                
#> [21] "Maps/grid2_SARPIL.csv"                
#> [22] "Maps/grid2_TRATRA.csv"                
#> [23] "calib_config.csv"                     
#> [24] "corr_eco3m_gog44_conversion_factor.nc"
#> [25] "corr_grid_mask_gabes_all99.csv"       
#> [26] "osm_all-parameters.csv"               
#> [27] "osm_param-fishing.csv"                
#> [28] "osm_param-grid.csv"                   
#> [29] "osm_param-init-pop.csv"               
#> [30] "osm_param-ltl.csv"                    
#> [31] "osm_param-movement.csv"               
#> [32] "osm_param-mpa.csv"                    
#> [33] "osm_param-natural-mortality.csv"      
#> [34] "osm_param-output.csv"                 
#> [35] "osm_param-predation.csv"              
#> [36] "osm_param-reproduction.csv"           
#> [37] "osm_param-species.csv"                
#> [38] "osm_param-starvation.csv"             
#> [39] "predation-accessibility.csv"          
#> [40] "reproduction-seasonality-sp0.csv"     
#> [41] "reproduction-seasonality-sp1.csv"     
#> [42] "reproduction-seasonality-sp10.csv"    
#> [43] "reproduction-seasonality-sp2.csv"     
#> [44] "reproduction-seasonality-sp3.csv"     
#> [45] "reproduction-seasonality-sp4.csv"     
#> [46] "reproduction-seasonality-sp5.csv"     
#> [47] "reproduction-seasonality-sp6.csv"     
#> [48] "reproduction-seasonality-sp7.csv"     
#> [49] "reproduction-seasonality-sp8.csv"     
#> [50] "reproduction-seasonality-sp9.csv"     
#> [51] "reproduction-seasonality.csv"

Running an example

Next step involves the running of the model itself. The function run_osmose facilitates this action asking for the required arguments to achieve a successful running. run_osmose uses and require a .jar file, corresponding to the java executable that is going to be used. However, osmose package includes some versions of java executables inside, so it is only necessary to indicates the version.

# Run an example using 'run_osmose' function (it will take less than 1 min)
run_osmose(input = demoPaths$config_file)
#> This is OSMOSE version 3.3.3
#> Your file lib has been download and/or deziped in this folder : /var/folders/3c/807k30_50mv_53hr_lqb6q0c0000gn/T//Rtmp1DrbUl/lib
#> Your file osmose_3.3.3.jar has been download and/or deziped in this folder : /var/folders/3c/807k30_50mv_53hr_lqb6q0c0000gn/T//Rtmp1DrbUl/osmose_3.3.3.jar
#> Running: 'java'  -jar '/var/folders/3c/807k30_50mv_53hr_lqb6q0c0000gn/T//Rtmp1DrbUl/osmose_3.3.3.jar' /var/folders/3c/807k30_50mv_53hr_lqb6q0c0000gn/T//Rtmp1DrbUl/gog/osm_all-parameters.csv

Read configuration and outputs

Once we have run an example, it is important to know what we have and the main function to do this is read_osmose. This function will ask for the path folder of outputs and the configuration file. read_osmose will return a list of fields with the information of whether an OSMOSE running or the configuration that is going to be used in a running, so if neither of them are indicated, the user will get an error. Output class will depend on the read info: if path is specified, output class will be osmose; otherwise, if ONLY input is given, the class will be osmose.config. If both are specified, the osmose class output will content inside a field called config of class osmose.config.

# Read outputs using 'read_osmose' function
outputs <- read_osmose(path = demoPaths$output_dir, 
                       input = demoPaths$config_file)

# Check class
class(outputs)
#> [1] "osmose"

# Check class of config level
class(outputs$config)
#> [1] "osmose.config" "list"

# Read ONLY configuration files
config <- read_osmose(input = demoPaths$config_file)

# Check class
class(config)
#> [1] "osmose.config" "list"

References

Halouani, Ghassen, Frida Ben Rais Lasram, Yunne Jai Shin, Laure Velez, Philippe Verley, Tarek Hattab, Ricardo Oliveros-Ramos, et al. 2016. “Modelling food web structure using an end-to-end approach in the coastal ecosystem of the Gulf of Gabes (Tunisia).” Ecological Modelling 339: 45–57. doi:10.1016/j.ecolmodel.2016.08.008.

Shin, Yunne-Jai, and Philippe Cury. 2001. “Exploring Fish Community Dynamics Through Size-Dependent Trophic Interactions Using a Spatialized Individual-Based Model.” Aquatic Living Resources 14 (2). EDP Sciences: 65–80.

———. 2004. “Using an Individual-Based Model of Fish Assemblages to Study the Response of Size Spectra to Changes in Fishing.” Canadian Journal of Fisheries and Aquatic Sciences 61 (3). NRC Research Press: 414–31.

Travers, Morgane, Yunne-Jai Shin, Lynne Shannon, and Philippe Cury. 2006. “Simulating and Testing the Sensitivity of Ecosystem-Based Indicators to Fishing in the Southern Benguela Ecosystem.” Canadian Journal of Fisheries and Aquatic Sciences 63 (4). NRC Research Press: 943–56.