quickstart.RmdAs for now, the package is yet to find its way into CRAN. However, you can use our alternative repo that enables you to use R’s install.packages():
install.packages("gadgetr", repos = "https://redus-imr.github.io/gadget")Or, you can download and install from the pre-compiled binaries here:
https://github.com/REDUS-IMR/gadget/releases/latestOr, you might want to compile it from the source available in Github:
devtools::install_github("REDUS-IMR/gadget", ref="gadgetr")
This guide demonstrates gadgetr’s capability of controlling a gadget model run and extracting relevant information during the run. To run simulations, GadgetR requires a gadget model as ‘input’ (normally a set of text files). In this tutorial, we demonstrate how you set up and run GadgetR simulations using a simple haddock model by James Begley.
The library ships with an example haddock model. What we need to do is calling loadExample() to obtain the full path of the model.
# Get the path of the example haddock data exPath <- gadgetr::loadExample() print(exPath) #> [1] "/home/runner/work/_temp/Library/gadgetr/extdata/haddock"
To initialize a gadgetR run, we have to specify the full path of the model folder and input (parameter) file. In the example model, the input file is the file named refinputfile.
# Initiate the haddock model gadgetr::initGadget(exPath, "refinputfile") #> Gadget version 2.2.00-BETA running on fv-az82 Tue Sep 15 12:17:30 2020 #> Starting Gadget from directory: /home/runner/work/_temp/Library/gadgetr/extdata/haddock #> using data from directory: /home/runner/work/_temp/Library/gadgetr/extdata/haddock #> #> Finished reading model data files, starting to run simulation #> [1] "Gadget is started with the given model in /home/runner/work/_temp/Library/gadgetr/extdata/haddock." #> NULL
The initGadget() function instructs gadget to load the model and preparing the internal data structure. If successful, the model is now ready to be run.
Now that the model is loaded, we can inspect some of the important objects in the simulation. The getEcosystemInfo() is a useful function that provides this type of information.
# Get the initial information initial <- gadgetr::getEcosystemInfo() print(initial) #> $fleet #> [1] "comm" "survey" "future" #> #> $stock #> [1] "had" #> #> $time #> currentTime currentYear currentStep totalSteps finished #> 1 1978 1 172 0 # Print start year print(initial$time["currentYear"]) #> currentYear #> 1978 # Print initial step number print(initial$time["currentTime"]) #> currentTime #> 1 # Print final step number print(initial$time["totalSteps"]) #> totalSteps #> 172
As we can see in the previous section, the example haddock model has a certain number of simulation steps. Now let’s loop through the time steps while collecting the important metrics from the fleets and the stocks.
The package provides two alternative functions to forward the simulation time. These functions are runStep() and runYear(), which forward the simulation by step and year, respectively. Both functions return the metrics from both stocks and fleets objects at a particular step or year.
# Variable for counting step lengthStep <- 1 # Loop for all steps stats <- list() while (TRUE){ # Append stats stats[[lengthStep]] <- gadgetr::runStep() # Stop at the end of time status <- gadgetr::getEcosystemInfo() if(status[["time"]]["finished"] == 1) break lengthStep <- lengthStep + 1 } print(lengthStep) #> [1] 172 # Get termination information term <- gadgetr::getEcosystemInfo() # Print end year print(term$time["currentYear"]) #> currentYear #> 2020 print(initial$time["currentYear"] + (lengthStep / 4) - 1) #> currentYear #> 2020 # Print last step number print(term$time["currentTime"]) #> currentTime #> 172 print(lengthStep) #> [1] 172
In the above code, a condition status[["time"]]["finished"] == 1 terminates the loop. The getEcosystemInfo() gives an updated status of the model run whenever it is called. It also gives information whether the simulation has reached to an end.
You may also safely replace the runStep() with runYear() in the above code. However, the metrics content in the stats objects will not be broke down into steps as you might have with runStep() function. This is because runYear() function will aggregate the steps’ metrics from the model’s objects.
The greatest advantage of this package is its ability to extract and modify information directly from/to the gadget’s internal runtime objects in memory. This will save users from tinkering with the gadget model configuration files and also it output printing files.
This guide won’t cover the on-the-fly modification of a gagdet internal objects. However, the code below should demonstrates the package’s capability to extract gadget information.
# Print out all status print(names(stats[[1]])) #> [1] "fleets" "stocks" print(names(stats[[1]]$stock)) #> [1] "had" print(names(stats[[1]]$fleet)) #> [1] "comm" "survey" "future" # Print haddock stock in step 1 print(names(stats[[1]]$stock$had)) #> [1] "stk" "ssb" "rec" "eat" print(tail(stats[[1]]$stock$had$stk)) #> year step area age length number meanWeights #> [855,] 1978 1 1 10 84.5 2167.5906 5.438262 #> [856,] 1978 1 1 10 85.5 1641.8743 5.618887 #> [857,] 1978 1 1 10 86.5 1228.4031 5.803317 #> [858,] 1978 1 1 10 87.5 907.7792 5.991590 #> [859,] 1978 1 1 10 88.5 662.6098 6.183739 #> [860,] 1978 1 1 10 89.5 477.7205 6.379800 # Print haddock recruitment in step 1 print(names(stats[[1]]$stock$had$rec)) #> [1] "renew" "spawn" print(tail(stats[[1]]$stock$had$rec$renew)) #> year step area age length renewalNumber renewalWeight #> [19,] 1978 1 1 1 22.5 544218.20585 0.1167141 #> [20,] 1978 1 1 1 23.5 134136.30078 0.1327542 #> [21,] 1978 1 1 1 24.5 27135.19955 0.1502071 #> [22,] 1978 1 1 1 25.5 4505.39788 0.1691329 #> [23,] 1978 1 1 1 26.5 613.96938 0.1895923 #> [24,] 1978 1 1 1 27.5 68.67105 0.2116456 print(stats[[1]]$stock$had$rec$spawn) #> <0 x 0 matrix> # Print haddock catch by commercial fleet in step 1 print(names(stats[[1]]$fleet)) #> [1] "comm" "survey" "future" print(names(stats[[1]]$fleet$comm$catch)) #> [1] "had" print(tail(stats[[1]]$fleet$comm$catch$had)) #> year step area age length numberConsumed biomassConsumed mortality #> [425,] 1978 1 1 10 78.5 943.42925 4248.9201 0.2418700 #> [426,] 1978 1 1 10 80.5 613.50613 2961.1357 0.2419795 #> [427,] 1978 1 1 10 82.5 379.73514 1960.9355 0.2420509 #> [428,] 1978 1 1 10 84.5 223.72674 1234.1016 0.2420975 #> [429,] 1978 1 1 10 86.5 125.47149 738.1895 0.2421279 #> [430,] 1978 1 1 10 88.5 66.98412 419.7142 0.2421477
After each simulation, it is necessary for users to properly terminate an active gadget simulation run. Use the code below when you finish with a simulation run or if you want to restart the current model or loading a new model.
# Sim cleanup gadgetr::endGadget() #> [1] "Gadget succesfully terminates." #> NULL
The endGadget() function will remove all gadget internal runtime objects from memory and ensure gadget library is ready to start another simulation run.