---
title: 'Tables and Stock Summary Description'
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: |
  %\VignetteIndexEntry{tables_description}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Description of the dataframes present in the database:

* metadata: Table with summarized metadata (only available in newer versions starting from v4.40)
* stock: This stores the stock database table
* assessment: This stores the assessment database table
* taxonomy: This stores the taxonomy database table
* management: This stores the management database table
* assessor: This stores the assessor database table
* assessmetod: This stores the assessmetod database table
* area: This stores the area database table
* biometrics: This stores the biometrics database table
* tsmetrics: This stores the tsmetrics database table
* timeseries: The time series data is a matrix object with the following headers/columns: (1) assessid (2) stockid (3) stocklong (4) tsid (5) tsyear (6) tsvalue
* bioparams: The parameter data is a matrix object with the following headers/columns: (1) assessid (2) stockid (3) stocklong (4) bioid (5) biovalue (6) bioyear (7) bionotes
* timeseries_values_views: This stores the timeseries values with timeseries type along the columns and stocks along the rows
* timeseries_units_views: This stores the timeseries values with timeseries type along the columns and stocks along the rows
* timeseries_ids_views: This stores the timeseries IDs with timeseries type along the columns and stocks along the rows
* timeseries_assessments_views: This stores the timeseries assessments with timeseries type along the columns and stocks along the rows
* timeseries_notes_views: This stores the timeseries notes with timeseries type along the columns and stocks along the rows
* timeseries_sources_views: This stores the timeseries sources with timeseries type along the columns and stocks along the rows
* timeseries_years_views: This stores the timeseries years with timeseries type along the columns and stocks along the rows
* bioparams_values_views: This stores the reference point values, with reference point type along the columns and stocks along the rows
* bioparams_units_views: This stores the reference point units, with reference point type along the columns and stocks along the rows
* bioparams_ids_views: This stores the reference point IDs, with reference point type along the columns and stocks along the rows
* bioparams_assessments_views: This stores the reference point assessments, with reference point type along the columns and stocks along the rows
* bioparams_sources_views: This stores the reference point sources, with reference point type along the columns and stocks along the rows
* bioparams_notes_views: This stores the reference point notes, with reference point type along the columns and stocks along the rows

## Newer Versions (v4.40 onwards) also contain tables of individual most-used time series:

* tb.data: Total Biomass
* ssb.data: Spawning Stock Biomass
* tn.data: Total Abundance
* r.data: Recruits
* tc.data: Total Catch
* tl.data: Total Landings
* recc.data: Recreational Catch
* f.data: Fishing Mortality
* er.data: Exploitation Rate
* divtb.data: TB/TBmsy
* divssb.data: SSB/SSBmsy
* ivf.data: F/Fmsy
* diver.data: ER/ERmsy
* divbpref.data: B/Bmsypref
* divupref.data: U/Umsypref
* tbbest.data: TBbest
* tcbest.data: TCbest
* erbest.data: ERbest
* divtb.mgt.data: TB/TBmgt
* divssb.mgt.data: SSB/SSBmgt
* divf.mgt.data: F/Fmgt
* diver.mgt.data: ER/ERmgt
* divbpref.mgt.data: B/Bmgtpref
* divupref.mgt.data: U/Umgtpref
* cpair.data: Cpair
* tac.data: TAC
* cadv.data: Cadvised
* survb.data: survB
* cpue.data: CPUE
* effort.data: EFFORT


## Stock Summary Description

### Information Contained in the Stock Summary Documents

* A list of all stocks present in the region
    + specifies whether the stock includes B/Bmsy, U/Umsy, B/Bmgt, and U/Umgt time series data
    + specifies whether TB or SSB is preferred, and whether ER or F is preferred, if both types are present

### Information available for each stock:

* Metadata (scientific name, area, management authority, assessor, assessment years)
* Reference points available for stock
* Time series available for stock
* Plots – based on available data, may include:
    +  Kobe plot (MSYpref) – Plots U/Umsy vs. B/Bmsy if available, filling in gaps with U/Umgt and B/Bmgt if         available
    + Kobe plot (MGTpref) – Plots U/Umgt vs. B/Bmgt if available, filling in gaps with U/Umsy and B/Bmsy if          available
    + Spawner Recruitment – Plots recruits vs. spawning-stock biomass
    + Surplus Production – Plots annual surplus production vs. total biomass
    + Total Biomass – Preferably plots the most recent TB time series from an assessment with a MSY,                management target, or limit reference point available, otherwise plots most recent TB time series.
    + Spawning stock biomass – Preferably plots the most recent SSB time series from an assessment with a MSY,       management target, or limit reference point available, otherwise plots most recent SSB time series.
    + Total abundance (in numbers) – Preferably plots the most recent TN time series from an assessment with a       MSY, management target, or limit reference point available, otherwise plots most recent TN time series.
    + Fishing mortality (instantaneous rate) – Preferably plots the most recent F time series from an               assessment with a MSY, management target, or limit reference point available, otherwise plots most            recent F time series.
    + Exploitation rate (annual proportion) – Preferably plots the most recent ER time series from an               assessment with a MSY, management target, or limit reference point available, otherwise plots most            recent ER time series.
    + Recruits – Plots the most recent recruitment time series. If known, the year range during which               recruitment deviates were estimated in the assessment model is shaded grey.
    + TC, TL, RecC – Plots most recent catch and/or landings as well as recreational catch  and MSY if they         are also available from that assessment. (The year range of moratoriums are shaded grey if available.)
    + TAC, Cpair, Cadv – Plots most recent total allowable catch or landings (or other measures of total            quota), the corresponding catch or landings, and the corresponding scientifically advised catch if            available from the same assessment.
    + survB – Plots the most recent fishery-independent survey biomass time series.
    + CPUE – Plots the most recent fishery-independent catch-per-unit-effort time series.
    + EFFORT – Plots the most recent fishing effort time series.
    + CdivMSY – Plots the ratio of the most recent catch time series to MSY. MSY is drawn from the assessment       directly if available, or else is calculated from Bmsy and Umsy reference points (including proxies) if       available.

### Acronym and Abbreviation Definitions

* B – Biomass; may be either total biomass or spawning stock biomass
* Bmgt – Biomass at management target reference point
* Bmsy – Biomass at MSY
* Cadv – Scientifically advised catch
* CdivMSY – Catch divided by MSY
* Cpair – Catch corresponding to TAC and Cadv
* CPUE – Catch per unit effort
* EFFORT – Measure of fishing effort (depends on fishery)
* ER – Exploitation rate (annual proportion)
* F – Fishing mortality (instantaneous rate)
* MSY – Maximum Sustainable Yield
* RecC – Recreational catch
* SSB – Spawning stock biomass
* survB – Survey biomass
* TAC – Total allowable catch
* TB – Total biomass
* TC – Total catch 
* TL – Total landings
* TN – Total abundance; in numbers
* U – Harvest rate; may be either exploitation rate or fishing mortality
* Umsy – Harvest rate at MSY
* Umgt – Harvest rate at management target reference point