In bstaton1/KuskoHarvPred: Harvest and Effort Predictions for Lower Kuskokwim River Subsistence Salmon Fisheries

knitr::opts_chunk$set(echo = FALSE, collapse = TRUE, comment = NA)
options(rmarkdown.html_vignette.check_title = FALSE)
library(fontawesome)

# select the CSS file
css_file = system.file("resources/KuskoHarv-vignette-styles.css", package = "KuskoHarvUtils")

# combine with style tags
css = c("<style>", readLines(css_file), "</style>") |> 
  paste(collapse = "\n")

r css

This vignette describes the process for updating predictive models when data from new years are added. As a first step, obtain the most current versions of the packages you will need:

install.packages("usethis")
install.packages("remotes")
remotes::install_github("bstaton1/KuskoHarvData")
remotes::install_github("bstaton1/KuskoHarvPred")

The steps in this vignette only need to be completed if the most current version number year of the 'KuskoHarvData' package exceeds that of 'KuskoHarvPred':

packageVersion("KuskoHarvData")

packageVersion("KuskoHarvPred")

Before You Begin: r fa("git-alt") Git and r fa("github") GitHub

:::{.indent}

Updating the predictions in 'KuskoHarvPred' requires basic operating knowledge of Git and GitHub (remote vs. local repositories, forking, pulling/pushing, committing, branching, and pull requests), and you are advised to use GitHub Desktop to interact with local and remote repositories. If this makes you uncomfortable or if you have any questions, please contact the package developer ([e-mail]) and he will assist as he is able.

If you are unfamiliar with these topics but wish to proceed, you can learn about them by reading the articles on each topic linked below; ignore any content regarding the command line or GitHub CLI -- these topics are unnecessary for our purposes.

• r fa("git-alt") Git overview
• r fa("github") GitHub Desktop
• r fa("code-fork") Forking workflow
• r fa("code-commit") Commits from GitHub Desktop
• r fa("arrow-up-from-bracket") Pushing changes from GitHub Desktop
• r fa("code-pull-request") Submitting a pull request

Specific instructions about how to perform the necessary GitHub tasks will not be described here, so please familiarize yourself before beginning. These instructions also assume you have installed R and RStudio Desktop (accept all defaults when prompted).

:::

# create a global section counter
counter <<- -1

# function to create the html tags to build the sectoin header
make_header = function(text, icon) {
  counter <<- counter + 1
  '<font size="+3">NUM</font> ICON _TEXT_' |> 
    stringr::str_replace("NUM", as.character(counter)) |> 
    stringr::str_replace("ICON", as.character(fa(icon))) |> 
    stringr::str_replace("TEXT", text)
}

r make_header("Fork & Clone (One Time Only)", "code-fork")

:::{.indent}

Complete this step only if you have not already done so in a previous year.

This R package is contained in the GitHub repository: bstaton1/KuskoHarvPred.

Ensure you have a GitHub account, and fork the repository to your account. Clone your remote forked repository to a local repository. You will make changes to the local repository, then push them up to your remote repository. After you are done with changes, you will submit a pull request to have them reviewed before they are merged in with the centralized repository.

:::

r make_header("Sync/Fetch/Pull", "download")

:::{.indent}

This step is essential to make sure your repository is current with the centralized version.

First, make sure your remote forked repository is up-to-date with the centralized repository by syncing your fork. Then, from GitHub Desktop, fetch and pull any changes to your local repository. This should not occur, but if you have any errors about merge conflicts, they will need to be addressed before proceeding.

:::

r make_header("Create a New Branch", "code-branch")

:::{.indent}

Do not ever make changes directly to the main (or master) branch -- instead, create a new branch in your local repository before proceeding. This will ensure that any changes you make will not interfere (just in case) with the current working version until they have been reviewed. Name the branch something like add-20YY-predictions. All changes you make from here forward should be on this branch.

:::

r make_header("Recalculate Predictions", "sync")

:::{.indent}

This step performs some of the longer-running calculations and saves the output for shipping with the package -- this saves computation time later.

From within your local repository, open the R project file (KuskoHarvPred.Rproj) in RStudio Desktop. Then execute the following command:

source("data-raw/make-pred-objs.R")

This step should take several minutes and you will be notified with a message saying that the objects fit_lists, pred_data, loo_output, and fit_data have been saved to the location R/sysdata.rda -- if you see any errors, you must stop and resolve them. Please do not hesitate to contact the package developer ([e-mail]). :::

r make_header("Increment Package Version", "plus")

:::{.indent}

From within your local repository, open the file named DESCRIPTION in RStudio Desktop, and change this field to reflect the year you just added:

Version: 20YY.0

For example, if the current version is 2023.1 this means data and predictions are current through 2023, and the package been patched 1 time (updated once after adding 2023 data to data through 2022). After adding the 2024 data, the version should be updated to 2024.0.

:::

r make_header("Commit Changes", "code-commit")

:::{.indent}

Open GitHub Desktop and commit the changes you've made as follows (except swap YY for the appropriate year information):

1. Commit all changes to exported objects (R/sysdata.rda).

   Commit message: Rebuild predictions with 20YY harvest monitoring data 2. Commit all changes to the DESCRIPTION file.

   Commit message: Update package version (now 20YY.0)

There should be no remaining changes to commit now.

:::

r make_header("Submit Pull Request", "code-pull-request")

:::{.indent}

You are now ready to push your branch to your forked remote repository and submit a pull request.

Name your pull request something like "Add 20YY Predictions" and ensure you are requesting to merge into bstaton1/KuskoHarvPred from YourUserName/KuskoHarvPred.

In the description, please note any quirks with the process or issues with the data that are of note. When you are done, submit the request -- this will notify the package developer that your changes are ready for review.

:::

THANK YOU for your contributions!!

bstaton1/KuskoHarvPred documentation built on Aug. 15, 2024, 3:30 p.m.