14r4ss.tex

\section[Using R To View Model Output (\texttt{r4ss})]{\protect\hyperref[sec:r4ss]{Using R To View Model Output (\texttt{r4ss})}}\label{sec:r4ss}

The R package \texttt{r4ss} includes tools for summarizing and plotting results, manipulating files, visualizing model parameterizations, and other tasks. Currently, information about \texttt{r4ss} can be found on \href{https://github.com/r4ss/r4ss}{GitHub}.  The software package is under continuous development to maintain compatibility with new versions of SS3 and to improve functionality.

The latest version of \texttt{r4ss} can be installed directly from GitHub at any time via the \texttt{remotes} package in R with the following commands:

\begin{quote}
	\begin{verbatim}
	> install.packages(``remotes'')
	> remotes::install_github(``r4ss/r4ss'')
	\end{verbatim}
\end{quote}

Once the \texttt{r4ss} package is installed, it can be loaded:

\begin{quote}
	\begin{verbatim}
	> library(r4ss)
	\end{verbatim}
\end{quote}

Two of the most commonly used functions for model diagnostics are \texttt{SS\_output()} and \texttt{SS\_plots()}. After running a model using SS3, the output files including \texttt{Report.sso} can be read into R using the \texttt{SS\_output()} function which stores quantities in a list with named objects. This list can then be passed to the \texttt{SS\_plots()} function, which creates a series of over 100 plots that are useful for visualizing output such as model fits to the data. For example, plots can be created using model output available in the directory ``C:/myfiles/mymodels/myrun'':

\begin{quote}
	\begin{verbatim}
	> base.model <- SS_output(``C:/myfiles/mymodels/myrun'')
	> SS_plots(base.model)
	\end{verbatim}
\end{quote}
  
%\pagebreak
The core functions available in \texttt{r4ss} include:
\begin{center}
	\begin{longtable}{p{4.5cm} p{10.52cm}}
		\hline
		Core Functions & \Tstrut\Bstrut\\
		\hline
		SS\_output \Tstrut & A function to create a list object for the output from Stock Synthesis \\
		SS\_plots  \Tstrut & Plot many quantities related to output from Stock Synthesis \\
		\hline
		
		\multicolumn{2}{l}{Download the SS3 Executable:} \Tstrut\Bstrut\\
		\hline
		\texttt{get\_ss3\_exe()} \Tstrut & Download the latest version or a specified version of the SS3 executable \\
		\hline
	
		\multicolumn{2}{l}{Model comparisons and other diagnostics:} \Tstrut\Bstrut\\
		\hline
		\texttt{SSsummarize()} \Tstrut & Read output from multiple SS3 models \\
		\texttt{SStableComparison()} \Tstrut & Make table comparing quantities across models \\
		\texttt{SSplotComparison()} \Tstrut & Plot output from multiple SS3 models \\
		\texttt{SSplotPars()} \Tstrut & Plot distributions of priors, posteriors, and estimates \\
		\texttt{SS\_profile()} \Tstrut & Run likelihood parameter profiles \\
		\texttt{SSplotProfile()} \Tstrut & Plot likelihood profile results \\
		\texttt{PinerPlot()} \Tstrut & Plot fleet-specific contributions to likelihood profile \\
		\texttt{Jitter()} \Tstrut & Run multiple model jitters to determine best model fit \\
		\texttt{SS\_doRetro()} \Tstrut & Run retrospective analysis \\
		\texttt{SSmohnsrho()} \Tstrut & Calculate Mohn's Rho values \\
		\texttt{SSplotRetroRecruits()} \Tstrut & Make retrospective pattern of recruitment estimates (a.k.a. squid plot) as seen in Pacific hake assessments\Bstrut \\
		\texttt{SS\_fitbiasramp()} \Tstrut & Estimate bias adjustment for recruitment deviates \Bstrut\\
		\hline
		
		\multicolumn{2}{l}{File manipulation for inputs:} \Tstrut\Bstrut\\
		\hline
		\texttt{SS\_readdat()} \Tstrut & Read data file \\
		\texttt{SS\_readctl()} \Tstrut & Read  control file \\
		\texttt{SS\_readforecast()} \Tstrut & Read forecast file \\
		\texttt{SS\_readstarter()} \Tstrut & Read starter file \\
		\texttt{SS\_readwtatage()} \Tstrut & Read weight-at-age file \\
		\texttt{SS\_writedat()} \Tstrut & Write data file \\
		\texttt{SS\_writectl()} \Tstrut & Write control file \\
		\texttt{SS\_writeforecast()} \Tstrut & Write forecast file \\
		\texttt{SS\_writestarter()} \Tstrut & Write starter file \\
		\texttt{SS\_writewtatage()} \Tstrut & Write weight-at-age file \\
		\texttt{SS\_makedatlist()} \Tstrut & Make a list for SS3 data \\
		\texttt{SS\_parlines()} \Tstrut & Get parameter lines from SS3 control file \\
		\texttt{SS\_changepars()} \Tstrut  & Change parameters in the control file \\
		\texttt{SSmakeMmatrix()} \Tstrut & Create inputs for entering a matrix of natural mortality by age and year \\
		\texttt{SS\_profile()} \Tstrut & Run a likelihood profile in SS3 (incomplete) \\
		\texttt{NegLogInt\_Fn()} \Tstrut & Calculated variances of time-varying parameters using SS3 implementation of the Laplace Approximation \Bstrut\\
		\hline
		
		\multicolumn{2}{l}{File manipulations for outputs:} \Tstrut\Bstrut\\
		\hline
		\texttt{SS\_recdevs()} \Tstrut & Insert a vector of recruitment deviations into the control file \\
		\hline

	\end{longtable}
\end{center}

\pagebreak