adfg-dsf / dsftools

Common Tools for Fisheries Analyses

dsftools

The goal of dsftools is to provide a library of common functions for fisheries analyses within the Alaska Department of Fish & Game, Division of Sport Fish.

The (multivariate) hope is that R-users within the Division can:

• More easily share code we're written, and make use of each other's code
• Standardize our methods for common analyses
• Collaborate and improve each other's code
• Get some Git(hub) & package development learning for free!

Installation

If you just want to use the functions in dsftools, you can install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("ADFG-DSF/dsftools")

A brief overview of commonly-used functions

For ASL (age, sex, and length) summaries:

• ASL_table() generates a summary table of ASL from vectors of data, and is robust to multiple sampling scenarios (stratified vs. pooled, total abundance known vs. estimated vs. unknown).
• verify_ASL_table() provides a graphical check of the methods used in ASL_table() via simulation.
• rp_ASL_table() graphically describes the relative precision of the estimates returned by ASL_table() via simulation.
• simulate_ASL_table() is the simulation function that may be called by verify_ and rp_, but may be called by itself.
• ASL_boilerplate() automagically creates text to accompany an ASL summary analysis or Operational Plan, to be written to Rmarkdown. This function may be used with inputs to ASL_table(), or directly from inputs describing the sampling scenario.

For sample size & relative precision statements:

• rp(): a generalized function for calculating confidence or (relative) accuracy from a vector of simulated values and a true value
• detection_probability(): in the context of a telemetry study, estimating the probability of detecting a single area or multiple areas used by some proportion of the marked population, given the sample size of instrumented fish, assuming random sampling

Miscellaneous functions

• logit() and expit(): functions for logit and inverse-logit
• se(): standard error, defined as sd/sqrt(n)
• plotcor(): a method for plotting a correlation matrix (mostly stolen from jagshelper::plotcor_jags())
• %inside%, %inside()%, %inside[)%, and %inside(]%: shorthand for checking if elements of a numeric vector are within a specified interval
• %s_l%, %s_leq%, %s_g%, %s_geq%, %s_inside%, %s_inside()%, %s_inside[)%, and %s_inside[)%: shortcuts for vector subsetting

What is an R package, and why is dsftools structured like one?

An R package is a standardized bundle of R functions, function documentation, example data, and most importantly, metadata. It can be loaded into your R package library, and you will be able to use the functions, access the function documentation (i.e. help()), and run example scripts within R/Rstudio.

You may notice the files DESCRIPTION and NAMESPACE at the root directory; these are important files that tell R how to interpret the package and its dependencies. The /man folder contains all function documentation.

I've written some cool R functions. Can I contribute them?

Yes please!!! That's the whole point of this package.

If you're new to the R package development workflow or just want to learn more, I highly recommend checking out https://r-pkgs.org/ because Hadley and Jennifer explain it all much better than I can.

Definitely check out Adam's excellent writeup on the use of Git & Github: https://adfg-dsf.github.io/Git_book/ as well as https://happygitwithr.com/

A few ground rules so we're all on the same page:

• Use devtools: The devtools package automates a lot of the package development tasks, and integrates well with RStudio. Make sure you have the latest version.

• Use roxygen2: The roxygen2 package automates building package documentation and metadata. Notice how the lines preceding each function within this package have tags that look like #' @description, etc. These "roxygen tags" create documentation and/or metadata in the appropriate places.

  • A couple of important ones: @export is necessary to export your function to the final package at the user level (an unexported function will be accessible to other dsftools functions, but not the user), and @importFrom will import functions from external packages.
  • An annoying step to enable Roxygen: In RStudio, navigate to Tools > Project Options > Build Tools, then check "Generate R Documentation with Roxygen", then "Configure..." and check all the boxes in the next popup.

• Add documentation: Add a help file with Roxygen for each function you contribute, and (for now) add a blurb in the README file.

• Add some automated tests: In tests/testthat/test_dsftools.R there are series of automated tests. These will run silently if dsftools's functions produce the desired output, and will complain otherwise. This is not required, but if you added a function, please add whatever tests you can think of! This provides a safeguard in case errors are inadvertently introduced, or (more likely) some update to R or a package dependency causes something to break. Tests aren't for now, tests are for the future.

• Version up: If you add or change stuff, bump up the Version in the DESCRIPTION file to let R know that this is a new version. I'm not sure if this is absolutely necessary, but it's a good practice.

• I don't know yet if the Fork/Pull Request or Collaborate model makes more sense. For now, let's try Fork/Pull Request for practice.

A few RStudio buttons you'll use

In the Build pane of RStudio:

• Install rebuilds the package and re-generates all Roxygen.
• Test runs all automated tests in the /tests folder.
• Check runs all tests, plus many additional checks to make sure that the package is functioning correctly and is complete in every conceivable way. It's totally possible to have a working package that does not completely pass Check, but since this package is collaborative, do your best to address any problems that Check identifies.

dsftools's Issues

better input handling for FPC= argument

Non-obvious error message is returned when a non-character is used in FPC= within ASL_table()

need an error message

An error message is needed in rp_ASL_table() when ptz= is not supplied. Currently, the function runs but does nothing and is very mysterious.

This is probably true for verify_ASL_table() as well.