improves readme, closes #55

pedersen-fisheries-lab · Nov 20, 2022 · 7aefbd9 · 7aefbd9
1 parent 2c05314
commit 7aefbd9
Show file tree

Hide file tree

Showing 2 changed files with 137 additions and 15 deletions.
diff --git a/README.Rmd b/README.Rmd
@@ -1,5 +1,8 @@
 ---
 output: github_document
+editor_options: 
+  markdown: 
+    wrap: 72
 ---
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
@@ -14,39 +17,107 @@ knitr::opts_chunk$set(
 ```
 
 # sspm
-<img src='man/figures/logo.png' style='float: right;' height="150" width="130"/>
+
+<img src="man/figures/logo.png" style="float: right;" height="150" width="130"/>
 
 <!-- badges: start -->
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT/)
+
+[![License:
+MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT/)
 [![R-CMD-check](https://github.com/pedersen-fisheries-lab/sspm/workflows/R-CMD-check/badge.svg)](https://github.com/pedersen-fisheries-lab/sspm/actions)
-[![Codecov test coverage](https://codecov.io/gh/pedersen-fisheries-lab/sspm/branch/main/graph/badge.svg)](https://app.codecov.io/gh/pedersen-fisheries-lab/sspm)
+[![Codecov test
+coverage](https://codecov.io/gh/pedersen-fisheries-lab/sspm/branch/main/graph/badge.svg)](https://app.codecov.io/gh/pedersen-fisheries-lab/sspm)
 [![Downloads](https://cranlogs.r-pkg.org/badges/sspm?color=brightgreen)](https://CRAN.R-project.org/package=sspm/)
-[![Latest Release](https://img.shields.io/github/v/release/pedersen-fisheries-lab/sspm?label=Latest%20Release)](https://github.com/pedersen-fisheries-lab/sspm/releases/latest)
-[![CRAN Version](https://img.shields.io/cran/v/sspm?label=CRAN%20Version)](https://CRAN.R-project.org/package=sspm)
-[![GitHub Version](https://img.shields.io/github/r-package/v/pedersen-fisheries-lab/sspm?label=GitHub%20Version)](https://github.com/pedersen-fisheries-lab/sspm/blob/main/DESCRIPTION)
+[![Latest
+Release](https://img.shields.io/github/v/release/pedersen-fisheries-lab/sspm?label=Latest%20Release)](https://github.com/pedersen-fisheries-lab/sspm/releases/latest)
+[![CRAN
+Version](https://img.shields.io/cran/v/sspm?label=CRAN%20Version)](https://CRAN.R-project.org/package=sspm)
+[![GitHub
+Version](https://img.shields.io/github/r-package/v/pedersen-fisheries-lab/sspm?label=GitHub%20Version)](https://github.com/pedersen-fisheries-lab/sspm/blob/main/DESCRIPTION)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.04724/status.svg)](https://doi.org/)
+
 <!-- badges: end -->
 
-The goal of `sspm` is to implement a gam-based spatial surplus production model, aimed at modeling northern shrimp population in Canada but potentially to any stock in any location. The package is opinionated in its implementation of SPMs as it internally makes the choice to use penalized spatial gams with time lags  based on Pedersen et al. (2020). However, it also aims to provide options for the user to customize their model.
+The goal of `sspm` is to implement a gam-based spatial surplus
+production model, aimed at modeling northern shrimp population in Canada
+but potentially to any stock in any location. The package is opinionated
+in its implementation of SPMs as it internally makes the choice to use
+penalized spatial gams with time lags based on Pedersen et al. (2020).
+However, it also aims to provide options for the user to customize their
+model.
 
 ## Installation
 
-You can install the released version of sspm from [CRAN](https://CRAN.R-project.org) with:
+You can install the released version of sspm from
+[CRAN](https://CRAN.R-project.org) with:
+
 ``` r
 install.packages("sspm")
 ```
 
-You can install the development version from [GitHub](https://github.com/) with:
+You can install the development version from
+[GitHub](https://github.com/) with:
+
 ``` r
 # install.packages("devtools")
 devtools::install_github("pedersen-fisheries-lab/sspm")
 # if you wish to build the vignettes:
 devtools::install_github("pedersen-fisheries-lab/sspm", build_vignettes = TRUE)
 ```
 
-## Vignettes
+## Purpose
+
+The `sspm` package follows a strict workflow, where spatial boundaries
+need to be defined and discretized into patches, so that we can apply a
+spatial GAM to the data. You can either use of of our built in methods
+for discretization or implement your own. Below is an example of a
+discretized set of patches:
+
+![](man/figures/patches.png){style="display: block; margin: 1em auto;"
+width="70%"}
+
+Then, we provide a framework to ingest trawling and fishing data, and
+smoothing the model spatially:
+
+![](man/figures/smoothed.png){style="display: block; margin: 1em auto;"
+width="70%"}
+
+Finally, the package allows for calculating the surplus production on a
+yearly basis, and model the impact of different variables on that
+productivity. You can then produce **one step ahead predictions** for
+the biomass.
 
-See the vignettes for an introduction to the `sspm` workflow.
+![](man/figures/preds.png){style="display: block; margin: 1em auto;"
+width="70%"}
 
-```{r, eval=FALSE}
+For an overview of the package design, please see our [workflow
+diagram](https://pedersen-fisheries-lab.github.io/sspm/articles/Package_and_workflow_design.html).
+
+### Getting started
+
+See the example vignette for an introduction to the `sspm` workflow.
+
+```{r eval=FALSE}
 browseVignettes("sspm")
 ```
+
+## See also
+
+`sspm` is opinionanted in its workflow and its use of GAMS, but other
+frameworks exist to make use of surplus production models (usually not
+in spatial capacity, however):
+
+-   [`openmse`](https://openmse.com/features-assessment-models/3-sp/)
+-   [`TropFishR`](https://github.com/tokami/TropFishR)
+
+## Cite this package
+
+You can cite this package like this "we ran a spatial surplus production
+model using the the R package sspm (Lucet & Pedersen 2022)". Here is the
+full bibliographic reference to include in your reference list (don't
+forget to update the 'last accessed' date):
+
+> Lucet, V., E. Pedersen (2022). The sspm R package: spatial surplus
+> production models for the management of northern shrimp fisheries. The
+> Journal of Open Source Software
+> (<https://joss.theoj.org/papers/d05fcbbc7ff3d1d2bc3c56466f2e21e5#>)
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 
 # sspm
 
-<img src='man/figures/logo.png' style='float: right;' height="150" width="130"/>
+<img src="man/figures/logo.png" style="float: right;" height="150" width="130"/>
 
 <!-- badges: start -->
 
@@ -19,6 +19,8 @@ Release](https://img.shields.io/github/v/release/pedersen-fisheries-lab/sspm?lab
 Version](https://img.shields.io/cran/v/sspm?label=CRAN%20Version)](https://CRAN.R-project.org/package=sspm)
 [![GitHub
 Version](https://img.shields.io/github/r-package/v/pedersen-fisheries-lab/sspm?label=GitHub%20Version)](https://github.com/pedersen-fisheries-lab/sspm/blob/main/DESCRIPTION)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.04724/status.svg)](https://doi.org/)
+
 <!-- badges: end -->
 
 The goal of `sspm` is to implement a gam-based spatial surplus
@@ -48,10 +50,59 @@ devtools::install_github("pedersen-fisheries-lab/sspm")
 devtools::install_github("pedersen-fisheries-lab/sspm", build_vignettes = TRUE)
 ```
 
-## Vignettes
+## Purpose
+
+The `sspm` package follows a strict workflow, where spatial boundaries
+need to be defined and discretized into patches, so that we can apply a
+spatial GAM to the data. You can either use of of our built in methods
+for discretization or implement your own. Below is an example of a
+discretized set of patches:
+
+<img src="man/figures/patches.png"
+style="display: block; margin: 1em auto;;width:70.0%" />
+
+Then, we provide a framework to ingest trawling and fishing data, and
+smoothing the model spatially:
+
+<img src="man/figures/smoothed.png"
+style="display: block; margin: 1em auto;;width:70.0%" />
+
+Finally, the package allows for calculating the surplus production on a
+yearly basis, and model the impact of different variables on that
+productivity. You can then produce **one step ahead predictions** for
+the biomass.
+
+<img src="man/figures/preds.png"
+style="display: block; margin: 1em auto;;width:70.0%" />
+
+For an overview of the package design, please see our [workflow
+diagram](https://pedersen-fisheries-lab.github.io/sspm/articles/Package_and_workflow_design.html).
 
-See the vignettes for an introduction to the `sspm` workflow.
+### Getting started
+
+See the example vignette for an introduction to the `sspm` workflow.
 
 ``` r
 browseVignettes("sspm")
 ```
+
+## See also
+
+`sspm` is opinionanted in its workflow and its use of GAMS, but other
+frameworks exist to make use of surplus production models (usually not
+in spatial capacity, however):
+
+- [`openmse`](https://openmse.com/features-assessment-models/3-sp/)
+- [`TropFishR`](https://github.com/tokami/TropFishR)
+
+## Cite this package
+
+You can cite this package like this “we ran a spatial surplus production
+model using the the R package sspm (Lucet & Pedersen 2022)”. Here is the
+full bibliographic reference to include in your reference list (don’t
+forget to update the ‘last accessed’ date):
+
+> Lucet, V., E. Pedersen (2022). The sspm R package: spatial surplus
+> production models for the management of northern shrimp fisheries. The
+> Journal of Open Source Software
+> (<https://joss.theoj.org/papers/d05fcbbc7ff3d1d2bc3c56466f2e21e5#>)