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

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

Here we describe the various functions within the `afscISS` package that obtain results provided from the `surveyISS` package.

## afscISS::get_ISS()
The primary result that is provided by the `afscISS` package is the annual input sample size (ISS) for age, length, or conditional age-at-length composition data by survey region; this is provided by the `afscISS::get_ISS()` function.
The following is an example for standard age composition ISS for GOA Pacific cod:

```
afscISS::get_ISS(species = 21720,
                 region = 'goa',
                 comp = 'age',
                 sex_cat = 4,
                 spec_case = NULL)
```

The `species` argument in the `afscISS::get_ISS()` function is the RACE species code for your species.

The `region` argument in the `afscISS::get_ISS()` function is the survey region for which you desire the ISS.
Currently there are 5 survey regions, described in the following table:

| region | Description |
| ---- | ---------------------------------- |
| ai | Aleutian Islands survey region |
| ebs | Eastern Bering Sea survey region |
| ebs_slope | Eastern Bering Sea slope survey region |
| goa | Gulf of Alaska survey region |
| nebs | Combined Northern and Eastern Bering Sea survey regions |

The `comp` argument in the `afscISS::get_ISS()` function is the composition type for which you desire ISS.
There are 3 options: `age` for age composition, `length` for length composition, and `caal` for conditional age-at-length composition.

The `sex_cat` argument in the `afscISS::get_ISS()` function is the sex category for the specific composition data for which you are obtaining ISS output.
There are 5 options, described in the following table:

| sex_cat | Description |
| ---- | ---------------------------------- |
| 0 | Combined sex categories (females + males + unsexed) that are combined prior to computation of composition|
| 1 | Male composition |
| 2 | Female composition |
| 12 | Female-Male composition that sums to 1 across both sexes (rather than sum to 1 across Females or Males only) |
| 4 | Combined sex categories (females + males + unsexed) that are combined after the computation of composition. Note that this is the historical standard for combined sex composition data at AFSC. Also note that there is no sex category of 4 for conditional age-at-length data, as it is equivalent to sex category 0. |

Finally, the `spec_case` argument in the `afscISS::get_ISS()` function specifies whether you desire ISS for a special case function within the `surveyISS` package.
There are three general categories of special cases: (1) stock complex special cases, (2) spatially-explicit special cases, and (3) length binning special case (note that the first two special cases only pertain the the AI and GOA survey regions).
The stock complex special cases include:

