diff --git a/NAMESPACE b/NAMESPACE index 74fc329..9c67677 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -29,6 +29,7 @@ export(disconnect_fram_db) export(error_check_code) export(fetch_quarto_templates) export(fetch_table) +export(fetch_table_bkchin) export(filter_ak) export(filter_bc) export(filter_ca) diff --git a/R/fetch_data.R b/R/fetch_data.R index 966fbcb..66a5a0b 100644 --- a/R/fetch_data.R +++ b/R/fetch_data.R @@ -55,10 +55,54 @@ fetch_table <- function(fram_db, table_name = NULL){ glue::glue('SELECT * FROM {table_name};')) |> fram_clean_tables() attr(output_table, 'species') <- fram_db$fram_db_species + + if(fram_db$fram_db_species == "CHINOOK" & table_name == "BackwardsFRAM"){ + cli::cli_alert_danger("Chinook BackwardsFRAM tables use different numbering for stock_id!\n This can cause problems when merging with other tables!\n Recommend fetch_table_bkchin() instead.") + } + return(output_table) } } +#' Safely fetch Chinook BackwardsFRAM table +#' +#' The BackwardsFRAM table uses a stock_id different numbering system from all other tables, and includes +#' sums of joint stocks (e.g. for a marked and unmarked pair of stocks, BackwardsFRAM will typically have an additional +#' stock which represents the sum of those two). Because the numbering is different but the column name is the same, +#' joining the Chinook BackwardsFRAM table with other tables can cause problems. +#' +#' This function augments fetch_table by renaming the `stock_id` column to `bk_stock_id`, and +#' then adding on the associated stock_id (with NAs when the bkfram stock is one of these new "sum" stocks +#' and the associated bkfram stock names). This function only works for Chinook databases. +#' +#' **The resulting dataframe will necessarily NOT be an exact match to the BackwardsFRAM table in the FRAM database. The stock_id column will differ (containing normal stock ID values instead of bk stock ID values), and there will be two additional columns.** +#' +#' @param fram_db FRAM database object +#' +#' @export +#' +#' @examples +#' #' @examples +#' \dontrun{ +#' ##Potentially problematic stock_id won't align with other tables +#' fram_db |> fetch_table('BackwardsFRAM') +#' ## "safe" version of the table; stock_id WILL align with other tables +#' fram_db |> fetch_table_bkchin() +#' } +fetch_table_bkchin <- function(fram_db){ + validate_fram_db(fram_db) + + if(fram_db$fram_db_species != "CHINOOK"){ + cli::cli_abort("`fetch_table_bkchin()` only appropriate for CHINOOK databases, not {fram_db$fram_db_species} database.") + } + + output_table <- fetch_table(fram_db, table_name = "BackwardsFRAM") |> + dplyr::rename(bk_stock_id = .data$stock_id) |> + dplyr::left_join(framrosetta::bk_lookup_chin, by = "bk_stock_id") + + return(output_table) +} + #' List names of FRAM table #' @@ -76,59 +120,59 @@ provide_table_names <- function(is_full = TRUE){ if(!is.logical(is_full)){ cli::cli_abort("`is_full` must be TRUE or FALSE, not `{is_full}`") } - if(is_full){ ## list of possible table names from a full table - c('AEQ', - 'BackwardsFRAM', - 'BaseCohort', - 'BaseExploitationRate', - 'BaseID', - 'ChinookBaseEncounterAdjustment', - 'ChinookBaseSizeLimit', - 'Cohort', - 'EncounterRateAdjustment', - 'Escapement', - 'Fishery', - 'FisheryModelStockProportion', - 'FisheryMortality', - 'FisheryScalers', - 'Growth', - 'IncidentalRate', - 'MaturationRate', - 'Mortality', - 'NaturalMortality', - 'NonRetention', - 'PSCMaxER', - 'ReportDriver', - 'RunEncounterRateAdjustment', - 'RunID', - 'ShakerMortRate', - 'SizeLimits', - 'SLRatio', - 'Stock', - 'StockFisheryRateScaler', - 'StockRecruit', - 'TAAETRSList', - 'TerminalFisheryFlag', - 'TimeStep' - ) - } else { - c( - 'BackwardsFRAM', - 'BaseID', - 'Cohort', - 'Escapement', - 'FisheryMortality', - 'FisheryScalers', - 'Mortality', - 'NonRetention', - 'PSCMaxER', - 'RunID', - 'SizeLimits', - 'SLRatio', - 'StockFisheryRateScaler', - 'StockRecruit', - 'TAAETRSList' - ) - } + if(is_full){ ## list of possible table names from a full table + c('AEQ', + 'BackwardsFRAM', + 'BaseCohort', + 'BaseExploitationRate', + 'BaseID', + 'ChinookBaseEncounterAdjustment', + 'ChinookBaseSizeLimit', + 'Cohort', + 'EncounterRateAdjustment', + 'Escapement', + 'Fishery', + 'FisheryModelStockProportion', + 'FisheryMortality', + 'FisheryScalers', + 'Growth', + 'IncidentalRate', + 'MaturationRate', + 'Mortality', + 'NaturalMortality', + 'NonRetention', + 'PSCMaxER', + 'ReportDriver', + 'RunEncounterRateAdjustment', + 'RunID', + 'ShakerMortRate', + 'SizeLimits', + 'SLRatio', + 'Stock', + 'StockFisheryRateScaler', + 'StockRecruit', + 'TAAETRSList', + 'TerminalFisheryFlag', + 'TimeStep' + ) + } else { + c( + 'BackwardsFRAM', + 'BaseID', + 'Cohort', + 'Escapement', + 'FisheryMortality', + 'FisheryScalers', + 'Mortality', + 'NonRetention', + 'PSCMaxER', + 'RunID', + 'SizeLimits', + 'SLRatio', + 'StockFisheryRateScaler', + 'StockRecruit', + 'TAAETRSList' + ) + } } diff --git a/man/fetch_table_bkchin.Rd b/man/fetch_table_bkchin.Rd new file mode 100644 index 0000000..6de6f67 --- /dev/null +++ b/man/fetch_table_bkchin.Rd @@ -0,0 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/fetch_data.R +\name{fetch_table_bkchin} +\alias{fetch_table_bkchin} +\title{Safely fetch Chinook BackwardsFRAM table} +\usage{ +fetch_table_bkchin(fram_db) +} +\arguments{ +\item{fram_db}{FRAM database object} +} +\description{ +The BackwardsFRAM table uses a stock_id different numbering system from all other tables, and includes +sums of joint stocks (e.g. for a marked and unmarked pair of stocks, BackwardsFRAM will typically have an additional +stock which represents the sum of those two). Because the numbering is different but the column name is the same, +joining the Chinook BackwardsFRAM table with other tables can cause problems. +} +\details{ +This function augments fetch_table by renaming the \code{stock_id} column to \code{bk_stock_id}, and +then adding on the associated stock_id (with NAs when the bkfram stock is one of these new "sum" stocks +and the associated bkfram stock names). This function only works for Chinook databases. + +\strong{The resulting dataframe will necessarily NOT be an exact match to the BackwardsFRAM table in the FRAM database. The stock_id column will differ (containing normal stock ID values instead of bk stock ID values), and there will be two additional columns.} +} +\examples{ +#' @examples +\dontrun{ +##Potentially problematic stock_id won't align with other tables +fram_db |> fetch_table('BackwardsFRAM') +## "safe" version of the table; stock_id WILL align with other tables +fram_db |> fetch_table_bkchin() +} +}