Package 'TAMMsupport'

Description

Helper function to parse full excel address into sheet, row, column. Removes ⁠'⁠ from sheet names. If given a cell range, returns only the address of the first cell.

Usage

address_parser(address)

Arguments

Value

list, with ⁠$sheet⁠ giving sheet name, ⁠$rows⁠ givng the row number, ⁠$cols⁠ giving the column number.

Examples

address_parser("SPS!AS3")
address_parser("'Input Page'!$B$30")

Description

Function to translate columns that "should" be numeric into numeric but doesn't do so if that would mean converting a true character string to NA.

Usage

as_numeric_safe(x)

Arguments

Value

Either numeric vector of x or (if that is lossy) character returns input.

Description

Format chunks of dataframe to present as %s, round digits

Usage

chunk_formater_percenter(df, block_ranges, percent_digits = 1)

Arguments

Value

Formatted version of df

Description

Format chunks of dataframe to round digits

Usage

chunk_formater_rounder(df, block_ranges, digits = 1)

Arguments

Value

Formatted version of df

Description

Read in chunks of the 2A_Cmrkd sheet

Usage

chunk_read_2A_Cmrkd(full_sheet, start_col, end_col, table_name)

Arguments

Description

Read chunk for table 2A_CUandM

Usage

chunk_read_2A_CUandM(full_sheet, start_col, end_col, table_name)

Arguments

Description

Read in individual chunks for sheet 2A_Cu&M_N

Usage

chunk_read_2A_CUandM_N(full_sheet, start_col, end_col, table_name)

Arguments

Description

Reads chunk of 2A_CUnmrkd sheet

Usage

chunk_read_2A_CUnmrkd(full_sheet, start_col, end_col, table_name)

Arguments

Description

Handles some of the repetitive tasks of processing individual chunks; this part is generalized and does not need to be different for each sheet. Lots of fiddliness in here because TAMM formatting is terrible

Usage

chunk_read_finisher(
  sheet_name,
  table_name,
  raw,
  raw_titles,
  data_er,
  do_er = TRUE
)

Arguments

Value

A list with $aeq and $er, each a dataframe

Description

Effectively a wrapper function for read_limiting_stock with some formatting added in. Filters to unmarked naturals, just present ER values.

Usage

clean_limiting_stock(file)

Arguments

Value

dataframe

Description

Summarizes the differences in input sheets and returns as a table. Wrapper for xldiff::excel_diff_table()

Usage

compare_chinook_inputs(
  file_1,
  file_2,
  proportional_threshold = 0.001,
  absolute_threshold = NULL,
  digits_show = 6,
  trim_cols = TRUE,
  diff_only = TRUE
)

Arguments

Value

Tibble of differences in the input files; only rows with differences are included. row_name variable gives the row name in the TAMM file, and column names match excel column names.

Description

Adapted from framrsquared::filter_wa(), but (a) only for Chinook (at present), and (b) uses TAMM fishery ids, so includes ids 72 and 73. Includes code for COHO based on FRAM ids. filter_tamm_wa() uses attributes to specify chinook or coho. To directly filter for chinook or coho, use filter_tamm_wa_chin() or filter_tamm_wa_coho().

Usage

filter_tamm_wa(.data)

filter_tamm_wa_chin(.data)

filter_tamm_wa_coho(.data)

Arguments

Details

a fishery_id column name.

Examples

## Not run: 
fram_dataframe |> filter_wa()

## End(Not run)

Description

Designed for tracking the status of TAMM inputs, which are typically color coded. Searches through specified sheet or sheets, looking for cells whose colors match the target_cell argument. Returns a condensed list of those entries.

Usage

find_color_matches(file, target_cell, sheets = "Input Page")

Arguments

Value

tibble summarizing entries with the color of interest, including sheet, row and column ids, and row name (entry of first column in sheet)

Examples

## Not run: 
file = "chin tamms/Chin2023_Final.xlsx"
find_color_matches(file, "B20")

## End(Not run)

Description

With argument sep = TRUE, will return data frame with separate columns for the area and the the "class" (Net, Troll, Sport)

Usage

fishery_renamer(x, sep = FALSE)

Arguments

Value

#vector with cleaned fishery names OR dataframe with cleaned name (⁠$full⁠), area without fishery type (⁠$area⁠) and type of fishery (⁠$class⁠).

Modify list of Chinook TAMM spreadsheet dataframes to facilitate comparison.

Description

Function is no longer needed for tamm_diff now that openxlsx

Usage

format_key_tamm_sheets_chin(
  dat,
  percent_digits = 1,
  numeric.digits = 1,
  numeric.digits.small = 4
)

