---
title: "Demonstration of the fishprior R package"
output: github_document
vignette: >
  %\VignetteIndexEntry{Demonstration of the fishprior R package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## fishprior

The vignette provides a demonstration on how to use the fishprior package to obtain priors for life-history parameters that will be applicable in the assessment of the status of the population.

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(fishprior)
```

## Data

Data for priors can be obtained from either FishBase using `get_fishbase_traits()` and `summarize_fishbase_traits()`, which is a wrapper around the `rfishbase` package.


This example provides code used to query FishBase for traits for three species. The `rfishbase` package provides a flexible approach for querying tables in FishBase, and our functions act as wrappers for these calls.

```{r example-fishbase, warning=FALSE, message=FALSE}
species_list <- c(
  "Merluccius merluccius",
  "Gadus chalcogrammus",
  "Anoplopoma fimbria"
)
example_base_raw <- get_fishbase_traits(spec_names = species_list)
example_base_raw
```

This data can be summarized to provide output similar to what is returned from FishLife. Only a handful of traits are currently summarized but more can be provided in the future should it be desired. Feel free to fill out a [GitHub Issue](https://github.com/NOAA-FIMS/fishprior) if you would like to see more traits summarized.

```{r summarize-example, warning=FALSE, message=FALSE}
example_base <- summarize_fishbase_traits(example_base_raw)
example_base
```

## Filtering

As an example of querying data and building custom priors, we will start with a simple example based on Atlantic cod (*Gadus morhua*). The data pulled from FishBase can be limited to just the data that pertains to cod. Each row represents a unique combination of study and trait. Initial columns store metadata about the study and the value column stores the value of the trait found in that study.

```{r example-cod, warning=FALSE, message=FALSE}
cod_traits <- get_fishbase_traits(spec_names = "Gadus morhua")
```

The study-specific traits can be summarized as we did before but now just for cod using `summarize_fishbase_traits()`.

```{r summarize-cod, warning=FALSE, message=FALSE}
cod_summary <- summarize_fishbase_traits(cod_traits)
```

This approach is simple because it uses all studies in FishBase to summarize data; in practice, it may be of interest to only use studies from a specific region. As a demonstration of how to do this, we provide a slightly more complex example. Each of the tables returned by `get_fishbase_traits()` has a `Locality` field, e.g., 

```{r locality}
cod_traits |>
  dplyr::count(Locality)
```

Looking at the locality for growth for example, a handful of studies are from eastern Canada and the northeastern United States. If we wanted to summarize only these studies, we can use some custom filtering.

```{r cod-filter}
cod_traits_filtered <- cod_traits |>
  dplyr::filter(
    rfishbase == "popgrowth",
    grepl(
      "Southern Gulf of St\\. Lawrence|Gulf of Maine|Southern New England",
      Locality
    )
  )
dplyr::count(cod_traits_filtered, trait, Locality)
```

And then we can pass our filtered data frame into `summarize_fishbase_traits()`

```{r summarize-code-filtered}
cod_summary_filtered <- summarize_fishbase_traits(cod_traits_filtered)
cod_summary_filtered
```

Because we only filtered locality for the results from `rfishbase::popgrowth()`, this filtering only affects summaries for parameters coming from this table ("log(growth_coefficient)", "log(length_infinity)").