[feat] Extract and format data for asar to SIS function

NAMESPACE

@@ -5,6 +5,7 @@ export(create_latex_table)
 export(create_rda)
 export(export_rda)
 export(extract_caps_alttext)
+export(extract_sis_data)
 export(filter_data)
 export(plot_aa)
 export(plot_abundance_at_age)

inst/WORDLIST

@@ -1,8 +1,12 @@
 BAM
+BMSY
 Birthseason
 CPUE
 FIMS
-FIMSdiags
+FLIMIT
+FMSY
+FTARGET
+Fmort
 Hennen
 Lifecycle
 MSY
@@ -12,13 +16,17 @@ ORCID
 Petrale
 Pre
 Preformatted
+Rceattle
 Rda
 Rmarkdown
 Rmd
+Spawners
+StockSmart
 Subseason
 aa
 alttext
 asar
+assmt
 bam
 birthseas
 cha
@@ -40,7 +48,6 @@ gp
 hline
 href
 is’
-kable
 kableExtra
 kobe
 kqs
@@ -52,7 +59,6 @@ nsim
 obsvpred
 pkgdown
 preformatted
-qmd
 rceattle
 rda
 rda's

inst/resources/sis_assmt_template.csv

@@ -0,0 +1,77 @@
+Variable,Explanation,Optional,Default,Value
+model_identifier,"Argument used to distinguish between base model and a new, updated model sent in subsequent submission. Options: 'base', 'updated_model_1', 'updated_model_2', etc.",YES,base,
+AS_POINT_OF_CONTACT,"The lead/corresponding author for a stock assessment, formatted as an email address.",NO,None,
+AS_CATCH_DATA,"Categorical classification describing the availability of catch data for use in the stock assessment. This level should be based on the data that was actually used in the final version of the assessment model. Options: 0 (No quantitative catch data available), 1 (Some catch data, but major gaps for some fishery sectors or historical periods), 2 (Enough catch data to establish magnitude/trends for a major fishery sector for data-limited methods or closed fisheries), 3 (Catch data generally available for all sectors, but some gaps exist), 4 (No data gaps substantially impede assessment, but catch is not without uncertainty), 5 (Very complete knowledge of total catch).",NO,None,
+AS_ABUNDANCE_DATA,"Categorical classification describing the availability of abundance data for use in the stock assessment. This level should be based on the data that was actually used in the final version of the assessment model. Options: 0 (No indicator of stock abundance/trend), 1 (Fishery-dependent CPUE available with high uncertainty, or expert opinion), 2 (Fishery-dependent CPUE sufficiently standardized for full assessments; no/insufficient fishery-independent data), 3 (Limited fishery-independent survey(s) provide relative abundance; limited spatiotemporal coverage or high variability), 4 (Complete fishery-independent survey(s) provide relative abundance covering large spatial extent over several years), 5 (Calibrated fishery-independent survey(s) or tag-recapture provide absolute abundance).",NO,None,
+AS_BIOLOGICAL_DATA,"Categorical classification describing the availability of biological/life history data for use in the stock assessment. This level should be based on the data that was actually used in the final version of the assessment model. Options: 0 (No life history data), 1 (Most life history factors not based on empirical data; derived using proxies/meta-analyses/borrowed), 2 (Some factors based on empirical data, but at least one derived via proxies/meta-analyses/borrowed), 3 (Most factors based on stock-specific empirical data), 4 (Data sufficient to track changes over time in at least growth), 5 (No major gaps in life history knowledge).",NO,None,
+AS_ECOSYSTEM_DATA,"Categorical classification describing the usage of ecosystem linkage data in the stock assessment. This level should be based on the data that was actually used in the final version of the assessment model. Options: 0 (No linkage/consideration of ecosystem dynamic/properties), 1 (Ecosystem-based hypotheses inform structure/inputs, but no explicit linkage to drivers), 2 (Includes some form of variability/effect to account for unidentified ecosystem dynamics), 3 (One or more features linked to dynamic data from environment, climate, habitat, or predator-prey), 4 (Linked to dynamic data supported directly by process studies), 5 (Configured to be coupled or linked with an ecosystem process).",NO,None,
+AS_COMP_DATA,"Categorical classification describing the availability of size/age composition data for use in the stock assessment. This level should be based on the data that was actually used in the final version of the assessment model. Options: 0 (No composition data collected), 1 (Some collected, but major gaps and not used), 2 (Enough collected to enable data-limited approaches), 3 (Enough collected over sufficient time series to be informative in age/size structured models), 4 (Enough age composition collected over sufficient time series to enable age-structured methods), 5 (Very complete age and size composition data).",NO,None,
+AS_MODEL_CAT,"Category of model used to complete the stock assessment (see Table 5.1; NOAA, 2018). Focuses on population dynamics structure, data requirements, and management advice types. If an ensemble approach was used, select the highest category describing one or more models in the ensemble. Options: 1 (Data-limited), 2 (Index-based), 3 (Aggregate Biomass Dynamics), 4 (Virtual Population Analysis), 5 (Statistical Catch-at-Length), 6 (Statistical Catch-at-Age).",NO,None,
+AS_TYPE,"Type of stock assessment, with regards to approach, technique, effort level, and complexity (NOAA, 2018). Assigned automatically by SIS. Options: 'Research Stock Assessment' (development/revision of data type/method), 'Research/Operational Stock Assessment' (management advice + substantial revision), 'Operational Assessment' (scientific advice focusing on stock status/catch limits), 'Stock Monitoring Update' (stock-level advice between assessments without changes to methods/data).",NO,None,
+AS_REVIEW_TYPE,"Final status of the assessment, chosen from a set of values found in the SIS manual. Options: 1 (Not Reviewed), 2 (Accept Previous Approach, Remand New Attempt), 3 (Full Acceptance), 4 (Partial Acceptance, Fishing Mortality Estimates), 5 (Partial Acceptance, Biomass Estimates), 6 (Partial Acceptance, Status Determinations Only), 7 (Reject, Data Insufficient for Assessment), 8 (Reject, Results Too Uncertain To Be Considered Accurate), 9 (Remand).",NO,None,
+ASSESSMENT_ID,Unique numeric identifier assigned to all stock assessment records. Assigned automatically by SIS.,NO,None,
+ENTITY_ID,Entity unique identifier value. Assigned automatically by SIS.,NO,None,
+AS_YEAR,Year the assessment was completed. Assigned automatically by SIS.,NO,None,
+AS_MONTH,Month the assessment was completed. Assigned automatically by SIS.,NO,None,
+AS_LAST_DATA_YEAR,Year of the 'latest' data used in the assessment.,NO,Extracted as F.end.year from key_quantities.csv,
+AS_B_BASIS,"The basis of the biomass unit. Options: Spawning Stock Biomass, Total Stock Biomass, Survey-Estimated Biomass, Escapement, Stock Reproductive Output, Survey Index, Total Stock Abundance.",NO,None,
+AS_F_BASIS,"The basis of the Fishing Mortality unit. Options: 1 (Max F at Age), 2 (F for Fully-Selected Fish), 3 (Catch / Biomass), 4 (Catch / Exploitable Biomass), 5 (Catch), 6 (Fishing Intensity), 7 (True F).",NO,None,
+AS_FMSY,Estimated and/or calculated value of Fishing Mortality at MSY.,NO,Extracted as F.MSY.terminal from key_quantities.csv,
+AS_F_FLIMIT_RATIO,The ratio of F / Flimit (i.e., AS_F_BEST / AS_FLIMIT). Automatically calculated by SIS but user can provide if desired.,YES,NULL,
+AS_F_BEST,"Best estimate of Fishing Mortality. Typically, Best F = Terminal F for the stock assessment unless transformed (e.g., averaging or retrospective adjustment).",NO,Extracted as F.terminal.est from key_quantities.csv,
+AS_FLIMIT_BASIS,"Basis for the recommended fishing mortality limit, calculated or directly estimated. Only utilized in Alaska as assessments utilize catch projections in the current year. Most stocks utilize Flimit = Fmsy. Example: 'F from 2024 asmt corresponding to 2023 OFL'.",YES,NULL,
+AS_B_YEAR,Year of the Biomass estimate for the stock.,NO,Extracted as B.terminal.year from key_quantities.csv,
+AS_B_MAX,Maximum estimated value within the approved confidence interval of the Biomass estimate. Equivalent to the value of Best B Confidence Interval Upper estimate.,NO,Extracted as B.terminal.max from key_quantities.csv,
+AS_BMSY,"Estimated stock size that would, on average, produce the maximum sustainable yield when fished at a level equal to FMSY.",NO,Extracted as B.msy from key_quantities.csv,
+AS_B_BMSY_RATIO,Ratio of B / Bmsy (i.e., AS_B_BEST / AS_BMSY). Automatically calculated by SIS but user can provide if desired.,YES,NULL,
+AS_STOCK_LEVEL_BMSY,"Whether the stock is above, near, or below Bmsy based upon the value provided in the AS_B_BMSY_RATIO field. Automatically calculated by SIS but user can provide if desired. Options: 'Above', 'Near' (between 80% and 99%), 'Below' (<80%).",YES,NULL,
+AS_B_MIN,Minimum estimated value within the approved confidence interval of the Biomass estimate. Equivalent to the value of Best B Confidence Interval Lower estimate.,NO,Extracted as B.terminal.max from key_quantities.csv,
+AS_B_BEST,"Best estimate of Biomass. Typically, Best B = Terminal B for the stock assessment unless transformed (e.g., averaging or retrospective adjustment).",NO,Extracted as B.terminal.est from key_quantities.csv,
+AS_BMSY_BASIS,Basis for the estimated BMSY value. Example: 'B35%'.,NO,None,
+AS_FMSY_BASIS,"Estimated fishing mortality rate that, on average, would produce the maximum sustainable yield from a stock at BMSY. Example: 'F35% as proxy'.",NO,None,
+AS_F_FMSY_RATIO,The ratio of F / Fmsy (i.e., AS_F_BEST / AS_FMSY). Automatically calculated by SIS but user can provide if desired.,YES,NULL,
+AS_FLIMIT,"Recommended fishing mortality limit from the assessment, above which the stock would be considered to be experiencing overfishing.",NO,Extracted as F.limit from key_quantities.csv,
+AS_F_YEAR,Terminal year estimate of stock Fishing Mortality. Always corresponds to the year of the Best estimate of Fishing Mortality (AS_F_BEST).,NO,Extracted as F.terminal.year from key_quantities.csv,
+AS_F_UNIT,"Unit of measure corresponding to the fishing mortality estimate. Linked to F Basis selections. Options: 1 (Apical F = Max F at Age), 2 (Fully-selected F = F for Fully-Selected Fish), 3 (Exploitation Rate = Catch / Biomass), 4 (Relative F = Catch / Exploitable Biomass), 5 (Metric Tons = Catch), 6 (1 - SPR = Fishing Intensity), 7 (F = Z - M = True F).",NO,None,
+AS_B_UNIT,"Unit of measure corresponding to the biomass estimate. Linked to B Basis selections. Options: 1 (Metric Tons = SSB / Total Biomass / Survey-Estimated Biomass), 2 (Thousand Metric Tons = SSB / Total Biomass / Survey-Estimated Biomass), 3 (Adult spawners - Natural & Hatchery - Escapement), 4 (Adult spawners - Hatchery - Escapement), 5 (Adult spawners - Natural - Escapement), 6 (Number of Eggs - Stock Reproductive Output), 7 (kg / tow - Survey Index), 8 (Number of Fish - Total Stock Abundance).",NO,None,
+AS_MODEL,Model software package used to complete the final version of the assessment. Example: 'SS'.,NO,None,
+AS_MODEL_VERSION,Version of the software package used to complete the final stock assessment. Example: '3.30.22'.,NO,None,
+AS_ENSEMBLE_FLAG,"Whether the assessment was completed using an ensemble or multimodeling approach. Options: 'Y' (yes), 'N' (no).",NO,None,
+AS_F_TRANSFORM,"Indicator identifying Fishing Mortality best estimates that include terminal year transformations (e.g., retrospective corrections or multi-year averaging). Options: 'Y' (yes), 'N' (no).",NO,None,
+AS_B_RANGE_BASIS,"Approach used to calculate the confidence intervals provided for the stock assessment. Options: 'Asymptotic', 'Credible', 'Bootstrapped', user-specified.",YES,NULL,
+AS_B_RANGE,Percentile range of the confidence intervals provided for the stock assessment.,YES,95,
+AS_B_TRANSFORM,"Indicator identifying Biomass best estimates that include terminal year transformations (e.g., retrospective corrections or multi-year averaging). Options: 'Y' (yes), 'N' (no).",NO,None,
+AS_F_MAX,Maximum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to Best F CI Upper estimate.,NO,Extracted as F.terminal.max from key_quantities.csv,
+AS_F_MIN,Minimum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to Best F CI Lower estimate.,NO,Extracted as F.terminal.min from key_quantities.csv,
+AS_F_RANGE_BASIS,"Approach used to calculate the confidence intervals provided for the stock assessment. Options: 'Asymptotic', 'Credible', 'Bootstrapped', user-specified.",YES,NULL,
+AS_F_RANGE,Percentile range of the confidence intervals provided for the stock assessment.,YES,95,
+AS_FMSY_MAX,Maximum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to Fmsy CI Upper estimate.,NO,Extracted as F.MSY.terminal.max from key_quantities.csv,
+AS_FMSY_MIN,Minimum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to Fmsy CI Lower estimate.,NO,Extracted as F.MSY.terminal.min from key_quantities.csv,
+AS_FMSY_RANGE_BASIS,"Approach used to calculate the confidence intervals provided for the stock assessment. Options: 'Asymptotic', 'Credible', 'Bootstrapped', user-specified.",YES,NULL,
+AS_FMSY_RANGE,Percentile range of the confidence intervals provided for the stock assessment.,YES,95,
+AS_FTARGET,Value of the Ftarget estimate produced by a stock assessment. Often used for stocks in a rebuilding plan.,NO,Extracted as F.target from key_quantities.csv,
+AS_FTARGET_BASIS,Approach used to calculate the Ftarget estimate produced by a stock assessment.,NO,None,
+AS_MSY,Value of the MSY estimated by the assessment.,NO,None,
+AS_MSY_UNIT,"Unit associated with the MSY value. Options: Metric tons, Thousand metric tons, lbs, Thousand lbs, Number of fish.",NO,None,
+AS_MSY_MAX,Maximum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to MSY CI Upper estimate.,NO,None,
+AS_MSY_MIN,Minimum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to MSY CI Lower estimate.,NO,None,
+AS_MSY_RANGE_BASIS,"Approach used to calculate the confidence intervals provided for the stock assessment. Options: 'Asymptotic', 'Credible', 'Bootstrapped', user-specified.",YES,NULL,
+AS_MSY_RANGE,Percentile range of the confidence intervals provided for the stock assessment.,YES,95,
+AS_BMSY_MAX,Maximum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to Bmsy CI Upper estimate.,NO,Extracted as B.msy.max from key_quantities.csv,
+AS_BMSY_MIN,Minimum estimated value within the approved confidence interval of the Fishing Mortality estimate. Equivalent to Bmsy CI Lower estimate.,NO,Extracted as B.msy.min from key_quantities.csv,
+AS_BMSY_RANGE_BASIS,"Approach used to calculate the confidence intervals provided for the stock assessment. Options: 'Asymptotic', 'Credible', 'Bootstrapped', user-specified.",YES,NULL,
+AS_BMSY_RANGE,Percentile range of the confidence intervals provided for the stock assessment.,YES,95,
+AS_BLIMIT,"Stock size threshold, below which the stock is considered to be overfished.",NO,None,
+AS_BLIMIT_BASIS,"Basis for the Blimit estimate. Examples: (0.7*Bmsy), B25%, etc.",NO,None,
+AS_B_COMMENT,"Specific comments associated with the best estimate of biomass for this assessment. 1,000 character limit.",NO,None,
+AS_F_COMMENT,"Specific comments associated with the best estimate of fishing mortality for this assessment. 1,000 character limit.",NO,None,
+AS_IAS_FLIMIT,International commission F limit estimate.,YES,NULL,
+AS_IAS_FLIMIT_BASIS,International commission estimate of Flimit estimation method. Example: 'msy'.,YES,NULL,
+AS_IAS_FMSY,International commission estimate of Fmsy.,YES,NULL,
+AS_IAS_FMSY_BASIS,International commission estimate of Fmsy estimation method.,YES,NULL,
+AS_IAS_FTARGET,International commission estimate of Ftarget.,YES,NULL,
+AS_IAS_FTARGET_BASIS,International commission estimate of Ftarget estimation method.,YES,NULL,
+AS_IAS_BLIMIT,International commission biomass limit estimate.,YES,NULL,
+AS_IAS_BLIMIT_BASIS,International commission estimate of Blimit estimation method.,YES,NULL,
+AS_IAS_BMSY,International commission estimate of Bmsy.,YES,NULL,
+AS_IAS_BMSY_BASIS,International commission estimate of Bmsy estimation method.,YES,NULL,