| spec_case | Description |
| ---- | ---------------------------------- |
| bsre | Provides output for the AI Blackspotted-Rougheye stock complex (where length pop'n computed for each individual species but age pop'n computed for the complex as a whole). |
| dr | Provides output for the GOA dusky rockfish stock. |
| rebs | Provides output for the GOA Rougheye-Blackspotted stock complex (where length and age pop'n are computed for each individual species and summed post-expansion). |

Note that for the `bsre`, `dr`, and `rebs` special cases, the `species` argument is not needed (so you can either leave this argument out or define it as NULL), as a special species code has already been defined (as an agglomeration of the individual species codes). Also note for that these stock complex special cases are not included in the spatially-explicit special cases.
The spatially-explicit special cases are as follows:

| spec_case | Description |
| ---- | ---------------------------------- |
| ai_subreg | Provides output for age/length composition (but not caal) computed at the sub-region scale within the AI survey region (and will also provide output for the combined values at the overall AI region). |
| w140 | Provides output for age/length composition (but not caal) computed for the GOA survey region west of 140$^\circ$ longitude (currently only computed for the GOA walleye pollock stock). |
| w_c_egoa | Provides output computed for the Western, Central, and Eastern GOA survey regions (and will also provide output for the combined values at the overall GOA region). |
| wc_egoa | Provides output computed for the Western-Central GOA (combined), and Eastern GOA survey regions (and will also provide output for the combined values at the overall GOA region). |

Finally, the length binning special case allows for custom length bins other than at 1 cm (which is the default setting).
Note that providing output for this case is still under construction (in terms of providing standard output from this package) and if you want to explore alternative length bins please contact us and we'll set up custom output for you.

The output that will return from the `afscISS::get_ISS()` function will include the following columns:

| Column | Description |
| ---- | ---------------------------------- |
| year | Survey year. |
| species_code | RACE species code. |
| sex | Numerical value for sex category (described in table above). |
| sex_desc | Text string with short description of sex category. |
| iss | Input sample size. |
| sd_iss | Standard deviation of input sample size (derived as the SD of a harmonic mean using the delta method). |
| nss* | Nominal sample size (the number of age/length samples collected). |
| nhl | Number of hauls from which samples were collected. |

*in the eastern bering sea survey region there is a juvenile/adult expansion that occurs within the length frequency data prior to the design-based expansion (further details can be found in this gapindex [issue](https://github.com/afsc-gap-products/gapindex/issues/68#issuecomment-2675557545)), thus, the nominal sample size in some cases (e.g., pollock) reported in this output will not be the actual numbers of fish lengthed, but will be much larger.
We note that this will have minimal (if any) impact on the resulting input sample size as previous experiments ([Hulson et al. 2024](https://cdnsciencepub.com/doi/10.1139/cjfas-2023-0164)) have shown that (1) length samples greater than 250 per haul have little influence on the resulting length composition input sample size (i.e., reducing from 10k expanded length samples to 500 actual samples withing a haul will have negligible impact), and (2) age composition input sample size was stable across a range of lengths sampled within a haul.

## afscISS::get_popn()

The `afscISS::get_popn()` function obtains the design-based expanded population at age or length values (will also provide the design-based mean and sd in length-at-age when obtaining age output). This output replicates what is provided in the GAP_PRODUCTS tables, with the exception of the special cases implemented in the `surveyISS` package that are not available in the `gapindex` package. Note that the `sex_cat` arguments for this function are 0 (sexes combined pre-expansion), 1 (males), 2 (females), 3 (unsexed), and 4 (sexes combined post-expansion) and does not include `sex_cat` argument of 12 (as those results are provided in this case for `sex_cat` 1 and 2 individually). The output that will return from the `afscISS::get_popn()` function for `comp = 'age'` will include the following columns:

| Column | Description |
| ---- | ---------------------------------- |
| year | Survey year. |
| species_code | RACE species code. |
| sex | Numerical value for sex category. |
| age | Age. |
| agepop | Design-based expanded population numbers for age. |
| mean_length | Design-based computed mean length-at-age. |
| sd_length | Design-based computed standard deviation in length-at-age. |

The output that will return from the `afscISS::get_popn()` function for `comp = 'length'` will include the following columns:

| Column | Description |
| ---- | ---------------------------------- |
| year | Survey year. |
| species_code | RACE species code. |
| length | Length in cm. |
| sex | Numerical value for sex category. |
| abund | Design-based expanded population numbers for length. |

## afscISS::get_comp()

The `afscISS::get_comp()` function obtains the computed age, length, and conditional age-at-length composition from design-based population estimates (i.e., the proportions that would be used in a stock assessment model). The output that will return from the `afscISS::get_comp()` function for `comp = 'age'` and `comp = 'length'` will include the following columns:

| Column | Description |
| ---- | ---------------------------------- |
| year | Survey year. |
| species_code | RACE species code. |
| sex | Numerical value for sex category. Note that when `sex_cat = 12` this will return values of 1 (males) and 2 (females) in the sex column where the proportions will sum to 1 across both sexes. |
| age/length | Age or length (in cm). |
| prop | Proportion at age or length. |
| q2_5th | 2.5th percentile in the bootstrapped proportion at age or length. |
| q97_5th | 97.5th percentile in the bootstrapped proportion at age or length. |

The output that will return from the `afscISS::get_comp()` function for `comp = 'caal'` will include the following columns:

| Column | Description |
| ---- | ---------------------------------- |
| year | Survey year. |
| species_code | RACE species code. |
| sex | Numerical value for sex category. Note that the only `sex_cat` arguments available for `comp = 'caal'` are 0 (combined sexes), 1 (males), and 2 (females). |
| length | Length in cm. |
| age | Age. |
| caal | Proportion at age within given length. |
| q2_5th | 2.5th percentile in the bootstrapped proportion at age within given length. |
| q97_5th | 97.5th percentile in the bootstrapped proportion at age within given length. |

## afscISS::get_bias()

The `afscISS::get_bias()` function obtains the average bias in the bootstrap simulated age/length/conditional age-at-length. The output that will return from the `afscISS::get_bias()` function for `comp = 'age'` and `comp = 'length'` will include the following columns:

| Column | Description |
| ---- | ---------------------------------- |
| year | Survey year. |
| species_code | RACE species code. |
| sex | Numerical value for sex category. |
| bias | Average bias in composition across age/length. |

The output that will return from the `afscISS::get_bias()` function for `comp = 'caal'` will include the same columns as `comp = 'age'` or `comp = 'length'`, with an additional column for length (in cm) to reflect that the bias column is the average bias in composition across age within given length. Note that the only `sex_cat` arguments available for `comp = 'caal'` are 0 (combined sexes), 1 (males), and 2 (females).