Arguments

Value

list of dataframes with same structure as dat, contents modified.

Description

Modify list of Coho TAMM spreadsheet dataframes to facilitate comparison.

Usage

format_key_tamm_sheets_coho(
  dat,
  percent_digits = 2,
  numeric.digits = 1,
  numeric.digits.small = 4
)

Arguments

Value

list of dataframes with same structure as dat, contents modified.

Description

Format TAMM overview for easy printing

Usage

format_overview(dat_overview)

Arguments

Value

list with the formatted data, a vector of indent information, and a vector of bolding information.

Description

Helper function to add spaces to excel formulas to improve readability. Can also add newlines based on a character or regular expression

Usage

formula_formater(x, newline_breakpoint = NULL)

Arguments

Value

character string

Examples

formula_formater("(SUM(A1:A4)*5/11)/(B3-B4)")
formula_formater("(SUM(A1:A4)*5/11)/(B3-B4)", newline_breakpoint = "/")
formula_formater("(SUM(A1:A4)*5/11)/(B3-B4)", newline_breakpoint = "[*-+/]")

Description

Intended for internal use within formatting functions. Note that percents in excel are read in as proportions in R – this makes them percents to make saved files more readable.

Usage

fun_percenter(x, percent_digits)

Arguments

Value

character vector with individual entries converted to percentages and rounded as appropriate.

Description

Intended for internal use within formatting functions.

Usage

fun_rounder(x, digits)

Arguments

Description

Uses output of format_overview()

Usage

kable_overview(dat_overview, ind_indent, col_bold)

Arguments

Value

html table

Description

Helper function to find all references in list created within tracer_formula, and create a simple dataframe representing all the "edges" of the traced network (that is, all the connections between cells). Gets called in trace_formula() to generate the ⁠$references⁠ component of the output.

Usage

make_tracer_edges(address_list)

Arguments

Value

tibble. ⁠$from⁠ is the index of the cell that is referenced, ⁠$to⁠ is hte index of the cell that is doing the referencing ⁠$from_name⁠ and ⁠$to_name⁠ are the excel addresses of the same.

Description

Usage

make_tracer_network(tracer_list, save_path = NULL, newline_breakpoint = NULL)

Arguments

Details

Render the dependency network created in trace_formula(); optionally save this to an interactive .html.

Value

interactive visNetwork object

Examples

## Not run: 
trace_network = trace_formula(path = "NOF material/NOF 2024/NOF 2/Chin1624.xlsx",
cell_start = "SPSmrkd!AS20")
make_tracer_network(trace_network)

## End(Not run)

Description

Helper function to parse list created within trace_formula into a tibble with each cell represented by a row. Called in trace_formula() to generate the ⁠$cells⁠ component of the output.

Usage

make_tracer_nodes(address_list)

Arguments

Value

tibble summarizing each cell in the tracing. See trace_formula() for details.

Read and combine aeq sections form tables 2a-2c

Description

Read and combine aeq sections form tables 2a-2c

Usage

process_2ac_aeqs(tab_2a, tab_2b, tab_2c)

Arguments

Value

dataframe of AEQ values for each stock in longform

function to process + combine the er sections from tables 2a-2c, used below

Description

function to process + combine the er sections from tables 2a-2c, used below

Usage

process_2ac_ers(tab_2a, tab_2b, tab_2c)

Arguments

Value

dataframe of ers in longform

Description

Quick helper function to format vectors that contain text and ERs

Usage

quick_er_format(x)

Arguments

Description

Primarily intended as a helper function for trace_formula(), but could be useful for other excel tasks. Drops $ and ⁠'⁠ symbols from addresses to simplify parsing.

Usage

range_splitter(address)

Arguments

Value

vector of individual excel-style cell addresses within that range

Examples

range_splitter("B10:C15")
range_splitter("'Input Sheet'!$AS30:$AS40")

Description

Gathers and cleans the AEQ and ER information for tamm sheets ⁠2aCmrkd⁠, ⁠2aCUnmkrd⁠, ⁠2aCUandM⁠, and ⁠2aCUandM_N⁠.

Usage

read_2a_sheets(tamm_filepath, stock_cleanup = TRUE)

Arguments

Value

list, with $aeq containing the primary information (AEQs of fishery impacts on each stock) and $er containing the ER information at the bottom of the spreadsheets.

Examples

## Not run: 
library(here)
filepath <- here("tamms/Chin2025.xlsx")
res <- read_2a_sheets(filepath)
jdf <- read_jdf(filepath)

