penPass: R package for Atlantic salmon PenPass model

#' @title Downstream data for Browns Mills
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. 
#' 
#' @format A dataframe with 857 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Amaral S, Fay C, Hecker G, Perkins N. 2012. Atlantic salmon survival 
#' estimates at mainstem hydroelectric projects on the Penobscot River. 
#' Phase 3 Final Report. Alden Research Laboratory, Inc., Holden, MA.
#' 
#' Nieland JL, Sheehan TF. 2020. Quantifying the Effects of Dams on Atlantic Salmon
#' in the Penobscot River Watershed, with a Focus on Weldon Dam. US Department of 
#' Commerce, Northeast Fisheries Science Center Reference Document 19-16, Woods 
#' Hole, MA.
#' 
#' Nieland JL, Sheehan TF, Saunders R. 2015. Assessing demographic effects of dams
#' on diadromous fish: a case study for Atlantic salmon in the Penobscot River, 
#' Maine. ICES Journal of Marine Science 72:2423–2437. 
#' 
#' Nieland JL, Sheehan TF, Saunders R, Murphy JS, Trinko Lake TR, Stevens JR. 2013. 
#' Dam Impact Analysis model for Atlantic salmon in the Penobscot River, Maine. US 
#' Department of Commerce, Northeast Fisheries Science Center Reference Document 
#' 13-09, Woods Hole, MA.
#' 
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"downstream_brownsmills"

#' @title Downstream data for Great Works
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. 
#' 
#' @format A dataframe with 7,168 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Amaral S, Fay C, Hecker G, Perkins N. 2012. Atlantic salmon survival 
#' estimates at mainstem hydroelectric projects on the Penobscot River. 
#' Phase 3 Final Report. Alden Research Laboratory, Inc., Holden, MA.
#' 
#' Nieland JL, Sheehan TF, Saunders R. 2015. Assessing demographic effects of dams
#' on diadromous fish: a case study for Atlantic salmon in the Penobscot River, 
#' Maine. ICES Journal of Marine Science 72:2423–2437. 
#' 
#' Nieland JL, Sheehan TF, Saunders R, Murphy JS, Trinko Lake TR, Stevens JR. 2013. 
#' Dam Impact Analysis model for Atlantic salmon in the Penobscot River, Maine. US 
#' Department of Commerce, Northeast Fisheries Science Center Reference Document 
#' 13-09, Woods Hole, MA.
#' 
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"downstream_greatworks"

#' @title Downstream data for Howland
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. 
#' 
#' @format A dataframe with 3,315 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Amaral S, Fay C, Hecker G, Perkins N. 2012. Atlantic salmon survival 
#' estimates at mainstem hydroelectric projects on the Penobscot River. 
#' Phase 3 Final Report. Alden Research Laboratory, Inc., Holden, MA.
#' 
#' Nieland JL, Sheehan TF, Saunders R. 2015. Assessing demographic effects of dams
#' on diadromous fish: a case study for Atlantic salmon in the Penobscot River, 
#' Maine. ICES Journal of Marine Science 72:2423–2437. 
#' 
#' Nieland JL, Sheehan TF, Saunders R, Murphy JS, Trinko Lake TR, Stevens JR. 2013. 
#' Dam Impact Analysis model for Atlantic salmon in the Penobscot River, Maine. US 
#' Department of Commerce, Northeast Fisheries Science Center Reference Document 
#' 13-09, Woods Hole, MA.
#' 
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"downstream_howland"

#' @title Downstream data for Mattaceunk
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. 
#' 
#' @format A dataframe with 8,681 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Amaral S, Fay C, Hecker G, Perkins N. 2012. Atlantic salmon survival 
#' estimates at mainstem hydroelectric projects on the Penobscot River. 
#' Phase 3 Final Report. Alden Research Laboratory, Inc., Holden, MA.
#' 
#' Nieland JL, Sheehan TF, Saunders R. 2015. Assessing demographic effects of dams
#' on diadromous fish: a case study for Atlantic salmon in the Penobscot River, 
#' Maine. ICES Journal of Marine Science 72:2423–2437. 
#' 
#' Nieland JL, Sheehan TF, Saunders R, Murphy JS, Trinko Lake TR, Stevens JR. 2013. 
#' Dam Impact Analysis model for Atlantic salmon in the Penobscot River, Maine. US 
#' Department of Commerce, Northeast Fisheries Science Center Reference Document 
#' 13-09, Woods Hole, MA.
#' 
"downstream_mattaceunk"

