Package 'mappestRisk'

Brachycaudus schwartzi whole life cycle development rate across temperatures

Description

A modified data set from Table 1 in Satar and Yokomi (2002) on days of development for Brachycaudus schwartzi across different constant temperatures and life stages

Usage

data(aphid)

Format

aphid

A data frame with 7 rows and 5 columns. The workflow is reproducible and available in ⁠/data-raw⁠ folder of the mappestRisk GitHub repository, which includes both the original summarized data set -satar_data.xlsx- and the R script with the dev. days to dev. rate conversion in prepare_aphid.R.

reference

"Satar2002" refers to the source paper as cited below in section Source.

temperature

Temperature treatments (ºC).

dev_days

Development days (i.e., days to fulfill development requirements from a life-stage to the following)

rate_value

Rate of Development (1/days), the reciprocal of Development days, see dev_days

stage

Life stage or instar evaluated. In this case, only data of the whole immature stages (i.e., nymphs) were used

Source

Satar, S. and Yokomi, R. (2002). Effect of temperature and host on development of Brachycaudus schwartzi (Homoptera: Aphididae). Ann. Entomol. Soc. Am. 95: 597-602. doi:10.1603/0013-8746(2002)095[0597:EOTAHO]2.0.CO;2.

Licence: CC BY-NC 3.0 (modified material).

---

Available Models Table

Description

Table containing the available models to be fit using fit_devmodels(). These models come from two other packages: devRate and rTPC .

Usage

data("available_models")

Format

available_models

A data.frame/tibble with 13 rows and 6 columns:

model_name

Model name to be used within fit_devmodels().

package

names of the packages used by fit_devmodels() to obtain appropriate start values for the user-provided data. When the package is rTPC package, start values are automatically computed with rTPC::get_start_vals(), which in turn relies on nls.multstart::nls_multstart(). When the package is devRate package, iterative starting values are computed using nls.multstart::nls_multstart(), using the parameters published in devRate::devRateEqStartVal() as first attempts to iterate. As an exception, if model_name == "briere1", generic starting values are provided and advised to the user due to the unrealistic value of some parameters in the devRate data set.

source_model_name

name of the function in the source packages rTPC and devRate.

formula, working_formula, n_params

formulas used for model fitting.

Source

Rebaudo, F., Struelens, Q., and Dangles, O. (2018). Modelling temperature-dependent development rate and phenology in arthropods: The devRate package for R. Methods Ecol Evol. 9: 1144-1150. doi:10.1111/2041-210X.12935.

Padfield, D., O´Sullivan, H., and Pawar, S., (2021). rTPC and nls.multstart: a new pipeline to fit thermal performance curves in R. Methods Ecol Evol. 12: 1138-1143. doi:10.1111/2041-210X.13585.

---

Country names

Description

Country names

Usage

country_names

Format

country_names

A character vector of country names (length = 231 countries)

Source

https://gadm.org

---

Fit Thermal Performance Curves

Description

Fit nonlinear regression models to data representing how development rate changes with temperature (known as Thermal Performance Curves), based on nls.multstart::nls_multstart() approach to development rate data across temperatures. The fitting procedure is built upon previous packages for starting values estimation, namely rTPC and devRate.

Usage

fit_devmodels(temp = NULL, dev_rate = NULL, model_name = NULL)

Arguments

temp	a vector of temperatures used in the experiment. It should have at least four different temperatures and must contain only numbers without any missing values.
dev_rate	a vector of estimated development rates corresponding to each temperature. These rates are calculated as the inverse of the number of days to complete the transition from the beginning of a certain life stage to the beginning of the following at each temperature. It must be numeric and of the same length as temp.
model_name	a string or a vector that specifies the model(s) to use for fitting the Thermal Performance Curves. Options include "all" or specific models listed in available_models. These models typically exhibit a common unimodal, left-skewed shape.

Value

A table in tibble format with estimates and standard errors for each parameter of the models specified by the user that have adequately converged. Models are sorted based on their Akaike Information Criterion (AIC) values, with the best fitting models shown first. Fitted models are also provided in list format in the model_list column and can be accessed using get_fitted_model() for for further inspection. It is important to consider ecological criteria alongside statistical information. For additional help in model selection, we recommend using plot_devmodels() and consulting relevant literature.

