Skip to contents

Determine Thermal Boundaries for Optimal Performance Level

Source: R/therm_suit_bounds.R
therm_suit_bounds.Rd

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. Alternatively, suitability_threshold can be set to "OPS" to calculate an interval of values between the quantile-50 by the left of the thermal optimum and the thermal optimum itself. This TPC region name comes from "Optimal Performance Safe". By "safe", we refer to temperatures at which the population still has margin before large heat-induced performance decreases under varying temperatures. A more detailed explanation is available in San-Segundo Molina et al. (2026) and the references therein.

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

San-Segundo Molina, D., Morales-Castilla, I., & Villén-Pérez, S. (2026). Future warming enhances rates of population increase of arthropod crop pests globally. Ecography 2026: e08568.

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

if (FALSE) { # interactive()
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)
}