## End(Not run)

Description

Reads sheet of 2A_Cmrkd

Usage

read_2aCmrkd(tamm_filepath, stock_cleanup = TRUE)

Arguments

Value

a list, with $aeq (the main parts of each table) and $er (the very bottom section)

Description

Read and process all parts of sheet 2A CU and M

Usage

read_2aCUandM(tamm_filepath, stock_cleanup = TRUE)

Arguments

Value

a list, with $aeq (the main parts of the table) and $er (the very bottom section) @return

Description

Read and combine all chunks for sheet 2A CU and M_N

Usage

read_2aCUandM_N(tamm_filepath, stock_cleanup = TRUE)

Arguments

Description

read all info for 2aCUnmrkd and process it.

Usage

read_2aCUnmrkd(tamm_filepath, stock_cleanup = TRUE)

Arguments

Value

a list, with $aeq (the main parts of the table) and $er (the very bottom section)

Description

Read in AEQ and ER information from the JDF sheet

Usage

read_jdf(tamm_filepath, stock_cleanup = TRUE)

Arguments

Value

List, with $aeq containing the combined AEQ information that is spread across multiple chunks in the TAMM sheet. List also contains $er = NULL, to provide parallel outputs to read_2a_sheets, which does have a non-null $er item in the output list.

Examples

## Not run: 
library(here)
filepath <- here("tamms/Chin2025.xlsx")
jdf <- read_jdf(filepath)

## End(Not run)

Description

Read in AEQ and ER information from the JDF Unmarked sheet

Usage

read_jdf_unmarked(tamm_filepath, stock_cleanup = TRUE)

Arguments

Value

List, with $aeq containing the combined AEQ information that is spread across multiple chunks in the TAMM sheet. List also contains $er = NULL, to provide parallel outputs to read_2a_sheets, which does have a non-null $er item in the output list.

Examples

## Not run: 
library(here)
filepath <- here("tamms/Chin2025.xlsx")
jdf <- read_jdf_unmarked(filepath)

## End(Not run)

Description

Read Chinook TAMM files to extract the key sheets

Usage

read_key_tamm_sheets_chin(file)

Arguments

Value

List of dataframes: ⁠$overview⁠, ⁠$limiting⁠, and ⁠$input⁠

Description

Read Chinook TAMM files to extract the key sheets

Usage

read_key_tamm_sheets_coho(file)

Arguments

Value

List of dataframes: ⁠$two⁠, ⁠$tami⁠, and ⁠$wacoast⁠

Description

Reads in the table, adds fishery type information.

Usage

read_limiting_stock(file, longform = FALSE)

Arguments

Value

data frame summarizing the TAMM limiting stock tab. The "block" of the limiting tab is identified with column "stock_type". "first_section" is the first section in the TAMM; this section is primarily natural fish but includes some hatchery fish if they were included in management objectives. "ALL_H" is all hatchery fish (in TAMM, block starts on row 81), "UM_H" is unmarked hatchery (in TAMM, starts on row 160), "UM_N" is unmarked naturals (in TAMM, starts row 239), "AD_H" is marked hatchery (in TAMM, starts row 318), and "AD_N" is marked naturals (unless programs begin marking natural fish, this should always be all 0s; in TAMM starts row 397).

Description

Extract and format management criterion from Chinook TAMM

Usage

read_management_chin(file)

Arguments

Value

Tibble, with ⁠$management_name⁠ giving the name of the management criteria as specified in the TAMM, ⁠$management_criteria⁠ giving a list of dataframes with the associated management criteria, formatted appropriately, and ⁠$notes⁠ giving a list of character vectors with notes (if any) to help interpret the criteria.

Examples

## Not run: 
cur.management = read_management_chin("Code Inputs/Pre-Season/TAMMs/2013_Final W_BP7.1.xlsx")

## End(Not run)

Description

Read overview sheet from TAMM and return key stock

Usage

read_overview(path)

Arguments

Value

dataframe

Description

The stock column of the overview tab uses R-unfriendly approaches to store season, overall stock name, and individual stocks in the stock column of the TAMM. read_overview_complete splits these into separate columns: season, primary_stock, and stock. For three stock (Green, Puyallup, Skokomish), the tamm presents model predictions across two rows with a single stock name due to merged cells. The stock column in the output preserves this information; the entry corresponding to the second row has the suffix "_row2".

Usage

read_overview_complete(path)

Arguments

Value

Dataframe containing all infomration from cells A2:H34 of the "ER_ESC_Overview_New" sheet.

Description

