04. R Package

R Package for Gmacs

The Gmacs R package gmr is designed to produce plots and diagnostics of Gmacs model outputs. The package is hosted on GitHub within the gmacs repository: https://github.com/seacode/gmacs/tree/develop/gmr.

Table of Contents

• Installation
• User Guide
  • Loading the Package
  • Reading Output
  • Plotting Results
  • Examples
  • Getting Help
• Contributing

Installation

The gmr package can be found at https://github.com/seacode/gmacs/tree/develop/gmr. The most recent development release of gmr can be downloaded and installed from GitHub through R using the devtools package:

install.packages("devtools")
devtools::install_github("seacode/gmacs", subdir = "/gmr", ref = "develop")

Sometimes the most recent development release of gmr will not install properly or will be unstable if the package is in the middle of being updated. In this case, previous release versions can be installed until the development release updates are complete. To install previous release versions of gmr, version 1 for example, use:

devtools::install_github("seacode/gmacs", subdir = "/gmr", ref = "V1.0")

User Guide

Loading the Package

Once the gmr package is installed, it can be loaded directly from the R console in the regular manner:

require(gmr)

The gmr package imports functions from other R packages including dplyr, ggplot2 and reshape2.

Reading Output

The function read_admb() reads Gmacs report files (.rep, and any other ADMB report files too). It returns an object which contains a list structure summarizing elements in the Gmacs report file. The supplied argument to the read_admb function need not contain any extensions, simply the name of the model file, e.g. gmacs.

It is common to want to plot the results of two or more models simultaneously. All gmr plotting functions support plotting multiple models, so long as the data from these models are stored as a list-of-lists. This can be done easily using the lapply function in R, for example:

models   <- c("examples/bbrkc/OneSex", "examples/bbrkc/TwoSex")
fn       <- paste0(models, "gmacs")
M        <- lapply(fn, read_admb)
names(M) <- c("OneSex", "TwoSex")

The last line above simply names the two elements of the list-of-lists and these names are used in the legend of any plots produced.

Plotting Results

The simplest way to plot the results of a Gmacs model is to use the wrapper function plot_gmacs(). This function will plot all available plots by default, or, any series of plots which have been specified via the argument which_plots. Each of the gmr plotting functions can also be accessed individually, for example plot_catch().

Examples

The following example shows how to read the output from a Gmacs model and then produce relevant plots. For demonstration purposes, the included demo model for Bristol Bay Red King Crab serves here as the source of model results.

# Load the gmr package for Gmacs:
require(gmr)

# Set working directory to that containing Gmacs model results:
setwd("c:/seacode/gmacs/examples/demo")

# Set theme for ggplot2 (works for themes classic, minimal, gray, bw):
set_ggtheme("classic")

# Read report file and create gmacs report object (a list):
gmrep <- read_admb("gmacs")

# Get plots of interest:
plot_catch(gmrep)
plot_catch_res(gmrep)
plot_sizecomp(gmrep)
plot_sizecomp_res(gmrep)

# Or plot via the plot wrapper function:
plot_gmacs(gmrep, which_plots = "all")

# Plot selected plots via the wrapper function:
plot_gmacs(gmrep, which_plots = c(1:3, 5, 8))

Getting Help

Each of the gmr functions contains internal Roxygen-style comments that generate help files. Help files can be accessed via R, e.g.

?gmr
?read_admb
?plot_catch

Contributing

R functions can be added to the gmr package in the style of the R Packages guide by Hadley Wickham.

Existing R functions for gmr are stored in the directory gmr/R, and new functions should be added to that directory too. New functions will be included in the package build process so long as they are useful, named and styled according to the R package building guide, and include a Roxygen header for documentation.

Function files should be named in the style do-something.R, functions themselves should be named in the style do_something(). The code below can be used as a template for creating new gmr functions:

#' Function title (be descriptive, e.g. Plot observed catch values)
#' 
#' Description of what the function does.
#' 
#' @param a the first expected argument to the function
#' @param b the second expected argument to the function
#' @return something done to a and b
#' @author Firstname M. Lastname
#' @examples
#' x <- do_something(a, b) # An example of how to run the function
#'
do_something <- function(a, b)
{
  out <- do_something_to(a, b)
  return(out)
}

Functions are stored in single files if they share common functionality, e.g. the plot-catch.R file contains both the plot_catch and the plot_catch_res functions. Following the R Package style-guide, it’s okay if some files only contain one function, especially if the function is large or has a lot of documentation, but where possible, it's good to group similar functions together. It's also good to use common prefixes and suffixes, e.g. plot-*.R and *-catch.R.