inst/resources/sis_ts_template.csv

@@ -0,0 +1 @@
+Year,Category,Primary,Description,Unit,Value

pkgdown/_pkgdown.yml

@@ -27,6 +27,8 @@ navbar:
         href: articles/how-caps-alttext-are-made.html
       - text: Standardizing Assessment Model Output
         href: articles/convert_output_details.html
+      - text: Automating data extraction for SIS
+        href: articles/extract-sis-data.html
 
     cheatsheet:
       text: Cheatsheet

tests/testthat/test-extract_sis_data.R

@@ -0,0 +1,48 @@
+test_that("extract_sis_data() runs with all possible rdas present", {
+  save_all_plots(stockplotr::example_data)
+  table_total_catch(stockplotr::example_data,
+                    module = "TIME_SERIES",
+                    interactive = FALSE,
+                    make_rda = TRUE)
+
+  files <- c(
+    fs::path("figures",
+             c("biomass_figure.rda", "spawning_biomass_figure.rda", "abundance_at_age_figure.rda", "fishing_mortality_figure.rda",  "index_figure.rda")
+             ),
+    fs::path("tables",
+             "total_catch_table.rda")
+  )
+
+  expect_true(all(file.exists(files)))
+
+  extract_sis_data()
+
+  # erase temporary testing files
+  file.remove(fs::path(getwd(), "sis_assmt_template.csv"))
+  file.remove(fs::path(getwd(), "sis_ts_template.csv"))
+  file.remove(fs::path(getwd(), "captions_alt_text.csv"))
+  file.remove(fs::path(getwd(), "key_quantities.csv"))
+  unlink(fs::path(getwd(), "figures"), recursive = T)
+  unlink(fs::path(getwd(), "tables"), recursive = T)
+})
+
+test_that("extract_sis_data() runs with some of all possible rdas present", {
+  plot_biomass(stockplotr::example_data, module = "TIME_SERIES", interactive = FALSE, make_rda = TRUE)
+  plot_fishing_mortality(stockplotr::example_data, interactive = FALSE, make_rda = TRUE)
+  expect_no_error(extract_sis_data())
+
+  # test that extract_sis_data() exports csvs
+  expect_true(file.exists(fs::path(getwd(), "sis_assmt_template.csv")))
+  expect_true(file.exists(fs::path(getwd(), "sis_ts_template.csv")))
+
+  # erase temporary testing files
+  file.remove(fs::path(getwd(), "sis_assmt_template.csv"))
+  file.remove(fs::path(getwd(), "sis_ts_template.csv"))
+  file.remove(fs::path(getwd(), "captions_alt_text.csv"))
+  file.remove(fs::path(getwd(), "key_quantities.csv"))
+  unlink(fs::path(getwd(), "figures"), recursive = T)
+})
+
+test_that("extract_sis_data() fails with no rdas present", {
+  expect_error(extract_sis_data())
+})