Source

The dataset used in the example was originally published in Satar & Yokomi (2022) under the CC-BY-NC license. The start values and equations for the 'briere1', 'lactin1', 'mod_polynomial' and 'wang' models have been obtained from the devRate package.

References

Angilletta, M.J., (2006). Estimating and comparing thermal performance curves. J. Therm. Biol. 31: 541-545. (for model selection in TPC framework)

Padfield, D., O'Sullivan, H. and Pawar, S. (2021). rTPC and nls.multstart: A new pipeline to fit thermal performance curves in R. Methods Ecol Evol. 12: 1138-1143.

Rebaudo, F., Struelens, Q. and Dangles, O. (2018). Modelling temperature-dependent development rate and phenology in arthropods: The devRate package for R. Methods Ecol Evol. 9: 1144-1150.

Satar, S. and Yokomi, R. (2002). Effect of temperature and host on development of Brachycaudus schwartzi (Homoptera: Aphididae). Ann. Entomol. Soc. Am. 95: 597-602.

See Also

nls.multstart::nls_multstart() for structure of model fitting approach

browseVignettes("rTPC") for model names, start values searching workflows and bootstrapping procedures using both rTPC and nls.multstart packages.

Examples

data("aphid")

fitted_tpcs <- fit_devmodels(temp = aphid$temperature,
                             dev_rate = aphid$rate_value,
                             model_name = c("lactin2", "briere2",
                                            "mod_weibull")
                             )
head(fitted_tpcs)

---

Get fitted model object

Description

Get fitted model object

Usage

get_fitted_model(fitted_df = NULL, model_name = NULL)

Arguments

fitted_df	A table with fitted models, as produced by fit_devmodels().
model_name	Character. Name of a fitted model, see available_models.

Value

A model object

Examples

data("aphid")

fitted_tpcs_aphid <- fit_devmodels(temp = aphid$temperature,
                                   dev_rate = aphid$rate_value,
                                   model_name = c("lactin2", "briere2", "ratkowsky")
                                   )
get_fitted_model(fitted_tpcs_aphid, "briere2")

---

Map pest risk

Description

This function produces a raster map where each pixel shows the number of months per year in which temperature is within a given set of bounds. If the input has several pairs of minimum and maximum temperatures (as produced by therm_suit_bounds()), the output raster has two layers: mean and standard deviation.

Usage

map_risk(
  t_vals = NULL,
  t_rast = NULL,
  region = NULL,
  res = 2.5,
  path = NULL,
  mask = TRUE,
  verbose = FALSE,
  plot = TRUE,
  interactive = FALSE
)

Arguments

t_vals	a data.frame or dplyr::tibble() as produced by therm_suit_bounds(). t_vals must contain results derived from a single model. It must contain at least one row of numeric values. Additionally, the minimum ("left") thermal boundary or tval_left must be lower than the maximum ("right") one, or tval_right for all rows. Nominative columns must be present in the input (i.e., model_name, suitability, pred_suit and iter).
t_rast	Optional 12-layer terra::SpatRaster() with monthly mean temperatures for the region of interest. If not provided, global WorldClim raster layers will be automatically (down)loaded using geodata::worldclim_global(), and cropped to region (if provided). Note that the download can be slow the first time you use the function in a new path. If you get a download error, consider running e.g options(timeout = 500) (or more).
region	Optional object specifying the region to map. Must overlap the extent of t_rast if both are provided. Can be a terra::SpatVector() polygon (obtained with terra::vect()); or an sf polygon, in which case it will be coerced with terra::vect()) to a terra::SpatVector(); or a character vector of country name(s) in English (see country_names), in which case climate maps will be downloaded for those countries; or a terra::SpatExtent() object (obtained with terra::ext()); or a numeric vector of length 4 specifying the region coordinates as follows: c(xmin, xmax, ymin, ymax). The latter two must be in the same CRS ast_rast if t_rast is provided, or in unprojected lon-lat coordinates (WGS84, EPSG:4326) otherwise. If NULL, the output maps will cover the entire t_rast if provided, or the entire world otherwise.
res	Argument to pass to geodata::worldclim_global() specifying the spatial resolution for the raster maps to download, if t_rast is not provided. The default is 2.5 arc-minutes. Beware that lower values (e.g., 0.5) may lead to extremely heavy data sets and large computation times.
path	Argument to pass to geodata::worldclim_global() (if t_rast is not provided) and/or to geodata::world() (if region is a vector of country names) specifying the folder path for the downloaded maps.
mask	Logical value to pass to terra::mask() specifying whether the output raster maps should be masked with the borders of the target 'region', if this is a polygon map or a vector of country names. The default is TRUE. If FALSE, the entire rectangular extent of 'region' will be used.
verbose	Logical value specifying whether to display messages about what the function is doing at possibly slow steps. The default is FALSE. Setting it to TRUE can be useful for checking progress when maps are large.
plot	Logical value specifying whether to plot the results in a map. Defaults to TRUE. Note that the function will always return a terra::SpatRaster() object even if plot = TRUE.
interactive	Logical value specifying whether the plotted map should be interactive (if plot=TRUE). The default is TRUE if the 'leaflet' package is installed.

