First-Stage expansion for composition data

First-stage expansions account for unsampled fish in the smallest measured unit. Where, in PacFIN data, the smallest measured unit typically a trip because that is what is available to the port or dockside sampler. Whereas, in survey data the smallest measured unit is typically a tow. Tow would be the smallest if we had samples from onboard observers rather than from dockside samplers.

getExpansion_1(
  Pdata,
  fa,
  fb,
  ma,
  mb,
  ua,
  ub,
  maxExp = 0.95,
  Exp_WA = TRUE,
  verbose = TRUE,
  plot = lifecycle::deprecated(),
  savedir = NULL
)

Arguments

Pdata: A data frame returned from PullBDS.PacFIN() containing biological samples. These data are stored in the Pacific Fishieries Information Network (PacFIN) data warehouse, which originated in 2014 and are pulled using sql calls.
fa, ma, ua: Female-, male-, and unsexed-specific weight–length coefficients for Stock Synthesis where the relationships were calculated using length in cm and weight in kg. There are no default values. You must calculate these values and pass them to the function. If a particular sex does not pertain to your data, then just pass NA for that relationship.
fb, mb, ub: Female-, male, and unsexed-specific weight–length exponents for Stock Synthesis where the relationships were calculated using length in cm and weight in kg. If a particular sex does not pertain to your data, then just pass NA for that relationship.
maxExp: The maximum expansion factor (either a number or a quantile) for building expansions. Typically, the default is 0.95. Set maxExp = Inf to see largest values.
Exp_WA: A logical values specifying if the samples from Washington should be exanded. The default is FALSE.
verbose: A logical specifying if output should be written to the screen or not. Good for testing and exploring your data but can be turned off when output indicates information that you already know. The printing of output to the screen does not affect any of the returned objects. The default is to always print to the screen, i.e., verbose = TRUE.
plot: Typically, a logical is passed defining if you would like the default plots to be created but users can also pass a string providing a path to a directory where those plots will be stored. The default is FALSE and no figures will be created unless this is changed. If TRUE is passed, then the figures will be saved to your current working directory.
savedir: A file path to the directory where the results will be saved. The default is NULL.

Value

A data.frame where all of the original columns in Pdata remain unaltered but additional columns are added. In particular columns starting with Expansion_Factor_1 are available for setting the Final_Expansion_Factor.

Details

The workflow is to run this function after cleanPacFIN(), which assures that all of the necessary columns are available and that the data are in the correct units. This function then calls two helper functions, EF1_Numerator() and EF1_Denominator() to calculate the weight of sampled fish and the weight of all fish of the respective species in the tow, respectively. Finally, the ratio of the two values is returned. Alternatively, users should consider using get_pacfin_expansions() which is a wrapper function that calls both the first and second stage functions for expanding composition data.

Expansion

Age data are expanded separately from lengths.
WA fish are generally only expanded using Expansion_Factor_2.
Other expansions are the product of Expansion_Factor_1 * Expansion_Factor_2.
For age-at-length comps, set Final_Expansion_Factor to 1 because each fish represents only itself.

Author

Andi Stephens, Kelli F. Johnson, Chantel R. Wetzel

Examples

if (FALSE) { # \dontrun{
# Calculate the weight--length parameters for input to this function
bds_survey <- nwfscSurvey::pull_bio(
  common_name = "widow rockfish",
  survey = "NWFSC.Combo"
)
pars <- nwfscSurvey::estimate_weight_length(
  data = bds_survey,
  col_length = "length_cm",
  col_weight = "weight_kg",
  verbose = FALSE
)
data_exp1 <- getExpansion_1(
  Pdata = bds_cleaned,
  fa = weight_length_estimates |>
    dplyr::filter(sex == "female") |>
    dplyr::pull("A"),
  fb = weight_length_estimates |>
    dplyr::filter(sex == "female") |>
    dplyr::pull("B"),
  ma = weight_length_estimates |>
    dplyr::filter(sex == "male") |>
    dplyr::pull("A"),
  mb = weight_length_estimates |>
    dplyr::filter(sex == "female") |>
    dplyr::pull("B"),
  ua = weight_length_estimates |>
    dplyr::filter(sex == "all") |>
    dplyr::pull("A"),
  ub = weight_length_estimates |>
    dplyr::filter(sex == "all") |>
    dplyr::pull("B"),
  maxExp = 0.95
)
} # }