Merge branch 'val-additonnal-comments' into main

.github/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to sspm
+
+This outlines how to propose a change to sspm. 
+For more detailed info about contributing to this, and other tidyverse packages, please see the
+[**development contributing guide**](https://rstd.io/tidy-contrib). 
+
+## Fixing typos
+
+You can fix typos, spelling mistakes, or grammatical errors in the documentation directly using the GitHub web interface, as long as the changes are made in the _source_ file. 
+This generally means you'll need to edit [roxygen2 comments](https://roxygen2.r-lib.org/articles/roxygen2.html) in an `.R`, not a `.Rd` file. 
+You can find the `.R` file that generates the `.Rd` by reading the comment in the first line.
+
+## Bigger changes
+
+If you want to make a bigger change, it's a good idea to first file an issue and make sure someone from the team agrees that it’s needed. 
+If you’ve found a bug, please file an issue that illustrates the bug with a minimal 
+[reprex](https://www.tidyverse.org/help/#reprex) (this will also help you write a unit test, if needed).
+
+### Pull request process
+
+*   Fork the package and clone onto your computer. If you haven't done this before, we recommend using `usethis::create_from_github("pedersen-fisheries-lab/sspm", fork = TRUE)`.
+
+*   Install all development dependencies with `devtools::install_dev_deps()`, and then make sure the package passes R CMD check by running `devtools::check()`. 
+    If R CMD check doesn't pass cleanly, it's a good idea to ask for help before continuing. 
+*   Create a Git branch for your pull request (PR). We recommend using `usethis::pr_init("brief-description-of-change")`.
+
+*   Make your changes, commit to git, and then create a PR by running `usethis::pr_push()`, and following the prompts in your browser.
+    The title of your PR should briefly describe the change.
+    The body of your PR should contain `Fixes #issue-number`.
+
+*  For user-facing changes, add a bullet to the top of `NEWS.md` (i.e. just below the first header). Follow the style described in <https://style.tidyverse.org/news.html>.
+
+### Code style
+
+*   New code should follow the tidyverse [style guide](https://style.tidyverse.org). 
+    You can use the [styler](https://CRAN.R-project.org/package=styler) package to apply these styles, but please don't restyle code that has nothing to do with your PR.  
+
+*  We use [roxygen2](https://cran.r-project.org/package=roxygen2), with [Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd-formatting.html), for documentation.  
+
+*  We use [testthat](https://cran.r-project.org/package=testthat) for unit tests. 
+   Contributions with test cases included are easier to accept.  
+
+## Code of Conduct
+
+Please note that the sspm project is released with a
+[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to this
+project you agree to abide by its terms.

README.Rmd

@@ -110,6 +110,12 @@ in spatial capacity, however):
 -   [`openmse`](https://openmse.com/features-assessment-models/3-sp/)
 -   [`TropFishR`](https://github.com/tokami/TropFishR)
 
+## Issues and support
+
+If you have found an issue with this package or are seeking support,
+open an issue on this repository describing the problem and including a
+minimal reproducible example.
+
 ## Cite this package
 
 You can cite this package like this "we ran a spatial surplus production
@@ -125,9 +131,9 @@ full bibliographic reference to include in your reference list
 Or see the [package citation
 page](https://pedersen-fisheries-lab.github.io/sspm/authors.html#citation).
 
-## Code of Conduct 
+## Code of Conduct
 
 Please note that the sspm project is released with a [Contributor Code
 of
-Conduct]([https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).)
+Conduct](%5Bhttps://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).](<https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html>).)
 By contributing to this project, you agree to abide by its terms.

README.md

@@ -95,6 +95,12 @@ in spatial capacity, however):
 - [`openmse`](https://openmse.com/features-assessment-models/3-sp/)
 - [`TropFishR`](https://github.com/tokami/TropFishR)
 
+## Issues and support
+
+If you have found an issue with this package or are seeking support,
+open an issue on this repository describing the problem and including a
+minimal reproducible example.
+
 ## Cite this package
 
 You can cite this package like this “we ran a spatial surplus production
@@ -109,3 +115,10 @@ full bibliographic reference to include in your reference list
 
 Or see the [package citation
 page](https://pedersen-fisheries-lab.github.io/sspm/authors.html#citation).
+
+## Code of Conduct
+
+Please note that the sspm project is released with a [Contributor Code
+of
+Conduct](%5Bhttps://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).\](<https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html>).)
+By contributing to this project, you agree to abide by its terms.

paper/paper.bib

@@ -205,7 +205,7 @@ @article{berkes_implementing_2012
 }
 
 @article{crowder_impacts_2008,
-	title = {The {Impacts} of {Fisheries} on {Marine} {Ecosystems} and the {Transition} to {Ecosystem}-{Based} {Management}},
+	title = {The impacts of fisheries on marine ecosystems and the transition to ecosystem-based management},
 	volume = {39},
 	url = {https://doi.org/10.1146/annurev.ecolsys.39.110707.173406},
 	doi = {10.1146/annurev.ecolsys.39.110707.173406},
@@ -243,7 +243,7 @@ @article{zhang_longer_2021
 
 @article{prager_suite_1994,
 	title = {A suite of extensions to a nonequilibrium surplus-production},
-	journal = {Fishery Bulletin - National Oceanic and Atmospheric Administration},
+	journal = {Fishery Bulletin},
 	language = {en},
 	author = {Prager, Michael H},
 	year = {1994},

paper/paper.md

@@ -1,6 +1,5 @@
 ---
-title: 'The sspm R package: spatial surplus production models for the management of
-  northern shrimp fisheries'
+title: 'The sspm R package for spatially-explicit surplus production population models'
 tags:
 - R
 - fisheries
@@ -28,21 +27,21 @@ affiliations:
 
 # Statement of need
 
-Population models are important tools for making management decisions, especially in fisheries, where predictive methods like Surplus Productivity Models (SPMs) are widely used. Fisheries analysts and managers often lack user-friendly, flexible tools to implement and apply SPMs. In addition, SPMs are rarely spatially explicit and usually cannot account for relevant ecosystem drivers. Therefore, there is a need for tools that implement spatially explicit surplus production models (SSPMs). The Northern Shrimp stock in the Newfoundland and Labrador Shelves is an example of a stock in need of an SSPM that can integrate important spatially-structured ecosystem drivers.
+Population models are important tools for making management decisions, especially in fisheries, where predictive methods like Surplus Production Models (SPMs) are widely used. Fisheries analysts and managers often lack user-friendly, flexible tools to implement and apply SPMs. In addition, SPMs are rarely spatially explicit and usually cannot account for relevant ecosystem drivers. Therefore, there is a need for tools that implement spatially explicit surplus production models (SSPMs). The Northern Shrimp stock in the Newfoundland and Labrador Shelves is an example of a stock in need of an SSPM that can integrate important spatially-structured ecosystem drivers.
 
 # Summary
 
 <!-- Pop models are important tools in fisheries science, but most are obsolete as they fail to account for ecosystem variables and spatio-temporal dynamics -->
 
-Population modelling is an exercise of interest within environmental sciences and adjacent fields. Early population models such as the logistic model assumed that while the abundance of a population might change over time, the conditions governing parameters affecting that rate of change, such as the maximum rate of growth or the carrying capacity of the population, stay constant over time [@gotelli_primer_2008]. Modern population models increasingly acknowledge the non-stationary nature of wild populations and work to incorporate environmental fluctuations into dynamic models [@thorson_importance_2015; @thorson_using_2017]. Population models designed to answer applied resource management questions, such as fisheries stock models, increasingly address how the dynamics of stocks vary across space and time. 
+Population modelling is an exercise of interest within environmental sciences and adjacent fields. Early population models such as the logistic model assumed that while the abundance of a population might change over time, the conditions governing parameters affecting that rate of change, such as the maximum rate of growth or the carrying capacity of the population, stay constant over time [@gotelli_primer_2008]. Modern population models increasingly acknowledge the non-stationary nature of wild populations and work to incorporate environmental fluctuations into dynamic models [@thorson_importance_2015; @thorson_using_2017]. Population models designed to answer applied resource management questions, such as fisheries assessment models, increasingly address how the dynamics of stocks vary across space and time. 
 
 Resource managers are becoming increasingly interested in how variation in ecosystem factors such as predator abundance and abiotic variables impact the spatiotemporal variability of population parameters, such as productivity [@zhang_longer_2021; @szuwalski_climate_2016]. Further, treating spatially structured stocks as single unstructured stocks can lead to substantially biased estimates of population change [@thorson_importance_2015]. However, stock models that explicitly incorporate spatial dynamics and time-varying ecosystem variables are still rare in fisheries science, despite the push for more ecosystem-based management methods in fisheries management [@crowder_impacts_2008; @berkes_implementing_2012; @tam_towards_2017]. 
 
 <!-- SPMs are simple, old pop models, in need of updating to account for the non-stationarity of the mechanisms that maintain stocks -->
 
 Surplus production models (SPMs) are one of the classic models used in fisheries and are based on modelling changes in the total biomass of a stock in a given location over time as a function of current stock abundance and fishing pressure [@walters_surplus_2008]. Classically, SPMs assume single unstructured stocks with purely logistic dynamics [@walters_surplus_2008] and, as such, have been of limited use for modelling more complex stocks. They are useful in data-poor contexts where the age structure of the population is not accessible or when age or length structure do not change substantially over time [@prager_suite_1994; @punt_extending_2003]. SPMs typically model spatially constant productivity. They also assume that populations are only affected by past abundance and fishing, which ignores stressors like climate change which affect growth rates independently of fishing pressure.
 
-In the context of global warming and shifting ranges, fisheries productivity is likely to be a moving target [@karp_accounting_2019], and managers need better methods that account for varying productivity [@szuwalski_climate_2016]. The Northern Shrimp (*Pandalus borealis*) in the Newfoundland and Labrador Shelves, which has undergone several periods of large-scale biomass change in the last two decades, despite a relatively constant harvest regime, is a prime example of a population thought to be affected by environmental conditions [@dfo_assessment_2019]. These populations currently lack a population model to understand the drivers of this change and to predict how fishing pressure and changing environmental conditions may affect future abundance, which managers are advised to account for.
+In the context of climate change and shifting ranges, fisheries productivity is likely to be a moving target [@karp_accounting_2019], and managers need better methods that account for varying productivity [@szuwalski_climate_2016]. The Northern Shrimp (*Pandalus borealis*) in the Newfoundland and Labrador Shelves, which has undergone several periods of large-scale biomass change in the last two decades, despite a relatively constant harvest regime, is a prime example of a population thought to be affected by environmental conditions [@dfo_assessment_2019]. These populations currently lack a population model to understand the drivers of this change and to predict how fishing pressure and changing environmental conditions may affect future abundance, which managers are advised to account for.
 
 <!-- Any pop models, including SPMs, can either be process based or statistical: we decide to implement a statistical approach so that we can benefit from confidence intervals -->
 
@@ -52,7 +51,7 @@ We have chosen a statistical approach to fitting SPMs. Statistical models allow
 
 In this paper, we use a statistical approach to fitting SPMs using Generalized Additive Models (GAMS), estimated using the `mgcv` R package [@wood_generalized_2017] as the backend. We apply this approach to the population of Northern Shrimp of the Newfoundland and Labrador Shelves, leveraging the smoothing properties of GAMs to account for varying productivity across time and space. The resulting model is a spatial SPM (SSPM), implemented via an R package: `sspm`.
 
-The R package `sspm` is designed to make spatially-explicit surplus production models (SSPM) simpler to estimate and apply to any spatially structured stock. The basic model it implements was first used to model time-varying production in Newfoundland and Labrador Northern Shrimp stocks [@pedersenNewSpatialEcosystembased2021]. However, the general modelling approach used here will work for any spatially structured fishery with sufficient data. It includes a range of features to manipulate harvest and biomass data. Those features are organized in a stepwise workflow, whose implementation is described in more detail in \autoref{fig:workflow} and in the next section.
+The R package `sspm` is designed to make SSPMs simpler to estimate and apply to any spatially structured stock. The basic model this packages implements was first used to model time-varying production in Newfoundland and Labrador Northern Shrimp stocks [@pedersenNewSpatialEcosystembased2021]. However, the general modelling approach used here will work for any spatially structured fishery with sufficient data. It includes a range of features to manipulate harvest and biomass data. Those features are organized in a stepwise workflow, whose implementation is described in more detail in \autoref{fig:workflow} and in the next section.
 
 Although it was developed in a fisheries context, the package is suited to model spatially-structured population dynamics in general.
 
@@ -67,8 +66,8 @@ The key workflow steps are:
 	2. The region within the boundary is discretized into patches with the `spm_discretize()` function, creating a `sspm_discrete_boundary` object.
 
 * Spatiotemporal smoothing of biomass and environmental predictors using GAMs.
-	3. The `spm_as_dataset()` function turns user-provided data frames of raw observations into `sspm_dataset` objects that explicitly track locations, data types, and aggregation scales for each input. `sspm` recognizes three types of data: **trawl** (i.e. biomass estimates from scientific surveys), **predictors**, and **catch** (i.e., harvest). 
-	4. The `spm_smooth()` uses GAMs to calculate spatially smoothed yearly estimates of biomass and environmental predictors for each patch from trawl-level data, based on the spatial structure from the `sspm_discrete_boundary` object. The user specifies a GAM formula with custom smooth terms. The output is another `sspm_dataset` object with a `smoothed_data` slot which contains the smoothed predictions for all patches.
+	3. The `spm_as_dataset()` function turns user-provided data frames of raw observations into `sspm_dataset` objects that explicitly track locations, data types, and aggregation scales for each input. `sspm` recognizes three types of data: **trawl** (i.e., biomass estimates from scientific surveys), **predictors**, and **catch** (i.e., harvest). 
+	4. The `spm_smooth()` function uses GAMs to calculate spatially smoothed yearly estimates of biomass and environmental predictors for each patch from trawl-level data, based on the spatial structure from the `sspm_discrete_boundary` object. The user specifies a GAM formula with custom smooth terms. The output is another `sspm_dataset` object with a `smoothed_data` slot which contains the smoothed predictions for all patches.
 
 * Computation of surplus production based on biomass density and fishing effort.
 	5. The `spm_aggregate_catch()` function aggregates catch into patches and years and calculates patch-specific productivity for each year as the ratio of estimated biomass density plus catch from the next year divided by estimated biomass density of the current year. The result is returned as a `sspm_dataset`.
@@ -85,7 +84,7 @@ The key workflow steps are:
 
 # Connections to other surplus-production based stock assessment approaches
 
-The `sspm` package uses a model-based, random-effects based approach to estimate the effects of ecosystem drivers on surplus production across space and time. Our approach is conceptually related to the stochastic stock assessment approaches used by the R packages `spict` [@pedersen_stochastic_2017] and `jabba` [@winker_jabba_2018] R packages for surplus production modelling, in that we assume that biomass dynamics can be modelled as effectively a logistic growth model with both process and measurement error. While `sspm` does not currently have the capacity to model biomass dynamics as a continuous-time process, as with `spict`, or incorporate prior parameter information on catchability or biomass dynamics as in `jabba`, `sspm` can model spatially and temporally varying productivity, which is currently not possible in these models.
+The `sspm` package uses a model-based, random-effects based approach to estimate the effects of ecosystem drivers on surplus production across space and time. Our approach is conceptually related to the stochastic stock assessment approaches used by the `spict` [@pedersen_stochastic_2017] and `jabba` [@winker_jabba_2018] R packages for surplus production modelling, in that we assume that biomass dynamics can be modelled as effectively a logistic growth model with both process and measurement error. While `sspm` does not currently have the capacity to model biomass dynamics as a continuous-time process, as with `spict`, or incorporate prior parameter information on catchability or biomass dynamics, as in `jabba`, `sspm` can model spatially and temporally varying productivity, which is currently not possible in these models.
 
 The `sspm` package can be viewed as a spatiotemporal Model of Intermediate Complexity  [a 'MICE-in-space' model; @thorson_spatio-temporal_2019] that can incorporate effects of other species and ecosystem drivers as well as changes in fishing pressure on stock status. Our approach is closely connected to approaches used by other modern model-based spatial abundance estimation software, such as the `VAST` R package [@thorson_spatio-temporal_2019] and the `sdmTMB` R package [@anderson2022sdmTMB]. Our method shares the same approach as both `VAST` and `sdmTMB` of using spatially explicit models to estimate local biomass density (\autoref{fig:workflow} steps 1,2, and 4), then aggregating up from those models to predict aggregate stock-level metrics such as total biomass and productivity (\autoref{fig:workflow} steps 8). The multiplicative surplus production model used by `sspm` is also conceptually similar to the vector-autoregessive model for biomass changes used by these two packages, as both `VAST` and `sdmTMB` can model local temporal changes as autoregressive processes on the link-scale of a generalized linear model. The `sspm` package cannot, however, model the dynamics of multiple species simultaneously; multi-species modelling would require generating a separate surplus production model (\autoref{fig:workflow} steps 5 and 6) for each species of interest.