5converting.tex

\hypertarget{ConvIssues}{}
\section[Converting Files from Stock Synthesis v.3.24]{\protect\hyperlink{ConvIssues}{Converting Files from Stock Synthesis v.3.24}}
Converting files from version 3.24 to version 3.30 can be performed by using the program \texttt{ss\_trans.exe}. This executable takes v.3.24 files as input and will output v.3.30 input and output files. SS\_trans executables are available for v.3.30.01 - v.3.30.17. The transitional executable was phased out with v.3.30.18. If a model needs to be converted from v.3.24 to a recent version, one should use the v.3.30.17 \texttt{ss\_trans.exe} available from the \href{https://github.com/nmfs-ost/ss3-source-code/releases/tag/v3.30.17}{v.3.30.17 release page on GitHub} to convert the files and then any additional adjustments needed between v.3.30.17 and newer versions should be done by hand. To see the changes that need to be made between v.3.30.17 and the latest release of SS3, please see the \href{https://github.com/orgs/nmfs-ost/projects/11}{change log for v.3.30.19 onward} as well as the \href{https://github.com/nmfs-ost/ss3-source-code/blob/v3.30.19/Change_log_for_SS_3.30.xlsx?raw=true}{Excel version of the change log} for versions prior to v.3.30.19.

The following file structure and steps are recommended for converting model files:
\begin{enumerate}
	\item Create ``transition'' folder. Place the 4 main model files (control, data, starter, and forecast) from version SS3 v.3.24 within the transition folder along with the SS3 transition executable (\texttt{ss\_trans.exe}). One tip is to use the \texttt{control.ss\_new} from the SS3 v.3.24 estimated model rather than the original control file which will set all parameter values at the previous estimated \gls{mle} parameters. Run the transition executable with a command like \texttt{ss\_trans -stopph -1} which will write ss\_new files but not go through the population dynamics or produce other output (whereas \texttt{-stopph 0} will run through the dynamics once without estimation and produce \texttt{Report.sso} and other output files, but may not produce the ss\_new files if there is any issue with the model setup).
	
	\item Create ``converted'' folder.  Place the ss\_new (\texttt{data.ss\_new}, \texttt{control.ss\_new}, \texttt{starter.ss\_new}, \texttt{forecast.ss\_new}) files created by the transition executable contained within the ``transition'' folder into this new folder. Rename the ss\_new files to the appropriate suffixes and change the names in the \texttt{starter.ss} file accordingly.
	
	\item Review the control (\texttt{control.ss\_new}) file to determine that all model functions converted correctly. The structural changes and assumptions for some advanced model features are too complicated to convert automatically. See below for some known features that may not convert. When needed, it is recommended to modify the \texttt{control.ss\_new} file, the converted control file, for only the features that failed to convert properly.
	
	\item Change the max phase to a value greater than the last phase in which the parameter is set to be estimated within the control file. Run the new v.3.30 executable (\texttt{ss3.exe}) within the ``converted'' folder using the renamed ss\_new files created from the transition executable.
	
	\item Compare likelihood and model estimates between the v.3.24 and v.3.30 model versions.
	
	\item If desired, update to versions of Stock Synthesis > v.3.30.17 by running the new v.3.30 input files with the higher executable.
\end{enumerate}

\noindent Some options have been substantially changed in v.3.30, which impedes the automatic converting of v.3.24 model files. Known examples of v.3.24 options that cannot be converted, but for which better alternatives are available in v.3.30 are:
\begin{enumerate}
	\item The use of catchability (Q) deviations,
	\item Complex birth seasons,
	\item Environmental effects on spawner-recruitment parameters,
	\item Setup of time-varying quantities for models that used the no-longer-available features (e.g., logistic bound constraint).
\end{enumerate}

\pagebreak