diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index 1b64d66..e40404b 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -30,35 +30,6 @@ jobs: steps: - uses: actions/checkout@v3 - - - name: Get the latest SS3 executable for linux and move to expected location - if: matrix.config.os == 'ubuntu-latest' - run: | - curl https://api.github.com/repos/nmfs-stock-synthesis/stock-synthesis/releases/latest | grep "browser_download_url" | grep -Eo 'https://[^\"]*' | grep "ss_linux" | xargs wget - mv ss_linux ss - sudo chmod a+x ss - cp ss inst/extdata/ss - rm ss - - - name: Get the latest SS3 executable for windows and move to expected location - if: matrix.config.os == 'windows-latest' - run: | - Invoke-WebRequest -Uri https://github.com/nmfs-stock-synthesis/stock-synthesis/releases/download/v3.30.21/ss_win.exe -Outfile "D:\a\ss3diags\ss3diags\ss_win.exe" - mv ss_win.exe ss.exe - cp ss.exe inst/extdata/ss.exe - - - uses: nick-fields/retry@v2 - if: matrix.config.os == 'macOS-latest' - with: - timeout_minutes: 3 - max_attempts: 3 - retry_on: error - command: | - curl https://api.github.com/repos/nmfs-stock-synthesis/stock-synthesis/releases/latest | grep "browser_download_url" | grep -Eo 'https://[^\"]*' | grep "ss_osx" | xargs wget - mv ss_osx ss - sudo chmod a+x ss - cp ss inst/extdata/ss - rm ss - uses: r-lib/actions/setup-pandoc@v2 @@ -78,15 +49,6 @@ jobs: with: error-on: '"error"' - - name: remove ss executable - run: | - if ["$RUNNER_OS" == "Linux" ]; then - rm inst/extdata/ss.exe - else - rm inst/extdata/ss - fi - shell: bash - diff --git a/DESCRIPTION b/DESCRIPTION index 6dd582e..f500bf1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -39,4 +39,4 @@ Encoding: UTF-8 LazyData: True LazyDataCompression: gzip Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.1 diff --git a/R/SSplotEnsemble.R b/R/SSplotEnsemble.R index 915b5dd..4468bc7 100644 --- a/R/SSplotEnsemble.R +++ b/R/SSplotEnsemble.R @@ -1,73 +1,42 @@ #' Model ensemble plots #' -#' Plots model ensembles and forecasts with uncertaity represented by MVLN or MCMC posteriors +#' Plots model ensembles and forecasts with uncertainty represented by MVLN or +#' MCMC posteriors #' -#' @param kb SSdeltaMVLN $kb type output -#' @param subplots option to "Bratio","Fvalue","SSB", "F", "Recr","Catch" +#' @param kb `kb` type output created by `SSdeltaMVLN()` +#' @param subplots vector to create subplots with these options: +#' \itemize{ +#' \item `"stock"` Fish Population +#' \item `"harvest"` Harvest Rate +#' \item `"SSB"` Spawning Stock Biomass +#' \item `"F"` Fishing Mortality +#' \item `"Recr"` Recruitment +#' \item `"Catch"` Total Catch +#' } #' @param models option to manually subset the models in `kb[["run"]]` -#' @param quantiles quantiles for uncertainty in plots. Input as a list, default is the 95TH percentile: list(c(0.025, 0.975)) -#' @param ylabs yaxis labels for quants -#' final year of values to show for each model. By default it is set to the -#' @param endyrvec ending year specified in each model. -#' @param plot Deprecated. Plots (and subplots) are drawn to the active plot device -#' by default (TRUE), and the option to disable this, via FALSE, is unused. -#' @param print Deprecated. Please use 'print_plot'. -#' @param print_plot print to PNG files? -#' @param pdf Deprecated. Please use 'use_pdf'. -#' @param use_pdf option for pdf plots (not tested for TRUE) -#' @param png Deprecated. Please use 'use_png'. -#' @param use_png Draw plots in PNG format -#' @param col Optional vector of colors to be used for lines. Input NULL -#' @param pch Optional vector of plot character values -#' @param lty Optional vector of line types -#' @param lwd Optional vector of line widths -#' @param tickEndYr TRUE/FALSE switch to turn on/off extra axis mark at final -#' year in timeseries plots. -#' @param ylimAdj Multiplier for ylim parameter. Allows additional white space -#' @param xlim Optional, years to use for x-axis. Default NULL uses all years available. -#' @param xaxs Choice of xaxs parameter (see ?par for more info) -#' @param yaxs Choice of yaxs parameter (see ?par for more info) -#' @param type Type parameter passed to points (default 'o' overplots points on -#' top of lines) -#' @param legend Add a legend to plot. TRUE by default. -#' @param legendlabels Optional vector of labels to include in legend. -#' @param legendloc Location of legend. Either a string like "topleft" or a vector -#' of two numeric values representing the fraction of the maximum in the x and y -#' dimensions, respectively. See ?legend for more info on the string options. -#' @param legendorder Optional vector of model numbers that can be used to have -#' the legend display the model names in an order that is different than that -#' which is represented in the summary input object. -#' @param legendncol Number of columns for the legend. -#' @param legendcex Allows to adjust legend cex -#' @param legendsp Space between legend labels -#' @param legendindex Allows to add legend for selected indices (plots) -#' @param pwidth Width of plot -#' @param pheight Height of plot -#' @param punits Units for PNG file -#' @param res Resolution for PNG file -#' @param ptsize Point size for PNG file -#' @param cex.main Character expansion for plot titles -#' @param plotdir Directory where PNG or PDF files will be written. By default -#' it will be the directory where the model was run. -#' @param filenameprefix Additional text to append to PNG or PDF file names. -#' It will be separated from default name by an underscore. -#' @param par list of graphics parameter values passed to par() function -#' @param verbose Report progress to R GUI? -#' @param shadealpha Transparency adjustment used to make uncertainty regions, default is 0.3 -#' @param new Deprecated. New plot windows are created by default (TRUE), and the -#' option to disable this, via FALSE, is unused. -#' @param add suppresses par() to create multiplot figs -#' @param xylabs TRUE or FALSE, include x- and y-axis labels. Defaults to TRUE -#' @param uncertainty TRUE/FALSE include uncertainty intervals around SSB or F estimated time series. Defaults to TRUE. -#' @param mcmcVec mcmc vector TODO TODO. Default is FALSE -#' @param indexQlabel TRUE/FALSE include labels for indices. Default is TRUE (currently not used) -#' @param indexQdigits Number of significant digits for catchability in legend. Default is 4 +#' @param quantiles quantiles for uncertainty in plots. Input as a list, +#' default is the 95TH percentile: `list(c(0.025, 0.975))` +#' @param ylabs y-axis labels for quants +#' @param shadealpha Transparency adjustment used to make uncertainty regions, +#' default is 0.3 +#' @param indexQlabel TRUE/FALSE include labels for indices. Default is TRUE +#' (currently not used) +#' @param indexQdigits Number of significant digits for catchability in legend. +#' Default is 4 +#' @param endyrvec Optional single year or vector of years representing the +#' final year of values to show for each model. By `"default"` it is set to the +#' ending year specified in each model. #' #' @importFrom grDevices graphics.off rgb adjustcolor dev.new dev.off #' @importFrom graphics polygon abline axis box #' @importFrom stats dnorm #' @importFrom lifecycle deprecated #' +#' @inheritParams SSplotGeneric +#' @inheritParams SSplotGenericLegend +#' @inheritParams SSplotGenericPar +#' @inheritParams SSplotGenericUncertainty +#' #' @author Mostly adopted from r4ss::SSplotComparisons by Taylor et al #' #' @examples @@ -128,7 +97,8 @@ SSplotEnsemble <- function(kb, mcmcVec = FALSE, indexQlabel = TRUE, indexQdigits = 4, - legendindex = NULL) { # plot different fits to a single index of abundance + legendindex = NULL) { + # plot different fits to a single index of abundance # Parameter DEPRECATION checks if (lifecycle::is_present(print)) { diff --git a/R/SSplotGeneric.R b/R/SSplotGeneric.R new file mode 100644 index 0000000..b16d95e --- /dev/null +++ b/R/SSplotGeneric.R @@ -0,0 +1,236 @@ +#' Generic SSplot function +#' +#' Generalized version of ss3diags SSplots functions. Not intended for +#' production +#' +#' @param pwidth +#' Default width of plot printed to plot in units of `punits` +#' +#' @param pheight +#' Height of plot printed to plot in units of `punits ` +#' +#' @param punits +#' Measurement units for `pwidth` and `pheight`. Default is `"in"`. +#' \itemize{ +#' \item `"px"` (pixels) +#' \item `"in"` (inches) +#' \item `"cm"` (centimeters) +#' \item `"mm"` (millimeters) +#' } +#' +#' @param res +#' Resolution for plots printed to files. +#' +#' @param ptsize +#' Point size for plotted text in plots printed in files. See `help("png")` +#' for more details +#' +#' @param cex.main +#' Character expansion for plot titles. +#' +#' @param plotdir +#' Directory where output plot file will be written. By default, +#' it will be the directory where the model was run. +#' +#' @param filenameprefix +#' Additional text to append to output plot file name. +#' It will be separated from default name by an underscore. +#' +#' @param par +#' A numerical vector of the form c(bottom, left, top, right) which +#' gives the number of lines of margin to be specified on the four sides of +#' the plot,which is passed to `par()`. Entering `NULL` passes plot's default +#' `par()` values (which depends on whether the main title is included or not) +#' +#' @param verbose +#' Flag to print additional diagnostic messages to R console +#' +#' @param plot +#' DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +#' plot device. The option to explicitly disable this option (FALSE), is not +#' implemented. This option flag will be defunct in a future version +#' +#' @param print +#' DEPRECATED, please use `print_plot`. +#' +#' @param print_plot +#' Flag to enable plot graphic device to print to PNG or PNG files. +#' +#' @param png +#' DEPRECATED. Please use `use_png`. +#' +#' @param use_png +#' Enables plots to be generated to PNG files. Defaults to print value +#' +#' @param pdf +#' DEPRECATED. Please use `use_pdf`. +#' +#' @param use_pdf +#' Enables plots to be generated to pdf file. +#' +#' @param new +#' Deprecated. New plot windows are created by default (TRUE), and the +#' option to disable this, via FALSE, is unused. +#' +#' @param add +#' suppresses `par()` to create multiplot figs +#' +#' @keywords internal +#' +SSplotGeneric <- function(pwidth = 6.5, + pheight = 5.0, + punits = "in", + res = 300, + ptsize = 10, + cex.main = 1, + plotdir = NULL, + filenameprefix = "", + par = list(mar = c(5, 4, 1, 1) + .1), + verbose = TRUE, + plot = TRUE, + print = deprecated(), + print_plot = FALSE, + png = deprecated(), + use_png = print_plot, + pdf = deprecated(), + use_pdf = FALSE, + new = TRUE, + add = FALSE) { + stop("SSplotGeneric not implemented") +} + + +#' Legend parameters for Generic SSplot +#' +#' Generalized version of ss3diags SSplots functions specfic to plot legend +#' parameters. Not intended for production. +#' +#' @param legend +#' Flag to enable legend to plot. TRUE by default. +#' +#' @param legendlabels +#' Optional vector of labels to include in legend. +#' +#' @param legendloc +#' Location of legend. Either a string like "topleft" or a vector of two +#' numeric values representing the fraction of the maximum in the x and y +#' dimensions, respectively. See `help("legend")` for more info on the +#' string options. +#' +#' @param legendorder +#' Optional vector of model numbers that can be used to have the legend +#' display the model names in an order that is different than that +#' which is represented in the summary input object. +#' +#' @param legendncol +#' Number of columns for the legend. +#' +#' @param legendcex +#' Allows to adjust legend cex +#' +#' @param legendsp +#' Space between legend labels +#' +#' @param legendindex +#' Allows to add legend for selected indices (plots) +#' +#' @keywords internal +#' +SSplotGenericLegend <- function(legend = TRUE, + legendlabels = "default", + legendloc = "topright", + legendorder = "default", + legendncol = 1, + legendcex = 1, + legendsp = 0.9, + legendindex = NULL) { + stop("SSplotGenericLegend not implemented") +} + + +#' Graphical Parameters for Stock Synthesis Generic plots. +#' +#' Generalized version of ss3diags SSplots functions to specify to `par()` or +#' to pass plot attributes. Not intended for production. +#' +#' @param col +#' Optional vector of colors to be used for lines. Input NULL +#' +#' @param pch +#' Optional vector of plot character values +#' +#' @param lty +#' Optional vector of line types +#' +#' @param lwd +#' Optional vector of line widths +#' +#' @param tickEndYr +#' [Logical][base::logical] flag: set TRUE or FALSE to switch to turn +#' on/off extra axis mark at final year in timeseries plots. +#' +#' @param ylimAdj +#' Multiplier for ylim parameter. Allows additional white space. +#' +#' @param xlim +#' Optional, years to use for x-axis. Default value NULL (or "default"), +#' uses all years available. +#' +#' @param xaxs +#' Choice of xaxs parameter See `?par` for more info. +#' +#' @param yaxs +#' Choice of yaxs parameter. See `?par` for more info. +#' +#' @param xylabs +#' [Logical][base::logical] flag: set TRUE or FALSE to include x- and +#' y-axis labels to the plot. Defaults to TRUE +#' +#' @param type +#' The type of plot to be drawn. For more details, see [`plot`][base::plot]. +#' +#' @keywords internal +#' +SSplotGenericPar <- function(col = NULL, + pch = NULL, + lty = 1, + lwd = 2, + tickEndYr = FALSE, + xlim = NULL, + ylimAdj = 1.05, + xaxs = "i", + yaxs = "i", + xylabs = TRUE, + type = "l") { + stop("SSplotGenericPar not implemented") +} + + +#' Uncertainty parameters for Stock Synthesis Generic plots. +#' +#' Generalized version of ss3diags SSplots functions to specify uncertainty. +#' Not intended for production. +#' +#' @param uncertainty +#' Logical flag to enable plots with uncertainty intervals. Either a single +#' TRUE/FALSE value, or a vector of TRUE/FALSE values around SSB or F +#' estimated timeseries, or a set of integers corresponding to +#' the choice of models. +#' +#' @param mcmcVec +#' Logical vector of TRUE/FALSE values (or single value) indicating +#' whether input values are from MCMC or to use normal distribution around +#' MLE. +#' +#' @param models Optional subset of the models of `summaryoutput` (or a similar +#' field with a different name): a list created by the function +#' [r4ss::SSsummarize]. Either `"all"` or a vector of numbers indicating +#' columns in summary tables. +#' +#' @keywords internal +#' +SSplotGenericUncertainty <- function(uncertainty = TRUE, + mcmcVec = FALSE, + models = "all") { + stop("SSplotGenericUncertainty not implemented") +} diff --git a/R/SSplotHCxval.R b/R/SSplotHCxval.R index e004a11..683e10f 100644 --- a/R/SSplotHCxval.R +++ b/R/SSplotHCxval.R @@ -1,81 +1,63 @@ #' Hindcasting Cross-Validations of Multiple Models #' -#' Plots one-step ahead hindcasting cross-validations and computes MASE from prediction residuals. -#' MASE is calculated as the average ratio of mean absolute error (MAE) of prediction residuals (MAE.PR) and naive predictions (MAE.base) -#' MASE.adj sets the MAE.base to a minimum MAE.base.adj (default=0.1) -#' MASE.adj allow passing (MASE<1) if MAE.PE < 0.1 and thus accurate if obs show very little annual variation +#' Plots one-step ahead hindcasting cross-validations and computes MASE from +#' prediction residuals.`MASE` is calculated as the average ratio of mean +#' absolute error (`MAE`) of prediction residuals (`MAE.PR`) and naive +#' predictions (`MAE.base`). `MASE.adj` sets the `MAE.base` to a minimum +#' `MAE.base.adj` (`default=0.1`). `MASE.adj` allow passing (`MASE<1`) if +#' `MAE.PE < 0.1` and thus accurate if obs show very little annual variation #' -#' @param retroSummary List created by r4ss::SSsummarize() or ss3diags::SSretroComps() -#' @param subplots optional use of c("cpue","len","age"), yet to be tested for age. -#' @param models Optional subset of the models described in -#' r4ss function summaryoutput(). Either "all" or a vector of numbers indicating -#' columns in summary tables. -#' @param Season option to specify Season as an integer of value 1-4 - Default uses first available, i.e. usual Seas = 1 +#' @param retroSummary List created by [r4ss::SSsummarize()] or +#' [ss3diags::SSretroComps()] +#' @param subplots optional use of the following: +#' \itemize{ +#' \item `"cpue"` Index of abundance data +#' \item `"len"` Length-composition data +#' \item `"age"` Age-composition data +#' } +#' @param Season option to specify Season as an integer of value 1-4. Default +#' uses first available, i.e. usual Seas = 1 #' @param endyrvec Optional single year or vector of years representing the #' final year of values to show for each model. By default it is set to the #' ending year specified in each model. -#' @param indexselect = Vector of fleet numbers for each model for which to compare -#' @param MAE.base.adj minimum MASE denominator (naive predictions) for MASE.adj (default = 0.1) -#' @param show.mase.adj if TRUE it show mase.adj in () in plot -#' @param indexfleets CHECK IF NEEDED or how to adjust indexfleets +#' @param MAE.base.adj minimum `MASE` denominator (naive predictions) for +#' `MASE.adj` (default = 0.1) +#' @param show.mase.adj if TRUE, it show `mase.adj` in plot +#' @param indexfleets Fleet numbers for each model to compare +#' indices of abundance. Can take different forms: +#' \itemize{ +#' \item integer: (default) create a single comparison plot for the chosen +#' index +#' \item NULL: create a separate plot for each index as long as the fleet +#' numbering is the same across all models. +#' \item vector of length equal to number of models: a single fleet number +#' for each model to be compared in a single plot +#' \item list: list of fleet numbers associated with indices within each +#' model to be compared, where the list elements are each a vector of the +#' same length but the names of the list elements don't matter and can be +#' absent. +#' } #' @param xmin optional number first year shown in plot (if available) -#' @param indexUncertainty Show fixed uncertainty intervals on index (not estimated) -#' @param plot Deprecated. Plots (and subplots) are drawn to the active plot device -#' by default (TRUE), and the option to disable this, via FALSE, is unused. -#' @param print Deprecated. Please use 'print_plot'. -#' @param print_plot Option to print to PNG files -#' @param png Deprecated, please use 'use_png'. -#' @param use_png Draw plots in PNG format -#' @param pdf PDF plots. Deprecated. Please use use_pdf. -#' @param use_pdf option for pdf plots -#' @param col Optional vector of colors to be used for lines. Input NULL -#' @param pch Optional vector of plot character values -#' @param lty Optional vector of line types -#' @param lwd Optional vector of line widths -#' @param tickEndYr TRUE/FALSE switch to turn on/off extra axis mark at final -#' year in timeseries plots. -#' @param ylimAdj Multiplier for ylim parameter. Allows additional white space -#' @param ylim will over-write ylimAdj if specified -#' @param xaxs Choice of xaxs parameter (see ?par for more info) -#' @param yaxs Choice of yaxs parameter (see ?par for more info) -#' @param type Type parameter passed to points (default 'o' overplots points on -#' top of lines) -#' @param legend Option to add a legend. TRUE by default. -#' @param legendlabels Optional vector of labels to include in legend. -#' @param legendloc Location of legend. Either a string like "topleft" or a vector -#' of two numeric values representing the fraction of the maximum in the x and y -#' dimensions, respectively. See ?legend for more info on the string options. -#' @param legendorder Optional vector of model numbers that can be used to have -#' the legend display the model names in an order that is different than that -#' which is represented in the summary input object. -#' @param legendncol Number of columns for the legend. -#' @param legendcex Allows to adjust legend cex -#' @param legendsp Space between legend labels -#' @param legendindex Allows to add legend for selected indices (plots) -#' @param pwidth Width of plot -#' @param pheight Height of plot -#' @param punits Units for PNG file -#' @param res Resolution for PNG file -#' @param ptsize Point size for PNG file -#' @param cex.main Character expansion for plot titles -#' @param plotdir Directory where PNG or PDF files will be written. By default -#' it will be the directory where the model was run. -#' @param filenameprefix Additional text to append to PNG or PDF file names. -#' It will be separated from default name by an underscore. -#' @param par list of graphics parameter values passed to par() function -#' @param verbose Report progress to R GUI? +#' @param ylim will over-write `ylimAdj` if specified #' @param shadecol uncertainty shading of hcxval horizon -#' @param shadecol1 uncertainty shading of early years not affected by hindcast (currently not used) -#' @param new Create new empty plot window -#' @param add suppresses par() to create multiplot figs -#' @param mcmcVec NOT TESTED Vector of TRUE/FALSE values (or single value) indicating -#' @param indexQlabel Add catchability to legend in plot of index fits (TRUE/FALSE)? +#' @param shadecol1 uncertainty shading of early years not affected by +#' hindcast (currently not used) +#' @param shadecol2 color for uncertainty in early years not affected by +#' hindcast +#' @param shadealpha Transparency adjustment used to make default `shadecol`. +#' (currently not used) +#' @param indexselect Vector of fleet numbers for each model for which to +#' compare +#' @param indexQlabel [Logical][base::logical] flag to add catchability to +#' legend in plot of index fits. #' @param indexQdigits Number of significant digits for catchability in legend -#' @param shadealpha Transparancy adjustment used to make default shadecol. (currently not used) -#' @param xlim Optional, values for x-axis range of years to display on plot. Default = "default" displays all years of available data. (currently not in use) -#' @param xylabs TRUE or FALSE, include x- and y-axis labels -#' @param uncertainty TRUE/FALSE include uncertainty intervals around SSB or F estimated timeseries. Defaults to TRUE. -#' @param shadecol2 color for uncertainty in early years not affected by hindcast +#' @param indexUncertainty Show fixed uncertainty intervals on index +#' (not estimated) +#' +#' @inheritParams SSplotGeneric +#' @inheritParams SSplotGenericLegend +#' @inheritParams SSplotGenericPar +#' @inheritParams SSplotGenericUncertainty #' #' @author Henning Winker (JRC-EC) and Laurence Kell (Sea++) #' diff --git a/R/SSplotJABBAres.R b/R/SSplotJABBAres.R index 07fe176..67c4d53 100644 --- a/R/SSplotJABBAres.R +++ b/R/SSplotJABBAres.R @@ -1,72 +1,41 @@ #' Residual plot #' -#' plots residuals for all indices as boxplot (color coded by fleet) with a loess showing systematic trends over time. This function is from the package JABBA. +#' Plots residuals for all indices as boxplot (color coded by fleet) with a +#' loess showing systematic trends over time. This function is from the package +#' JABBA (Just Another Bayesian Biomass Assessment). #' -#' @param ss3rep Stock Synthesis output as read by r4SS function SS_output -#' @param subplots string of type of data to plot, 'cpue' for index of abundance data, 'len' or 'age' for length- or age-composition, 'size' for generalized size composition, or 'con' for conditional age-at-length data. -#' @param seas string indicating how to treat data from multiple seasons -#' 'comb' - combine seasonal data for each year and plot against Yr -#' 'sep' - treat season separately, plotting against Yr.S. -#' If is.null(seas), it is assumed that there is only one season and option 'comb' is used. -#' @param plot Deprecated. Plots (and subplots) are drawn to the active plot device -#' by default (TRUE), and the option to disable this, via FALSE, is unused. -#' @param print Deprecated. Please use 'print_plot'. -#' @param print_plot Option to print to PNG files -#' @param png Deprecated. please use 'use_png'. -#' @param use_png Draw plots in PNG format -#' @param pdf Deprecated. Please use 'use_pdf'. -#' @param use_pdf option for pdf plots (not tested for TRUE) -#' @param indexselect Vector of fleet numbers for each model for which to compare -#' @param miny minimum abs values of ylim -#' @param col Optional vector of colors to be used for lines. Input NULL -#' @param pch Optional vector of plot character values -#' @param lty Optional vector of line types -#' @param lwd Optional vector of line widths -#' @param tickEndYr TRUE/FALSE switch to turn on/off extra axis mark at final -#' year in time series plots. -#' @param ylimAdj Multiplier for ylim parameter. Allows additional white space -#' @param xaxs Choice of x-axis parameter (see ?par for more info) -#' @param yaxs Choice of y-axis parameter (see ?par for more info) -#' @param type Type parameter passed to points (default 'o' overplots points on -#' top of lines) -#' @param legend Option to add a legend. TRUE by default. -#' @param legendlabels Optional vector of labels to include in legend. -#' @param legendloc Location of legend. Either a string like "topleft" or a vector -#' of two numeric values representing the fraction of the maximum in the x and y -#' dimensions, respectively. See ?legend for more info on the string options. -#' @param legendorder Optional vector of model numbers that can be used to have -#' the legend display the model names in an order that is different than that -#' which is represented in the summary input object. -#' @param legendncol Number of columns for the legend. -#' @param legendcex Allows to adjust legend cex. Defaults to 1. -#' @param legendsp Space between legend labels -#' @param legendindex Allows to add legend for selected indices (plots) -#' @param pwidth Width of plot -#' @param pheight Height of plot -#' @param punits Units for PNG file -#' @param res Resolution for PNG file -#' @param ptsize Point size for PNG file -#' @param cex.main Character expansion for plot titles -#' @param plotdir Directory where PNG or PDF files will be written. By default -#' it will be the directory where the model was run. -#' @param filenameprefix Additional text to append to PNG or PDF file names. -#' It will be separated from default name by an underscore. -#' @param par list of graphics parameter values passed to par() function -#' @param verbose Report progress to R GUI? +#' @param ss3rep Stock Synthesis output as read by [r4ss::SS_output()] +#' @param subplots string of type of data to plot: +#' \itemize{ +#' \item `"cpue"` Index of abundance data +#' \item `"len"` Length-composition data +#' \item `"age"` Age-composition data +#' \item `"size"` Generalized size composition data +#' \item `"con"` Conditional age-at-length data. +#' } +#' @param seas string indicating how to treat data from multiple seasons: +#' \itemize{ +#' \item `"comb"` Combine seasonal data for each year and plot against Yr +#' \item `"sep"` Treat season separately, plotting against `Yr.S`. +#' \item `NULL` If NULL, it is assumed that there is only one season and +#' option `"comb"` is used. +#' } +#' @param indexselect Vector of fleet numbers for each model for which to +#' compare +#' @param miny minimum abs values of `ylim` #' @param boxcol color boxes -#' @param new Deprecated. New plot windows are created by default (TRUE), and the -#' option to disable this, via FALSE, is unused. -#' @param add supresses par() to create multiplot figs -#' @param xlim Optional, values for x-axis range of years to display on plot. -#' Default = "default" displays all years of available data. (currently not used) -#' @param ylim Optional, min and max values for the ylim to override the "default" value (-0.7, 0.5) -#' @param xylabs TRUE or FALSE, include x- and y-axis labels +#' @param ylim Optional, min and max values for the ylim to override the +#' `"default"` value (-0.7, 0.5) +#' @param xylabs [Logical][base::logical] flag. Enables x- and y-axis labels. +#' +#' @inheritParams SSplotGeneric +#' @inheritParams SSplotGenericLegend +#' @inheritParams SSplotGenericPar #' #' @author Henning Winker (JRC-EC) #' #' @keywords ssplot rmsetable #' -#' #' @importFrom grDevices grey #' @importFrom graphics boxplot #' @importFrom stats predict loess runif residuals diff --git a/R/SSplotModelcomp.R b/R/SSplotModelcomp.R index c442ec7..e994813 100644 --- a/R/SSplotModelcomp.R +++ b/R/SSplotModelcomp.R @@ -1,83 +1,62 @@ #' Compare Multiple SS Model Estimates #' -#' A function to plot SSB, B-ratio, F, Recruits, and/or Index of Abundance fits from multiple SS models. This function uses an object of multiple SS models summarized with r4ss:SSsummarize(). +#' A function to plot SSB, B-ratio, F, Recruits, and/or Index of Abundance fits +#' from multiple SS models. This function uses an object of multiple SS models +#' summarized with [r4ss::SSsummarize()]. #' -#' @param summaryoutput List created by r4ss::SSsummarize() -#' @param models Optional subset of the models described in -#' r4ss function summaryoutput(). Either "all" or a vector of numbers indicating -#' columns in summary tables. +#' @param summaryoutput List created by [r4ss::SSsummarize()] #' @param subplots option to "SSB","Bratio","Fvalue","Recruits","Index" -#' @param brp option to set reference point c("msy","btargs") -#' @param fmsy to specify Fvalue as F/Fmsy if so in starter file setting +#' \itemize{ +#' \item `"SSB"` Spawning Stock Biomass +#' \item `"Bratio"` Stock Biomass relative to biomass reference point +#' \item `"Fvalue"` Fishing Mortality +#' \item `"Recruits"` Age-0 Recruits +#' \item `"Index"` Index of abundance +#' \item `"RecDev"` Recruitment Deviations +#' } +#' @param brp option to set reference point `c("msy","btargs")` +#' @param fmsy to specify `Fvalue` as `F/Fmsy` if so in starter file setting #' @param ylabs yaxis labels for quants #' final year of values to show for each model. By default it is set to the -#' @param endyrvec ending year specified in each model. -#' @param xmin = NULL optional number first year shown in plot (if available) -#' @param indexselect = Vector of fleet numbers for each model for which to compare -#' @param indexfleets CHECK IF NEEDED or how to adjust indexfleets -#' @param indexUncertainty Show fixed uncertainty intervals on index (not estimated) -#' @param plot Deprecated. Plots (and subplots) are drawn to the active plot device -#' by default (TRUE), the option to disable this via FALSE, is unused here. -#' @param print Deprecated. Please use 'print_plot'. -#' @param print_plot print to PNG files? -#' @param pdf Deprecated. Please use 'use_png'. -#' @param use_pdf option for pdf plots (not tested for TRUE) -#' @param png Deprecated. Please use 'use_png'. -#' @param use_png png TODO TODO Defaults to print value -#' @param col Optional vector of colors to be used for lines. Input NULL -#' @param pch Optional vector of plot character values -#' @param lty Optional vector of line types -#' @param lwd Optional vector of line widths -#' @param tickEndYr TRUE/FALSE switch to turn on/off extra axis mark at final -#' year in timeseries plots. Default is FALSE -#' @param ylimAdj Multiplier for ylim parameter. Allows additional white space -#' @param xaxs Choice of xaxs parameter (see ?par for more info) -#' @param yaxs Choice of yaxs parameter (see ?par for more info) -#' @param type Type parameter passed to points (default 'o' overplots points on -#' top of lines) -#' @param legend Option to add a legend. TRUE by default. -#' @param legendlabels Optional vector of labels to include in legend. -#' @param legendloc Location of legend. Either a string like "topleft" or a vector -#' of two numeric values representing the fraction of the maximum in the x and y -#' dimensions, respectively. See ?legend for more info on the string options. -#' @param legendorder Optional vector of model numbers that can be used to have -#' the legend display the model names in an order that is different than that -#' which is represented in the summary input object. -#' @param legendncol Number of columns for the legend. -#' @param legendcex Allows to adjust legend cex -#' @param legendsp Space between legend labels -#' @param legendindex Allows to add lengend for selected indices (plots) -#' @param pwidth Width of plot -#' @param pheight Height of plot -#' @param punits Units for PNG file -#' @param res Resolution for PNG file -#' @param ptsize Point size for PNG file -#' @param cex.main Character expansion for plot titles -#' @param plotdir Directory where PNG or PDF files will be written. By default -#' it will be the directory where the model was run. -#' @param filenameprefix Additional text to append to PNG or PDF file names. -#' It will be separated from default name by an underscore. -#' @param par list of graphics parameter values passed to par() function -#' @param verbose Report progress to R GUI? +#' @param xmin NULL optional number first year shown in plot (if available) +#' @param indexselect Vector of fleet numbers for each model for which to +#' compare +#' @param indexfleets Fleet numbers for each model to compare +#' indices of abundance. Can take different forms: +#' \itemize{ +#' \item integer (default): create a single comparison plot for the chosen +#' index +#' \item NULL: create a separate plot for each index as long as the fleet +#' numbering is the same across all models. +#' \item vector of length equal to number of models: a single fleet number +#' for each model to be compared in a single plot +#' \item list: list of fleet numbers associated with indices within each +#' model to be compared, where the list elements are each a vector of the +#' same length but the names of the list elements don't matter and can be +#' absent. +#' } +#' @param indexUncertainty Show fixed uncertainty intervals on index +#' (not estimated) #' @param shadecol uncertainty shading of hcxval horizon #' @param shadealpha Transparency adjustment used to make default shadecol -#' @param new Deprecated. New plot windows are created by default (TRUE), and the -#' option to disable this, via FALSE, is unused. -#' @param add surpresses par() to create multiplot figs -#' @param mcmcVec NOT TESTED Vector of TRUE/FALSE values (or single value) indicating -#' @param indexQlabel TRUE/FALSE, if TRUE add catchability to legend in plot of index fits (currently not used) +#' @param indexQlabel [Logical][base::logical]. If TRUE add catchability to +#' legend in plot of index fits (currently not used) #' @param indexQdigits Number of significant digits for catchability in legend -#' @param png draws to png files. Deprecated. -#' @param use_png Draw plots in PNG format, defaults to 'print_plot' value -#' @param xlim Optional, values for x-axis range of years to display on plot. Default = "default" displays all years of available data. (currently not used) -#' @param xylabs TRUE or FALSE, include x- and y-axis labels -#' @param uncertainty TRUE/FALSE include uncertainty intervals around SSB or F estimated timeseries. Defaults to TRUE. +#' @param endyrvec Optional single year or vector of years representing the +#' final year of values to show for each model. By `"default"` it is set to the +#' ending year specified in each model. +#' #' @author Mostly adopted from r4ss::SSplotComparisons by Taylor et al #' @export #' #' @importFrom grDevices pdf #' @importFrom lifecycle deprecated #' +#' @inheritParams SSplotGeneric +#' @inheritParams SSplotGenericLegend +#' @inheritParams SSplotGenericPar +#' @inheritParams SSplotGenericUncertainty +#' #' @keywords ssplot hindcasting #' SSplotModelcomp <- function(summaryoutput = ss3diags::retroSimple, @@ -133,7 +112,8 @@ SSplotModelcomp <- function(summaryoutput = ss3diags::retroSimple, mcmcVec = FALSE, indexQlabel = TRUE, indexQdigits = 4, - indexfleets = 1) { # plot different fits to a single index of abundance + indexfleets = 1) { + # plot different fits to a single index of abundance # Parameter DEPRECATION checks if (lifecycle::is_present(print)) { diff --git a/R/SSplotRetro.R b/R/SSplotRetro.R index d83fa31..a53ef91 100644 --- a/R/SSplotRetro.R +++ b/R/SSplotRetro.R @@ -1,75 +1,39 @@ #' Retrospective-Forecast with One-Step Ahead Hindcasting #' -#' Plots retrospective pattern, including (optional) one-step ahead forecast and computes Mohn's Rho +#' Plots retrospective pattern, including (optional) one-step ahead forecast +#' and computes Mohn's Rho #' -#' @param summaryoutput List created by r4ss::SSsummarize() -#' @param models Optional subset of the models described in -#' r4ss function summaryoutput(). Either "all" or a vector of numbers indicating -#' columns in summary tables. +#' @param summaryoutput List created by [r4ss::SSsummarize()] #' @param endyrvec Optional single year or vector of years representing the #' final year of values to show for each model. By default it is set to the #' ending year specified in each model. -#' @param subplots Optional vector of subplots to be created, "SSB", "Bratio", "Fvalue", "Recruits", "Index" -#' @param plot Option to draw subplots and plot in the interface. Deprecated. Option to disable will be removed in future version. -#' @param print print to PNG files? Deprecated. Please use print_plot. -#' @param print_plot Option to print to PNG files -#' @param png Deprecated, please use 'use_png' -#' @param use_png Draw plots in PNG format -#' @param pdf PDF plots. Deprecated. Please use use_pdf. -#' @param use_pdf option for pdf plots (currently does not work when subplots specified) -#' @param xlim optional xlim, which overwrites xmin -#' @param xmin optional minimum year shown in plot (default first yr) -#' @param labels yaxis lable for biomass (bony fish and sharks) -#' @param ylim option to specify ylim range -#' @param forecast if true one-step ahead forecasts are shown in plot -#' @param forecastrho if true one-step ahead forecast rho value is denoted in plot -#' @param col Optional vector of colors to be used for lines. Input NULL -#' @param pch Optional vector of plot character values -#' @param lty Optional vector of line types -#' @param lwd Optional vector of line widths -#' @param tickEndYr TRUE/FALSE switch to turn on/off extra axis mark at final -#' year in timeseries plots. -#' @param ylimAdj Multiplier for ylim parameter. Allows additional white space -#' @param xaxs Choice of xaxs parameter (see ?par for more info) -#' @param yaxs Choice of yaxs parameter (see ?par for more info) -#' @param type Type parameter passed to points (default 'o' overplots points on -#' top of lines) -#' @param legend Add a legend? -#' @param legendlabels Optional vector of labels to include in legend. -#' @param legendloc Location of legend. Either a string like "topleft" or a vector -#' of two numeric values representing the fraction of the maximum in the x and y -#' dimensions, respectively. See ?legend for more info on the string options. -#' @param legendorder Optional vector of model numbers that can be used to have -#' the legend display the model names in an order that is different than that -#' which is represented in the summary input object. -#' @param legendncol Number of columns for the legend. -#' @param legendcex Allows to adjust legend cex -#' @param legendsp Space between legend labels -#' @param legendindex Allows to add lengend for selected indices (plots) -#' @param pwidth Width of plot -#' @param pheight Height of plot -#' @param punits Units for PNG file -#' @param res Resolution for PNG file -#' @param ptsize Point size for PNG file -#' @param cex.main Character expansion for plot titles -#' @param plotdir Directory where PNG or PDF files will be written. By default -#' it will be the directory where the model was run. -#' @param filenameprefix Additional text to append to PNG or PDF file names. -#' It will be separated from default name by an underscore. -#' @param par list of graphics parameter values passed to par() function -#' @param verbose Report progress to R GUI? +#' @param subplots Optional vector of subplots to be created: +#' \itemize{ +#' \item `"SSB"` Spawning Stock Biomass +#' \item `"F"` Fishing Mortality +#' } +#' @param xmin optional minimum year shown in plot (default first yr) +#' @param labels `yaxis` label for biomass (bony fish and sharks) +#' @param ylim option to specify `ylim` range +#' @param forecast [Logical][base::logical]. If TRUE, one-step ahead forecasts +#' are shown in plot +#' @param forecastrho [Logical][base::logical]. If TRUE, one-step ahead +#' forecast rho value is denoted in plot #' @param shadecol uncertainty shading of hcxval horizon #' @param shadecol1 uncertainty shading of early years not affected by hindcast -#' @param new Deprecated. New plot windows are created by default (TRUE), and the -#' option to disable this, via FALSE, is unused. -#' @param add surpresses par() to create multiplot figs -#' @param mcmcVec NOT TESTED Vector of TRUE/FALSE values (or single value) indicating mcmc values are used -#' @param indexQlabel TRUE/FALSE, if TRUE add catchability to legend in plot of index fits (currently not used) +#' @param shadealpha set the transparency level (alpha) of the area of +#' uncertainty. Defaults to 0.3 (currently not used) +#' @param indexQlabel [Logical][base::logical]. If TRUE, add catchability to +#' legend in plot of index fits (currently not used) #' @param indexQdigits Number of significant digits for catchability in legend -#' @param showrho TRUE/FALSE include Mohn's rho value? Defaults to TRUE -#' @param xylabs TRUE or FALSE, include x- and y-axis labels. Defaults to TRUE -#' @param uncertainty TRUE/FALSE include uncertainty intervals around SSB or F estimated timeseries. Defaults to TRUE. -#' @param shadealpha set the transparency level (alpha) of the area of uncertainty. Defalut to 0.3 (currently not used) +#' @param showrho [Logical][base::logical] flag to include Mohn's rho value. +#' Defaults to TRUE +#' +#' @inheritParams SSplotGeneric +#' @inheritParams SSplotGenericLegend +#' @inheritParams SSplotGenericPar +#' @inheritParams SSplotGenericUncertainty +#' #' #' @author Henning Winker (JRC-EC) and Laurance Kell (Sea++) #' @@ -129,7 +93,6 @@ SSplotRetro <- function(summaryoutput, new = TRUE, add = FALSE, mcmcVec = FALSE, - # documented params not in usage -ef shadecol1 = grey(0.5, 0.4), indexQlabel = TRUE, indexQdigits = 4, diff --git a/R/SSplotRunstest.R b/R/SSplotRunstest.R index 15a26c9..df1f275 100644 --- a/R/SSplotRunstest.R +++ b/R/SSplotRunstest.R @@ -1,13 +1,16 @@ #' Runs Test for Residuals #' -#' This function uses randtests::runs.test to do perform a runs test on residuals to determine if they are randomly distributed. It also calculates the 3 x sigma limits +#' This function uses randtests::runs.test to do perform a runs test on +#' residuals to determine if they are randomly distributed. It also calculates +#' the 3 x sigma limits #' -#' runs test is conducted with library(randtests) +#' runs test is conducted with `library(randtests)` #' #' @param x residuals from CPUE fits -#' @param type only c("resid","observations") -#' @param mixing c("less","greater","two.sided"). Default less is checking for positive autocorrelation only +#' @param type only `c("resid","observations")` +#' @param mixing `c("less","greater","two.sided")`. Default less is checking +#' for positive autocorrelation only #' #' @return runs p value and 3 x sigma limits #' @@ -53,60 +56,50 @@ ssruns_sig3 <- function(x, type = NULL, mixing = "less") { #' Residual Diagnostics #' -#' Function for residual diagnostics. Plots residuals and 3x sigma limits for indices or mean age or length and outputs a runs test table. Note, if you do not want to plot the residuals, use function ss3diags::SSrunstest. +#' Function for residual diagnostics. Plots residuals and 3x sigma limits for +#' indices or mean age or length and outputs a runs test table. Note, if you do +#' not want to plot the residuals, use [ss3diags::SSrunstest()]. #' -#' -#' @param ss3rep Stock Synthesis output as read by r4SS function SS_output -#' @param mixing c("less","greater","two.sided"). Default less is checking for positive autocorrelation only -#' @param subplots optional 'cpue' for index data, 'len' for length composition data, 'size' for -#' generalized size composition data, 'age' for age composition data, -#' or 'con' for conditional age at length data -#' @param indexselect Vector of fleet numbers for each model for which to compare -#' @param miny minimum abs values of ylim -#' @param plot Deprecated. Plots (and subplots) are drawn to the active plot device -#' by default (TRUE), the option to disable this via FALSE, is unused here. -#' @param print Deprecated. Please use 'print_plot'. -#' @param print_plot Option to print to PNG files -#' @param png Deprecated, please use 'use_png'. -#' @param use_png Draw plots in PNG format -#' @param pdf PDF plots. Deprecated. Please use use_pdf. -#' @param use_pdf option for pdf plots -#' @param miny the absolute value of the min and max value for ylim, default is 1 -#' @param pch Optional vector of plot character values -#' @param lty Optional vector of line types -#' @param lwd Optional vector of line widths -#' @param tickEndYr TRUE/FALSE switch to turn on/off extra axis mark at final -#' year in timeseries plots. -#' @param ylimAdj Multiplier for ylim parameter. Allows additional white space -#' @param xaxs Choice of xaxs parameter (see ?par for more info) -#' @param yaxs Choice of yaxs parameter (see ?par for more info) -#' @param type Type parameter passed to points (default 'o' overplots points on -#' top of lines) -#' @param legend Option to add a legend. TRUE by default. -#' @param legendloc Location of legend. Either a string like "topleft" or a vector +#' @param ss3rep Stock Synthesis output as read by [r4ss::SS_output()] +#' @param mixing `c("less","greater","two.sided")`. Default less is checking +#' for positive autocorrelation only +#' @param subplots optional flag for: +#' \itemize{ +#' \item `"cpue"` Index of abundance data +#' \item `"len"` Length composition data +#' \item `"size"` Generalized size composition data +#' \item `"age"` Age composition data +#' \item `"con"` Conditional age-at-length data +#' } +#' @param indexselect Vector of fleet numbers for each model for which to +#' compare +#' @param miny the absolute value of the min and max value for `ylim`. +#' Default is 1 +#' @param legend Flag to enable legend to plot. TRUE by default. +#' @param legendloc Location of legend. Either a string like "topleft" or a +#' vector of two numeric values representing the fraction of the maximum in +#' the x and y dimensions, respectively. See `help("legend")` for more info +#' on the string options. #' @param legendcex Allows to adjust legend cex -#' @param pwidth Width of plot -#' @param pheight Height of plot -#' @param punits Units for PNG file -#' @param res Resolution for PNG file -#' @param ptsize Point size for PNG file -#' @param cex.main Character expansion for plot titles -#' @param plotdir Directory where PNG or PDF files will be written. By default -#' it will be the directory where the model was run. -#' @param filenameprefix Additional text to append to PNG or PDF file names. -#' It will be separated from default name by an underscore. -#' @param par list of graphics parameter values passed to par() function -#' @param verbose TRUE or FALSE, should the progress be reported to R GUI? -#' @param new Create new empty plot window (TRUE or FALSE) -#' @param add suppresses par() to create multiplot figs -#' @param xlim Optional, values for x-axis range of years to display on plot. Default = "default" displays all years of available data. -#' @param ylim Optional, values for y-axis range to display on plot. Default = "default" will range from -1 to 1. -#' @param xylabs TRUE or FALSE, include x- and y-axis labels -#' @return a dataframe with runs test p-value, if the test has passed or failed, 3x sigma high and low limits, and the type of data used. Rows are for each fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and failed if p-value < 0.5 (residuals are not random) +#' @param ylim Optional, values for y-axis range to display on plot. +#' The default: `"default"`, will range from -1 to 1. +#' +#' @inheritParams SSplotGeneric +#' @inheritParams SSplotGenericPar +#' +#' @return a dataframe with runs test p-value, if the test has passed or failed, +#' 3x sigma high and low limits, and the type of data used. Rows are for each +#' fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and +#' failed if p-value < 0.5 (residuals are not random) +#' #' @author Henning Winker (JRC-EC) and Laurance Kell (Sea++) +#' #' @keywords ssplot runsTest +#' #' @importFrom lifecycle deprecated +#' #' @export +#' SSplotRunstest <- function(ss3rep = ss3diags::simple, mixing = "less", @@ -120,6 +113,7 @@ SSplotRunstest <- function(ss3rep = ss3diags::simple, use_pdf = FALSE, indexselect = NULL, miny = 1, + col = NULL, pch = 21, lty = 1, lwd = 2, @@ -398,15 +392,32 @@ SSplotRunstest <- function(ss3rep = ss3diags::simple, #----------------------------------------------------------------------------------------- #' Residual Diagnostics Plot #' -#' Function for residual diagnostics. Outputs a runs test table that gives runs test p-values, if the runs test passed (p-value > 0.05, residuals are random) or failed (p-value < 0.05, residuals are not random), the 3x sigma limits for indices or mean age or length and the type of input data (cpue, length comp, age comp, size comp, or conditional age-at-length). -#' +#' Function for residual diagnostics. Outputs a runs test table that gives runs +#' test p-values, if the runs test passed (p-value > 0.05, residuals are random) +#' or failed (p-value < 0.05, residuals are not random), the 3x sigma limits for +#' indices or mean age or length and the type of input data (cpue, length comp, +#' age comp, size comp, or conditional age-at-length). #' -#' @param ss3rep Stock Synthesis output as read by r4SS function SS_output -#' @param mixing c("less","greater","two.sided"). Default less is checking for positive autocorrelation only -#' @param quants optional use of c("cpue","len","age","con"), default uses CPUE. -#' @param indexselect Vector of fleet numbers for each model for which to compare +#' @param ss3rep Stock Synthesis output as read by [r4ss::SS_output()] +#' @param mixing `c("less","greater","two.sided")`. Default less is checking for +#' positive autocorrelation only +#' @param quants optional use of `c("cpue","len","age","con")`, default uses +#' `"cpue"`. +#' \itemize{ +#' \item `"cpue"` Index of abundance data +#' \item `"len"` Length composition data +#' \item `"age"` Age composition data +#' \item `"con"` Conditional age-at-length data +#' } +#' @param indexselect Vector of fleet numbers for each model for which to +#' compare #' @param verbose Report progress to R GUI? -#' @return a dataframe with runs test p-value, if the test has passed or failed, 3x sigma high and low limits, and the type of data used. Rows are for each fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and failed if p-value < 0.5 (residuals are not random) +#' +#' @return a dataframe with runs test p-value, if the test has passed or failed, +#' 3x sigma high and low limits, and the type of data used. Rows are for each +#' fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and +#' failed if p-value < 0.5 (residuals are not random) +#' #' @author Henning Winker (JRC-EC) and Laurance Kell (Sea++) #' #' @keywords diags runsTest diff --git a/man/SSplotEnsemble.Rd b/man/SSplotEnsemble.Rd index 022a42b..c463d7d 100644 --- a/man/SSplotEnsemble.Rd +++ b/man/SSplotEnsemble.Rd @@ -57,33 +57,44 @@ SSplotEnsemble( ) } \arguments{ -\item{kb}{SSdeltaMVLN $kb type output} - -\item{subplots}{option to "Bratio","Fvalue","SSB", "F", "Recr","Catch"} +\item{kb}{\code{kb} type output created by \code{SSdeltaMVLN()}} + +\item{subplots}{vector to create subplots with these options: +\itemize{ +\item \code{"stock"} Fish Population +\item \code{"harvest"} Harvest Rate +\item \code{"SSB"} Spawning Stock Biomass +\item \code{"F"} Fishing Mortality +\item \code{"Recr"} Recruitment +\item \code{"Catch"} Total Catch +}} \item{models}{option to manually subset the models in \code{kb[["run"]]}} -\item{quantiles}{quantiles for uncertainty in plots. Input as a list, default is the 95TH percentile: list(c(0.025, 0.975))} +\item{quantiles}{quantiles for uncertainty in plots. Input as a list, +default is the 95TH percentile: \code{list(c(0.025, 0.975))}} -\item{ylabs}{yaxis labels for quants -final year of values to show for each model. By default it is set to the} +\item{ylabs}{y-axis labels for quants} -\item{endyrvec}{ending year specified in each model.} +\item{endyrvec}{Optional single year or vector of years representing the +final year of values to show for each model. By \code{"default"} it is set to the +ending year specified in each model.} -\item{plot}{Deprecated. Plots (and subplots) are drawn to the active plot device -by default (TRUE), and the option to disable this, via FALSE, is unused.} +\item{plot}{DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +plot device. The option to explicitly disable this option (FALSE), is not +implemented. This option flag will be defunct in a future version} -\item{print}{Deprecated. Please use 'print_plot'.} +\item{print}{DEPRECATED, please use \code{print_plot}.} -\item{print_plot}{print to PNG files?} +\item{print_plot}{Flag to enable plot graphic device to print to PNG or PNG files.} -\item{png}{Deprecated. Please use 'use_png'.} +\item{png}{DEPRECATED. Please use \code{use_png}.} -\item{use_png}{Draw plots in PNG format} +\item{use_png}{Enables plots to be generated to PNG files. Defaults to print value} -\item{pdf}{Deprecated. Please use 'use_pdf'.} +\item{pdf}{DEPRECATED. Please use \code{use_pdf}.} -\item{use_pdf}{option for pdf plots (not tested for TRUE)} +\item{use_pdf}{Enables plots to be generated to pdf file.} \item{col}{Optional vector of colors to be used for lines. Input NULL} @@ -93,34 +104,39 @@ by default (TRUE), and the option to disable this, via FALSE, is unused.} \item{lwd}{Optional vector of line widths} -\item{tickEndYr}{TRUE/FALSE switch to turn on/off extra axis mark at final -year in timeseries plots.} +\item{tickEndYr}{\link[base:logical]{Logical} flag: set TRUE or FALSE to switch to turn +on/off extra axis mark at final year in timeseries plots.} -\item{xlim}{Optional, years to use for x-axis. Default NULL uses all years available.} +\item{xlim}{Optional, years to use for x-axis. Default value NULL (or "default"), +uses all years available.} -\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space} +\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space.} -\item{xaxs}{Choice of xaxs parameter (see ?par for more info)} +\item{xaxs}{Choice of xaxs parameter See \code{?par} for more info.} -\item{yaxs}{Choice of yaxs parameter (see ?par for more info)} +\item{yaxs}{Choice of yaxs parameter. See \code{?par} for more info.} -\item{xylabs}{TRUE or FALSE, include x- and y-axis labels. Defaults to TRUE} +\item{xylabs}{\link[base:logical]{Logical} flag: set TRUE or FALSE to include x- and +y-axis labels to the plot. Defaults to TRUE} -\item{type}{Type parameter passed to points (default 'o' overplots points on -top of lines)} +\item{type}{The type of plot to be drawn. For more details, see \code{\link[base:plot]{plot}}.} -\item{uncertainty}{TRUE/FALSE include uncertainty intervals around SSB or F estimated time series. Defaults to TRUE.} +\item{uncertainty}{Logical flag to enable plots with uncertainty intervals. Either a single +TRUE/FALSE value, or a vector of TRUE/FALSE values around SSB or F +estimated timeseries, or a set of integers corresponding to +the choice of models.} -\item{legend}{Add a legend to plot. TRUE by default.} +\item{legend}{Flag to enable legend to plot. TRUE by default.} \item{legendlabels}{Optional vector of labels to include in legend.} -\item{legendloc}{Location of legend. Either a string like "topleft" or a vector -of two numeric values representing the fraction of the maximum in the x and y -dimensions, respectively. See ?legend for more info on the string options.} +\item{legendloc}{Location of legend. Either a string like "topleft" or a vector of two +numeric values representing the fraction of the maximum in the x and y +dimensions, respectively. See \code{help("legend")} for more info on the +string options.} -\item{legendorder}{Optional vector of model numbers that can be used to have -the legend display the model names in an order that is different than that +\item{legendorder}{Optional vector of model numbers that can be used to have the legend +display the model names in an order that is different than that which is represented in the summary input object.} \item{legendncol}{Number of columns for the legend.} @@ -129,45 +145,61 @@ which is represented in the summary input object.} \item{legendsp}{Space between legend labels} -\item{pwidth}{Width of plot} +\item{pwidth}{Default width of plot printed to plot in units of \code{punits}} -\item{pheight}{Height of plot} +\item{pheight}{Height of plot printed to plot in units of \code{punits }} -\item{punits}{Units for PNG file} +\item{punits}{Measurement units for \code{pwidth} and \code{pheight}. Default is \code{"in"}. +\itemize{ +\item \code{"px"} (pixels) +\item \code{"in"} (inches) +\item \code{"cm"} (centimeters) +\item \code{"mm"} (millimeters) +}} -\item{res}{Resolution for PNG file} +\item{res}{Resolution for plots printed to files.} -\item{ptsize}{Point size for PNG file} +\item{ptsize}{Point size for plotted text in plots printed in files. See \code{help("png")} +for more details} -\item{cex.main}{Character expansion for plot titles} +\item{cex.main}{Character expansion for plot titles.} -\item{plotdir}{Directory where PNG or PDF files will be written. By default +\item{plotdir}{Directory where output plot file will be written. By default, it will be the directory where the model was run.} -\item{filenameprefix}{Additional text to append to PNG or PDF file names. +\item{filenameprefix}{Additional text to append to output plot file name. It will be separated from default name by an underscore.} -\item{par}{list of graphics parameter values passed to par() function} +\item{par}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of +the plot,which is passed to \code{par()}. Entering \code{NULL} passes plot's default +\code{par()} values (which depends on whether the main title is included or not)} -\item{verbose}{Report progress to R GUI?} +\item{verbose}{Flag to print additional diagnostic messages to R console} -\item{shadealpha}{Transparency adjustment used to make uncertainty regions, default is 0.3} +\item{shadealpha}{Transparency adjustment used to make uncertainty regions, +default is 0.3} \item{new}{Deprecated. New plot windows are created by default (TRUE), and the option to disable this, via FALSE, is unused.} -\item{add}{suppresses par() to create multiplot figs} +\item{add}{suppresses \code{par()} to create multiplot figs} -\item{mcmcVec}{mcmc vector TODO TODO. Default is FALSE} +\item{mcmcVec}{Logical vector of TRUE/FALSE values (or single value) indicating +whether input values are from MCMC or to use normal distribution around +MLE.} -\item{indexQlabel}{TRUE/FALSE include labels for indices. Default is TRUE (currently not used)} +\item{indexQlabel}{TRUE/FALSE include labels for indices. Default is TRUE +(currently not used)} -\item{indexQdigits}{Number of significant digits for catchability in legend. Default is 4} +\item{indexQdigits}{Number of significant digits for catchability in legend. +Default is 4} \item{legendindex}{Allows to add legend for selected indices (plots)} } \description{ -Plots model ensembles and forecasts with uncertaity represented by MVLN or MCMC posteriors +Plots model ensembles and forecasts with uncertainty represented by MVLN or +MCMC posteriors } \examples{ \dontrun{ diff --git a/man/SSplotGeneric.Rd b/man/SSplotGeneric.Rd new file mode 100644 index 0000000..81526ef --- /dev/null +++ b/man/SSplotGeneric.Rd @@ -0,0 +1,87 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/SSplotGeneric.R +\name{SSplotGeneric} +\alias{SSplotGeneric} +\title{Generic SSplot function} +\usage{ +SSplotGeneric( + pwidth = 6.5, + pheight = 5, + punits = "in", + res = 300, + ptsize = 10, + cex.main = 1, + plotdir = NULL, + filenameprefix = "", + par = list(mar = c(5, 4, 1, 1) + 0.1), + verbose = TRUE, + plot = TRUE, + print = deprecated(), + print_plot = FALSE, + png = deprecated(), + use_png = print_plot, + pdf = deprecated(), + use_pdf = FALSE, + new = TRUE, + add = FALSE +) +} +\arguments{ +\item{pwidth}{Default width of plot printed to plot in units of \code{punits}} + +\item{pheight}{Height of plot printed to plot in units of \code{punits }} + +\item{punits}{Measurement units for \code{pwidth} and \code{pheight}. Default is \code{"in"}. +\itemize{ +\item \code{"px"} (pixels) +\item \code{"in"} (inches) +\item \code{"cm"} (centimeters) +\item \code{"mm"} (millimeters) +}} + +\item{res}{Resolution for plots printed to files.} + +\item{ptsize}{Point size for plotted text in plots printed in files. See \code{help("png")} +for more details} + +\item{cex.main}{Character expansion for plot titles.} + +\item{plotdir}{Directory where output plot file will be written. By default, +it will be the directory where the model was run.} + +\item{filenameprefix}{Additional text to append to output plot file name. +It will be separated from default name by an underscore.} + +\item{par}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of +the plot,which is passed to \code{par()}. Entering \code{NULL} passes plot's default +\code{par()} values (which depends on whether the main title is included or not)} + +\item{verbose}{Flag to print additional diagnostic messages to R console} + +\item{plot}{DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +plot device. The option to explicitly disable this option (FALSE), is not +implemented. This option flag will be defunct in a future version} + +\item{print}{DEPRECATED, please use \code{print_plot}.} + +\item{print_plot}{Flag to enable plot graphic device to print to PNG or PNG files.} + +\item{png}{DEPRECATED. Please use \code{use_png}.} + +\item{use_png}{Enables plots to be generated to PNG files. Defaults to print value} + +\item{pdf}{DEPRECATED. Please use \code{use_pdf}.} + +\item{use_pdf}{Enables plots to be generated to pdf file.} + +\item{new}{Deprecated. New plot windows are created by default (TRUE), and the +option to disable this, via FALSE, is unused.} + +\item{add}{suppresses \code{par()} to create multiplot figs} +} +\description{ +Generalized version of ss3diags SSplots functions. Not intended for +production +} +\keyword{internal} diff --git a/man/SSplotGenericLegend.Rd b/man/SSplotGenericLegend.Rd new file mode 100644 index 0000000..0ca1b82 --- /dev/null +++ b/man/SSplotGenericLegend.Rd @@ -0,0 +1,44 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/SSplotGeneric.R +\name{SSplotGenericLegend} +\alias{SSplotGenericLegend} +\title{Legend parameters for Generic SSplot} +\usage{ +SSplotGenericLegend( + legend = TRUE, + legendlabels = "default", + legendloc = "topright", + legendorder = "default", + legendncol = 1, + legendcex = 1, + legendsp = 0.9, + legendindex = NULL +) +} +\arguments{ +\item{legend}{Flag to enable legend to plot. TRUE by default.} + +\item{legendlabels}{Optional vector of labels to include in legend.} + +\item{legendloc}{Location of legend. Either a string like "topleft" or a vector of two +numeric values representing the fraction of the maximum in the x and y +dimensions, respectively. See \code{help("legend")} for more info on the +string options.} + +\item{legendorder}{Optional vector of model numbers that can be used to have the legend +display the model names in an order that is different than that +which is represented in the summary input object.} + +\item{legendncol}{Number of columns for the legend.} + +\item{legendcex}{Allows to adjust legend cex} + +\item{legendsp}{Space between legend labels} + +\item{legendindex}{Allows to add legend for selected indices (plots)} +} +\description{ +Generalized version of ss3diags SSplots functions specfic to plot legend +parameters. Not intended for production. +} +\keyword{internal} diff --git a/man/SSplotGenericPar.Rd b/man/SSplotGenericPar.Rd new file mode 100644 index 0000000..21cfdd6 --- /dev/null +++ b/man/SSplotGenericPar.Rd @@ -0,0 +1,51 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/SSplotGeneric.R +\name{SSplotGenericPar} +\alias{SSplotGenericPar} +\title{Graphical Parameters for Stock Synthesis Generic plots.} +\usage{ +SSplotGenericPar( + col = NULL, + pch = NULL, + lty = 1, + lwd = 2, + tickEndYr = FALSE, + xlim = NULL, + ylimAdj = 1.05, + xaxs = "i", + yaxs = "i", + xylabs = TRUE, + type = "l" +) +} +\arguments{ +\item{col}{Optional vector of colors to be used for lines. Input NULL} + +\item{pch}{Optional vector of plot character values} + +\item{lty}{Optional vector of line types} + +\item{lwd}{Optional vector of line widths} + +\item{tickEndYr}{\link[base:logical]{Logical} flag: set TRUE or FALSE to switch to turn +on/off extra axis mark at final year in timeseries plots.} + +\item{xlim}{Optional, years to use for x-axis. Default value NULL (or "default"), +uses all years available.} + +\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space.} + +\item{xaxs}{Choice of xaxs parameter See \code{?par} for more info.} + +\item{yaxs}{Choice of yaxs parameter. See \code{?par} for more info.} + +\item{xylabs}{\link[base:logical]{Logical} flag: set TRUE or FALSE to include x- and +y-axis labels to the plot. Defaults to TRUE} + +\item{type}{The type of plot to be drawn. For more details, see \code{\link[base:plot]{plot}}.} +} +\description{ +Generalized version of ss3diags SSplots functions to specify to \code{par()} or +to pass plot attributes. Not intended for production. +} +\keyword{internal} diff --git a/man/SSplotGenericUncertainty.Rd b/man/SSplotGenericUncertainty.Rd new file mode 100644 index 0000000..46d2142 --- /dev/null +++ b/man/SSplotGenericUncertainty.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/SSplotGeneric.R +\name{SSplotGenericUncertainty} +\alias{SSplotGenericUncertainty} +\title{Uncertainty parameters for Stock Synthesis Generic plots.} +\usage{ +SSplotGenericUncertainty(uncertainty = TRUE, mcmcVec = FALSE, models = "all") +} +\arguments{ +\item{uncertainty}{Logical flag to enable plots with uncertainty intervals. Either a single +TRUE/FALSE value, or a vector of TRUE/FALSE values around SSB or F +estimated timeseries, or a set of integers corresponding to +the choice of models.} + +\item{mcmcVec}{Logical vector of TRUE/FALSE values (or single value) indicating +whether input values are from MCMC or to use normal distribution around +MLE.} + +\item{models}{Optional subset of the models of \code{summaryoutput} (or a similar +field with a different name): a list created by the function +\link[r4ss:SSsummarize]{r4ss::SSsummarize}. Either \code{"all"} or a vector of numbers indicating +columns in summary tables.} +} +\description{ +Generalized version of ss3diags SSplots functions to specify uncertainty. +Not intended for production. +} +\keyword{internal} diff --git a/man/SSplotHCxval.Rd b/man/SSplotHCxval.Rd index c4be77b..e16e504 100644 --- a/man/SSplotHCxval.Rd +++ b/man/SSplotHCxval.Rd @@ -66,26 +66,34 @@ SSplotHCxval( ) } \arguments{ -\item{retroSummary}{List created by r4ss::SSsummarize() or ss3diags::SSretroComps()} +\item{retroSummary}{List created by \code{\link[r4ss:SSsummarize]{r4ss::SSsummarize()}} or +\code{\link[=SSretroComps]{SSretroComps()}}} -\item{subplots}{optional use of c("cpue","len","age"), yet to be tested for age.} +\item{subplots}{optional use of the following: +\itemize{ +\item \code{"cpue"} Index of abundance data +\item \code{"len"} Length-composition data +\item \code{"age"} Age-composition data +}} -\item{Season}{option to specify Season as an integer of value 1-4 - Default uses first available, i.e. usual Seas = 1} +\item{Season}{option to specify Season as an integer of value 1-4. Default +uses first available, i.e. usual Seas = 1} -\item{print}{Deprecated. Please use 'print_plot'.} +\item{print}{DEPRECATED, please use \code{print_plot}.} -\item{print_plot}{Option to print to PNG files} +\item{print_plot}{Flag to enable plot graphic device to print to PNG or PNG files.} -\item{png}{Deprecated, please use 'use_png'.} +\item{png}{DEPRECATED. Please use \code{use_png}.} -\item{use_png}{Draw plots in PNG format} +\item{use_png}{Enables plots to be generated to PNG files. Defaults to print value} -\item{pdf}{PDF plots. Deprecated. Please use use_pdf.} +\item{pdf}{DEPRECATED. Please use \code{use_pdf}.} -\item{use_pdf}{option for pdf plots} +\item{use_pdf}{Enables plots to be generated to pdf file.} -\item{models}{Optional subset of the models described in -r4ss function summaryoutput(). Either "all" or a vector of numbers indicating +\item{models}{Optional subset of the models of \code{summaryoutput} (or a similar +field with a different name): a list created by the function +\link[r4ss:SSsummarize]{r4ss::SSsummarize}. Either \code{"all"} or a vector of numbers indicating columns in summary tables.} \item{endyrvec}{Optional single year or vector of years representing the @@ -94,13 +102,16 @@ ending year specified in each model.} \item{xmin}{optional number first year shown in plot (if available)} -\item{indexselect}{= Vector of fleet numbers for each model for which to compare} +\item{indexselect}{Vector of fleet numbers for each model for which to +compare} -\item{MAE.base.adj}{minimum MASE denominator (naive predictions) for MASE.adj (default = 0.1)} +\item{MAE.base.adj}{minimum \code{MASE} denominator (naive predictions) for +\code{MASE.adj} (default = 0.1)} -\item{show.mase.adj}{if TRUE it show mase.adj in () in plot} +\item{show.mase.adj}{if TRUE, it show \code{mase.adj} in plot} -\item{indexUncertainty}{Show fixed uncertainty intervals on index (not estimated)} +\item{indexUncertainty}{Show fixed uncertainty intervals on index +(not estimated)} \item{col}{Optional vector of colors to be used for lines. Input NULL} @@ -110,36 +121,41 @@ ending year specified in each model.} \item{lwd}{Optional vector of line widths} -\item{tickEndYr}{TRUE/FALSE switch to turn on/off extra axis mark at final -year in timeseries plots.} +\item{tickEndYr}{\link[base:logical]{Logical} flag: set TRUE or FALSE to switch to turn +on/off extra axis mark at final year in timeseries plots.} -\item{xlim}{Optional, values for x-axis range of years to display on plot. Default = "default" displays all years of available data. (currently not in use)} +\item{xlim}{Optional, years to use for x-axis. Default value NULL (or "default"), +uses all years available.} -\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space} +\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space.} -\item{ylim}{will over-write ylimAdj if specified} +\item{ylim}{will over-write \code{ylimAdj} if specified} -\item{xaxs}{Choice of xaxs parameter (see ?par for more info)} +\item{xaxs}{Choice of xaxs parameter See \code{?par} for more info.} -\item{yaxs}{Choice of yaxs parameter (see ?par for more info)} +\item{yaxs}{Choice of yaxs parameter. See \code{?par} for more info.} -\item{xylabs}{TRUE or FALSE, include x- and y-axis labels} +\item{xylabs}{\link[base:logical]{Logical} flag: set TRUE or FALSE to include x- and +y-axis labels to the plot. Defaults to TRUE} -\item{type}{Type parameter passed to points (default 'o' overplots points on -top of lines)} +\item{type}{The type of plot to be drawn. For more details, see \code{\link[base:plot]{plot}}.} -\item{uncertainty}{TRUE/FALSE include uncertainty intervals around SSB or F estimated timeseries. Defaults to TRUE.} +\item{uncertainty}{Logical flag to enable plots with uncertainty intervals. Either a single +TRUE/FALSE value, or a vector of TRUE/FALSE values around SSB or F +estimated timeseries, or a set of integers corresponding to +the choice of models.} -\item{legend}{Option to add a legend. TRUE by default.} +\item{legend}{Flag to enable legend to plot. TRUE by default.} \item{legendlabels}{Optional vector of labels to include in legend.} -\item{legendloc}{Location of legend. Either a string like "topleft" or a vector -of two numeric values representing the fraction of the maximum in the x and y -dimensions, respectively. See ?legend for more info on the string options.} +\item{legendloc}{Location of legend. Either a string like "topleft" or a vector of two +numeric values representing the fraction of the maximum in the x and y +dimensions, respectively. See \code{help("legend")} for more info on the +string options.} -\item{legendorder}{Optional vector of model numbers that can be used to have -the legend display the model names in an order that is different than that +\item{legendorder}{Optional vector of model numbers that can be used to have the legend +display the model names in an order that is different than that which is represented in the summary input object.} \item{legendncol}{Number of columns for the legend.} @@ -150,56 +166,89 @@ which is represented in the summary input object.} \item{legendindex}{Allows to add legend for selected indices (plots)} -\item{pwidth}{Width of plot} +\item{pwidth}{Default width of plot printed to plot in units of \code{punits}} -\item{pheight}{Height of plot} +\item{pheight}{Height of plot printed to plot in units of \code{punits }} -\item{punits}{Units for PNG file} +\item{punits}{Measurement units for \code{pwidth} and \code{pheight}. Default is \code{"in"}. +\itemize{ +\item \code{"px"} (pixels) +\item \code{"in"} (inches) +\item \code{"cm"} (centimeters) +\item \code{"mm"} (millimeters) +}} -\item{res}{Resolution for PNG file} +\item{res}{Resolution for plots printed to files.} -\item{ptsize}{Point size for PNG file} +\item{ptsize}{Point size for plotted text in plots printed in files. See \code{help("png")} +for more details} -\item{cex.main}{Character expansion for plot titles} +\item{cex.main}{Character expansion for plot titles.} -\item{plotdir}{Directory where PNG or PDF files will be written. By default +\item{plotdir}{Directory where output plot file will be written. By default, it will be the directory where the model was run.} -\item{filenameprefix}{Additional text to append to PNG or PDF file names. +\item{filenameprefix}{Additional text to append to output plot file name. It will be separated from default name by an underscore.} -\item{par}{list of graphics parameter values passed to par() function} +\item{par}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of +the plot,which is passed to \code{par()}. Entering \code{NULL} passes plot's default +\code{par()} values (which depends on whether the main title is included or not)} -\item{verbose}{Report progress to R GUI?} +\item{verbose}{Flag to print additional diagnostic messages to R console} \item{shadecol}{uncertainty shading of hcxval horizon} -\item{shadecol2}{color for uncertainty in early years not affected by hindcast} +\item{shadecol2}{color for uncertainty in early years not affected by +hindcast} -\item{shadealpha}{Transparancy adjustment used to make default shadecol. (currently not used)} +\item{shadealpha}{Transparency adjustment used to make default \code{shadecol}. +(currently not used)} -\item{new}{Create new empty plot window} +\item{new}{Deprecated. New plot windows are created by default (TRUE), and the +option to disable this, via FALSE, is unused.} -\item{add}{suppresses par() to create multiplot figs} +\item{add}{suppresses \code{par()} to create multiplot figs} -\item{mcmcVec}{NOT TESTED Vector of TRUE/FALSE values (or single value) indicating} +\item{mcmcVec}{Logical vector of TRUE/FALSE values (or single value) indicating +whether input values are from MCMC or to use normal distribution around +MLE.} -\item{indexQlabel}{Add catchability to legend in plot of index fits (TRUE/FALSE)?} +\item{indexQlabel}{\link[base:logical]{Logical} flag to add catchability to +legend in plot of index fits.} \item{indexQdigits}{Number of significant digits for catchability in legend} -\item{indexfleets}{CHECK IF NEEDED or how to adjust indexfleets} - -\item{plot}{Deprecated. Plots (and subplots) are drawn to the active plot device -by default (TRUE), and the option to disable this, via FALSE, is unused.} - -\item{shadecol1}{uncertainty shading of early years not affected by hindcast (currently not used)} +\item{indexfleets}{Fleet numbers for each model to compare +indices of abundance. Can take different forms: +\itemize{ +\item integer: (default) create a single comparison plot for the chosen +index +\item NULL: create a separate plot for each index as long as the fleet +numbering is the same across all models. +\item vector of length equal to number of models: a single fleet number +for each model to be compared in a single plot +\item list: list of fleet numbers associated with indices within each +model to be compared, where the list elements are each a vector of the +same length but the names of the list elements don't matter and can be +absent. +}} + +\item{plot}{DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +plot device. The option to explicitly disable this option (FALSE), is not +implemented. This option flag will be defunct in a future version} + +\item{shadecol1}{uncertainty shading of early years not affected by +hindcast (currently not used)} } \description{ -Plots one-step ahead hindcasting cross-validations and computes MASE from prediction residuals. -MASE is calculated as the average ratio of mean absolute error (MAE) of prediction residuals (MAE.PR) and naive predictions (MAE.base) -MASE.adj sets the MAE.base to a minimum MAE.base.adj (default=0.1) -MASE.adj allow passing (MASE<1) if MAE.PE < 0.1 and thus accurate if obs show very little annual variation +Plots one-step ahead hindcasting cross-validations and computes MASE from +prediction residuals.\code{MASE} is calculated as the average ratio of mean +absolute error (\code{MAE}) of prediction residuals (\code{MAE.PR}) and naive +predictions (\code{MAE.base}). \code{MASE.adj} sets the \code{MAE.base} to a minimum +\code{MAE.base.adj} (\code{default=0.1}). \code{MASE.adj} allow passing (\code{MASE<1}) if +\code{MAE.PE < 0.1} and thus accurate if obs show very little annual variation } \author{ Henning Winker (JRC-EC) and Laurence Kell (Sea++) diff --git a/man/SSplotJABBAres.Rd b/man/SSplotJABBAres.Rd index 8386c84..9378252 100644 --- a/man/SSplotJABBAres.Rd +++ b/man/SSplotJABBAres.Rd @@ -53,33 +53,45 @@ SSplotJABBAres( ) } \arguments{ -\item{ss3rep}{Stock Synthesis output as read by r4SS function SS_output} +\item{ss3rep}{Stock Synthesis output as read by \code{\link[r4ss:SS_output]{r4ss::SS_output()}}} -\item{subplots}{string of type of data to plot, 'cpue' for index of abundance data, 'len' or 'age' for length- or age-composition, 'size' for generalized size composition, or 'con' for conditional age-at-length data.} +\item{subplots}{string of type of data to plot: +\itemize{ +\item \code{"cpue"} Index of abundance data +\item \code{"len"} Length-composition data +\item \code{"age"} Age-composition data +\item \code{"size"} Generalized size composition data +\item \code{"con"} Conditional age-at-length data. +}} -\item{seas}{string indicating how to treat data from multiple seasons -'comb' - combine seasonal data for each year and plot against Yr -'sep' - treat season separately, plotting against Yr.S. -If is.null(seas), it is assumed that there is only one season and option 'comb' is used.} +\item{seas}{string indicating how to treat data from multiple seasons: +\itemize{ +\item \code{"comb"} Combine seasonal data for each year and plot against Yr +\item \code{"sep"} Treat season separately, plotting against \code{Yr.S}. +\item \code{NULL} If NULL, it is assumed that there is only one season and +option \code{"comb"} is used. +}} -\item{plot}{Deprecated. Plots (and subplots) are drawn to the active plot device -by default (TRUE), and the option to disable this, via FALSE, is unused.} +\item{plot}{DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +plot device. The option to explicitly disable this option (FALSE), is not +implemented. This option flag will be defunct in a future version} -\item{print}{Deprecated. Please use 'print_plot'.} +\item{print}{DEPRECATED, please use \code{print_plot}.} -\item{print_plot}{Option to print to PNG files} +\item{print_plot}{Flag to enable plot graphic device to print to PNG or PNG files.} -\item{png}{Deprecated. please use 'use_png'.} +\item{png}{DEPRECATED. Please use \code{use_png}.} -\item{use_png}{Draw plots in PNG format} +\item{use_png}{Enables plots to be generated to PNG files. Defaults to print value} -\item{pdf}{Deprecated. Please use 'use_pdf'.} +\item{pdf}{DEPRECATED. Please use \code{use_pdf}.} -\item{use_pdf}{option for pdf plots (not tested for TRUE)} +\item{use_pdf}{Enables plots to be generated to pdf file.} -\item{indexselect}{Vector of fleet numbers for each model for which to compare} +\item{indexselect}{Vector of fleet numbers for each model for which to +compare} -\item{miny}{minimum abs values of ylim} +\item{miny}{minimum abs values of \code{ylim}} \item{col}{Optional vector of colors to be used for lines. Input NULL} @@ -89,76 +101,89 @@ by default (TRUE), and the option to disable this, via FALSE, is unused.} \item{lwd}{Optional vector of line widths} -\item{tickEndYr}{TRUE/FALSE switch to turn on/off extra axis mark at final -year in time series plots.} +\item{tickEndYr}{\link[base:logical]{Logical} flag: set TRUE or FALSE to switch to turn +on/off extra axis mark at final year in timeseries plots.} -\item{xlim}{Optional, values for x-axis range of years to display on plot. -Default = "default" displays all years of available data. (currently not used)} +\item{xlim}{Optional, years to use for x-axis. Default value NULL (or "default"), +uses all years available.} -\item{ylim}{Optional, min and max values for the ylim to override the "default" value (-0.7, 0.5)} +\item{ylim}{Optional, min and max values for the ylim to override the +\code{"default"} value (-0.7, 0.5)} -\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space} +\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space.} -\item{xaxs}{Choice of x-axis parameter (see ?par for more info)} +\item{xaxs}{Choice of xaxs parameter See \code{?par} for more info.} -\item{yaxs}{Choice of y-axis parameter (see ?par for more info)} +\item{yaxs}{Choice of yaxs parameter. See \code{?par} for more info.} -\item{xylabs}{TRUE or FALSE, include x- and y-axis labels} +\item{xylabs}{\link[base:logical]{Logical} flag. Enables x- and y-axis labels.} -\item{type}{Type parameter passed to points (default 'o' overplots points on -top of lines)} +\item{type}{The type of plot to be drawn. For more details, see \code{\link[base:plot]{plot}}.} -\item{legend}{Option to add a legend. TRUE by default.} +\item{legend}{Flag to enable legend to plot. TRUE by default.} \item{legendlabels}{Optional vector of labels to include in legend.} -\item{legendloc}{Location of legend. Either a string like "topleft" or a vector -of two numeric values representing the fraction of the maximum in the x and y -dimensions, respectively. See ?legend for more info on the string options.} +\item{legendloc}{Location of legend. Either a string like "topleft" or a vector of two +numeric values representing the fraction of the maximum in the x and y +dimensions, respectively. See \code{help("legend")} for more info on the +string options.} -\item{legendorder}{Optional vector of model numbers that can be used to have -the legend display the model names in an order that is different than that +\item{legendorder}{Optional vector of model numbers that can be used to have the legend +display the model names in an order that is different than that which is represented in the summary input object.} \item{legendncol}{Number of columns for the legend.} -\item{legendcex}{Allows to adjust legend cex. Defaults to 1.} +\item{legendcex}{Allows to adjust legend cex} \item{legendsp}{Space between legend labels} \item{legendindex}{Allows to add legend for selected indices (plots)} -\item{pwidth}{Width of plot} +\item{pwidth}{Default width of plot printed to plot in units of \code{punits}} -\item{pheight}{Height of plot} +\item{pheight}{Height of plot printed to plot in units of \code{punits }} -\item{punits}{Units for PNG file} +\item{punits}{Measurement units for \code{pwidth} and \code{pheight}. Default is \code{"in"}. +\itemize{ +\item \code{"px"} (pixels) +\item \code{"in"} (inches) +\item \code{"cm"} (centimeters) +\item \code{"mm"} (millimeters) +}} -\item{res}{Resolution for PNG file} +\item{res}{Resolution for plots printed to files.} -\item{ptsize}{Point size for PNG file} +\item{ptsize}{Point size for plotted text in plots printed in files. See \code{help("png")} +for more details} -\item{cex.main}{Character expansion for plot titles} +\item{cex.main}{Character expansion for plot titles.} -\item{plotdir}{Directory where PNG or PDF files will be written. By default +\item{plotdir}{Directory where output plot file will be written. By default, it will be the directory where the model was run.} -\item{filenameprefix}{Additional text to append to PNG or PDF file names. +\item{filenameprefix}{Additional text to append to output plot file name. It will be separated from default name by an underscore.} -\item{par}{list of graphics parameter values passed to par() function} +\item{par}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of +the plot,which is passed to \code{par()}. Entering \code{NULL} passes plot's default +\code{par()} values (which depends on whether the main title is included or not)} -\item{verbose}{Report progress to R GUI?} +\item{verbose}{Flag to print additional diagnostic messages to R console} \item{boxcol}{color boxes} \item{new}{Deprecated. New plot windows are created by default (TRUE), and the option to disable this, via FALSE, is unused.} -\item{add}{supresses par() to create multiplot figs} +\item{add}{suppresses \code{par()} to create multiplot figs} } \description{ -plots residuals for all indices as boxplot (color coded by fleet) with a loess showing systematic trends over time. This function is from the package JABBA. +Plots residuals for all indices as boxplot (color coded by fleet) with a +loess showing systematic trends over time. This function is from the package +JABBA (Just Another Bayesian Biomass Assessment). } \author{ Henning Winker (JRC-EC) diff --git a/man/SSplotModelcomp.Rd b/man/SSplotModelcomp.Rd index 62cca09..855a721 100644 --- a/man/SSplotModelcomp.Rd +++ b/man/SSplotModelcomp.Rd @@ -64,43 +64,57 @@ SSplotModelcomp( ) } \arguments{ -\item{summaryoutput}{List created by r4ss::SSsummarize()} +\item{summaryoutput}{List created by \code{\link[r4ss:SSsummarize]{r4ss::SSsummarize()}}} -\item{plot}{Deprecated. Plots (and subplots) are drawn to the active plot device -by default (TRUE), the option to disable this via FALSE, is unused here.} +\item{plot}{DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +plot device. The option to explicitly disable this option (FALSE), is not +implemented. This option flag will be defunct in a future version} -\item{print}{Deprecated. Please use 'print_plot'.} +\item{print}{DEPRECATED, please use \code{print_plot}.} -\item{print_plot}{print to PNG files?} +\item{print_plot}{Flag to enable plot graphic device to print to PNG or PNG files.} -\item{png}{draws to png files. Deprecated.} +\item{png}{DEPRECATED. Please use \code{use_png}.} -\item{use_png}{Draw plots in PNG format, defaults to 'print_plot' value} +\item{use_png}{Enables plots to be generated to PNG files. Defaults to print value} -\item{pdf}{Deprecated. Please use 'use_png'.} +\item{pdf}{DEPRECATED. Please use \code{use_pdf}.} -\item{use_pdf}{option for pdf plots (not tested for TRUE)} +\item{use_pdf}{Enables plots to be generated to pdf file.} -\item{models}{Optional subset of the models described in -r4ss function summaryoutput(). Either "all" or a vector of numbers indicating +\item{models}{Optional subset of the models of \code{summaryoutput} (or a similar +field with a different name): a list created by the function +\link[r4ss:SSsummarize]{r4ss::SSsummarize}. Either \code{"all"} or a vector of numbers indicating columns in summary tables.} -\item{subplots}{option to "SSB","Bratio","Fvalue","Recruits","Index"} +\item{subplots}{option to "SSB","Bratio","Fvalue","Recruits","Index" +\itemize{ +\item \code{"SSB"} Spawning Stock Biomass +\item \code{"Bratio"} Stock Biomass relative to biomass reference point +\item \code{"Fvalue"} Fishing Mortality +\item \code{"Recruits"} Age-0 Recruits +\item \code{"Index"} Index of abundance +\item \code{"RecDev"} Recruitment Deviations +}} -\item{brp}{option to set reference point c("msy","btargs")} +\item{brp}{option to set reference point \code{c("msy","btargs")}} -\item{fmsy}{to specify Fvalue as F/Fmsy if so in starter file setting} +\item{fmsy}{to specify \code{Fvalue} as \code{F/Fmsy} if so in starter file setting} \item{ylabs}{yaxis labels for quants final year of values to show for each model. By default it is set to the} -\item{endyrvec}{ending year specified in each model.} +\item{endyrvec}{Optional single year or vector of years representing the +final year of values to show for each model. By \code{"default"} it is set to the +ending year specified in each model.} -\item{xmin}{= NULL optional number first year shown in plot (if available)} +\item{xmin}{NULL optional number first year shown in plot (if available)} -\item{indexselect}{= Vector of fleet numbers for each model for which to compare} +\item{indexselect}{Vector of fleet numbers for each model for which to +compare} -\item{indexUncertainty}{Show fixed uncertainty intervals on index (not estimated)} +\item{indexUncertainty}{Show fixed uncertainty intervals on index +(not estimated)} \item{col}{Optional vector of colors to be used for lines. Input NULL} @@ -110,34 +124,39 @@ final year of values to show for each model. By default it is set to the} \item{lwd}{Optional vector of line widths} -\item{tickEndYr}{TRUE/FALSE switch to turn on/off extra axis mark at final -year in timeseries plots. Default is FALSE} +\item{tickEndYr}{\link[base:logical]{Logical} flag: set TRUE or FALSE to switch to turn +on/off extra axis mark at final year in timeseries plots.} -\item{xlim}{Optional, values for x-axis range of years to display on plot. Default = "default" displays all years of available data. (currently not used)} +\item{xlim}{Optional, years to use for x-axis. Default value NULL (or "default"), +uses all years available.} -\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space} +\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space.} -\item{xaxs}{Choice of xaxs parameter (see ?par for more info)} +\item{xaxs}{Choice of xaxs parameter See \code{?par} for more info.} -\item{yaxs}{Choice of yaxs parameter (see ?par for more info)} +\item{yaxs}{Choice of yaxs parameter. See \code{?par} for more info.} -\item{xylabs}{TRUE or FALSE, include x- and y-axis labels} +\item{xylabs}{\link[base:logical]{Logical} flag: set TRUE or FALSE to include x- and +y-axis labels to the plot. Defaults to TRUE} -\item{type}{Type parameter passed to points (default 'o' overplots points on -top of lines)} +\item{type}{The type of plot to be drawn. For more details, see \code{\link[base:plot]{plot}}.} -\item{uncertainty}{TRUE/FALSE include uncertainty intervals around SSB or F estimated timeseries. Defaults to TRUE.} +\item{uncertainty}{Logical flag to enable plots with uncertainty intervals. Either a single +TRUE/FALSE value, or a vector of TRUE/FALSE values around SSB or F +estimated timeseries, or a set of integers corresponding to +the choice of models.} -\item{legend}{Option to add a legend. TRUE by default.} +\item{legend}{Flag to enable legend to plot. TRUE by default.} \item{legendlabels}{Optional vector of labels to include in legend.} -\item{legendloc}{Location of legend. Either a string like "topleft" or a vector -of two numeric values representing the fraction of the maximum in the x and y -dimensions, respectively. See ?legend for more info on the string options.} +\item{legendloc}{Location of legend. Either a string like "topleft" or a vector of two +numeric values representing the fraction of the maximum in the x and y +dimensions, respectively. See \code{help("legend")} for more info on the +string options.} -\item{legendorder}{Optional vector of model numbers that can be used to have -the legend display the model names in an order that is different than that +\item{legendorder}{Optional vector of model numbers that can be used to have the legend +display the model names in an order that is different than that which is represented in the summary input object.} \item{legendncol}{Number of columns for the legend.} @@ -146,29 +165,39 @@ which is represented in the summary input object.} \item{legendsp}{Space between legend labels} -\item{legendindex}{Allows to add lengend for selected indices (plots)} +\item{legendindex}{Allows to add legend for selected indices (plots)} -\item{pwidth}{Width of plot} +\item{pwidth}{Default width of plot printed to plot in units of \code{punits}} -\item{pheight}{Height of plot} +\item{pheight}{Height of plot printed to plot in units of \code{punits }} -\item{punits}{Units for PNG file} +\item{punits}{Measurement units for \code{pwidth} and \code{pheight}. Default is \code{"in"}. +\itemize{ +\item \code{"px"} (pixels) +\item \code{"in"} (inches) +\item \code{"cm"} (centimeters) +\item \code{"mm"} (millimeters) +}} -\item{res}{Resolution for PNG file} +\item{res}{Resolution for plots printed to files.} -\item{ptsize}{Point size for PNG file} +\item{ptsize}{Point size for plotted text in plots printed in files. See \code{help("png")} +for more details} -\item{cex.main}{Character expansion for plot titles} +\item{cex.main}{Character expansion for plot titles.} -\item{plotdir}{Directory where PNG or PDF files will be written. By default +\item{plotdir}{Directory where output plot file will be written. By default, it will be the directory where the model was run.} -\item{filenameprefix}{Additional text to append to PNG or PDF file names. +\item{filenameprefix}{Additional text to append to output plot file name. It will be separated from default name by an underscore.} -\item{par}{list of graphics parameter values passed to par() function} +\item{par}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of +the plot,which is passed to \code{par()}. Entering \code{NULL} passes plot's default +\code{par()} values (which depends on whether the main title is included or not)} -\item{verbose}{Report progress to R GUI?} +\item{verbose}{Flag to print additional diagnostic messages to R console} \item{shadecol}{uncertainty shading of hcxval horizon} @@ -177,18 +206,36 @@ It will be separated from default name by an underscore.} \item{new}{Deprecated. New plot windows are created by default (TRUE), and the option to disable this, via FALSE, is unused.} -\item{add}{surpresses par() to create multiplot figs} +\item{add}{suppresses \code{par()} to create multiplot figs} -\item{mcmcVec}{NOT TESTED Vector of TRUE/FALSE values (or single value) indicating} +\item{mcmcVec}{Logical vector of TRUE/FALSE values (or single value) indicating +whether input values are from MCMC or to use normal distribution around +MLE.} -\item{indexQlabel}{TRUE/FALSE, if TRUE add catchability to legend in plot of index fits (currently not used)} +\item{indexQlabel}{\link[base:logical]{Logical}. If TRUE add catchability to +legend in plot of index fits (currently not used)} \item{indexQdigits}{Number of significant digits for catchability in legend} -\item{indexfleets}{CHECK IF NEEDED or how to adjust indexfleets} +\item{indexfleets}{Fleet numbers for each model to compare +indices of abundance. Can take different forms: +\itemize{ +\item integer (default): create a single comparison plot for the chosen +index +\item NULL: create a separate plot for each index as long as the fleet +numbering is the same across all models. +\item vector of length equal to number of models: a single fleet number +for each model to be compared in a single plot +\item list: list of fleet numbers associated with indices within each +model to be compared, where the list elements are each a vector of the +same length but the names of the list elements don't matter and can be +absent. +}} } \description{ -A function to plot SSB, B-ratio, F, Recruits, and/or Index of Abundance fits from multiple SS models. This function uses an object of multiple SS models summarized with r4ss:SSsummarize(). +A function to plot SSB, B-ratio, F, Recruits, and/or Index of Abundance fits +from multiple SS models. This function uses an object of multiple SS models +summarized with \code{\link[r4ss:SSsummarize]{r4ss::SSsummarize()}}. } \author{ Mostly adopted from r4ss::SSplotComparisons by Taylor et al diff --git a/man/SSplotRetro.Rd b/man/SSplotRetro.Rd index c83c6b8..1a91684 100644 --- a/man/SSplotRetro.Rd +++ b/man/SSplotRetro.Rd @@ -63,45 +63,56 @@ SSplotRetro( ) } \arguments{ -\item{summaryoutput}{List created by r4ss::SSsummarize()} +\item{summaryoutput}{List created by \code{\link[r4ss:SSsummarize]{r4ss::SSsummarize()}}} -\item{subplots}{Optional vector of subplots to be created, "SSB", "Bratio", "Fvalue", "Recruits", "Index"} +\item{subplots}{Optional vector of subplots to be created: +\itemize{ +\item \code{"SSB"} Spawning Stock Biomass +\item \code{"F"} Fishing Mortality +}} -\item{plot}{Option to draw subplots and plot in the interface. Deprecated. Option to disable will be removed in future version.} +\item{plot}{DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +plot device. The option to explicitly disable this option (FALSE), is not +implemented. This option flag will be defunct in a future version} -\item{print}{print to PNG files? Deprecated. Please use print_plot.} +\item{print}{DEPRECATED, please use \code{print_plot}.} -\item{print_plot}{Option to print to PNG files} +\item{print_plot}{Flag to enable plot graphic device to print to PNG or PNG files.} -\item{png}{Deprecated, please use 'use_png'} +\item{png}{DEPRECATED. Please use \code{use_png}.} -\item{use_png}{Draw plots in PNG format} +\item{use_png}{Enables plots to be generated to PNG files. Defaults to print value} -\item{pdf}{PDF plots. Deprecated. Please use use_pdf.} +\item{pdf}{DEPRECATED. Please use \code{use_pdf}.} -\item{use_pdf}{option for pdf plots (currently does not work when subplots specified)} +\item{use_pdf}{Enables plots to be generated to pdf file.} -\item{models}{Optional subset of the models described in -r4ss function summaryoutput(). Either "all" or a vector of numbers indicating +\item{models}{Optional subset of the models of \code{summaryoutput} (or a similar +field with a different name): a list created by the function +\link[r4ss:SSsummarize]{r4ss::SSsummarize}. Either \code{"all"} or a vector of numbers indicating columns in summary tables.} \item{endyrvec}{Optional single year or vector of years representing the final year of values to show for each model. By default it is set to the ending year specified in each model.} -\item{xlim}{optional xlim, which overwrites xmin} +\item{xlim}{Optional, years to use for x-axis. Default value NULL (or "default"), +uses all years available.} \item{xmin}{optional minimum year shown in plot (default first yr)} -\item{labels}{yaxis lable for biomass (bony fish and sharks)} +\item{labels}{\code{yaxis} label for biomass (bony fish and sharks)} -\item{ylim}{option to specify ylim range} +\item{ylim}{option to specify \code{ylim} range} -\item{forecast}{if true one-step ahead forecasts are shown in plot} +\item{forecast}{\link[base:logical]{Logical}. If TRUE, one-step ahead forecasts +are shown in plot} -\item{forecastrho}{if true one-step ahead forecast rho value is denoted in plot} +\item{forecastrho}{\link[base:logical]{Logical}. If TRUE, one-step ahead +forecast rho value is denoted in plot} -\item{showrho}{TRUE/FALSE include Mohn's rho value? Defaults to TRUE} +\item{showrho}{\link[base:logical]{Logical} flag to include Mohn's rho value. +Defaults to TRUE} \item{col}{Optional vector of colors to be used for lines. Input NULL} @@ -111,32 +122,36 @@ ending year specified in each model.} \item{lwd}{Optional vector of line widths} -\item{tickEndYr}{TRUE/FALSE switch to turn on/off extra axis mark at final -year in timeseries plots.} +\item{tickEndYr}{\link[base:logical]{Logical} flag: set TRUE or FALSE to switch to turn +on/off extra axis mark at final year in timeseries plots.} -\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space} +\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space.} -\item{xaxs}{Choice of xaxs parameter (see ?par for more info)} +\item{xaxs}{Choice of xaxs parameter See \code{?par} for more info.} -\item{yaxs}{Choice of yaxs parameter (see ?par for more info)} +\item{yaxs}{Choice of yaxs parameter. See \code{?par} for more info.} -\item{xylabs}{TRUE or FALSE, include x- and y-axis labels. Defaults to TRUE} +\item{xylabs}{\link[base:logical]{Logical} flag: set TRUE or FALSE to include x- and +y-axis labels to the plot. Defaults to TRUE} -\item{type}{Type parameter passed to points (default 'o' overplots points on -top of lines)} +\item{type}{The type of plot to be drawn. For more details, see \code{\link[base:plot]{plot}}.} -\item{uncertainty}{TRUE/FALSE include uncertainty intervals around SSB or F estimated timeseries. Defaults to TRUE.} +\item{uncertainty}{Logical flag to enable plots with uncertainty intervals. Either a single +TRUE/FALSE value, or a vector of TRUE/FALSE values around SSB or F +estimated timeseries, or a set of integers corresponding to +the choice of models.} -\item{legend}{Add a legend?} +\item{legend}{Flag to enable legend to plot. TRUE by default.} \item{legendlabels}{Optional vector of labels to include in legend.} -\item{legendloc}{Location of legend. Either a string like "topleft" or a vector -of two numeric values representing the fraction of the maximum in the x and y -dimensions, respectively. See ?legend for more info on the string options.} +\item{legendloc}{Location of legend. Either a string like "topleft" or a vector of two +numeric values representing the fraction of the maximum in the x and y +dimensions, respectively. See \code{help("legend")} for more info on the +string options.} -\item{legendorder}{Optional vector of model numbers that can be used to have -the legend display the model names in an order that is different than that +\item{legendorder}{Optional vector of model numbers that can be used to have the legend +display the model names in an order that is different than that which is represented in the summary input object.} \item{legendncol}{Number of columns for the legend.} @@ -145,49 +160,64 @@ which is represented in the summary input object.} \item{legendsp}{Space between legend labels} -\item{legendindex}{Allows to add lengend for selected indices (plots)} +\item{legendindex}{Allows to add legend for selected indices (plots)} -\item{pwidth}{Width of plot} +\item{pwidth}{Default width of plot printed to plot in units of \code{punits}} -\item{pheight}{Height of plot} +\item{pheight}{Height of plot printed to plot in units of \code{punits }} -\item{punits}{Units for PNG file} +\item{punits}{Measurement units for \code{pwidth} and \code{pheight}. Default is \code{"in"}. +\itemize{ +\item \code{"px"} (pixels) +\item \code{"in"} (inches) +\item \code{"cm"} (centimeters) +\item \code{"mm"} (millimeters) +}} -\item{res}{Resolution for PNG file} +\item{res}{Resolution for plots printed to files.} -\item{ptsize}{Point size for PNG file} +\item{ptsize}{Point size for plotted text in plots printed in files. See \code{help("png")} +for more details} -\item{cex.main}{Character expansion for plot titles} +\item{cex.main}{Character expansion for plot titles.} -\item{plotdir}{Directory where PNG or PDF files will be written. By default +\item{plotdir}{Directory where output plot file will be written. By default, it will be the directory where the model was run.} -\item{filenameprefix}{Additional text to append to PNG or PDF file names. +\item{filenameprefix}{Additional text to append to output plot file name. It will be separated from default name by an underscore.} -\item{par}{list of graphics parameter values passed to par() function} +\item{par}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of +the plot,which is passed to \code{par()}. Entering \code{NULL} passes plot's default +\code{par()} values (which depends on whether the main title is included or not)} -\item{verbose}{Report progress to R GUI?} +\item{verbose}{Flag to print additional diagnostic messages to R console} \item{shadecol}{uncertainty shading of hcxval horizon} \item{new}{Deprecated. New plot windows are created by default (TRUE), and the option to disable this, via FALSE, is unused.} -\item{add}{surpresses par() to create multiplot figs} +\item{add}{suppresses \code{par()} to create multiplot figs} -\item{mcmcVec}{NOT TESTED Vector of TRUE/FALSE values (or single value) indicating mcmc values are used} +\item{mcmcVec}{Logical vector of TRUE/FALSE values (or single value) indicating +whether input values are from MCMC or to use normal distribution around +MLE.} \item{shadecol1}{uncertainty shading of early years not affected by hindcast} -\item{indexQlabel}{TRUE/FALSE, if TRUE add catchability to legend in plot of index fits (currently not used)} +\item{indexQlabel}{\link[base:logical]{Logical}. If TRUE, add catchability to +legend in plot of index fits (currently not used)} \item{indexQdigits}{Number of significant digits for catchability in legend} -\item{shadealpha}{set the transparency level (alpha) of the area of uncertainty. Defalut to 0.3 (currently not used)} +\item{shadealpha}{set the transparency level (alpha) of the area of +uncertainty. Defaults to 0.3 (currently not used)} } \description{ -Plots retrospective pattern, including (optional) one-step ahead forecast and computes Mohn's Rho +Plots retrospective pattern, including (optional) one-step ahead forecast +and computes Mohn's Rho } \author{ Henning Winker (JRC-EC) and Laurance Kell (Sea++) diff --git a/man/SSplotRunstest.Rd b/man/SSplotRunstest.Rd index ebc0411..36a869e 100644 --- a/man/SSplotRunstest.Rd +++ b/man/SSplotRunstest.Rd @@ -17,6 +17,7 @@ SSplotRunstest( use_pdf = FALSE, indexselect = NULL, miny = 1, + col = NULL, pch = 21, lty = 1, lwd = 2, @@ -46,32 +47,43 @@ SSplotRunstest( ) } \arguments{ -\item{ss3rep}{Stock Synthesis output as read by r4SS function SS_output} +\item{ss3rep}{Stock Synthesis output as read by \code{\link[r4ss:SS_output]{r4ss::SS_output()}}} -\item{mixing}{c("less","greater","two.sided"). Default less is checking for positive autocorrelation only} +\item{mixing}{\code{c("less","greater","two.sided")}. Default less is checking +for positive autocorrelation only} -\item{subplots}{optional 'cpue' for index data, 'len' for length composition data, 'size' for -generalized size composition data, 'age' for age composition data, -or 'con' for conditional age at length data} +\item{subplots}{optional flag for: +\itemize{ +\item \code{"cpue"} Index of abundance data +\item \code{"len"} Length composition data +\item \code{"size"} Generalized size composition data +\item \code{"age"} Age composition data +\item \code{"con"} Conditional age-at-length data +}} -\item{plot}{Deprecated. Plots (and subplots) are drawn to the active plot device -by default (TRUE), the option to disable this via FALSE, is unused here.} +\item{plot}{DEPRECATED. By default, TRUE, Plots (and subplots) are drawn to the +plot device. The option to explicitly disable this option (FALSE), is not +implemented. This option flag will be defunct in a future version} -\item{print}{Deprecated. Please use 'print_plot'.} +\item{print}{DEPRECATED, please use \code{print_plot}.} -\item{print_plot}{Option to print to PNG files} +\item{print_plot}{Flag to enable plot graphic device to print to PNG or PNG files.} -\item{png}{Deprecated, please use 'use_png'.} +\item{png}{DEPRECATED. Please use \code{use_png}.} -\item{use_png}{Draw plots in PNG format} +\item{use_png}{Enables plots to be generated to PNG files. Defaults to print value} -\item{pdf}{PDF plots. Deprecated. Please use use_pdf.} +\item{pdf}{DEPRECATED. Please use \code{use_pdf}.} -\item{use_pdf}{option for pdf plots} +\item{use_pdf}{Enables plots to be generated to pdf file.} -\item{indexselect}{Vector of fleet numbers for each model for which to compare} +\item{indexselect}{Vector of fleet numbers for each model for which to +compare} -\item{miny}{the absolute value of the min and max value for ylim, default is 1} +\item{miny}{the absolute value of the min and max value for \code{ylim}. +Default is 1} + +\item{col}{Optional vector of colors to be used for lines. Input NULL} \item{pch}{Optional vector of plot character values} @@ -79,61 +91,82 @@ by default (TRUE), the option to disable this via FALSE, is unused here.} \item{lwd}{Optional vector of line widths} -\item{tickEndYr}{TRUE/FALSE switch to turn on/off extra axis mark at final -year in timeseries plots.} +\item{tickEndYr}{\link[base:logical]{Logical} flag: set TRUE or FALSE to switch to turn +on/off extra axis mark at final year in timeseries plots.} -\item{xlim}{Optional, values for x-axis range of years to display on plot. Default = "default" displays all years of available data.} +\item{xlim}{Optional, years to use for x-axis. Default value NULL (or "default"), +uses all years available.} -\item{ylim}{Optional, values for y-axis range to display on plot. Default = "default" will range from -1 to 1.} +\item{ylim}{Optional, values for y-axis range to display on plot. +The default: \code{"default"}, will range from -1 to 1.} -\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space} +\item{ylimAdj}{Multiplier for ylim parameter. Allows additional white space.} -\item{xaxs}{Choice of xaxs parameter (see ?par for more info)} +\item{xaxs}{Choice of xaxs parameter See \code{?par} for more info.} -\item{yaxs}{Choice of yaxs parameter (see ?par for more info)} +\item{yaxs}{Choice of yaxs parameter. See \code{?par} for more info.} -\item{xylabs}{TRUE or FALSE, include x- and y-axis labels} +\item{xylabs}{\link[base:logical]{Logical} flag: set TRUE or FALSE to include x- and +y-axis labels to the plot. Defaults to TRUE} -\item{type}{Type parameter passed to points (default 'o' overplots points on -top of lines)} +\item{type}{The type of plot to be drawn. For more details, see \code{\link[base:plot]{plot}}.} -\item{legend}{Option to add a legend. TRUE by default.} +\item{legend}{Flag to enable legend to plot. TRUE by default.} -\item{legendloc}{Location of legend. Either a string like "topleft" or a vector} +\item{legendloc}{Location of legend. Either a string like "topleft" or a +vector of two numeric values representing the fraction of the maximum in +the x and y dimensions, respectively. See \code{help("legend")} for more info +on the string options.} \item{legendcex}{Allows to adjust legend cex} -\item{pwidth}{Width of plot} +\item{pwidth}{Default width of plot printed to plot in units of \code{punits}} -\item{pheight}{Height of plot} +\item{pheight}{Height of plot printed to plot in units of \code{punits }} -\item{punits}{Units for PNG file} +\item{punits}{Measurement units for \code{pwidth} and \code{pheight}. Default is \code{"in"}. +\itemize{ +\item \code{"px"} (pixels) +\item \code{"in"} (inches) +\item \code{"cm"} (centimeters) +\item \code{"mm"} (millimeters) +}} -\item{res}{Resolution for PNG file} +\item{res}{Resolution for plots printed to files.} -\item{ptsize}{Point size for PNG file} +\item{ptsize}{Point size for plotted text in plots printed in files. See \code{help("png")} +for more details} -\item{cex.main}{Character expansion for plot titles} +\item{cex.main}{Character expansion for plot titles.} -\item{plotdir}{Directory where PNG or PDF files will be written. By default +\item{plotdir}{Directory where output plot file will be written. By default, it will be the directory where the model was run.} -\item{filenameprefix}{Additional text to append to PNG or PDF file names. +\item{filenameprefix}{Additional text to append to output plot file name. It will be separated from default name by an underscore.} -\item{par}{list of graphics parameter values passed to par() function} +\item{par}{A numerical vector of the form c(bottom, left, top, right) which +gives the number of lines of margin to be specified on the four sides of +the plot,which is passed to \code{par()}. Entering \code{NULL} passes plot's default +\code{par()} values (which depends on whether the main title is included or not)} -\item{verbose}{TRUE or FALSE, should the progress be reported to R GUI?} +\item{verbose}{Flag to print additional diagnostic messages to R console} -\item{new}{Create new empty plot window (TRUE or FALSE)} +\item{new}{Deprecated. New plot windows are created by default (TRUE), and the +option to disable this, via FALSE, is unused.} -\item{add}{suppresses par() to create multiplot figs} +\item{add}{suppresses \code{par()} to create multiplot figs} } \value{ -a dataframe with runs test p-value, if the test has passed or failed, 3x sigma high and low limits, and the type of data used. Rows are for each fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and failed if p-value < 0.5 (residuals are not random) +a dataframe with runs test p-value, if the test has passed or failed, +3x sigma high and low limits, and the type of data used. Rows are for each +fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and +failed if p-value < 0.5 (residuals are not random) } \description{ -Function for residual diagnostics. Plots residuals and 3x sigma limits for indices or mean age or length and outputs a runs test table. Note, if you do not want to plot the residuals, use function ss3diags::SSrunstest. +Function for residual diagnostics. Plots residuals and 3x sigma limits for +indices or mean age or length and outputs a runs test table. Note, if you do +not want to plot the residuals, use \code{\link[=SSrunstest]{SSrunstest()}}. } \author{ Henning Winker (JRC-EC) and Laurance Kell (Sea++) diff --git a/man/SSrunstest.Rd b/man/SSrunstest.Rd index 0c9f279..7b73829 100644 --- a/man/SSrunstest.Rd +++ b/man/SSrunstest.Rd @@ -13,21 +13,37 @@ SSrunstest( ) } \arguments{ -\item{ss3rep}{Stock Synthesis output as read by r4SS function SS_output} +\item{ss3rep}{Stock Synthesis output as read by \code{\link[r4ss:SS_output]{r4ss::SS_output()}}} -\item{mixing}{c("less","greater","two.sided"). Default less is checking for positive autocorrelation only} +\item{mixing}{\code{c("less","greater","two.sided")}. Default less is checking for +positive autocorrelation only} -\item{quants}{optional use of c("cpue","len","age","con"), default uses CPUE.} +\item{quants}{optional use of \code{c("cpue","len","age","con")}, default uses +\code{"cpue"}. +\itemize{ +\item \code{"cpue"} Index of abundance data +\item \code{"len"} Length composition data +\item \code{"age"} Age composition data +\item \code{"con"} Conditional age-at-length data +}} -\item{indexselect}{Vector of fleet numbers for each model for which to compare} +\item{indexselect}{Vector of fleet numbers for each model for which to +compare} \item{verbose}{Report progress to R GUI?} } \value{ -a dataframe with runs test p-value, if the test has passed or failed, 3x sigma high and low limits, and the type of data used. Rows are for each fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and failed if p-value < 0.5 (residuals are not random) +a dataframe with runs test p-value, if the test has passed or failed, +3x sigma high and low limits, and the type of data used. Rows are for each +fleet. Note, runs test passed if p-value > 0.05 (residuals are random) and +failed if p-value < 0.5 (residuals are not random) } \description{ -Function for residual diagnostics. Outputs a runs test table that gives runs test p-values, if the runs test passed (p-value > 0.05, residuals are random) or failed (p-value < 0.05, residuals are not random), the 3x sigma limits for indices or mean age or length and the type of input data (cpue, length comp, age comp, size comp, or conditional age-at-length). +Function for residual diagnostics. Outputs a runs test table that gives runs +test p-values, if the runs test passed (p-value > 0.05, residuals are random) +or failed (p-value < 0.05, residuals are not random), the 3x sigma limits for +indices or mean age or length and the type of input data (cpue, length comp, +age comp, size comp, or conditional age-at-length). } \author{ Henning Winker (JRC-EC) and Laurance Kell (Sea++) diff --git a/man/ssruns_sig3.Rd b/man/ssruns_sig3.Rd index 25a3930..ffb4a5d 100644 --- a/man/ssruns_sig3.Rd +++ b/man/ssruns_sig3.Rd @@ -9,18 +9,21 @@ ssruns_sig3(x, type = NULL, mixing = "less") \arguments{ \item{x}{residuals from CPUE fits} -\item{type}{only c("resid","observations")} +\item{type}{only \code{c("resid","observations")}} -\item{mixing}{c("less","greater","two.sided"). Default less is checking for positive autocorrelation only} +\item{mixing}{\code{c("less","greater","two.sided")}. Default less is checking +for positive autocorrelation only} } \value{ runs p value and 3 x sigma limits } \description{ -This function uses randtests::runs.test to do perform a runs test on residuals to determine if they are randomly distributed. It also calculates the 3 x sigma limits +This function uses randtests::runs.test to do perform a runs test on +residuals to determine if they are randomly distributed. It also calculates +the 3 x sigma limits } \details{ -runs test is conducted with library(randtests) +runs test is conducted with \code{library(randtests)} } \author{ Henning Winker (JRC-EC) and Laurence Kell (Sea++) diff --git a/tests/testthat.R b/tests/testthat.R index 54013a7..905f637 100644 --- a/tests/testthat.R +++ b/tests/testthat.R @@ -7,9 +7,9 @@ files_path <- system.file("extdata", package = "ss3diags") run_tmp <- file.path(tempdir(check = TRUE), "test-runs") dir.create(run_tmp, showWarnings = FALSE) file.copy(from = list.files(files_path, full.names = TRUE), to = run_tmp) - +r4ss::get_ss3_exe(dir = run_tmp, version = "v3.30.21") ## Run retrospectives -if (file.exists(file.path(files_path, "ss")) | file.exists(file.path(files_path, "ss.exe"))) { +if (file.exists(file.path(run_tmp, "ss3")) | file.exists(file.path(run_tmp, "ss3.exe"))) { r4ss::retro(dir = run_tmp, oldsubdir = "", newsubdir = "retrospectives", years = 0:-3, show_in_console = FALSE) # Creating retrospective object here so that multiple test files can access it without having to re-run retrospective for each test retroModels <- r4ss::SSgetoutput( diff --git a/tests/testthat/SSmase_test.R b/tests/testthat/SSmase_test.R deleted file mode 100644 index 893b116..0000000 --- a/tests/testthat/SSmase_test.R +++ /dev/null @@ -1,31 +0,0 @@ -## File is deprecated by MOshima 6/12/23 - -# library(ss3diags) -# Tests -# sma = r4ss::SSsummarize(retro.sma) -# Check joint MASE for indices -# SSmase(retro.sma) -# select indices -# SSmase(retro.sma, indexselect = c(4)) -# check for length comps -# smaL = ss3diags::SSretroComps(retro.sma) -# SSmase(retro.sma, quants = "len", indexselect = 2:4) - -# check manually -# mase <- SSmase(retro.sma, residuals = T) -# Joint mase from index 1, 3,4 -# mae <- apply( -# mase$Residuals[c("Pred.Res", "Naive.Res")], 2, -# function(x) mean(abs(x)) -# ) -# MASE -# mae[1] / mae[2] -# compare -# SSmase(retro.sma) - -# Check hake -# phk= r4ss::SSsummarize(retro.phk) -# SSmase(retro.phk, verbose = T, indexselect = 1) -# check for age comps -# phkA <- ss3diags::SSretroComps(retro.phk) -# SSmase(retro.phk, quants = "age") diff --git a/tests/testthat/test-HCxval.R b/tests/testthat/test-HCxval.R index d86dc18..c983af2 100644 --- a/tests/testthat/test-HCxval.R +++ b/tests/testthat/test-HCxval.R @@ -1,8 +1,5 @@ ## Test script for hindcast cross validation and MASE -# retroSimple <- ss3diags::retroSimple -# retrosum.simple <- r4ss::SSsummarize(retroSimple) - path <- file.path(tempdir(), "test_runs") dir.create(path, showWarnings = FALSE)