From 733895ac940aa9d90cd2877d12b71eccdfc88ff6 Mon Sep 17 00:00:00 2001 From: "kathryn.doering" Date: Tue, 1 Sep 2020 16:59:08 -0700 Subject: [PATCH] docs: update readme, #39 --- README.Rmd | 34 +++++++++++++++++++------ README.md | 41 ++++++++++++++++++------------ man/figures/README-plot_SSB-1.png | Bin 9526 -> 9417 bytes 3 files changed, 51 insertions(+), 24 deletions(-) diff --git a/README.Rmd b/README.Rmd index c3b5b505..8318e4b6 100644 --- a/README.Rmd +++ b/README.Rmd @@ -66,10 +66,15 @@ Note that this is a toy example and not a true MSE, so the OM and EM structures First, we will load the `SSMSE` package and create a folder in which to run the example: ```{r, echo=FALSE, results="hide"} devtools::load_all(".") # for rendering this readme when it is in the SSMSE pkg +library(r4ss) +library(foreach) #if using run_parallel = TRUE +library(doParallel) #if using run_parallel = TRUE ``` ```{r, eval=FALSE} library(SSMSE) #load the package library(r4ss) #install using remotes::install_github("r4ss/r4ss@development) +library(foreach) #if using run_parallel = TRUE +library(doParallel) #if using run_parallel = TRUE ``` ```{r} # Create a folder for the output in the working directory. @@ -87,24 +92,37 @@ cod_1_path <- file.path(run_SSMSE_dir, "cod-1") # make model read initial values from control file and not ss.par start <- r4ss::SS_readstarter(file = file.path(cod_1_path, "starter.ss"), verbose = FALSE) start$init_values_src # verify reading from the control file -# change the natural mortality paramter from 0.2 to 0.1 in the control files +# change the steepness from 0.2 to 0.1 in the control files r4ss::SS_changepars(dir = cod_1_path, ctlfile = "control.ss_new", newctlfile = "control_modified.ss", strings = "SR_BH_steep", newvals = 1) -# remove files with M = 0.2 +parfile <- r4ss::SS_readpar_3.30(parfile = file.path(cod_1_path, "ss.par"), + datsource = file.path(cod_1_path, "ss3.dat"), + ctlsource = file.path(cod_1_path, "control.ss_new"), + verbose = FALSE) +# remove files with old steepness values file.remove(file.path(cod_1_path, "control.ss_new")) file.remove(file.path(cod_1_path, "control.ss")) file.remove(file.path(cod_1_path, "ss.par")) # delete control file because no longer need. -# rename file with M = 0.1 to control.ss_new () and make a copy as the control file +# rename file to control.ss_new () and make a copy as the control file file.rename(from = file.path(cod_1_path, "control_modified.ss"), to = file.path(cod_1_path, "control.ss")) ``` -Rerun this model with no estimation to get valid ss.par and control.ss_new files: +Rerun this model with no estimation to get valid ss.par and control.ss_new files, +then add in the historical recruitment deviations: ```{r, results = "hide"} -# run SS with no estimateion SSMSE:::run_ss_model(dir = cod_1_path, admb_options = "-maxfn 0 -phase 50 -nohess", verbose = FALSE) +# add back original recdevs into the model (b/c not specified through the ctl file) +new_parfile <- r4ss::SS_readpar_3.30(parfile = file.path(cod_1_path, "ss.par"), + datsource = file.path(cod_1_path, "ss3.dat"), + ctlsource = file.path(cod_1_path, "control.ss"), verbose = FALSE) + # add in the recdevs to new the parfile +new_parfile$recdev1[, "recdev"] <- parfile$recdev1[, "recdev"] +r4ss::SS_writepar_3.30(new_parfile, outfile = file.path(cod_1_path, "ss.par"), + verbose = FALSE) + ``` The argument `sample_struct` specifies the structure for sampling from the OM (and passing to the EM). The function `create_sample_struct` can be used to construct a simple sampling structure consistent with an input data file: @@ -133,8 +151,7 @@ We can now use `run_SSMSE` to run the MSE analysis loop: ```{r, warning = FALSE, message = FALSE} run_res_path <- file.path(run_SSMSE_dir, "results") dir.create(run_res_path) -# run 1 iteration and 1 scenario of SSMSE using an EM. -run_SSMSE(scen_name_vec = c("H-ctl", "H-1"), # name of the scenario +run_SSMSE(scen_name_vec = c("H-ctl", "H-1"),# name of the scenario out_dir_scen_vec = run_res_path, # directory in which to run the scenario iter_vec = c(5,5), # run with 5 iterations each OM_name_vec = NULL, # specify directories instead @@ -146,6 +163,7 @@ run_SSMSE(scen_name_vec = c("H-ctl", "H-1"), # name of the scenario nyrs_assess_vec = c(3, 3), # Years between assessments rec_dev_pattern = c("none"), # Don't use recruitment deviations impl_error_pattern = c("none"), # Don't use implementation error + run_parallel = TRUE, sample_struct_list = sample_struct_list, # How to sample data for running the EM. seed = 12345) #Set a fixed integer seed that allows replication ``` @@ -154,7 +172,7 @@ The function `SSMSE_summary_all` can be used to summarize the model results in a ```{r} # Summarize 1 iteration of output -summary <- SSMSE_summary_all(normalizePath(run_res_path)) +summary <- SSMSE_summary_all(run_res_path) ``` Plotting and data manipulation can then be done with these summaries. For example, SSB over time by model can be plotted. The models include the Operating Model (cod_OM), Estimation model (EM) for the historical period of years 0-100 (cod_EM_init), the EM run with last year of data in year 103 (cod_EM_103), and the EM run with last year of data in 106 (cod_EM_106). diff --git a/README.md b/README.md index e74db2b6..ff42b0b4 100644 --- a/README.md +++ b/README.md @@ -85,18 +85,18 @@ through year 106). First, we will load the `SSMSE` package and create a folder in which to run the example: - ## Loading SSMSE ``` r library(SSMSE) #load the package library(r4ss) #install using remotes::install_github("r4ss/r4ss@development) +library(foreach) #if using run_parallel = TRUE +library(doParallel) #if using run_parallel = TRUE ``` ``` r # Create a folder for the output in the working directory. run_SSMSE_dir <- file.path("run_SSMSE-ex") dir.create(run_SSMSE_dir) -## Warning in dir.create(run_SSMSE_dir): 'run_SSMSE-ex' already exists ``` The cod model with H = 0.65 is included as external package data. @@ -109,53 +109,62 @@ cod_mod_path <- system.file("extdata", "models", "cod", package = "SSMSE") file.copy(from = cod_mod_path, to = run_SSMSE_dir, recursive = TRUE) ## [1] TRUE file.rename(from = file.path(run_SSMSE_dir, "cod"), to = file.path(run_SSMSE_dir, "cod-1")) -## Warning in file.rename(from = file.path(run_SSMSE_dir, "cod"), to = -## file.path(run_SSMSE_dir, : cannot rename file 'run_SSMSE-ex/cod' to 'run_SSMSE- -## ex/cod-1', reason 'Access is denied' -## [1] FALSE +## [1] TRUE cod_1_path <- file.path(run_SSMSE_dir, "cod-1") # make model read initial values from control file and not ss.par start <- r4ss::SS_readstarter(file = file.path(cod_1_path, "starter.ss"), verbose = FALSE) start$init_values_src # verify reading from the control file ## [1] 0 -# change the natural mortality paramter from 0.2 to 0.1 in the control files +# change the steepness from 0.2 to 0.1 in the control files r4ss::SS_changepars(dir = cod_1_path, ctlfile = "control.ss_new", newctlfile = "control_modified.ss", strings = "SR_BH_steep", newvals = 1) ## parameter names in control file matching input vector 'strings' (n=1): ## [1] "SR_BH_steep" ## These are the ctl file lines as they currently exist: ## LO HI INIT PRIOR PR_SD PR_type PHASE env_var&link dev_link dev_minyr -## 107 0.2 1 1 0.7 0.05 0 -4 0 0 0 +## 107 0.2 1 0.65 0.7 0.05 0 -4 0 0 0 ## dev_maxyr dev_PH Block Block_Fxn Label Linenum ## 107 0 0 0 0 SR_BH_steep 107 ## line numbers in control file (n=1): ## 107 ## wrote new file to control_modified.ss with the following changes: ## oldvals newvals oldphase newphase oldlos newlos oldhis newhis oldprior -## 1 1 1 -4 -4 0.2 0.2 1 1 0.7 +## 1 0.65 1 -4 -4 0.2 0.2 1 1 0.7 ## newprior oldprsd newprsd oldprtype newprtype comment ## 1 0.7 0.05 0.05 0 0 # SR_BH_steep -# remove files with M = 0.2 +parfile <- r4ss::SS_readpar_3.30(parfile = file.path(cod_1_path, "ss.par"), + datsource = file.path(cod_1_path, "ss3.dat"), + ctlsource = file.path(cod_1_path, "control.ss_new"), + verbose = FALSE) +# remove files with old steepness values file.remove(file.path(cod_1_path, "control.ss_new")) ## [1] TRUE file.remove(file.path(cod_1_path, "control.ss")) ## [1] TRUE file.remove(file.path(cod_1_path, "ss.par")) # delete control file because no longer need. ## [1] TRUE -# rename file with M = 0.1 to control.ss_new () and make a copy as the control file +# rename file to control.ss_new () and make a copy as the control file file.rename(from = file.path(cod_1_path, "control_modified.ss"), to = file.path(cod_1_path, "control.ss")) ## [1] TRUE ``` Rerun this model with no estimation to get valid ss.par and -control.ss\_new files: +control.ss\_new files, then add in the historical recruitment +deviations: ``` r -# run SS with no estimateion SSMSE:::run_ss_model(dir = cod_1_path, admb_options = "-maxfn 0 -phase 50 -nohess", verbose = FALSE) +# add back original recdevs into the model (b/c not specified through the ctl file) +new_parfile <- r4ss::SS_readpar_3.30(parfile = file.path(cod_1_path, "ss.par"), + datsource = file.path(cod_1_path, "ss3.dat"), + ctlsource = file.path(cod_1_path, "control.ss"), verbose = FALSE) + # add in the recdevs to new the parfile +new_parfile$recdev1[, "recdev"] <- parfile$recdev1[, "recdev"] +r4ss::SS_writepar_3.30(new_parfile, outfile = file.path(cod_1_path, "ss.par"), + verbose = FALSE) ``` The argument `sample_struct` specifies the structure for sampling from @@ -219,8 +228,7 @@ We can now use `run_SSMSE` to run the MSE analysis loop: ``` r run_res_path <- file.path(run_SSMSE_dir, "results") dir.create(run_res_path) -# run 1 iteration and 1 scenario of SSMSE using an EM. -run_SSMSE(scen_name_vec = c("H-ctl", "H-1"), # name of the scenario +run_SSMSE(scen_name_vec = c("H-ctl", "H-1"),# name of the scenario out_dir_scen_vec = run_res_path, # directory in which to run the scenario iter_vec = c(5,5), # run with 5 iterations each OM_name_vec = NULL, # specify directories instead @@ -232,6 +240,7 @@ run_SSMSE(scen_name_vec = c("H-ctl", "H-1"), # name of the scenario nyrs_assess_vec = c(3, 3), # Years between assessments rec_dev_pattern = c("none"), # Don't use recruitment deviations impl_error_pattern = c("none"), # Don't use implementation error + run_parallel = TRUE, sample_struct_list = sample_struct_list, # How to sample data for running the EM. seed = 12345) #Set a fixed integer seed that allows replication ``` @@ -249,7 +258,7 @@ should be installed automatically when SSMSE is downloaded. ``` r # Summarize 1 iteration of output -summary <- SSMSE_summary_all(normalizePath(run_res_path)) +summary <- SSMSE_summary_all(run_res_path) ## Extracting results from 2 scenarios ## Starting H-1 with 5 iterations ## Starting H-ctl with 5 iterations diff --git a/man/figures/README-plot_SSB-1.png b/man/figures/README-plot_SSB-1.png index 6ac923130afafcc469b66d016e573e838ec68778..d1c120e8dde8a1edcc18e16b35e19bac670c06a1 100644 GIT binary patch literal 9417 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 literal 9526 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