Extract Treaty and Nontreaty numbers from "2A_CU&M_H+N" TAMM sheet. For Elwha and Dungeoness, separate allocations are calculated using column O of the JDF tab

Usage

read_tnt_allocation_chin(file)

Arguments

Details

Currently provides dataframe with stock.original column identifying the stock based on their names in the TAMM, and stock.clean with more human-readable names (which are generally consistent with other stock names, like those used to label the management criterion).

Value

dataframe with the treaty and nontreaty mortalities at each stock.

Description

Internal tool to simplify converting TAMM sheet to stock management criterion lists. See read_management_chin() for example use.

Usage

reformat_management(
  df,
  cols.percent,
  rows.percent = NULL,
  rows.header = 2,
  notes = NULL
)

Arguments

Value

Stock management criterion list, containing dataframe extracted from TAMM and notes hard-coded in based on TAMM cell comments.

Description

Helper function to check an atomic string and convert to numeric if it contains a legal number.

Usage

safe_convert_numeric(x)

Arguments

Value

Input formatted as character string or numeric

Examples

safe_convert_numeric("AS20-BC2")
safe_convert_numeric("10.5")

Description

Intended use case is to compare low, mid, and high ocean option.

Usage

tamm_compare(
  tamm_names,
  tamm_path = getwd(),
  fisheries = NULL,
  clean = TRUE,
  overwrite = TRUE
)

Arguments

Value

Nothing

Examples

## Not run: 
tamm_path <- "C:/Users/edwc1477/Documents/WDFW FRAM team work/NOF material/NOF 2024/FRAM"
tamm_names <- c("Chin1024.xlsx", "Chin1124.xlsx", "Chin1224.xlsx")
tamm_compare3(tamm_names = tamm_names, tamm_path = tamm_path)

## End(Not run)

Description

Intended use case is to compare low, mid, and high ocean option.

Usage

tamm_compare3(tamm_names, tamm_path = getwd(), clean = TRUE, overwrite = TRUE)

Arguments

Value

Nothing

Examples

## Not run: 
tamm_path <- "C:/Users/edwc1477/Documents/WDFW FRAM team work/NOF material/NOF 2024/FRAM"
tamm_names <- c("Chin1024.xlsx", "Chin1124.xlsx", "Chin1224.xlsx")
tamm_compare3(tamm_names = tamm_names, tamm_path = tamm_path)

## End(Not run)

Description

Compare key sheets of TAMM files

Usage

tamm_diff(
  file_1,
  file_2,
  results_name,
  proportional_threshold = 0.001,
  absolute_threshold = NULL,
  extra_width = NULL
)

Arguments

Examples

## Not run: 
tamm_diff(
  file_1 = here("FRAM/Chin1124.xlsx"),
  file_2 = here("NOF 2/Chin2524.xlsx"),
  results_name = here("Chin 1124 vs Chin 2524.xlsx")
)

## End(Not run)

Description

Functions that add formatting to broadly replicate the formatting of the TAMM sheets. Colored foregrounds have been toned down to help change highlighting pop, and some of the complicated or superfluous formatting has been skipped.

Usage

tamm_format_overview(wb, diff.sheet, tabname = "overview")

tamm_format_limiting(wb, tabname = "limiting")

tamm_format_input(wb, tabname = "input", wrap.text = FALSE)

tamm_format_wacoast(wb, tabname = "wacoast")

Arguments

Description

Generate report of figures from TAMM file

Usage

tamm_report(
  tamm_name,
  tamm_path = getwd(),
  clean = TRUE,
  overwrite = TRUE,
  additional_children = NULL,
  additional_support_files = NULL
)

Arguments

Details

This function generates a summary report of a single chinook TAMM (Terminal Area Management Module) file. The common use case is to call this function for a tamm, and then view the resulting html report (which will be generated in the same folder as the TAMM). However, this function also provides substantial flexibility in the form of optional user-created child quarto documents, which requires some additional context to develop and use.

tamm_report is implemented using a parameterized quarto report and a child quarto document, which are included in the package. The resulting report includes some broadly useful content – currently, a replication of the overview TAMM sheet and bar charts showing the breakdown of exploitation rates by fishery for each stock listed in the ⁠limiting stock complete⁠ TAMM sheet. However, individuals or organizations may consistently want additional, specific visualizations based on their own needs. For example, individual tribes may want to visualize impacts on a single stock, but use AEQ instead of ER rates. The tamm_report function is designed to integrate these extra components with the additional_children argument.

