overview

library(framrosetta)
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

framrosetta was developed to store the various lookup tables/mappings necessary to work with FRAM data, or to link other data (TOCAS, WAFT, PSC stock and fishery identities) to FRAM tables or vice versa. Most tables in FRAM identify stock and fisheries by id numbers, but we often want to present figures or analyses using names (or we need to filter to a specific fishery or stock of interest, and we have the name but not the id).

Key functions:

Adding stock or fishery label

Frequently we work with tables that use stock id or fishery id to identify stocks or fisheries; while useful for programming, id numbers are not the easiest to read. label_stocks() and label_fisheries() use stock_id and fishery_id to add human-readable stock and fishery names. These functions are flexible (can manually specify the species or ), but the simplest use-case is to label tables pulled from a fram database with the framrosetta package, which works with default arguments. Here is an example, using an artificial dataframe because we cannot use framrsquared::fetch_table() in vignettes.

## create example data with random coho stock id, fishery ids, and landed catch
## We use 
dat = stock_coho_fram[sample(1:nrow(stock_coho_fram), size = 5),] |> 
  dplyr::select(stock_id) |> 
  mutate(fishery_id = sample(1:200, size = length(stock_id), replace = TRUE),
           landed_catch = runif(length(stock_id), min = 1, max = 1000))
# This makes a dataframe that could reasonably be output from framrsquared functions
dat
#> # A tibble: 5 × 3
#>   stock_id fishery_id landed_catch
#>      <dbl>      <int>        <dbl>
#> 1      208        134         696.
#> 2      231         81         129.
#> 3       98        169         587.
#> 4      189         16         403.
#> 5      142         51         652.
## Not very human readable
## make the stock_id human readable
dat |> 
  label_stocks()
#> # A tibble: 5 × 4
#>   stock_id stock_label                         fishery_id landed_catch
#>      <dbl> <chr>                                    <int>        <dbl>
#> 1      208 Georgia Strait Mainland Wild Marked        134         696.
#> 2      231 Upper Fraser River Wild UnMarked            81         129.
#> 3       98 Green River Wild Marked                    169         587.
#> 4      189 Oregon Anadromous Hatchery UnMarked         16         403.
#> 5      142 Queets River Fall Hatchery Marked           51         652.

## make both stock_id and fishery_id human readable
dat |> 
  label_stocks() |> 
  label_fisheries()
#> # A tibble: 5 × 5
#>   stock_id stock_label                     fishery_id fishery_label landed_catch
#>      <dbl> <chr>                                <int> <chr>                <dbl>
#> 1      208 Georgia Strait Mainland Wild M…        134 Puyallup R N…         696.
#> 2      231 Upper Fraser River Wild UnMark…         81 WA Area 4B-5…         129.
#> 3       98 Green River Wild Marked                169 Lower Fraser…         587.
#> 4      189 Oregon Anadromous Hatchery UnM…         16 Brookings Tr…         403.
#> 5      142 Queets River Fall Hatchery Mar…         51 Humptulips R…         652.

Searching for stock or fishery

To identify a stock or fishery from an ID number, or to find the stock or fishery ID based on the name, framrosetta includes two search functions. fishery_search takes either a fishery ID number or a full or partial name and returns a tibble summarizing all fisheries that match; stock_search does the same for stocks. In both cases, the species argument must be provided to determine if the function should return the relevant "CHINOOK" or "COHO" fisheries / stocks. The pattern argument can take regular expressions, and is case insensitive.

