Based on the fit of statistical models to population data, the function estimates the decline on the number of mature individuals across time, expressed in percentage.
pop.decline(
pop.size = NULL,
years = NULL,
taxa = NULL,
models = "all",
project.years = NULL,
output = "all",
by.taxon = FALSE,
parallel = FALSE,
NbeCores = 2,
show_progress = TRUE,
...
)a vector, data frame or matrix containing the (estimated) number of mature individuals of species (i.e. population size). If a data frame or matrix, rows are the species and columns are the population sizes.
a vector containing the years for which the population sizes is available
a vector containing the name of the species in pop.size
a vector containing the names of the statistical models to be fitted to species population data
a vector containing the years for which the number of mature individuals should be predicted using the best candidate statistical model
a character or vector containing the desired output from the function. The options are: "predictions", "model.fit", "model.selection" and "best.model". By default, the function returns only the predictions.
logical. Should the output list be organized by the selected output options (i.e. predictions, model.fit, model.selection and best.model) for all taxa or should it contain one taxon per taxon with all selected outputs? Defaults to FALSE (list organized by outputs and not taxa).
a logical. Whether running should be performed in parallel. FALSE by default.
an integer. Register the number of cores for parallel execution. Two by default.
logical. Whether progress informations should be displayed. TRUE by default
other parameters to be passed as arguments for functions
pop.decline.fit and ICtab.mod.select
a named list
By default, the function compares the fit of six statistical models to the
population trends, namely: linear, quadratic, exponential, logistic,
generalized logistic and piece-wise. But users can use different combinations
of those models using the argument models, according to the specificity
of their study region or groups of organism. See pop.decline.fit for
more details and assumptions on how those models are fitted to population
data and how the candidate models are selected.
IUCN 2019. Guidelines for Using the IUCN Red List Categories and Criteria. Version 14. Standards and Petitions Committee. Downloadable from: http://www.iucnredlist.org/documents/RedListGuidelines.pdf.
## Creating vectors with the population data and time intervals
#(adapted from the IUCN 2019 workbook for Criterion A, available
#at: https://www.iucnredlist.org/resources/criterion-a)
pop = c(10000, 9050, 8250, 7500, 7200, 6950)
pop1 = c(10000, NA, 8200, NA, NA, 6000)
yrs = c(1970, 1975, 1980, 1985, 1990, 2000)
tax = c("species A", "species B")
pops = matrix(c(pop, pop1), nrow = length(tax),
dimnames = list(tax, yrs), byrow = TRUE)
## Fitting data with different models and settings
# only one species, all models (default)
pop.decline(pop, yrs)
#>
|
| | 0%
|
|======================================================================| 100%
#> $predictions
#> $predictions$species1
#> years pop.size predicted
#> 1 1970 10000 10000
#> 2 1975 9050 9050
#> 3 1980 8250 8250
#> 4 1985 7500 7500
#> 5 1990 7200 7200
#> 6 2000 6950 6950
#>
#>
#> $model.fit
#> $model.fit$species1
#> Call: segmented.lm(obj = md, seg.Z = ~ys, psi = c(quebras[1], quebras[1]/2),
#> control = segmented::seg.control(display = FALSE, it.max = 100,
#> n.boot = 50))
#>
#> Coefficients of the linear terms:
#> (Intercept) ys U1.ys U2.ys
#> 1.0000 -0.0190 0.0040 0.0125
#>
#> Estimated Break-Point(s):
#> psi1.ys psi2.ys
#> 6.25 16.40
#>
#>
#> $model.selection
#> $model.selection$species1
#> dAICc df
#> linear 272.85 3
#> quadratic 277.65 4
#> exponential 270.64 3
#> logistic 277.08 3
#> general_logistic 289.83 4
#> piecewise 0.00 7
#>
#>
#> $best.model
#> $best.model$species1
#> [1] "piecewise"
#>
#>
# two species or more
pop.decline(pops)
#>
|
| | 0%
|
|=================================== | 50%
|
|======================================================================| 100%
#> Warning: Breakpoint estimate(s) outdistanced to allow finite estimates and st.errs
#> Warning: Estimation failed. Too many breakpoints? Returning a lm fit..
#> Warning: No piece-wise model was fit to population data due to lack of convergence, probably caused by too few observations
#>
#> $predictions
#> $predictions$`species A`
#> years pop.size predicted
#> 1 1970 10000 10000
#> 2 1975 9050 9050
#> 3 1980 8250 8250
#> 4 1985 7500 7500
#> 5 1990 7200 7200
#> 6 2000 6950 6950
#>
#> $predictions$`species B`
#> years pop.size predicted
#> 1 1970 10000 9914.3
#> 2 1975 NA 9100.0
#> 3 1980 8200 8352.6
#> 4 1985 NA 7666.5
#> 5 1990 NA 7036.8
#> 6 2000 6000 5928.4
#>
#>
#> $model.fit
#> $model.fit$`species A`
#> Call: segmented.lm(obj = md, seg.Z = ~ys, psi = c(quebras[1], quebras[1]/2),
#> control = segmented::seg.control(display = FALSE, it.max = 100,
#> n.boot = 50))
#>
#> Coefficients of the linear terms:
#> (Intercept) ys U1.ys U2.ys
#> 1.0000 -0.0190 0.0040 0.0125
#>
#> Estimated Break-Point(s):
#> psi1.ys psi2.ys
#> 6.25 16.40
#>
#> $model.fit$`species B`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 0.99143 -0.01714
#> residual sum-of-squares: 0.0003575
#>
#> Number of iterations to convergence: 4
#> Achieved convergence tolerance: 9.668e-06
#>
#>
#> $model.selection
#> $model.selection$`species A`
#> dAICc df
#> linear 272.85 3
#> quadratic 277.65 4
#> exponential 270.64 3
#> logistic 277.08 3
#> general_logistic 289.83 4
#> piecewise 0.00 7
#>
#> $model.selection$`species B`
#> dAICc df
#> linear 4.10 3
#> quadratic 10.83 4
#> exponential 0.00 3
#> logistic 8.83 3
#>
#>
#> $best.model
#> $best.model$`species A`
#> [1] "piecewise"
#>
#> $best.model$`species B`
#> [1] "exponential"
#>
#>
# two species or more, less models
pop.decline(pops, models = c("linear", "quadratic"))
#>
|
| | 0%
|
|=================================== | 50%
|
|======================================================================| 100%
#> $predictions
#> $predictions$`species A`
#> years pop.size predicted
#> 1 1970 10000 9527.9
#> 2 1975 9050 9014.3
#> 3 1980 8250 8500.7
#> 4 1985 7500 7987.1
#> 5 1990 7200 7473.6
#> 6 2000 6950 6446.4
#>
#> $predictions$`species B`
#> years pop.size predicted
#> 1 1970 10000 9800
#> 2 1975 NA 9150
#> 3 1980 8200 8500
#> 4 1985 NA 7850
#> 5 1990 NA 7200
#> 6 2000 6000 5900
#>
#>
#> $model.fit
#> $model.fit$`species A`
#> Nonlinear regression model
#> model: ps ~ a + b * ys
#> data: stats::na.omit(DATA)
#> a b
#> 0.95279 -0.01027
#> residual sum-of-squares: 0.008528
#>
#> Number of iterations to convergence: 0
#> Achieved convergence tolerance: 1.077e-14
#>
#> $model.fit$`species B`
#> Nonlinear regression model
#> model: ps ~ a + b * ys
#> data: stats::na.omit(DATA)
#> a b
#> 0.980 -0.013
#> residual sum-of-squares: 0.0014
#>
#> Number of iterations to convergence: 0
#> Achieved convergence tolerance: 5.13e-09
#>
#>
#> $model.selection
#> $model.selection$`species A`
#> dAICc df
#> linear 0.0 3
#> quadratic 4.8 4
#>
#> $model.selection$`species B`
#> dAICc df
#> linear 0 3
#> quadratic 2 4
#>
#>
#> $best.model
#> $best.model$`species A`
#> [1] "linear"
#>
#> $best.model$`species B`
#> [1] "linear"
#>
#>
pop.decline(pops, models = "exponential")
#>
|
| | 0%
|
|=================================== | 50%
|
|======================================================================| 100%
#> $predictions
#> $predictions$`species A`
#> years pop.size predicted
#> 1 1970 10000 9670.1
#> 2 1975 9050 9042.5
#> 3 1980 8250 8455.7
#> 4 1985 7500 7907.0
#> 5 1990 7200 7393.9
#> 6 2000 6950 6465.4
#>
#> $predictions$`species B`
#> years pop.size predicted
#> 1 1970 10000 9914.3
#> 2 1975 NA 9100.0
#> 3 1980 8200 8352.6
#> 4 1985 NA 7666.5
#> 5 1990 NA 7036.8
#> 6 2000 6000 5928.4
#>
#>
#> $model.fit
#> $model.fit$`species A`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 0.96701 -0.01342
#> residual sum-of-squares: 0.005893
#>
#> Number of iterations to convergence: 4
#> Achieved convergence tolerance: 6.345e-06
#>
#> $model.fit$`species B`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 0.99143 -0.01714
#> residual sum-of-squares: 0.0003575
#>
#> Number of iterations to convergence: 4
#> Achieved convergence tolerance: 9.668e-06
#>
#>
#> $model.selection
#> $model.selection$`species A`
#> NULL
#>
#> $model.selection$`species B`
#> NULL
#>
#>
#> $best.model
#> $best.model$`species A`
#> [1] "exponential"
#>
#> $best.model$`species B`
#> [1] "exponential"
#>
#>
# two species or more, exponential models with projections
pop.decline(pops, models = "exponential", project.years = c(1960, 2050))
#>
|
| | 0%
|
|=================================== | 50%
|
|======================================================================| 100%
#> $predictions
#> $predictions$`species A`
#> years pop.size predicted
#> 1 1960 NA 11058.8
#> 2 1970 10000 9670.1
#> 3 1975 9050 9042.5
#> 4 1980 8250 8455.7
#> 5 1985 7500 7907.0
#> 6 1990 7200 7393.9
#> 7 2000 6950 6465.4
#> 8 2050 NA 3305.2
#>
#> $predictions$`species B`
#> years pop.size predicted
#> 1 1960 NA 11768.1
#> 2 1970 10000 9914.3
#> 3 1975 NA 9100.0
#> 4 1980 8200 8352.6
#> 5 1985 NA 7666.5
#> 6 1990 NA 7036.8
#> 7 2000 6000 5928.4
#> 8 2050 NA 2516.1
#>
#>
#> $model.fit
#> $model.fit$`species A`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 1.10588 -0.01342
#> residual sum-of-squares: 0.005893
#>
#> Number of iterations to convergence: 8
#> Achieved convergence tolerance: 1.124e-06
#>
#> $model.fit$`species B`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 1.17681 -0.01714
#> residual sum-of-squares: 0.0003575
#>
#> Number of iterations to convergence: 6
#> Achieved convergence tolerance: 1.121e-06
#>
#>
#> $model.selection
#> $model.selection$`species A`
#> NULL
#>
#> $model.selection$`species B`
#> NULL
#>
#>
#> $best.model
#> $best.model$`species A`
#> [1] "exponential"
#>
#> $best.model$`species B`
#> [1] "exponential"
#>
#>
pop.decline(pops, models = "exponential", project.years = c(1973, 2005))
#>
|
| | 0%
|
|=================================== | 50%
|
|======================================================================| 100%
#> $predictions
#> $predictions$`species A`
#> years pop.size predicted
#> 1 1970 10000 9670.1
#> 2 1973 NA 9288.5
#> 3 1975 9050 9042.5
#> 4 1980 8250 8455.7
#> 5 1985 7500 7907.0
#> 6 1990 7200 7393.9
#> 7 2000 6950 6465.4
#> 8 2005 NA 6045.8
#>
#> $predictions$`species B`
#> years pop.size predicted
#> 1 1970 10000 9914.3
#> 2 1973 NA 9417.4
#> 3 1975 NA 9100.0
#> 4 1980 8200 8352.6
#> 5 1985 NA 7666.5
#> 6 1990 NA 7036.8
#> 7 2000 6000 5928.4
#> 8 2005 NA 5441.4
#>
#>
#> $model.fit
#> $model.fit$`species A`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 0.96701 -0.01342
#> residual sum-of-squares: 0.005893
#>
#> Number of iterations to convergence: 4
#> Achieved convergence tolerance: 6.345e-06
#>
#> $model.fit$`species B`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 0.99143 -0.01714
#> residual sum-of-squares: 0.0003575
#>
#> Number of iterations to convergence: 4
#> Achieved convergence tolerance: 9.668e-06
#>
#>
#> $model.selection
#> $model.selection$`species A`
#> NULL
#>
#> $model.selection$`species B`
#> NULL
#>
#>
#> $best.model
#> $best.model$`species A`
#> [1] "exponential"
#>
#> $best.model$`species B`
#> [1] "exponential"
#>
#>
# two species or more, different outputs
pop.decline(pops, models = "exponential", output = "model.fit")
#>
|
| | 0%
|
|=================================== | 50%
|
|======================================================================| 100%
#> $model.fit
#> $model.fit$`species A`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 0.96701 -0.01342
#> residual sum-of-squares: 0.005893
#>
#> Number of iterations to convergence: 4
#> Achieved convergence tolerance: 6.345e-06
#>
#> $model.fit$`species B`
#> Nonlinear regression model
#> model: ps ~ a * exp(b * ys)
#> data: stats::na.omit(DATA)
#> a b
#> 0.99143 -0.01714
#> residual sum-of-squares: 0.0003575
#>
#> Number of iterations to convergence: 4
#> Achieved convergence tolerance: 9.668e-06
#>
#>
pop.decline(pops, models = c("linear", "quadratic", "exponential"),
output = "model.selection")
#>
|
| | 0%
|
|=================================== | 50%
|
|======================================================================| 100%
#> $model.selection
#> $model.selection$`species A`
#> dAICc df
#> linear 2.22 3
#> quadratic 7.02 4
#> exponential 0.00 3
#>
#> $model.selection$`species B`
#> dAICc df
#> linear 4.1 3
#> quadratic 6.1 4
#> exponential 0.0 3
#>
#>
## Another examples
# Few observations (warning or no model fit below 3 observations)
pop.decline(pop.size = c(10000, 8200, 6000), years = c(1970, 1985, 2000),
models = "all", project.years = 2030)
#>
|
| | 0%
|
|======================================================================| 100%
#> Warning: no residual degrees of freedom (other warnings expected)
#> breakpoint estimate(s): 15.16406
#> Warning: No piece-wise model was fit to population data due to lack of convergence, probably caused by too few observations
#>
#> $predictions
#> $predictions$species1
#> years pop.size predicted
#> 1 1970 10000 10066.7
#> 2 1985 8200 8066.7
#> 3 2000 6000 6066.7
#> 4 2030 NA 2066.7
#>
#>
#> $model.fit
#> $model.fit$species1
#> Nonlinear regression model
#> model: ps ~ a + b * ys
#> data: stats::na.omit(DATA)
#> a b
#> 1.00667 -0.01333
#> residual sum-of-squares: 0.0002667
#>
#> Number of iterations to convergence: 0
#> Achieved convergence tolerance: 1.423e-14
#>
#>
#> $model.selection
#> $model.selection$species1
#> dAICc df
#> linear 0.00 3
#> quadratic 9.09 4
#> exponential 4.79 3
#> logistic 7.09 3
#>
#>
#> $best.model
#> $best.model$species1
#> [1] "linear"
#>
#>
if (FALSE) { # \dontrun{
# Not enough observations (error)
pop.decline(pop.size = c(10000, 6000), years = c(1970, 2000))
} # }