#' @title Downstream data for Medway
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. 
#' 
#' @format A dataframe with 7,589 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Amaral S, Fay C, Hecker G, Perkins N. 2012. Atlantic salmon survival 
#' estimates at mainstem hydroelectric projects on the Penobscot River. 
#' Phase 3 Final Report. Alden Research Laboratory, Inc., Holden, MA.
#' 
#' Nieland JL, Sheehan TF, Saunders R. 2015. Assessing demographic effects of dams
#' on diadromous fish: a case study for Atlantic salmon in the Penobscot River, 
#' Maine. ICES Journal of Marine Science 72:2423–2437. 
#' 
#' Nieland JL, Sheehan TF, Saunders R, Murphy JS, Trinko Lake TR, Stevens JR. 2013. 
#' Dam Impact Analysis model for Atlantic salmon in the Penobscot River, Maine. US 
#' Department of Commerce, Northeast Fisheries Science Center Reference Document 
#' 13-09, Woods Hole, MA.
#' 
"downstream_medway"

#' @title Downstream data for Milford
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. This dataset was updated in 2020 following changes to the
#' hydrosystem associated with the Penobscot River Restoration Project.
#' 
#' @format A dataframe with 9,356 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Nieland JL, Sheehan TF. 2020. Quantifying the Effects of Dams on Atlantic Salmon
#' in the Penobscot River Watershed, with a Focus on Weldon Dam. US Department of 
#' Commerce, Northeast Fisheries Science Center Reference Document 19-16, Woods 
#' Hole, MA.
#' 
"downstream_milford"

#' @title Downstream data for Moosehead
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow.
#' 
#' @format A dataframe with 753 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source Nieland et al. (2013, 2015)
#' 
"downstream_moosehead"

#' @title Downstream data for Orono
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. This dataset was updated in 2020 following changes to the
#' hydrosystem associated with the Penobscot River Restoration Project.
#' 
#' @format A dataframe with 4,457 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Nieland JL, Sheehan TF. 2020. Quantifying the Effects of Dams on Atlantic Salmon
#' in the Penobscot River Watershed, with a Focus on Weldon Dam. US Department of 
#' Commerce, Northeast Fisheries Science Center Reference Document 19-16, Woods 
#' Hole, MA.
#' 
"downstream_orono"

#' @title Downstream data for Stillwater
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow. This dataset was updated in 2020 following changes to the
#' hydrosystem associated with the Penobscot River Restoration Project.
#' 
#' @format A dataframe with 4,456 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Nieland JL, Sheehan TF. 2020. Quantifying the Effects of Dams on Atlantic Salmon
#' in the Penobscot River Watershed, with a Focus on Weldon Dam. US Department of 
#' Commerce, Northeast Fisheries Science Center Reference Document 19-16, Woods 
#' Hole, MA.
#' 
"downstream_stillwater"

#' @title Downstream data for Veazie
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow.
#' 
#' @format A dataframe with 13,939 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Amaral S, Fay C, Hecker G, Perkins N. 2012. Atlantic salmon survival 
#' estimates at mainstem hydroelectric projects on the Penobscot River. 
#' Phase 3 Final Report. Alden Research Laboratory, Inc., Holden, MA.
#' 
#' Nieland JL, Sheehan TF, Saunders R. 2015. Assessing demographic effects of dams
#' on diadromous fish: a case study for Atlantic salmon in the Penobscot River, 
#' Maine. ICES Journal of Marine Science 72:2423–2437. 
#' 
#' Nieland JL, Sheehan TF, Saunders R, Murphy JS, Trinko Lake TR, Stevens JR. 2013. 
#' Dam Impact Analysis model for Atlantic salmon in the Penobscot River, Maine. US 
#' Department of Commerce, Northeast Fisheries Science Center Reference Document 
#' 13-09, Woods Hole, MA.
#' 
"downstream_veazie"