Value

This function returns a terra::SpatRaster() with up to 2 layers: the (mean()) number of months with temperature within the species' thermal bounds; and (if t_vals has >1 rows) the standard deviation (stats::sd()) around that mean.

Examples

data("aphid")

fitted_tpcs <- fit_devmodels(temp = aphid$temperature,
                             dev_rate = aphid$rate_value,
                             model_name = "all")

plot_devmodels(temp = aphid$temperature,
               dev_rate = aphid$rate_value,
               fitted_parameters = fitted_tpcs,
               species = "Brachycaudus schwartzi",
               life_stage = "Nymphs")

boot_tpcs <- predict_curves(temp = aphid$temperature,
                            dev_rate = aphid$rate_value,
                            fitted_parameters = fitted_tpcs,
                            model_name_2boot = c("lactin2", "briere2", "beta"),
                            propagate_uncertainty = TRUE,
                            n_boots_samples = 10)

print(boot_tpcs)

plot_uncertainties(temp = aphid$temperature,
                   dev_rate = aphid$rate_value,
                   bootstrap_tpcs = boot_tpcs,
                   species = "Brachycaudus schwartzi",
                   life_stage = "Nymphs")


boundaries <- therm_suit_bounds(preds_tbl = boot_tpcs,
                                model_name = "lactin2",
                                suitability_threshold = 80)

risk_map_reunion <- map_risk(t_vals = boundaries,
                             path = tempdir(),
                             region = "Réunion",
                             mask = TRUE,
                             plot = TRUE,
                             interactive = FALSE,
                             verbose = TRUE)

---

Plot fitted thermal performance curves

Description

Plot the predicted development rates across temperatures based on fitted Thermal Performance Curves (TPCs) for one or several models displayed in facets.

Usage

plot_devmodels(
  temp = NULL,
  dev_rate = NULL,
  fitted_parameters = NULL,
  species = NULL,
  life_stage = NULL
)

Arguments

temp	a vector of temperatures used in the experiment. It should have at least four different temperatures and must contain only numbers without any missing values.
dev_rate	a vector of estimated development rates corresponding to each temperature. These rates are calculated as the inverse of the number of days to complete the transition from the beginning of a certain life stage to the beginning of the following at each temperature. It must be numeric and of the same length as temp.
fitted_parameters	a tibble obtained with fit_devmodels(), including parameter names, estimates, standard errors, AICs, and nls objects (fitted_models) using the nls.multstart::nls_multstart() approach.
species	optional a string of the target species that will constitute the plot title. Must be of type "character".
life_stage	optional a string of the target life stage that will constitute the plot subtitle. Must be of type "character".

Value

A plot with predicted values (development rate) across temperatures for models that have adequately converged using fit_devmodels() function. It's a ggplot object, which can be assigned to a user-defined object.

References

Angilletta, M.J., (2006). Estimating and comparing thermal performance curves. J. Therm. Biol. 31: 541-545. (for model selection in TPC framework)

Padfield, D., O'Sullivan, H. and Pawar, S. (2021). rTPC and nls.multstart: A new pipeline to fit thermal performance curves in R. Methods Ecol Evol. 12: 1138-1143.

