In bstaton1/KuskoHarvData: Data Collected by the Lower Kuskokwim River In-season Subsistence Salmon Harvest Monitoring Program

knitr::opts_chunk$set(echo = FALSE, collapse = TRUE, comment = "#>")
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 all data sets in the package. These steps should only be completed after all in-season harvest data have been finalized and the Bethel Test Fishery has completed operations for the year (late August).

Obtain the most current versions of the packages you will need:

install.packages("devtools")
remotes::install_github("bstaton1/KuskoHarvEst")
remotes::install_github("bstaton1/KuskoHarvData")

The steps in this vignette only need to be completed if the most current version number year of the 'KuskoHarvData' package is behind that of the most recent year of completed monitoring:

packageVersion("KuskoHarvData")

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

:::{.indent}

Updating the data sets in 'KuskoHarvData' 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/KuskoHarvData.

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-data. All changes you make from here forward should be on this branch.

:::

r make_header("Organize/Add Opener Data Files", "folder-open")

:::{.indent}

Only add data from openers in which drift gillnets were allowed. It is okay to retain the set net data for these openers, but do not add data from set net only openers.

Each opener should have at least these data files:

• BBH_20YY_0M_DD.csv: completed trip interview data from the Bethel Boat Harbor
• CBM_20YY_0M_DD.csv: completed trip interview data from the Community Based Harvest Monitoring Program
• Flight_counts_20YY_08_12.csv: flight data

Where the YY, M, and DD are replaced with the appropriate year, month, and day, respectively. The file FC_20YY_0M_DD.csv (ONC fish camp surveys) may also be available, include it as well if so. Please see here for the proper formatting of these files, but if they worked properly to produce estimates in-season using 'KuskoHarvEst', then they will work properly here.

Within the data-raw subfolder of your local 'KuskoHarvData' repo, create a new subfolder for each driftnet opener with data you plan to add. Follow the example given by previous openers exactly (i.e., one subfolder per opener, named 20YY_0M_DD with the appropriate date information) and place the data files for each opener in each subfolder.

:::

r make_header("Add Opener Metadata", "table")

:::{.indent}

Within the data-raw subfolder, you will find a file called opener-metadata.csv -- open it in a spreadsheet editor.

Add a new row for each drift opener following the examples from previous openers exactly (i.e., date/time formatting is essential). Ideally the USFWS or ADF&G announcement that authorized the opener would be added, but if this is not available, please enter NA for this column.

:::

r make_header("Update Bethel Test Fishery Data", "table")

:::{.indent}

Navigate to the Alaska Department of Fish and Game Bethel Test Fishery webpage, click "Daily CPUE All Species", scroll to the bottom, click Export > Data > CSV Format. Place the downloaded file (will be named PUB_Bethel Test Fish - Daily CPUE.csv) in the data-raw subdirectory of your local repo.

Because of the timeline of Bethel Test Fishery operations, do not complete this step or proceed until after August 31 in the current year.

:::

r make_header("Compile Exported Data Objects", "sync")

:::{.indent}

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

source("data-raw/execute-prep-scripts.R")

This step will take some time (could be a half hour or more). While the code runs, progress messages will be printed to the console -- if you see any errors, you must stop and resolve them. Please do not hesitate to contact the package developer ([e-mail]) if needed.

:::

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 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, M, and DD for the appropriate date information):

1. Commit all changes to all opener data files (data-raw/20YY_0M_DD/*.csv).

   Commit message: Add 20YY harvest monitoring data 2. Commit all changes to the opener meta data file (data-raw/opener-metadata.csv).

   Commit message: Add 20YY opener meta data 3. Commit all changes to the Bethel Test Fishery data file (data-raw/PUB_Bethel Test Fish - Daily CPUE.csv).

   Commit message: Add 20YY BTF data 4. Commit all changes to all files with the extension .rda (found in the data subfolder).

   Commit message: Update exported data objects 5. 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 Data" and ensure you are requesting to merge into bstaton1/KuskoHarvData from YourUserName/KuskoHarvData.

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/KuskoHarvData documentation built on Aug. 15, 2024, 3:29 p.m.