#' @title Downstream data for West Enfield
#' 
#' @description Alden research estimates of downstream survival from the 
#' Atlantic salmon Dam Impact analysis model v67. Estimates are based on 
#' in-river flow.
#' 
#' @format A dataframe with 9,368 observations of 4 variables
#' \describe{
#'   \code{flow_cfs } Value of flow (discharge) \cr \cr
#'   \code{cumulative_prob } Cumulative flow probability \cr \cr
#'   \code{flow_prob } Probability of individual flow value \cr \cr
#'   \code{smolt_surv_prob } Smolt survival probability given flow \cr \cr
#' }
#' 
#' @source
#' Amaral S, Fay C, Hecker G, Perkins N. 2012. Atlantic salmon survival 
#' estimates at mainstem hydroelectric projects on the Penobscot River. 
#' Phase 3 Final Report. Alden Research Laboratory, Inc., Holden, MA.
#' 
#' Nieland JL, Sheehan TF, Saunders R. 2015. Assessing demographic effects of dams
#' on diadromous fish: a case study for Atlantic salmon in the Penobscot River, 
#' Maine. ICES Journal of Marine Science 72:2423–2437. 
#' 
#' Nieland JL, Sheehan TF, Saunders R, Murphy JS, Trinko Lake TR, Stevens JR. 2013. 
#' Dam Impact Analysis model for Atlantic salmon in the Penobscot River, Maine. US 
#' Department of Commerce, Northeast Fisheries Science Center Reference Document 
#' 13-09, Woods Hole, MA.
#' 
"downstream_westenfield"

#' @title Empirical cumulative distribution function for natural mortality
#' per kilometer
#' 
#' @description Empirical cumulative distribution function for natural mortality
#' per kilometer derived by Stevens et al. (2019).
#' 
#' @format A dataframe with 34 observations of 3 variables
#' \describe{
#'   \code{prop_lost_per_km } Proportion of fish lost per kilometer \cr \cr
#'   \code{cumulative frequency } Cumulative probability at observation \cr \cr
#'   \code{prob } Probability of occurrence for a given observation \cr \cr
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"mort_per_km"

#' @title Flow ratios data set
#' 
#' @description GageID and associated flow ratios by dam in the Penobscot
#' River based on Stevens et al. (2019).
#' 
#' @format A dataframe with 21 observations of 3 variables
#' \describe{
#'   \code{dam } Name of dam \cr \cr
#'   \code{GageID } USGS Gage used to determine dam-specific flow
#'   \code{flow_ratio } Ratio of flow from gage \cr \cr
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"flow_ratios"

#' @title Stillwater logistic regression parameters
#' 
#' @description Parameter estimates and statistics for logistic regression
#' characterizing probability of fish using Stillwater Branch for downstream
#' migration around Marsh Island in the Penobscot River, USA. Used to predict
#' probability of fish using Stillwater Branch conditional on flow (cfs).
#' 
#' @format A dataframe with 2 observations of 5 variables
#' \describe{
#'   \code{parameter } Model parameter \cr \cr
#'   \code{estimate } Estimated mean for parameter
#'   \code{se } Estimated standard error for parameter \cr \cr
#'   \code{z test statistic for regression}
#'   \code{p p-values for parameters}
#' }
#' 
#' @source
#' Stich, DS, M Bailey, and JD Zydlewski. 2014. Survival of 
#' Atlantic Salmon Salmo salar smolts through a hydropower 
#' complex. Journal of Fish Biology 85:1074-1096.
#' 
"stillwater_pars"

#' @title Stocking data for Penobscot River watershed
#' 
#' @description Number of Atlantic salmon smolts stocked in each of 22 sites
#' by year.
#' 
#' @format A dataframe with 440 observations of 3 variables
#' \describe{
#'   \code{Year } Year of stocking \cr \cr
#'   \code{site_code } Site code corresponding to `stocking_site` in `distance_traveled`
#'   \code{n_stocked } Number of smolts stocked
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"stocking_data"