## Figure out the coho fishery ids for the kmz fisheries
fishery_search("kmz", "COHO")
#> # A tibble: 2 × 5
#>   species version_number fishery_id fishery_name fishery_title
#>   <chr>            <int>      <int> <chr>        <chr>        
#> 1 COHO                 1          5 Ca KMZ Spt   KMZ Sport    
#> 2 COHO                 1          6 Ca KMZ Trl   KMZ Troll
## Figure out which Coho fishery has id 50
fishery_search(50, "COHO")
#> # A tibble: 1 × 5
#>   species version_number fishery_id fishery_name fishery_title           
#>   <chr>            <int>      <int> <chr>        <chr>                   
#> 1 COHO                 1         50 GryHbr Net   Grays Harbor Estuary Net
## Find all the Chinook noocksack stocks
stock_search("nooksack", "CHINOOK")
#> # A tibble: 6 × 7
#>   species stock_version stock_id production_region_number management_unit_number
#>   <chr>           <int>    <int>                    <int>                  <int>
#> 1 CHINOOK             5        4                        1                      6
#> 2 CHINOOK             5        6                        1                     10
#> 3 CHINOOK             5        2                        1                      2
#> 4 CHINOOK             5        3                        1                      5
#> 5 CHINOOK             5        5                        1                      9
#> 6 CHINOOK             5        1                        1                      1
#> # ℹ 2 more variables: stock_name <chr>, stock_long_name <chr>
## Figure out which Chinook stock has id 21
stock_search(21, "CHINOOK")
#> # A tibble: 1 × 7
#>   species stock_version stock_id production_region_number management_unit_number
#>   <chr>           <int>    <int>                    <int>                  <int>
#> 1 CHINOOK             5       21                        4                      1
#> # ℹ 2 more variables: stock_name <chr>, stock_long_name <chr>

Table summaries

framrosetta contains the following tables for translating FRAM fisheries, stocks, and areas to other fishery data or human readable formats:

`rmis_fram`

Translating between FRAM and RMIS.

knitr::kable(head(rmis_fram, 5))

psc_code	fishery_id	fishery_name	gear
2F 29FW	169	Fraser Spt	40
2F 29FW	169	Fraser Spt	41
2F 29FW	169	Fraser Spt	42
2F 29FW	169	Fraser Spt	43
2F 29FW	169	Fraser Spt	44

`tocas_fram`

Translating between FRAM and TOCAS.

knitr::kable(head(tocas_fram, 5))

fisher_type	gear	disposition	catch_area	fishery_id	fishery_name
1	41	C&SF	1	34	A1-Ast 41
1	41	COMM	1	34	A1-Ast 41
1	41	ORGN	1	34	A1-Ast 41
1	41	TEST	1	34	A1-Ast 41
1	41	TKHM	1	34	A1-Ast 41

`waft_fram`

Translating between WAFT and FRAM.

knitr::kable(head(waft_fram, 5))

fisher_type	gear	disposition	catch_area	fishery_id	fishery_name
1	41	C&SF	01	34	A1-Ast 41
1	41	COMM	01	34	A1-Ast 41
1	41	ORGN	01	34	A1-Ast 41
1	41	TEST	01	34	A1-Ast 41
1	41	TKHM	01	34	A1-Ast 41

`stock_chinook_fram`

Translating between Chinook stock IDs and human-readable names.

knitr::kable(head(stock_chinook_fram, 5))

species	stock_version	stock_id	production_region_number	management_unit_number	stock_name	stock_long_name
CHINOOK	5	4	1	6	M-NK Sp Hat	Marked Nooksack Spr Hatchery
CHINOOK	5	6	1	10	M-NK Sp Nat	Marked Nooksack Spr Natural
CHINOOK	5	8	2	2	M-Skag FF	Marked Skagit Summer/Fall Fing
CHINOOK	5	10	2	6	M-SkagFYr	Marked Skagit Summer/Fall Year
CHINOOK	5	12	2	10	M-SkagSpY	Marked Skagit Spring Year

`stock_coho_fram`

Translating between Coho stock IDs and human-readable names.

knitr::kable(head(stock_coho_fram, 5))

species	stock_version	stock_id	production_region_number	management_unit_number	stock_name	stock_long_name	limiting_stock_name	limiting_stock_name_tamm
COHO	1	1	1	1	U-nkskrw	Nooksack River Wild UnMarked	NA	NA
COHO	1	2	1	2	M-nkskrw	Nooksack River Wild Marked	NA	NA
COHO	1	3	1	3	U-kendlh	Kendall Creek Hatchery UnMarked	NA	NA
COHO	1	4	1	4	M-kendlh	Kendall Creek Hatchery Marked	NA	NA
COHO	1	5	1	5	U-skokmh	Skookum Creek Hatchery UnMarked	NA	NA

