| Type: | Package |
| Title: | Predict Fish Hatch and Emergence Timing |
| Version: | 0.3.2 |
| Maintainer: | Bryan M. Maitland <bryan.maitland@usda.gov> |
| Description: | Predict hatch and emergence timing for a wide range of wild fishes using the effective value framework (Sparks et al., (2019) <doi:10.1139/cjfas-2017-0468>). 'hatchR' offers users access to established phenological models and the flexibility to incorporate custom parameterizations using external datasets. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.3.2 |
| URL: | https://bmait101.github.io/hatchR/, https://github.com/bmait101/hatchR |
| BugReports: | https://github.com/bmait101/hatchR/issues |
| Depends: | R (≥ 4.1.0) |
| Imports: | dplyr (≥ 1.1.4), ggplot2 (≥ 3.5.1), ggtext (≥ 0.1.2), lifecycle (≥ 1.0.4), lubridate (≥ 1.9.4), rlang (≥ 1.1.4), stats, tibble (≥ 3.2.1), utils |
| Suggests: | knitr (≥ 1.49), readr (≥ 2.1.5), purrr (≥ 1.0.2), rmarkdown (≥ 2.29), nycflights13 (≥ 1.0.2), tidyr (≥ 1.3.1), stringr (≥ 1.5.1), ggridges (≥ 0.5.6), patchwork (≥ 1.3.0), testthat (≥ 3.0.0), cli (≥ 3.6.1) |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2025-03-03 23:57:51 UTC; BryanMaitland |
| Author: | Bryan M. Maitland 
[aut, cre],
Morgan M. Sparks
[aut, cph],
Eli Felts [ctb] |
| Repository: | CRAN |
| Date/Publication: | 2025-03-05 15:40:02 UTC |
hatchR: Predict Fish Hatch and Emergence Timing
Description
Predict hatch and emergence timing for a wide range of wild fishes using the effective value framework (Sparks et al., (2019) doi:10.1139/cjfas-2017-0468). 'hatchR' offers users access to established phenological models and the flexibility to incorporate custom parameterizations using external datasets.
Author(s)
Maintainer: Bryan M. Maitland bryan.maitland@usda.gov (ORCID)
Authors:
Morgan M. Sparks morgan.sparks@usda.gov (ORCID) [copyright holder]
Other contributors:
Eli Felts eli_felts@fws.gov (ORCID) [contributor]
See Also
Useful links:
Report bugs at https://github.com/bmait101/hatchR/issues
Check if the dates in a data frame are continuous.
Description
Check if the dates in a data frame are continuous.
Usage
check_continuous(data, dates)
Arguments
data |
A data.frame, or data frame extension (e.g. a tibble). |
dates |
Column representing the date of the temperature measurements. |
Value
A message indicating if the dates are continuous or if there are breaks. If there are breaks, a vector of row numbers where the breaks occur is returned.
Examples
library(hatchR)
check_continuous(crooked_river, date)
Example dataset: Crooked River, Idaho
Description
Daily stream temperature data from Crooked River, a tributary to the North Fork Boise River, Idaho.
Usage
crooked_river
Format
Data frame with columns
- date
Date and time measurement was taken.
- temperture
Temperature in degrees Celsius.
Source
Dan Isaak, US Forest Service Rocky Mountain Research Station.
Examples
crooked_river
Fit B&M model 2 to new data using stats::nls()
Description
Generate your own custom parameterized models for predicting hatching and emergence phenology.
Usage
fit_model(temp, days, species = NULL, development_type = NULL)
Arguments
temp |
Numeric vector of temperatures |
days |
Numeric vector of days to hatch or emerge |
species |
Character string of species name (e.g., "sockeye") |
development_type |
Character string of development type: "hatch" or "emerge" |
Details
hatchR also includes functionality to generate your own custom parameterized models for predicting hatching and emergence phenology. Importantly, the custom parameterization relies on the model format developed from model 2 of Beacham and Murray (1990), which we chose because of its overall simplicity and negligible loss of accuracy. See Beacham and Murray (1990) and Sparks et al. (2019) for more specific discussion regarding model 2 and the development of the effective value approach.
Value
List with fit model object, model coefficients, model specifications data.frame, and plot of observations and model fit.
Examples
library(hatchR)
# vector of temperatures
temperature <- c(2, 5, 8, 11, 14)
# vector of days to hatch
days_to_hatch <- c(194, 87, 54, 35, 28)
bt_hatch_mod <- fit_model(
temp = temperature,
days = days_to_hatch, species = "sockeye", development_type = "hatch"
)
Central Idaho Water Temperature Data
Description
Water temperature data from Isaak et al. (2018). Generally covers the Boise, Payette, Clearwater, and upper Salmon River watersheds.
Usage
idaho
Format
Data frame
- date
Date measurement was taken.
- site
Site ID.
- temp_c
Temperature in degrees Celsius.
Source
https://hess.copernicus.org/articles/22/6225/2018/
References
Isaak, D.J., Luce, C.H., Chandler, G.L., Horan, D.L., Wollrab, S.P. (1990). Principal components of thermal regimes in mountain river networks. Hydrology and Earth System Sciences, 22(12), 6225–6240.
Examples
idaho
Select a development model structure
Description
The function calls a model table with the parameterizations for
different species from different studies built in. Refer to the
table (model_table) before using function to find inputs for
the different function arguments. It pulls the model format as a
string and parses it to be usable in hatchR model.
Usage
model_select(author, species, model_id, development_type = "hatch")
Arguments
author |
Character string of author name. |
species |
Character string of species name. |
model_id |
Either model number from Beacham and Murray (1990) or specific to other paper (e.g., Sparks et al. 2017 = AK). |
development_type |
The phenology type. A vector with possible values "hatch" or "emerge". The default is "hatch". |
Value
A data.frame giving model specifications to be passed to
predict_phenology().
Examples
library(hatchR)
# access the parameterization for sockeye hatching using
# model #2 from Beacham and Murray (1990)
sockeye_hatch_mod <- model_select(
author = "Beacham and Murray 1990",
species = "sockeye",
model_id = 2,
development_type = "hatch"
)
# print
sockeye_hatch_mod
Table of phenology models
Description
Table providing the model parameterizations for the phenology models.
Usage
model_table
Format
Data frame with 5 columns:
- author
Author-year short citation
- species
Species name
- model_id
Identification number for a model parameterization
- development_type
Hatch or emergence
- expression
character string of parameterized function expression
Source
Beacham & Murray (1990), Sparks et al. (2017), Austin et al. (2019).
References
Beacham, T.D., Murray, C.B. (1990). Temperature, egg size, and development of embryos and alevins of five species of Pacific salmon: a comparative analysis. Canadian Journal of Zoology, 68, 1931–1940.
Sparks, M.M., Westley, P.A.H., Falke, J.A., Quinn, T.A. (2017). Thermal adaptation and phenotypic plasticity in a warming world: Insights from common garden experiments on Alaskan sockeye salmon. Canadian Journal of Fisheries and Aquatic Sciences, 76(1), 123–135.
Austin, C.C., Essington, T.E., Quinn, T.A. (2019). Spawning and emergence phenology of bull trout Salvelinus confluentus under differing thermal regimes. Canadian Journal of Fisheries and Aquatic Sciences, 94(1), 191–195.
Examples
model_table
Visual check of imported temperature data
Description
The plot_check_temp function is used to plot imported data to check
temperature values. The function takes a data frame with dates and
temperature values, and plots the temperature values over time. The
function also allows users to specify the visual thresholds for minimum and maximum temperature
values to be plotted.
Usage
plot_check_temp(data, dates, temperature, temp_min = 0, temp_max = 25)
Arguments
data |
A data.frame, or data frame extension (e.g. a tibble). |
dates |
Vector of dates for temperature measurements. Must be date or date-time class. |
temperature |
Vector of temperature values. |
temp_min |
Threshold for lower range of expected temperature. Default is 0. |
temp_max |
Threshold for upper range of expected temperature. Default is 25. |
Value
A object of class "gg" and "ggplot" that can be printed to the console or saved as an image.
Examples
library(hatchR)
plot_check_temp(
data = crooked_river,
dates = date,
temperature = temp_c
)
Visualize fish phenology
Description
The function takes the output from predict_phenology() and creates a
basic ggplot2 plot object to visualize the predicted phenology.
Usage
plot_phenology(plot, style = "all", labels = TRUE)
Arguments
plot |
A list containing the output from |
style |
The style of the plot. A vector with possible values "all", "ef_cumsum", "ef_daily". The default is "all". |
labels |
Logical. If TRUE (default), labels are added to the plot. |
Value
A object of class "gg" and "ggplot".
Examples
library(hatchR)
# get model parameterization
sockeye_hatch_mod <- model_select(
author = "Beacham and Murray 1990",
species = "sockeye",
model = 2,
development_type = "hatch"
)
# predict phenology
sockeye_hatch <- predict_phenology(
data = woody_island,
dates = date,
temperature = temp_c,
spawn.date = "1990-08-18",
model = sockeye_hatch_mod
)
plot_phenology(sockeye_hatch)
plot_phenology(sockeye_hatch, style = "ef_cumsum")
plot_phenology(sockeye_hatch, style = "ef_daily")
plot_phenology(sockeye_hatch, labels = FALSE)
Predict phenology of fish
Description
Predict the phenology of fish using the effective value framework.
Usage
predict_phenology(data, dates, temperature, spawn.date, model)
Arguments
data |
Data frame with dates and temperature. |
dates |
Date of temperature measurements. |
temperature |
Temperature measurements. |
spawn.date |
Date of spawning, given as a character string (e.g., "1990-08-18"). Must be year-month-day in format shown. |
model |
A data.frame with a column named "expression" or a character vector
giving model specifications. Can be obtained using |
Value
A list with the following elements:
-
days_to_develop: A numeric vector of length 1; number of predicted days to hatch or emerge. -
ef_table: An n x 4 tibble (n = number of days to hatch or emerge) with the dates, temperature, effective values, and cumulative sum of the effective values. -
dev.period: a 1x2 dataframe with the dates corresponding to when your fish's parent spawned (input withpredict_phenology(spawn.date = ...)) and the date when the fish is predicted to hatch or emerge. -
model_specs: A data.frame with the model specifications.
References
Sparks, M.M., Falke, J.A., Quinn, T.A., Adkinson, M.D., Schindler, D.E. (2019). Influences of spawning timing, water temperature, and climatic warming on early life history phenology in western Alaska sockeye salmon. Canadian Journal of Fisheries and Aquatic Sciences, 76(1), 123–135.
Examples
library(hatchR)
# get model parameterization
sockeye_hatch_mod <- model_select(
author = "Beacham and Murray 1990",
species = "sockeye",
model_id = 2,
development_type = "hatch"
)
# predict phenology
sockeye_hatch <- predict_phenology(
data = woody_island,
dates = date,
temperature = temp_c,
spawn.date = "1990-08-18",
model = sockeye_hatch_mod
)
Summarize temperature data to daily values
Description
The summarize_temp function is used to summarize sub-daily temperature
measurements to obtain mean daily temperature.
Usage
summarize_temp(data, dates, temperature)
Arguments
data |
A data.frame, or data frame extension (e.g. a tibble). |
dates |
Column representing the date of temperature measurements. |
temperature |
Column representing temperature values. |
Value
A data.frame with summarized daily temperature values.
Examples
library(hatchR)
summarize_temp(
data = idaho,
dates = date,
temperature = temp_c
)
Example dataset: Woody Island, Lake Iliamna, Alaska
Description
Temperature Data from Woody Island in Lake Iliamna, Alaska
Usage
woody_island
Format
Data frame with columns:
- date
Date measurement was taken.
- temp_c
Temperature in degrees Celsius.
Source
Sparks et al. (2019)
References
Sparks, M.M., Falke, J.A., Quinn, T.A., Adkinson, M.D., Schindler, D.E., Bartz, K., Young, D., Westley, P.A.H. (2019). Influences of spawning timing, water temperature, and climatic warming on early life history phenology in western Alaska sockeye salmon. Canadian Journal of Fisheries and Aquatic Sciences, 76(1), 123–135.
Examples
woody_island