invacost (version 1.1-6)

modelCosts: 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,
  ...
)

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().

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!)

Author

Boris Leroy , 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. 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
# \donttest{
db.over.time <- expandYearlyCosts(invacost,
                                  startcolumn = "Probable_starting_year_adjusted",
                                  endcolumn = "Probable_ending_year_adjusted")
                                  
### Analysis
res <- modelCosts(db.over.time)
res# }