---
title: "framrsquared"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{framrsquared}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(framrsquared)
```

The simplest use of the framrsquared package is import tables from a FRAM database into r-friendly format (tibbles), and filter to relevant fisheries or stocks. To do this, we use `connect_fram_db()` to create a connection, `fetch_table()` to pull in one or more tables, and -- if relevant -- one or more `filter_*()` to filter to the relevant subset of the table. Whenever we are done reading from a FRAM database, we use
`disconnect_fram_db()` to end the connection with our database file.


## Connecting to a FRAM database

```r
library(framrsquared)

fram_db <- connect_fram_db("<path_to_database>")

✔ Successfully connected to FRAM database
Database Species: COHO
Run Count:  34
Last Run Date:  Wed, April 10, 2024 05:42 PM
Last Run Name:  bc-Coho2425
Last Modify Date:  Wed, April 10, 2024 05:41 PM

```

## Importing FRAM tables into R
Imported tables from the FRAM database are automatically converted to [tibbles](https://github.com/tidyverse/tibble) and column names are converted to snakecase.
```r
time_step <- fram_db |> 
  fetch_table('TimeStep')

time_step

# A tibble: 9 × 5
  species version_number time_step_id time_step_name time_step_title   
  <chr>            <int>        <int> <chr>          <chr>             
1 COHO                 1            1 Jan-Jun        January - June    
2 COHO                 1            2 July           July              
3 COHO                 1            3 August         August            
4 COHO                 1            4 Septmbr        September         
5 COHO                 1            5 Oct-Dec        October - December
6 CHINOOK              1            1 Oct-Apr-1      October-April-1   
7 CHINOOK              1            2 May-June       May - June        
8 CHINOOK              1            3 July-Sept      July - September  
9 CHINOOK              1            4 Oct-Apr-2      October-April-2 
```

## Dynamic and Additive Fisheries Filtering
Filtering functions in this package are agnostic to species and designed to retain the same syntax between Chinook FRAM databases and coho FRAM databases.

State level filters:

- `filter_wa()` Filters fisheries to Washington
- `filter_bc()` Filters fisheries to Canada
- `filter_ca()` Filters fisheries to California
- `filter_or()` Filters fisheries to Oregon
- `filter_or()` Filters fisheries to Alaska

Gear level filters:

- `filter_net()` Filters to net fisheries
- `filter_sport()` Filters to sport fisheries

Regional level filters:

- `filter_marine()` Filters to marine fisheries
- `filter_coast()` Filters to coastal fisheries
- `filter_puget_sound()` Filters to Puget Sound Fisheries

## Example use case

Here we use these tools to identify the marine puget sound sport fisheries from a Coho database and then from a chinook database.

```r
# coho database
fram_db_coho <- connect_fram_db('<path_to_coho_database>')

fram_db_coho |> 
  fetch_table('Fishery') |>
  filter_marine() |>
  filter_puget_sound() |>
  filter_sport()

  # A tibble: 10 × 5
   species version_number fishery_id fishery_name fishery_title                     
   <chr>            <int>      <int> <chr>        <chr>                             
 1 COHO                 1         91 Area 5 Spt   WA Area 5 Sport (Sekiu)           
 2 COHO                 1         92 Area 6 Spt   WA Area 6 Sport (Port Angeles)    
 3 COHO                 1         93 Area 7 Spt   WA Area 7 Sport (San Juan Islands)
 4 COHO                 1        106 Ar 8-1 Spt   WA Area 8.1 Sport (Skagit Bay)    
 5 COHO                 1        107 Area 9 Spt   WA Area 9 Sport (Admirality Inlet)
 6 COHO                 1        115 Ar 8-2 Spt   WA Area 8.2 Sport (Everett)       
 7 COHO                 1        118 Ar 10  Spt   WA Area 10 Sport (Seattle)        
 8 COHO                 1        129 Ar 11  Spt   WA Area 11 Sport (Tacoma)         
 9 COHO                 1        136 Ar 13  Spt   WAArea 13 Marine Sport            
10 COHO                 1        152 Ar 12  Spt   Area 12 Marine Sport   

# chinook database
fram_db_chinook <- connect_fram_db('<path_to_chinook_database>')

fram_db_chinook |> 
  fetch_table('Fishery') |>
  filter_marine() |>
  filter_puget_sound() |>
  filter_sport()

# A tibble: 12 × 5
   species version_number fishery_id fishery_name fishery_title    
   <chr>            <int>      <int> <chr>        <chr>            
 1 CHINOOK              1         56 A 10 Sport   NT Area 10 Sport 
 2 CHINOOK              1         57 A 11 Sport   NT Area 11 Sport 
 3 CHINOOK              1         60 A 10A Sprt   NT Area 10A Sport
 4 CHINOOK              1         62 A 10E Sprt   NT Area 10E Sport
 5 CHINOOK              1         64 A 12 Sport   NT Area 12 Sport 
 6 CHINOOK              1         67 A 13 Sport   NT Area 13 Sport 
 7 CHINOOK              1         36 Ar 7 Sport   NT Area 7 Sport  
 8 CHINOOK              1         42 Ar 5 Sport   NT Area 5 Sport  
 9 CHINOOK              1         45 Ar 8-1 Spt   NT Area 8-1 Sport
10 CHINOOK              1         48 Area8D Spt   NT Area 8D Sport 
11 CHINOOK              1         53 Ar 9 Sport   NT Area 9 Sport  
12 CHINOOK              1         54 Ar 6 Sport   NT Area 6 Sport  

# disconnect databases
disconnect_fram_db(fram_db_coho)
✔ Successfully disconnected from FRAM database (fram_db_coho)

disconnect_fram_db(fram_db_chinook)
✔ Successfully disconnected from FRAM database (fram_db_chinook)
```