Merge pull request #51 from nmfs-fish-tools/main

Merge recent commits into shiny_app branch

.Rbuildignore

@@ -0,0 +1,5 @@
+^.*\.Rproj$
+^\.Rproj\.user$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

.github/workflows/call-r-cmd-check.yml

@@ -0,0 +1,12 @@
+# Run r cmd check
+name: call-r-cmd-check
+# on specifies the build triggers. See more info at https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+on:
+# The default build trigger is to run the action on every push and pull request, for any branch
+  push:
+  # To run the default repository branch weekly on sunday, uncomment the following 2 lines
+  #schedule:
+    #- cron: '0 0 * * 0'
+jobs:
+  call-workflow:
+    uses: nmfs-fish-tools/ghactions4r/.github/workflows/r-cmd-check.yml@main

.github/workflows/call-update-pkgdown.yml

@@ -0,0 +1,13 @@
+# updates exiting pkgdown site for a repository
+# deploys to a branch gh-pages
+name: call-update-pkgdown
+# on specifies the build triggers. See more info at https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+on:
+# this workflow runs on pushes to main or master or any time a new tag is pushed
+  # workflow_dispatch:
+  push:
+    # branches: [main, master]
+    # tags: ['*']
+jobs:
+  call-workflow:
+    uses: nmfs-fish-tools/ghactions4r/.github/workflows/update-pkgdown.yml@main

.gitignore

@@ -2,3 +2,5 @@
 .Rhistory
 .RData
 .Ruserdata