Rebaudo, F., Struelens, Q. and Dangles, O. (2018). Modelling temperature-dependent development rate and phenology in arthropods: The devRate package for R. Methods Ecol Evol. 9: 1144-1150.

Satar, S. and Yokomi, R. (2002). Effect of temperature and host on development of Brachycaudus schwartzi (Homoptera: Aphididae). Ann. Entomol. Soc. Am. 95: 597-602.

See Also

fit_devmodels() for fitting Thermal Performance Curves to development rate data, which is in turn based on nls.multstart::nls_multstart().

Examples

data("aphid")

fitted_tpcs <- fit_devmodels(temp = aphid$temperature,
                             dev_rate = aphid$rate_value,
                             model_name = c("lactin2", "briere2", "mod_weibull"))

plot_devmodels(temp = aphid$temperature,
               dev_rate = aphid$rate_value,
               fitted_parameters = fitted_tpcs,
               species = "Brachycaudus schwartzi",
               life_stage = "Nymphs")

---

Draw bootstrapped Thermal Performance Curves (TPCs) to visualize uncertainty in parameter estimation of TPC fitting

Description

Draw bootstrapped Thermal Performance Curves (TPCs) to visualize uncertainty in parameter estimation of TPC fitting

Usage

plot_uncertainties(
  temp = NULL,
  dev_rate = NULL,
  bootstrap_tpcs = NULL,
  species = NULL,
  life_stage = NULL,
  alpha = 0.2
)

Arguments

temp	a vector of temperatures used in the experiment. It should have at least four different temperatures and must contain only numbers without any missing values.
dev_rate	a vector of estimated development rates corresponding to each temperature. These rates are calculated as the inverse of the number of days to complete the transition from the beginning of a certain life stage to the beginning of the following at each temperature. It must be numeric and of the same length as temp.
bootstrap_tpcs	a tibble A tibble object as produced by predict_curves(), containing bootstrapped TPCs to propagate uncertainty.
species	optional a string of the target species that will constitute the plot title. Must be of type "character".
life_stage	optional a string of the target life stage that will constitute the plot subtitle. Must be of type "character".
alpha	a number between 0 and 1 to choose transparency of the bootstrapped curves (0 = complete transparency, 1 = solid line).

Value

A ggplot object containing the visual representation of the estimate TPC and the bootstrapped uncertainty curves as a ribbon. Each model is represented in a facet, and data points are also explicit.

References

Angilletta, M.J., (2006). Estimating and comparing thermal performance curves. J. Therm. Biol. 31: 541-545. (for model selection in TPC framework)

Padfield, D., O'Sullivan, H. and Pawar, S. (2021). rTPC and nls.multstart: A new pipeline to fit thermal performance curves in R. Methods Ecol Evol. 12: 1138-1143.

Rebaudo, F., Struelens, Q. and Dangles, O. (2018). Modelling temperature-dependent development rate and phenology in arthropods: The devRate package for R. Methods Ecol Evol. 9: 1144-1150.

Satar, S. and Yokomi, R. (2002). Effect of temperature and host on development of Brachycaudus schwartzi (Homoptera: Aphididae). Ann. Entomol. Soc. Am. 95: 597-602.

See Also

browseVignettes("rTPC") for model names, start values searching workflows, and bootstrapping procedures using both rTPC::get_start_vals() and nls.multstart::nls_multstart()

fit_devmodels() for fitting Thermal Performance Curves to development rate data, which is in turn based on nls.multstart::nls_multstart(). predict_curves() for bootstrapping procedure based on the above-mentioned rTPC vignettes.

Examples

data("aphid")

fitted_tpcs <- fit_devmodels(temp = aphid$temperature,
                             dev_rate = aphid$rate_value,
                             model_name = "all")

plot_devmodels(temp = aphid$temperature,
               dev_rate = aphid$rate_value,
               fitted_parameters = fitted_tpcs,
               species = "Brachycaudus swartzi",
               life_stage = "Nymphs")

boot_tpcs <- predict_curves(temp = aphid$temperature,
                            dev_rate = aphid$rate_value,
                            fitted_parameters = fitted_tpcs,
                            model_name_2boot = c("lactin2", "briere2", "beta"),
                            propagate_uncertainty = TRUE,
                            n_boots_samples = 10)

print(boot_tpcs)