#' @title Distance traveled within segments
#' 
#' @description Distance traveled by Atlantic salmon smolts within 
#' collection units or segments in the Penobscot River, Maine based
#' on Stevens et al. (2019).
#' 
#' @format A dataframe with 43 observations of 4 variables
#' \describe{
#'   \code{sub_basin } Sub-basin within Penobscot River catchment \cr \cr
#'   \code{stocking_location } Stocking location \cr \cr
#'   \code{site_code } Code for site/stocking location \cr \cr
#'   \code{km_traveled } Distance traveled from stocking location to ocean in km \cr \cr
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"distance_traveled"

#' @title East Branch Penobscot (EPN) sub-basin
#' 
#' @description Dataframe containing sub-basin characteristics for 
#' collection segments and dam names in the East Branch Penobscot River
#' (Stevens et al. 2019).
#' 
#' @format A dataframe with 33 observations of 6 variables
#' \describe{
#'   \code{huc_collection_segment_or_damname } Location within Penobscot River catchment corresponding to the same column in \code{\link{distance_traveled}} \cr \cr
#'   \code{habitat_unit_code } Habitat unit code(s) or HUCs \cr \cr
#'   \code{available_habitat_units_or_segment_length } Available habitat units or segment length of collection segment or dam reach \cr \cr
#'   \code{point_stock_pct_segment } Percent distance into segment length to stock \cr \cr
#'   \code{saturation } Proportion of wild smolt habitat occupied
#'   \code{n_smolts } Number of smolts (zero or NA by default)
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"EPN"

#' @title West Branch Penobscot (EPN) sub-basin
#' 
#' @description Dataframe containing sub-basin characteristics for 
#' collection segments and dam names in the West Branch Penobscot River
#' (Stevens et al. 2019).
#' 
#' @format A dataframe with 82 observations of 6 variables
#' \describe{
#'   \code{huc_collection_segment_or_damname } Location within Penobscot River catchment corresponding to the same column in \code{\link{distance_traveled}} \cr \cr
#'   \code{habitat_unit_code } Habitat unit code(s) or HUCs \cr \cr
#'   \code{available_habitat_units_or_segment_length } Available habitat units or segment length of collection segment or dam reach \cr \cr
#'   \code{point_stock_pct_segment } Percent distance into segment length to stock \cr \cr
#'   \code{saturation } Proportion of wild smolt habitat occupied
#'   \code{n_smolts } Number of smolts (zero or NA by default)
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"WPN"

#' @title Mattawamkeag River sub-basin
#' 
#' @description Dataframe containing sub-basin characteristics for 
#' collection segments and dam names in the Mattawamkeag River
#' (Stevens et al. 2019).
#' 
#' @format A dataframe with 62 observations of 6 variables
#' \describe{
#'   \code{huc_collection_segment_or_damname } Location within Penobscot River catchment corresponding to the same column in \code{\link{distance_traveled}} \cr \cr
#'   \code{habitat_unit_code } Habitat unit code(s) or HUCs \cr \cr
#'   \code{available_habitat_units_or_segment_length } Available habitat units or segment length of collection segment or dam reach \cr \cr
#'   \code{point_stock_pct_segment } Percent distance into segment length to stock \cr \cr
#'   \code{saturation } Proportion of wild smolt habitat occupied
#'   \code{n_smolts } Number of smolts (zero or NA by default)
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"Matt"

#' @title Piscataquis River sub-basin
#' 
#' @description Dataframe containing sub-basin characteristics for 
#' collection segments and dam names in the Piscataquis River
#' (Stevens et al. 2019).
#' 
#' @format A dataframe with 54 observations of 6 variables
#' \describe{
#'   \code{huc_collection_segment_or_damname } Location within Penobscot River catchment corresponding to the same column in \code{\link{distance_traveled}} \cr \cr
#'   \code{habitat_unit_code } Habitat unit code(s) or HUCs \cr \cr
#'   \code{available_habitat_units_or_segment_length } Available habitat units or segment length of collection segment or dam reach \cr \cr
#'   \code{point_stock_pct_segment } Percent distance into segment length to stock \cr \cr
#'   \code{saturation } Proportion of wild smolt habitat occupied
#'   \code{n_smolts } Number of smolts (zero or NA by default)
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"PISC"

