modelCosts: Model the trend of invasive alien species costs over time

In invacost: Analyse Biological Invasion Costs with the 'InvaCost' Database

Model the trend of invasive alien species costs over time

Description

This function fits different models on 'InvaCost' data expressed per year in order to estimate and predict the trend of invasive alien Species costs over time.

Usage

modelCosts(
  costdb,
  cost.column = "Cost_estimate_per_year_2017_USD_exchange_rate",
  year.column = "Impact_year",
  cost.transf = "log10",
  in.millions = TRUE,
  confidence.interval = 0.95,
  minimum.year = 1960,
  maximum.year = max(costdb[, year.column]),
  final.year = max(costdb[, year.column]),
  incomplete.year.threshold = NULL,
  incomplete.year.weights = NULL,
  gam.k = -1,
  mars.nprune = NULL,
  ...
)

Arguments

costdb	The expanded 'InvaCost' database output from expandYearlyCosts, where costs occurring over several years are expanded over each year of impact
cost.column	Name of the cost column to use in costdb (usually, choose between the exchange rate (default) or Purchase Power Parity cost per year)
year.column	Name of the year column to use in costdb
cost.transf	Type of transformation you want to apply on cost values. The default is a log10 transformation, which is commonly applied in economics, allows to fit linear regression with a normal distribution of residuals, and makes plots easier to read. You can apply another transformation by specifying the name of the transformation function (e.g., natural logarithm, "log"). Specify NA or NULL to avoid any transformation
in.millions	If TRUE, cost values are transformed in millions (to make graphs easier to read), else if , cost values are not transformed
confidence.interval	A numeric value between 0 and 1, corresponding to the desired confidence interval around model predictions
minimum.year	The starting year of this analysis. By default, 1960 was chosen because it marks the period from which world bank data is available for exchange rates and inflation values
maximum.year	The ending year for this analysis. By default, the last year of costdb is chosen
final.year	The year for which the costs predicted by models is printed in the output. Default is the last year of costdb. Note that this is only for convenience, since predictions for all years are available in the estimated.annual.costs element of the output object
incomplete.year.threshold	Estimated threshold for incomplete cost data. All years above or equal to this threshold will be excluded from model calibration, because of the time-lag between economic impacts of invasive alien species and the documentation and publication of these impacts
incomplete.year.weights	A named vector containing weights of years for the regressions. Useful to decrease the weights of incomplete years in regressions. Names of this vector must correspond to years
gam.k	The smoothing factor of GAM; default value of -1 lets the GAM find the smoothing factor automatically. Provide a manual value if you have expectations about the shape of the curve and want to avoid overfitting because of interannual variations
mars.nprune	The maximum number of model terms in the MARS model. Lowering this value reduces the number of terms in the MARS model, which can be useful if you have expectations about the shape of the curve and want to reduce the impact of interannual variations
...	Other arguments (you do not need them!)

Value

A list with 3 to 6 elements (only the first three are provided if you selected a cost transformation different from log10):

• input.data: the input cost data, for reproducibility of analyses

• cost.data: the costs of invasions per year, as sums of all costs for each year

• parameters: parameters used to run the function. The minimum.year and maximum.year are based on the input data (i.e., the user may specify minimum.year = 1960 but the input data may only have data starting from 1970, hence the minimum.year will be 1970)

• fitted.models: a list of objects containing the fitted models. They can be extracted individually for refining analyses or making new predictions

• estimated.annual.costs: a data.frame containing the predicted cost values for each year for all the fitted models

• RMSE: an array containing RMSE of models for the calibration data and for all data. NOTE: the RMSE for Quantile Regressions is not a relevant metric, IGNORE it unless you know what you are doing!

• final.year.cost: a vector containing the estimated annual costs of invasive alien species based on all models for final.year.

The structure of this object can be seen using str().

Author(s)

Boris Leroy [e-mail], Andrew Kramer, Anne-Charlotte Vaissière, Christophe Diagne

References

https://github.com/Farewe/invacost

Leroy Boris, Kramer Andrew M, Vaissière Anne-Charlotte, Kourantidou Melina, Courchamp Franck & Diagne Christophe (2022). Analysing economic costs of invasive alien species with the invacost R package. Methods in Ecology and Evolution. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/2041-210X.13929")}

See Also

expandYearlyCosts to get the database in appropriate format.

Examples

data(invacost)

### Cleaning steps
# Eliminating data with no information on starting and ending years
invacost <- invacost[-which(is.na(invacost$Probable_starting_year_adjusted)), ]
invacost <- invacost[-which(is.na(invacost$Probable_ending_year_adjusted)), ]
# Keeping only observed and reliable costs
invacost <- invacost[invacost$Implementation == "Observed", ]
invacost <- invacost[which(invacost$Method_reliability == "High"), ]
# Eliminating data with no usable cost value
invacost <- invacost[-which(is.na(invacost$Cost_estimate_per_year_2017_USD_exchange_rate)), ]

### Expansion

db.over.time <- expandYearlyCosts(invacost,
                                  startcolumn = "Probable_starting_year_adjusted",
                                  endcolumn = "Probable_ending_year_adjusted")
                                  
### Analysis
res <- modelCosts(db.over.time)
res

invacost documentation built on May 29, 2024, 3:34 a.m.