The basic principle is that the individual or group can write a reusable "child" .qmd file, see this explanation using Rmarkdown), which will effectively be inserted into the main report. As an example, we might create a simple additional child .qmd file called extra-tamm-child.qmd to include a small table summarizing a few key aspects of the Nooksack Earlies stock. The contents of that file are provided in the example below.

When we call tamm_report(), we can include as an argument ⁠additional_children = ⁠ with the file name (including file path) for our new file. In this way we can easily include this extra content any time we create a tamm report. If desired, multiple child files can be created, and additional_children can take a character vector with each child file name.

When writing child documents, formatting and chunks work akin to copy-pasting a section of a quarto file out of the main file. (To easily access the main quarto file, run tamm_report() with clean = FALSE, which will leave tamm-visualizer.qmd and tamm-visualizer-child.qmd files in the folder with the TAMM file). The child document will have access to key objects

• dat.all: the output of read_limiting_stock with longform = TRUE called on the TAMM;

• dat_overview: the output of of read_overview called on the TAMM;

• and dat: the specific filtered and formatted version of the limiting stock data generated in the ⁠limiting stock tab⁠ chunk of tamm-visualizer.qmd and used in generating the unmarked natural stock exploitation rate figures. When developing a child document, it may be useful to create in the working environment versions of dat.all and dat_overview from an example TAMM to facilitate writing appropriate filters, plot-making code, etc. The primary quarto report loads in the tidyverse, framrsquared, kableExtra, and TAMMsupport packages, but you can include additional packages for the child documents as needed by adding ⁠library(packagename⁠ calls just like in any other context.

If the additional_children files need to read contents of additional files (or call children .qmd files of their own to streamline looping over stocks or fisheries), the file paths to these supplemental files can be provided in the ⁠additional.support files⁠ argument. These files will be copied into the same folder as the .qmd files, so the children quarto files can be written to access the supplemental files without dealing with file paths.

For questions/support in developing child documents to extend the report, contact Collin Edwards at WDFW.

Value

Nothing

Examples

## Not run: 
##### CONTENTS FOR extra-tamm-child.qmd #####-----------------------------
## Test section

Hypothetical world in which we want a table summarizing the impacts of three
fisheries on the "Nooksack Earlies" stock.

```{r}
kable(dat |> filter(stock == "Nooksack Earlies") |> filter(fishery_id %in% 16:18))
```
#### END CONTENTS FOR extra-tamm-child.qmd #####--------------------------

tamm_path = "C:/Users/edwc1477/Documents/WDFW FRAM team work/NOF material/NOF 2024/NOF 2"
tamm_name = "Chin2124.xslx"
tamm_report(tamm_name = "Chin2124.xlsx", tamm_path = tamm_path)
## Now with our extra content, presuming `extra-tamm-child.qmd` is saved in our documents folder
tamm_report(tamm_name = "Chin2124.xlsx", tamm_path = tamm_path,
  additional_children = "C:/Users/JohnDoe/Documents/extra-tamm-child.qmd")

## End(Not run)

Description

Usage

trace_formula(
  path,
  cell_start,
  max_it = 5000,
  verbose = TRUE,
  split_ranges = FALSE
)

Arguments

Value

"trace object" – list defining the dependency network.

⁠$cells⁠

tibble summarizing each of the cells in the dependency network, starting with the cell_start. Within this, ⁠$id⁠ is an index; ⁠$label⁠ is the cell address; ⁠$formula⁠ is the formula in that cell if there is a formula, otherwise it is the contents of the cell, ⁠$contents⁠ is the non-formula cell contents (i.e., if a formula is present, ⁠$contents⁠ will be the results of the formula); ⁠$is.formula⁠ is a logical identifying if this cell contains a formula, or is purely a numeric / string / etc contents; ⁠$addresses.referenced⁠ is a character vector of all excel addresses in ⁠$formula⁠, and sheet is the sheet associated with the current cell.

⁠$references⁠

is a tibble summarizing each of the edges of the dependency network – that is, all of the references in one cell to another. ⁠$from⁠ is the index of the cell that is referenced; ⁠$to⁠ is the index of the cell that is doing the referencing; ⁠$from_name⁠ and ⁠$to_name⁠ are the excel addresses of the same.

⁠$raw.tracing⁠

list created during tracing that forms the backbone of trace_formula. Intended for internal use; ⁠$cells⁠ and ⁠$references⁠ contains the important results here.

Examples

## Not run: 
trace_network = trace_formula(path = "NOF material/NOF 2024/NOF 2/Chin1624.xlsx",
 cell_start = "SPSmrkd!AS20")

## End(Not run)

Description

Confirm object is dataframe

Usage

validate_data_frame(
  x,
  ...,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

Arguments