+StockAssessment/*/
+docs

DESCRIPTION

@@ -9,6 +9,11 @@ License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
     license
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.0.9000
+RoxygenNote: 7.3.1
 Imports: 
-    mvbutils
+    mvbutils,
+    tools
+Suggests: 
+    testthat (>= 3.0.0)
+Config/testthat/edition: 3
+Config/testthat/parallel: true

NAMESPACE

@@ -7,3 +7,5 @@ export(Weight)
 export(add_object)
 export(read_in)
 export(shiny_dd)
+export(validate_Rd)
+import(tools)

R/Catch.R

@@ -8,7 +8,7 @@
 #' \item{Rationale}{Landings and catch are sometimes thought to be
 #' interchangeable but they are not given that catch can also include
 #' bycatch or unwanted catch.}
-#' \item{Alternatives}{total mortality}
+#' \item{Alternatives}{total mortality, harvest, total removals}
 #' \item{Range of possible values}{0--Inf}
 #' \item{Units}{mt, numbers}
 #' }

R/FishingMortalityAtMaximumSustainableYield.R

@@ -1,4 +1,5 @@
 #' Fishing mortality at maximum sustainable yield (FMSY)
+#'
 #' A biological reference point for fisheries management
 #' based on the fishing mortality rate (F) that achieves the maximum
 #' sustainable yield (MSY).
@@ -11,8 +12,8 @@
 #' where the subscript can be in either all capital letters or all
 #' lower-case letters, some use lower-case letters for the type of reference
 #' point, and some use all capital letters.}
-#' \item{Alternatives: Fproxy, F_msy, Fmsy}{}
-#' \item{Range of possible values: 0--Inf}{}
+#' \item{Alternatives}{Fproxy, F_msy, Fmsy}
+#' \item{Range of possible values}{0--Inf}
 #' \item{Units}{\code{time^{-1}}}
 #' }
-FishingMortalityAtMaximumSustainableYield <- NULL
+FishingMortalityAtMaximumSustainableYield <- NULL

R/Forecast.R

@@ -1,6 +1,6 @@
 #' Forecast
 #'
-#' A probabilistic statement about future events.
+#' A probabilistic statement about future events based on what will happen.
 #'
 #' @format
 #' \describe{

R/Projection.R

@@ -0,0 +1,15 @@
+#' Projection
+#'
+#' A probabilistic statement about future events based on what might happen.
+#'
+#' @format
+#' \describe{
+#' \item{Examples}{short-term projection}
+#' \item{Rationale}{Future weather is a forecast because it does not require
+#' an if statement, whereas future spawning biomass is a projection because
+#' it depends on an assumption about future catches.}
+#' \item{Alternatives}{forecast, prediction}
+#' \item{Range of possible values}{}
+#' \item{Units}{}
+#' }
+Projection <- NULL

R/SpawningBiomass.R

@@ -1,18 +1,17 @@
 #' Spawning Biomass (SB)
 #'
-#' 1. The total weight of all fish (both males and females)
-#' in the population that contribute to reproduction. Often
-#' conventionally defined as the biomass of all individuals
-#' beyond “age at first maturity” or “size at first maturity,”
-#' i.e. beyond the age or size class in which 50 percent of
-#' the individuals are mature; 2. The total biomass of fish
-#' of reproductive age during the breeding season of a
-#' stock. Most often used as a proxy for measuring
-#' egg production, the SSB depends on the abundance of
-#' the various age classes composing the stock and their
-#' past exploitation pattern, rate of growth, fishing and
-#' natural mortality rates, onset of sexual maturity, and
-#' environmental conditions.
+#' The mass of fish (males and females or females only) in the 
+#' population that contribute to reproduction. Often conventionally 
+#' defined as the product of weight at age and the proportion 
+#' mature at age. Alternatively, it can be defined as the biomass of 
+#' all individuals at or above “age at 50 percent maturity” or “size 
+#' at 50 percent maturity” or the total biomass of fish of reproductive 
+#' age during the breeding season of a population. Spawning biomass depends on the 
+#' abundance of the various age classes composing the population and their 
+#' past exploitation pattern, rate of growth, fishing and natural mortality
+#' rates, onset of sexual maturity, and environmental conditions. Most often 
+#' used as a proxy for measuring egg production.
+#' 
 #'
 #' @format
 #' \describe{

R/validate_Rd.R

@@ -0,0 +1,72 @@
+#' Function to validate terms in the dictionary.
+#'
+#' The dictionary terms are written in R documentation (Rd) format.
+#' This function reads the Rd file using the `tools::parse_Rd` function
+#' validate the information in each section (e.g., examples, rationale,
+#' range of possible values, etc.).
+#'
+#' @param Rd_file a Rd filename to use as input.
+#' @return a message if the term passes all validations.
+#' @import tools
+#' @export
+validate_Rd <- function(Rd_file) {
+  if (is.null(Rd_file)) stop("Please provide the path to the R documentation (Rd) file.")
+
+  Rd <- tools::parse_Rd(Rd_file)
+  tags <- tools:::RdTags(Rd)
+
+  # Validate name
+  name <- Rd[[which(tags == "\\name")]]
+  if (is.null(name[[1]][1])) stop("Name is not provided. This should be the basename of the Rd file.")
+
+  # Validate title
+  title <- Rd[[which(tags == "\\title")]]
+  if (is.null(title[[1]][1])) stop("Title is not provided. Title should be capitalized and not end in a period.")
+
+  # Validate description
+  description <- Rd[[which(tags == "\\description")]]
+  if (gsub("[\r\n]", "", description[[2]][1]) == title[[1]][1] |
+    is.null(description[[1]][1])) {
+    stop("Description is not provided. This should be capitalized and not end in a period.")
+  }
+
+  # Extract format section for validating examples, rationale, alternatives, range of possible values, and units
+  format <- Rd[[which(tags == "\\format")]][[2]]
+  items <- c("Examples", "Rationale", "Alternatives", "Range of possible values", "Units")
+  missing_items <- items[!is.element(items, unlist(format))]
+  if (any(!is.element(items, unlist(format)))) stop(paste("Missing", paste(missing_items, collapse = ", ")))
+
+  # Validate examples
+  if (format[[2]][[1]][[1]][1] == "Examples" &
+    length(format[[2]][[2]]) == 0) {
+    stop("Examples are not provided. Use NA if there is no input for examples.")
+  }
+
+  # Validate rationale
+  if (format[[4]][[1]][[1]][1] == "Rationale" &
+    length(format[[4]][[2]]) == 0) {
+    stop("Rationale is not provided.")
+  }
+
+  # Validate alternatives
+  if (format[[6]][[1]][[1]][1] == "Alternatives" &
+    length(format[[6]][[2]]) == 0) {
+    stop("Alternatives are not provided. Use NA if there is no input for alternatives.")
+  }
+
+  # Validate range of possible values
+  if (format[[8]][[1]][[1]][1] == "Range of possible values" &
+    length(format[[8]][[2]]) == 0) {
+    stop("Range of possible values is not provided. Use NA if there is no input for range of possible values.")
+  }
+
+  # Validate range of possible values
+  if (format[[10]][[1]][[1]][1] == "Units" &
+    length(format[[10]][[2]]) == 0) {
+    stop("Units are not provided. Use NA if there is no input for units.")
+  }
+
+
+  # Return a message if the term passes all validations
+  message(paste("Term", name[[1]][1], "has passed all validations!"))
+}

README.md

@@ -1,4 +1,4 @@
-# data_dictionary
+# fishdictionary
 This is meant to be an open source `R` package that can be used to denote common fisheries terminology and standardize use. The dictionary is written in a JSON format and can be added to using the R functions described below.
 
 # Installation
@@ -8,6 +8,3 @@ This is meant to be an open source `R` package that can be used to denote common
 # Shiny app
 
 # How to contribute
-
-
-[Manuscript](https://docs.google.com/document/d/10FzlwMlHo6fe5Rh3F-HTWNMWzt4GAM8iaqe8dxBl0ks/edit?usp=sharing)