`stock_coho_psc`

Translating between Coho FRAM stock IDs and PSC IDs and names.

knitr::kable(head(stock_coho_psc, 5))

species	fram_stock_id	psc_stock_id	psc_stock_name
COHO	17	1	Skagit
COHO	18	1	Skagit
COHO	23	1	Skagit
COHO	24	1	Skagit
COHO	29	2	Stillaguamish

`fishery_chinook_fram`

Translating between Chinook fishery IDs and human-readable names.

knitr::kable(head(fishery_chinook_fram, 5))

species	version_number	fishery_id	fishery_name	fishery_title
CHINOOK	1	55	Tr 6B:9Net	Tr Area 6B:9 Net
CHINOOK	1	56	A 10 Sport	NT Area 10 Sport
CHINOOK	1	57	A 11 Sport	NT Area 11 Sport
CHINOOK	1	58	NT10:11Net	NT Area 10:11 Net
CHINOOK	1	59	Tr10:11Net	Tr Area 10:11 Net

`fishery_coho_fram`

Translating between Coho fishery IDs and human-readable names.

knitr::kable(head(fishery_coho_fram, 5))

species	version_number	fishery_id	fishery_name	fishery_title
COHO	1	1	No Cal Trm	No Calif Cst Terminal Catch
COHO	1	2	Cn Cal Trm	Cntrl Cal Cst Term Catch
COHO	1	3	Ft Brg Spt	Fort Bragg Sport
COHO	1	4	Ft Brg Trl	Fort Bragg Troll
COHO	1	5	Ca KMZ Spt	KMZ Sport

`fishery_coho_psc`

Translating between Coho FRAM fishery IDs and PSC IDs and names.

knitr::kable(head(fishery_coho_psc, 5))

species	fram_fishery_id	psc_fishery_id	psc_group_code	psc_fishery_name	psc_fishery_order
COHO	1	18	Southern U.S.	SOF All	17
COHO	2	18	Southern U.S.	SOF All	17
COHO	3	18	Southern U.S.	SOF All	17
COHO	4	18	Southern U.S.	SOF All	17
COHO	5	18	Southern U.S.	SOF All	17

`timestep_chinook_fram`

Translating between Chinook time-step IDs and human-readable names.

knitr::kable(head(timestep_chinook_fram, 5))

species	version_number	time_step_id	time_step_name	time_step_title
CHINOOK	1	1	Oct-Apr	October - April
CHINOOK	1	2	May-June	May - June
CHINOOK	1	3	July-Sept	July - September
CHINOOK	1	4	Oct-Apr2	October - April2

`timestep_coho_fram`

Translating between Coho time-step IDs and human-readable names.

knitr::kable(head(timestep_coho_fram, 5))

species	version_number	time_step_id	time_step_name	time_step_title
COHO	1	1	Jan-Jun	January - June
COHO	1	2	July	July
COHO	1	3	August	August
COHO	1	4	Septmbr	September
COHO	1	5	Oct-Dec	October - December

`bk_lookup_chin`

For Chinook only, the backwards FRAM algorithm uses a separate stock ID system that is hard-coded into FRAM. The underlying idea is that normally FRAM tracks two versions of each stock (marked and unmarked), or occasionally four versions of each stock (marked and unmarked). For part of backwards fram for Chinook, the algorithm separately handles the total number of fish across these versions of stock and the allocation of those fish into the two (or four) stocks. To do so, the algorithm creates a new stock id numbering system, with an additional “sum” stock for each of the pairs (or sets of four) marked/unmarked or marked/unmarked x hatch/natural stocks.

Unfortunately, this means that the BackwardFRAM table in any Chinook database has a StockID that does not match the StockID column in any of the other tables. framrosetta::bk_lookup_chin maps between the stock ids in the BackwardsFRAM table ($bk_stock_id) and the stock ids everywhere else ($stock_id).

knitr::kable(head(bk_lookupfun_chin, 5))

function (max_stock = NA)

{

if (!is.na(max_stock) & (!is.numeric(max_stock) | max_stock%%1 !=

0)) {

cli::cli_alert(“max_stock must be an integer.”)

- Key functions:
- Table summaries