plot_uncertainties(temp = aphid$temperature,
                   dev_rate = aphid$rate_value,
                   bootstrap_tpcs = boot_tpcs,
                   species = "Brachycaudus schwartzi",
                   life_stage = "Nymphs")

---

Propagate parameter uncertainty of TPC fits using bootstrap with residual resampling

Description

Propagate parameter uncertainty of TPC fits using bootstrap with residual resampling

Usage

predict_curves(
  temp = NULL,
  dev_rate = NULL,
  fitted_parameters = NULL,
  model_name_2boot = NULL,
  propagate_uncertainty = TRUE,
  n_boots_samples = 100
)

Arguments

temp	a vector of temperatures used in the experiment. It should have at least four different temperatures and must contain only numbers without any missing values.
dev_rate	a vector of estimated development rates corresponding to each temperature. These rates are calculated as the inverse of the number of days to complete the transition from the beginning of a certain life stage to the beginning of the following at each temperature. It must be numeric and of the same length as temp.
fitted_parameters	a tibble obtained with fit_devmodels() function, including parameter names, estimates, standard errors, AICs, and nls objects (fitted_models) using the nls.multstart::nls_multstart() approach.
model_name_2boot	A vector of strings including one or several TPC models fitted by fit_devmodels(). Contrarily to that function, model_name_2boot = "all" is not allowed in this function due to the slow bootstrapping procedure. We recommend applying this function only to a small pre-selection of models (e.g., one to four) based on statistical and ecological criteria with the help of plot_devmodels() function.
propagate_uncertainty	A logical argument that specifies whether to propagate parameter uncertainty by bootstrap with residual resampling. If FALSE, the function returns predictions from the fitted TPCs for the selected model(s). If TRUE, bootstrap is applied using residual resampling to obtain multiple TPCs as detailed in vignettes of the rTPC package. Defaults to TRUE.
n_boots_samples	Number of bootstrap resampling iterations (default is 100). A larger number of iterations makes the resampling procedure more robust, but typically 100 is sufficient for propagating parameter uncertainty, as increasing n_boots_samples will increase computation time for predicting resampled TPCs.

Value

A tibble object with as many curves (TPCs) as the number of iterations provided in the n_boots_samples argument if propagate_uncertainty = TRUE minus the bootstrap samples that could not be fitted (i.e., new nonlinear regression models did not converge for them). Otherwise, it returns just one prediction TPC from model fit estimates. Each resampled TPC consists of a collection of predictions for a set of temperatures from temp - 20 to temp + 15 with a resolution of 0.1°C and a unique identifier called boots_iter. In addition to the uncertainty TPCs, the estimated TPC is also explicit in the output tibble.

References

Angilletta, M.J., (2006). Estimating and comparing thermal performance curves. J. Therm. Biol. 31: 541-545. (for model selection in TPC framework)

Padfield, D., O'Sullivan, H. and Pawar, S. (2021). rTPC and nls.multstart: A new pipeline to fit thermal performance curves in R. Methods Ecol Evol. 12: 1138-1143.

Rebaudo, F., Struelens, Q. and Dangles, O. (2018). Modelling temperature-dependent development rate and phenology in arthropods: The devRate package for R. Methods Ecol Evol. 9: 1144-1150.

Satar, S. and Yokomi, R. (2002). Effect of temperature and host on development of Brachycaudus schwartzi (Homoptera: Aphididae). Ann. Entomol. Soc. Am. 95: 597-602.

See Also

browseVignettes("rTPC") for model names, start values searching workflows, and bootstrapping procedures using both rTPC::get_start_vals() and nls.multstart::nls_multstart()

fit_devmodels() for fitting Thermal Performance Curves to development rate data, which is in turn based on nls.multstart::nls_multstart().

Examples

data("aphid")

fitted_tpcs <- fit_devmodels(temp = aphid$temperature,
                             dev_rate = aphid$rate_value,
                             model_name = "all")

plot_devmodels(temp = aphid$temperature,
               dev_rate = aphid$rate_value,
               fitted_parameters = fitted_tpcs,
               species = "Brachycaudus schwartzi",
               life_stage = "Nymphs")