#' @title Penobscot River sub-basin
#' 
#' @description Dataframe containing sub-basin characteristics for 
#' collection segments and dam names in the lower Penobscot River
#' (Stevens et al. 2019). Inherits argument values from functions used 
#' on all other sub-basins.
#' 
#' @format A dataframe with 125 observations of 6 variables
#' \describe{
#'   \code{huc_collection_segment_or_damname } Location within Penobscot River catchment corresponding to the same column in \code{\link{distance_traveled}} \cr \cr
#'   \code{habitat_unit_code } Habitat unit code(s) or HUCs \cr \cr
#'   \code{available_habitat_units_or_segment_length } Available habitat units or segment length of collection segment or dam reach \cr \cr
#'   \code{point_stock_pct_segment } Percent distance into segment length to stock \cr \cr
#'   \code{saturation } Proportion of wild smolt habitat occupied
#'   \code{n_smolts } Number of smolts (zero or NA by default)
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"PN"

#' @title Cumulative distribution ranks for flows by year
#' 
#' @description Cumulative distribution ranks for flows by year at
#' USGS gage stations in the Penobscot River watershed, Maine, USA.
#' 
#' @format A dataframe with 9858 observations of 6 variables
#' \describe{
#'   \code{GageID } US Geological Survey gage ID \cr \cr
#'   \code{Location } Gage location \cr \cr
#'   \code{Day } Ordinal day of year for measurement \cr \cr
#'   \code{cum_prob } Cumulative flow probability \cr \cr
#'   \code{Year } Year of measurement
#'   \code{flow } Flow measurement
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"flow_ranks"

#' @title Cumulative distribution ranks for flows by year
#' 
#' @description Cumulative distribution ranks for survival at 
#' dams in the Penobscot River watershed based on cumulative flow
#' distribution in \code{\link{flow_ranks}}.
#' 
#' @format A dataframe with 17391 observations of 5 variables
#' \describe{
#'   \code{GageID } US Geological Survey gage ID \cr \cr
#'   \code{Location } Gage location \cr \cr
#'   \code{Day } Ordinal day of year for measurement \cr \cr
#'   \code{cum_prob } Cumulative flow probability \cr \cr
#'   \code{Year } Year of measurement
#'   \code{flow } Flow measurement
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"survival_ranks"

#' @title Latent estuary survival coefficients for dams
#' 
#' @description Latent estuary survival coeffficients for number of 
#' dams passed by fish based on Stich et al. (2015) as implemented
#' by Stevens et al. (2019).
#' 
#' @format A dataframe with 8 observations of 4 variables
#' \describe{
#'   \code{n_dams } Number of dams passed \cr \cr
#'   \code{n_dams_std } Standardized value for number of dams \cr \cr
#'   \code{s_logit } Logit-scale estuary survival based on number of dams passed \cr \cr
#'   \code{s_real } Real-scale estuary survival based on number of dams passed \cr \cr
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
#' Stich, DS, JF Kocik, GB Zydlewski, and JD Zydlewski. 2015. Linking behavior,
#' physiology, and survival of Atlantic Salmon smolts during estuary 
#' migration. Marine and Coastal Fisheries: Dynamics, Management, 
#' and Ecosystem Science 7:68-86.
#' 
"latent_estuary"
#'
#' @title Stillwater split flows
#' 
#' @description Proportion of flow entering the Stillwater Branch
#' under varying in-river flow measured at West Enfield Dam 
#' (Stevens et al. 2019).
#' 
#' @format A dataframe with 30 observations of 3 variables
#' \describe{
#'   \code{total_flow } Flow (cfs) measured at West Enfield Dam \cr \cr
#'   \code{stillwater_flow } Flow (cfs) entering Stillwater Branch \cr \cr
#'   \code{s_logit } Proportion of flow entering Stillwater Branch \cr \cr
#' }
#' 
#' @source
#' Stevens, JR, JF Kocik, and TF Sheehan. 2019. Modeling the impacts of dams and 
#' stocking practices on an endangered Atlantic salmon (Salmo salar) 
#' population in the Penobscot River, Maine, USA. Canadian Journal of Fisheries
#' and Aquatic Sciences 76:1795-1807.
#' 
"stillwater_splits"