boot_tpcs <- predict_curves(temp = aphid$temperature,
                            dev_rate = aphid$rate_value,
                            fitted_parameters = fitted_tpcs,
                            model_name_2boot = c("lactin2", "briere2", "beta"),
                            propagate_uncertainty = TRUE,
                            n_boots_samples = 10)

head(boot_tpcs)

---

Determine Thermal Boundaries for Optimal Performance Level

Description

Calculate thermal boundaries that define the suitable region of a Thermal Performance Curve (TPC) corresponding to a user-defined optimal performance level.

Usage

therm_suit_bounds(
  preds_tbl = NULL,
  model_name = NULL,
  suitability_threshold = NULL
)

Arguments

preds_tbl	a tibble object as produced by predict_curves().
model_name	character. Name of one or several of the TPC models fitted first in fit_devmodels() and predicted next in predict_curves(). If using model_name = "all" all models contained in preds_tbl will be used. Please, note that some models (most typically, briere, mod_poly, wang and ratkowsky) may calculate unrealistic thermal boundaries. We recommend to double-check it and compare among several models.
suitability_threshold	A numeric value from 50 to 100 representing the quantile of the curve that provides the user-defined optimal performance. For instance, setting suitability_threshold to 80 identifies the top 20% (or quantile 80) of the maximum values of the development rate predicted by the chosen TPC model. If suitability_threshold equals 100, the function returns the optimum temperature for development rate.

Value

A tibble with six columns:

• model_name: A string indicating the selected TPC model used for projections.

• suitability: A string indicating the suitability threshold in percentage (see suitability_threshold).

• tval_left: A number representing the lower thermal boundary delimiting the suitable region of the TPC.

• tval_right: A number representing the upper thermal boundary delimiting the suitable region of the TPC.

• pred_suit: A number corresponding to the predicted development rate value determining the chosen quantile threshold of the maximum rate (i.e., suitability percentage of maximum rate).

• iter: A string determining the TPC identity from the bootstrapping procedure in predict_curves() function, or estimate when it represents the estimated TPC fitted in fit_devmodels().

References

Angilletta, M.J., (2006). Estimating and comparing thermal performance curves. J. Therm. Biol. 31: 541-545. (for model selection in TPC framework)

Padfield, D., O'Sullivan, H. and Pawar, S. (2021). rTPC and nls.multstart: A new pipeline to fit thermal performance curves in R. Methods Ecol Evol. 12: 1138-1143.

Rebaudo, F., Struelens, Q. and Dangles, O. (2018). Modelling temperature-dependent development rate and phenology in arthropods: The devRate package for R. Methods Ecol Evol. 9: 1144-1150.

Satar, S. and Yokomi, R. (2002). Effect of temperature and host on development of Brachycaudus schwartzi (Homoptera: Aphididae). Ann. Entomol. Soc. Am. 95: 597-602.

See Also

browseVignettes("rTPC") for model names, start values searching workflows, and bootstrapping procedures using both rTPC::get_start_vals() and nls.multstart::nls_multstart()

fit_devmodels() for fitting Thermal Performance Curves to development rate data, which is in turn based on nls.multstart::nls_multstart(). predict_curves() for bootstrapping procedure based on the above-mentioned rTPC vignettes.

Examples

data("aphid")

fitted_tpcs <- fit_devmodels(temp = aphid$temperature,
                             dev_rate = aphid$rate_value,
                             model_name = "all")

plot_devmodels(temp = aphid$temperature,
               dev_rate = aphid$rate_value,
               fitted_parameters = fitted_tpcs,
               species = "Brachycaudus schwartzi",
               life_stage = "Nymphs")

boot_tpcs <- predict_curves(temp = aphid$temperature,
                            dev_rate = aphid$rate_value,
                            fitted_parameters = fitted_tpcs,
                            model_name_2boot = c("lactin2", "briere2", "beta"),
                            propagate_uncertainty = TRUE,
                            n_boots_samples = 10)

print(boot_tpcs)


plot_uncertainties(temp = aphid$temperature,
                   dev_rate = aphid$rate_value,
                   bootstrap_tpcs = boot_tpcs,
                   species = "Brachycaudus schwartzi",
                   life_stage = "Nymphs")


boundaries <- therm_suit_bounds(preds_tbl = boot_tpcs,
                                model_name = "lactin2",
                                suitability_threshold = 80)
head(boundaries)

---